Resource Handlers

What is a Resource Handler?

A resource handler (RH) is a connection to your virtualization platform or public cloud provider that CloudBolt uses to perform actions like server creation or modification on your behalf. Creating resource handlers for each of your virtualization technologies and public cloud providers lets you use them through CloudBolt’s unified interface.

Creating New RHs

CloudBolt Admins can create new resource handlers from the CB UI: AdminResource HandlersAdd a resource handler

Creating new RHs in CB does not change external systems in any way, it can be considered a safe, read-only operation. Changes will only be made if users are given permissions in CloudBolt to manage servers and then they make changes, for example pressing the “Power Off” button on a server.

Technology-Specific Information

Each virtualization platform CloudBolt supports requires different information. This section explains RH tech-specific fields and behavior.

vCenter

Account Username & Password
The credentials for the vCenter account that CloudBolt will use to perform server creation, power management, synchronization, deletion, and other actions.
Clusters
Clusters are required to deploy using CloudBolt. If you are attempting to deploy to a single node, first create a cluster using vCenter. A CloudBolt Environment will automatically be created for each cluster selected, and the cluster-specific options (such as the resource pools and datastores) will be imported.
Network Requirements
CloudBolt communicates with VMware using the standard HTTPS connection on port 443. Network rules must allow traffic on port 443 between the CloudBolt server and all vCenters and ESX hosts.

NSX

If your vCenter supports advanced network configurations like vxlans and edge appliances, you will want to go to the NSX tab and configure the following:

NSX Endpoint
Defines and manages the NSX Manager connection endpoint used to create vxlans, edge appliances and support all advanced network concepts. See Virtual Networks for more info.
Edge Gateway Configuration

Add default values that should be used when creating an NSX Edge Services Gateway appliance like Provider Network, Cluster, Datastore, CLI Credentials and other attributes.

NOTE: In order to determine the IP to be used for the uplink interface of the ESG it is necessary that the provider network defined in the NSX Edge Configuration object be associated with an IP Pool. The provider network should also be fully configured in CloudBolt with appropriate values for Gateway and Netmask.

Nutanix Acropolis

Resource Handler connections to Nutanix Acropolis use the Acropolis Prism Element (PE) API. CloudBolt does not currently support Acropolis Prism Central (PC), so each Resource Handler you set up will connect to exactly one Acropolis Cluster.

Connections to Acropolis use SSL (HTTPS) by default, and require a username and password for an account that has read and write privileges within Prism: e.g. an account that can provision VMs, modify/delete existing VMs, and read information about VMs. Connections also require a port (which defaults to 9440) and hostname. Because connections use SSL by default, you may need to apply a host SSL certificate to your Acropolis cluster (contact Nutanix support for further details) where the hostname matches the hostname you enter into CloudBolt.

CloudBolt provisions new VMs on Acropolis from Disk Images hosted in the Image Service. These images may need to be customized based on typical Acropolis requirements, e.g.:

  • CentOS servers require the acpid yum package to be installed to support power controls from Acropolis. (CloudBolt issues shutdown and reboot commands using Acropolis’ ACPI operating system-based power control support as opposed to performing hard shutdown/power cycle. CentOS does not support ACPI out of the box compared to, e.g., Windows.)
  • On Linux servers, your network interfaces need to be ready for cloning operations. (e.g. your image needs to be configured so that eth0 connects on VM startup, instead of attempting to connect to eth1.)

If you are not using the Image Service today, you will need to create images from existing VM disks by using the acli command-line utility. CloudBolt Software has found that the easiest way to do so is to run the following example commands by SSHing into your Acropolis cluster:

# This command clones the VM Disk on a VM named "centos6-template" to an image named "centos6".
acli image.create centos6 clone_from_vmdisk=vm:centos6-template:scsi.0
# This command marks the newly-created image as a disk-type image. (As opposed to a CDROM ISO.)
acli image.update centos6 image_type=kDiskImage

OpenStack

