The CloudStack API is a low level API that has been used to implement the CloudStack web UIs. It is also a good basis for implementing other popular APIs such as EC2/S3 and emerging DMTF standards.

Many CloudStack API calls are asynchronous. These will return a Job ID immediately when called. This Job ID can be used to query the status of the job later. Also, status calls on impacted resources will provide some indication of their state.

The API has a REST-like query basis and returns results in XML or JSON.

See the Developer’s Guide and the API Reference.

Provisioning and Authentication API

CloudStack expects that a customer will have their own user provisioning infrastructure. It provides APIs to integrate with these existing systems where the systems call out to CloudStack to add/remove users..

CloudStack supports pluggable authenticators. By default, CloudStack assumes it is provisioned with the user’s password, and as a result authentication is done locally. However, external authentication is possible as well. For example, see Using an LDAP Server for User Authentication.

User Data and Meta Data

The user-data service on a Shared or Isolated Network can be provided through the Virtual Router or through an attached iso called the Config drive.

User Data and Meta Data Via Virtual Router

CloudStack provides API access to attach up to 32KB of user data to a deployed VM. Deployed VMs also have access to instance metadata via the virtual router.

User data can be accessed once the IP address of the virtual router is known. Once the IP address is known, use the following steps to access the user data:

  1. Run the following command to find the virtual router.
  2. Access user data by running the following command using the result of the above command

Meta Data can be accessed similarly, using a URL of the form http://10.1.1.1/latest/meta-data/{metadata type}. (For backwards compatibility, the previous URL http://10.1.1.1/latest/{metadata type} is also supported.) For metadata type, use one of the following:

  • service-offering. A description of the VMs service offering
  • availability-zone. The Zone name
  • local-ipv4. The guest IP of the VM
  • local-hostname. The hostname of the VM
  • public-ipv4. The first public IP for the router. (E.g. the first IP of eth2)
  • public-hostname. This is the same as public-ipv4
  • instance-id. The instance name of the VM

User Data and Meta Data via Config Drive

Config drive is an ISO file that is mounted as a cd-rom on a user VM and contains the user VM related userdata, metadata (incl. ssh-keys) and password files.

Enable config drive

To use the config drive the network offering must have the “ConfigDrive” provider selected for the userdata service.

If the networkoffering uses ConfigDrive for userdata and the template is password enabled, the password string for the VM is placed in the vm_password.txt file and it is included in the ISO.

ConfigDrive availability

At VM start the config drive ISO is attached on the 2nd cd/dvd drive of the user instance, such that any other ISO image (e.g. boot image or vmware tools) is mounted on 1st cd/dvd drive. This means existing functionality of supporting 1 cd rom drive is still available.

At password reset or update of user data, the Config Drive ISO will be rebuilt. The existing ISO is mounted on a temporary directory, password, userdata or ssh-keys are updated and a new ISO is built from the updated directory structure.

In case of a password reset, the new password will be picked-up at VM start. To access the updated userdata, the user needs to remount the config drive ISO.

When a VM is stopped, the ConfigDrive network element will trigger the Secondary Storage VM to remove the ISO from the secondary storage. If the config drive is stored on primary storage, the network element will trigger the host to remove the ISO.

The config drive ISO can be stored on primary storage by setting the global setting vm.configdrive.primarypool.enabled to true. This is currently only supported with use of the KVM Hypervisor.

Supporting ConfigDrive

Extra data is added to the VM profile to enable the creation of the config drive:

VMdata - a list of String arrays representing [“directory”, “filename”, “content”] on the ConfigDrive device.

  • <mountdir>/cloudstack
    • /metadata:
      • availability-zone.txt
      • instance-id.txt
      • service-offering.txt
      • cloud-identifier.txt
      • local-hostname.txt
      • vm-id.txt
      • public-keys.txt
    • /password
      • vm_password.txt
      • vm_password_md5checksum (for windows VM’s)
  • <mountdir>/openstack/version/:
    • user_data (=hardlink to <mountdir>/cloudstack/user_data/user_data.txt)
      • vendor_data.json
      • meta_data.json
      • Network_data.json
    • label, which is configurable in global settings:
      • name : vm.configdrive.label
      • default: config-2

For more detailed information about the Config Drive implementation refer to the Wiki Article