Credentials
To start using OpenStack as a resource available in CloudBolt, it’s necessary to provide basic connectivity to the primary OpenStack API endpoint. These include IP, port, account username and password, as well as the Authentication Policy in use by your OpenStack infrastructure. Note that different policies may require additional information like a Primary Project ID and default Domain.
Projects/Tenants
After uploading your credentials, you can choose which Projects/Tenants you’d like CloudBolt to manage.

Google Compute Engine

Integration with GCE can be set up using a Service Account Key. You can generate one with the following steps:

  1. Navigate to the Credentials page in the GCE console
  2. Click “Create Credentials”, then “Service account key”
  3. Select the service account to use, or create a new one.
  4. Make sure that the JSON key type is selected, then click Create to download the .json file
  5. Make sure the Google Compute Engine API is enabled for this project. This is disabled by default for new projects, but can be enabled in the Google Cloud Console from API Library, by searching for “Google Compute Engine”.
  6. In the CloudBolt UI, add a new Google Compute Engine resource handler and upload the JSON file in the form

After uploading your credentials, you can choose which locations you’d like CloudBolt to manage.

Other Notes
When building new servers, GCE marks them as ready before they may be fully booted, and services like ssh may not yet be running. If you are attempting to run remote scripts on servers at the end of the provisioning process and you receive a connection refused error, go to the parameters tab on the environment in CloudBolt and add the “Post Provisioning Delay” parameter with a single option of 30 (to add a 30s delay before attempting to run scripts).

Azure Classic (Service Management)

Integration with Azure can be set up using the following steps:

  1. Navigate to the Azure console
  2. Click the settings link in the lower left
  3. Copy the subscription ID you would like CloudBolt to use. This will be used when setting up the RH in CloudBolt
  4. Follow the directions from Microsoft for creating a certificate on Linux. This procedure can be followed from the CloudBolt server
  5. Upload the .cer file that was created to the Azure console. This can be done by navigating to settings –> management certificates –> upload
  6. Run mkdir -p /var/opt/cloudbolt/resourcehandlers/azure/
  7. Move the .pem file that was created above to /var/opt/cloudbolt/resourcehandlers/azure/
  8. Make sure the .pem file is accessible by running chmod o+r /var/opt/cloudbolt/resourcehandlers/azure/filename.pem
  9. From the Resource Handlers page in the CloudBolt UI, click the “Add a resource handler” button and enter the relevant information from above, and select which locations you would like CloudBolt to manage

Azure requires a username and password when provisioning a new server. The owner’s CloudBolt username is the default username, but there is no default password. You can allow the user to specify one in the order form by adding the Password parameter to the group or environment, set it on the template, or set a default in the Global Parameter Defaults page of the UI.

Azure (Resource Manager)

Azure provides a new way to deploy and manage virtual machines and other resources. If you used the earlier service deployment model and want to learn about the changes, see Understanding Resource Manager deployment and classic deployment. Integration with Azure can be set up using the following steps:

  1. Navigate to the Azure portal.

  2. On the dashboard, click the link to Subscriptions.

  3. Copy the subscription ID you would like CloudBolt to use. This will be used when setting up the RH in CloudBolt.

  4. Create an Active Directory application that can access resources. Follow the instructions available in Azure’s documentation.

  5. Record the Client ID, Secret, and Tenant ID for the new Active Directory application, as those will also be needed to set up the RH in Cloudbolt.

    1. Note: the new Azure portal refers to Client ID as ‘Application ID’, and Tenant ID as ‘Directory ID’. The Secret will be an authentication key generated using Azure’s documentation.
  6. Add the application as an owner for the subscription.

    1. Click on ‘subscriptions’ from the menu on the left and select the subscription you will be using. You might have to click ‘More services’ to see the option for ‘subscriptions’.

    2. Click on ‘Access control (IAM)’ for the chosen subscription.

    3. Click on ‘Add’, choose ‘owner’, search for your application name, select it and click ‘save’.

      1. Note: If owner permissions are not allowed for your subscription, the minimal permissions needed are ‘Virtual Machine Contributor’ and ‘Storage Account Contributor’.
  7. From the Resource Handlers page in the CloudBolt UI, click the “Add a resource handler” button and enter the relevant information from above, and select which locations you would like CloudBolt to manage

Provisioning

Azure requires a username and password when provisioning a new server. The owner’s CloudBolt username is the default username, but there is no default password. There is a password parameter provided with every Azure environment to allow users to specify a password on the order form. You can also set a default in the Global Parameter Defaults page of the UI.

Servers may be provisioned with managed disks (default) or with a custom storage account (“Use custom storage account” Azure parameter). By default servers are provisioned with Standard HDD-based storage. To use high-performance, low-latency SSD disks on supported server sizes, admins should configure the “Storage Type” Azure parameter.

To further customize your Azure VMs, there are some optional parameters which can be added to groups, environments, or directly to servers. These include:

  • Azure License Type: If you would like to take advantage of Azure’s “bring your own license” functionality, add this parameter to the group or environment so an appropriate value, such as “Windows_Server”, can be provided in the order form and used during provisioning.
  • Deallocate with power off: When set to True on a server, powering off the server will also deallocate it, which stops the VM from incurring charges, but also deletes the public and internal IP.
  • Location or ‘node_location’, allows you to specify a location for the VM. Also known as region, zone, tenant or datacenter, depending on the provider.
  • Skip Creation of Security Group: If set to true, the server will not receive its own network security group. The subnet security group will still apply.
  • Azure Resource Group: Allows you to specify a resource group to provision into or auto-create a new one.
  • Azure Storage Account: Allows you to specify a location for storing VM disks or auto-create a new one.
  • Availability Set: a logical grouping of VMs within a datacenter that allows Azure to understand how your application is built to provide for redundancy and availability. This parameter allows you to choose an existing or auto-create a new availability set for your VM.
  • Delete Empty Azure Resource Group: If set to true, deleting a server will clean up its resource group if the resulting group is empty.
  • Use custom storage account: If true, specify an existing Azure storage account to be used or let one be created automatically; otherwise, Azure will manage disks and storage accounts automatically.

Importing Images

Azure provides over 3000 images per region, and fetching them can take a long time. To avoid fetching the entire list when you want to use an image, a rule has been added that will cache available Azure images. That rule gets run nightly, but must be run once before images are available.

By default, this rule only imports a whitelist of images provided by CloudBolt. You may implement your own whitelist in customer_settings.py. This must be a list of tuples containing the publisher, offer, SKU and version of each image you’d like to import, like the following example:

AZURE_IMAGE_WHITELIST = [
    ('redhat', 'RHEL', '6.7', '6.7.20160302'),
    ('MicrosoftWindowsServer', 'WindowsServer', '2012-R2-Datacenter', '4.0.20160518'),
    ('canonical', 'UbuntuServer', '16.04.0-LTS', '16.04.201605161')
]

To disable the use of a whitelist and import all images, go to Admin > Rules > Fetch and Cache Available Azure Images and edit the ‘use_whitelist’ action input, changing the default value to False.

Syncing Resources

Resource Groups and Storage Accounts can be managed directly from CloudBolt via tabs on the Environment detail pages. On each tab, you can sync existing resources from your Azure subscription. You can add new resources directly, although both resource types can also be automatically created when provisioning a server.

Existing resources can be deleted, which will remove that resource from Azure. CloudBolt provides a parameter ‘Delete Empty Azure Resource Group’ available to add to Azure environments and servers. When deleting a server with this parameter set to True, the associated Resource Group will also be deleted if it becomes empty.

Existing resources can also be enabled or disabled in CloudBolt, which determines if that resource is available as a parameter for provisioning servers within the given environment.

Alternative Cloud Environments

Normally, the Azure resource handler connects to the default public version of Azure, including regions in the US and Canada. However, it can also connect to alternative clouds with their own regions like Germany, China, and US Gov. Choose one of the alternate Cloud Environment choices when creating a new instance of the resource handler, or on the credentials form of an existing handler.

AWS

When an AWS RH is created, CloudBolt provides a choice of regions to be imported, and one CB environment will be created for each. Additionally, VPCs can be specified for each CB AWS environment to build & manage instances within a specific VPC.

Environments

Each AWS environment comes with out of the box parameters and options to allow for easeful deployment and customization of AWS instances from CloudBolt. These are all shown under the “AWS Parameters” tab on the environment and include the following:

  • Instance Type *
  • Elastic IP Allows you to specify an Elastic IP at provision time.
  • Key pairs *
  • Security Groups *
  • Availability Zone Allows you to optionally launch new AWS instances into a specific availability zone within a region to protect an application from the failure of a single Amazon data center.
  • EBS Volume Type A required parameter for specifying volume type when provisioning or adding a disk to an existing server
  • IOPS Input/Output Operations per second. This parameter is dependent on EBS Volume Type and is needed for creating io1 volumes.
  • Auto-delete EBS Volumes on termination True by default, this sets your volumes to be deleted automatically when deleting the attached instance.

*An AWS environment will discover which instance types, keypairs, and security groups are available.

Networks and AMIs may also be imported for each environment.

For information about passwords on AWS Windows Instances, see the remote scripts section.

Images

When you import AMIs in CloudBolt, CloudBolt will create an OS Build for that AMI. If you import the corresponding AMI in other regions, CloudBolt will automatically reuse the pre-existing OS Build, and associate the newly imported AMI with it. This will only happen if the name of the OS Build has not been altered and matches the name of the AMI. However, CB Admins can edit the OS Build for an AMI to override that default behavior.

Hyper-V

Integration with a Hyper-V resource is done by running remote scripts on the Hyper-V server defined by the IP you provide, using the credentials stored with the Resource Handler. Please ensure that the Hyper-V server can have scripts run on it with WinRM and that the credentials are sufficient to do so. For information about running remote scripts, see the remote scripts page.

IBM SoftLayer

Integration with IBM SoftLayer can be set up using the following steps:

  1. Navigate to the IBM SoftLayer console
  2. Click on your name in the top-right corner of the page
  3. Note the Username and Authentication Key on the page
  4. From the Resource Handlers page in the CloudBolt UI, click the “Add a resource handler” button and enter the relevant information from above, and select which datacenters you would like CloudBolt to manage

Note: IBM SoftLayer appends a domain name to the hostname you provide. By default, CloudBolt will append ‘example.com’. For example, if you provide ‘president’ as the hostname, the FQDN will become ‘president.example.com’. Contact CloudBolt Support for information on how to change the domain name suffix to something else.

OpenStack

To set up your OpenStack account with CloudBolt, perform the following steps:
  1. Select a protocol (HTTP or HTTPS).
  2. Select an authentication policy (v2 or v3).
  3. Enter the IP Address, port, username and password for your OpenStack server.
  4. Continue, then enter a domain and project ID for your account.

Oracle Compute Cloud

Integration with Oracle Compute Cloud can be set up using the following steps:

  1. Look up the necessary login information. This includes the API endpoint URL provided when you subscribed to the service, the identity domain, username, and password
  2. From the Resource Handlers page in the CloudBolt UI, click the “Add a resource handler” button and enter the login information. Note that the API endpoint URL is split between the Protocol & API Endpoint fields

AWS GovCloud

AWS GovCloud (US) resource handlers can currently connect to a single region, us-gov-west-1. When a handler is created, an Environment is automatically created that maps to that region. To create a GovCloud resource handler using this region, provide an EC2 endpoint of ec2.us-gov-west-1.amazonaws.com and an Elastic Load Balancer endpoint of elasticloadbalancing.us-gov-west-1.amazonaws.com.

If AWS adds additional regions to AWS GovCloud, CloudBolt will be updated to support multiple regions from one GovCloud resource handler. Until then, each GovCloud resource handler is associated with a single region.

Eucalyptus

Similar to AWS GovCloud, Eucalyptus resource handlers connect to a single region, so creating one will automatically create one Environment that maps to that default region.

XenServer

XenServer resource handlers connect to a single hypervisor. To set up a XenServer resource handler, you’ll need to know the protocol, IP address, port, username, and password for the hypervisor.

Configuring Static IPs

When provisioning a Xen VM through CloudBolt, you can assign a static IP address to the VM. To learn more on how to set up a static IP address, see DHCP and Static Addressing. Note that in order to configure an IP address, the VM will need to have XenServer tools installed. This can be done using an image which already has the tools installed on it.

Parameters that Alter RH Behavior

  • “Skip RH Hostname Validation” - If set to True, CloudBolt provisioning jobs will skip calling the resource handler to check whether the VM name is already in use. This can speed up provisioning, but may lead to job failures due to name collisions. This applies to any RH which has logic for checking for name availability (ex. VMware, Xen, GCE, OpenStack). Using this parameter does not skip hostname validation orchestration actions.
  • “Skip Network Configuration” - If set to True, CloudBolt provisioning jobs will skip calling the resource handler to customize network configuration for new VMs. Applies only to VMware.

Next Steps After Creating a RH

In order to use a newly created RH for provisioning, you will next need to create an environment, associate the RH with the environment, and import templates/images for that RH. Note that some RHs will automatically create an environment and associate it with the RH, so in those cases you only need to import templates/images for the RH.

Importing New or Modified Resources

VMs

Every half-hour, CloudBolt will automatically query your resource handlers for any changes to VMs.

If new servers have been created or deleted outside of CloudBolt, server records in CloudBolt will be created or deleted. Likewise, if changes are made to a server’s power status, CPU count, memory size, or other fields, the existing records in CloudBolt will be updated to reflect those changes. When servers are updated by this syncing process, CloudBolt records history events, which can be seen in the history tab of the server’s detail view.

If you want to trigger this syncing process manually:

  1. Click Admin
  2. Click Resource Handlers
  3. Click Sync VMs from all resource handlers, or click on a specific RH, then on its Servers tab, then Sync VMs from resource handler

A sync job will be started and a link will appear that you can click to view the job page, which will automatically update with information on the syncing process.

Networks

To import all of the networks for a given RH:

  1. Click Admin
  2. Click Resource Handlers
  3. Click on the name of a RH to open its detail view
  4. On the Networks tab, click Import networks. A dialog will show that lists all networks discovered on the RH that are not in CloudBolt
  5. Select the networks that you want CloudBolt to be aware of, and click Import selected networks to make them usable from within CloudBolt

Google Compute Engine subnetworks

Google Compute subnetworks are imported by CloudBolt when their associated network is imported. The subnetworks will be listed below their network on the resource handler’s Networks tab. When adding networks to an environment, any subnetworks that match the region of the environment will also be available. A list of the added networks and subnetworks will then be available when provisioning a server within that environment. If a server is provisioned with a subnetwork, instead of a top-level network, the parent network will automatically be associated with the server.

Templates

To import all of the images for a given RH:

  1. Click Admin
  2. Click Resource Handlers
  3. Click on the name of a RH to open its detail view
  4. Click the Images tab (AMIs for AWS)
  5. Click Import images. A dialog will show that lists all newly discovered images
  6. Select the images that you want CloudBolt to be aware of, and click Import selected images to make them usable from within CloudBolt

If clicking Import images causes CloudBolt to realize that images that were previously imported no longer exist in your virtualization technology, then those old images will be automatically removed from CloudBolt.

CloudBolt will automatically make an OS Build for each imported image. However, you can change the name of that OS Build or associate the image with a different one. OS Builds are a higher-level concept above images that can be used to label or group images and reference them in a more generic way. The strongest use case for OS Builds is in the catalog, where a blueprint can include a server tier with an OS Build that refers to multiple images. Then, the actual image used when the blueprint is ordered will depend on the Environment selected. Some aspects of OS Builds can be modified from the resource handler’s Images tab, while other changes are made from Admin -> OS Builds.