Product SiteDocumentation Site

3.2. What's New in the API for 3.0

3.2.1. Enabling Port 8096

Port 8096, which allows API calls without authentication, is closed and disabled by default on any fresh 3.0.1 installations. You can enable 8096 (or another port) for this purpose as follows:
  1. Ensure that the first Management Server is installed and running.
  2. Set the global configuration parameter integration.api.port to the desired port.
  3. Restart the Management Server.
  4. On the Management Server host machine, create an iptables rule allowing access to that port.

3.2.2. Stopped VM

CloudStack now supports creating a VM without starting it. You can determine whether the VM needs to be started as part of the VM deployment. A VM can now be deployed in two ways: create and start a VM (the default method); or create a VM and leave it in the stopped state.
A new request parameter, startVM, is introduced in the deployVm API to support the stopped VM feature.
The possible values are:
  • true - The VM starts as a part of the VM deployment.
  • false - The VM is left in the stopped state at the end of the VM deployment.
The default value is true.

3.2.3. Change to Behavior of List Commands

There was a major change in how our List* API commands work in CloudStack 3.0 compared to 2.2.x. The rules below apply only for managed resources – those that belong to an account, domain, or project. They are irrelevant for the List* commands displaying unmanaged (system) resources, such as hosts, clusters, and external network resources.
When no parameters are passed in to the call, the caller sees only resources owned by the caller (even when the caller is the administrator). Previously, the administrator saw everyone else's resources by default.
When accountName and domainId are passed in:
  • The caller sees the resources dedicated to the account specified.
  • If the call is executed by a regular user, the user is authorized to specify only the user's own account and domainId.
  • If the caller is a domain administrator, CloudStack performs an authorization check to see whether the caller is permitted to view resources for the given account and domainId.
When projectId is passed in, only resources belonging to that project are listed.
When domainId is passed in, the call returns only resources belonging to the domain specified. To see the resources of subdomains, use the parameter isRecursive=true. Again, the regular user can see only resources owned by that user, the root administrator can list anything, and a domain administrator is authorized to see only resources of the administrator's own domain and subdomains.
To see all resources the caller is authorized to see, except for Project resources, use the parameter listAll=true.
To see all Project resources the caller is authorized to see, use the parameter projectId=-1.
There is one API command that doesn't fall under the rules above completely: the listTemplates command. This command has its own flags defining the list rules:
listTemplates Flag
Description
featured
Returns templates that have been marked as featured and public.
self
Returns templates that have been registered or created by the calling user.
selfexecutable
Same as self, but only returns templates that are ready to be deployed with.
sharedexecutable
Ready templates that have been granted to the calling user by another user.
executable
Templates that are owned by the calling user, or public templates, that can be used to deploy a new VM.
community
Returns templates that have been marked as public but not featured.
all
Returns all templates (only usable by admins).
The CloudStack UI on a general view will display all resources that the logged-in user is authorized to see, except for project resources. To see the project resources, select the project view.

3.2.4. Removed API commands

  • createConfiguration (Adds configuration value)
  • configureSimulator (Configures simulator)

3.2.5. Added API commands in 3.0

3.2.5.1. Added in 3.0.2

  • changeServiceForSystemVm
    Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect.

3.2.5.2. Added in 3.0.1

  • changeServiceForSystemVm
    Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect.

3.2.5.3. Added in 3.0.0

assignVirtualMachine (Move a user VM to another user under same domain.)
restoreVirtualMachine (Restore a VM to original template or specific snapshot)
createLBStickinessPolicy (Creates a Load Balancer stickiness policy )
deleteLBStickinessPolicy (Deletes a LB stickiness policy.)
listLBStickinessPolicies (Lists LBStickiness policies.)
ldapConfig (Configure the LDAP context for this site.)
addSwift (Adds Swift.)
listSwifts (List Swift.)
migrateVolume (Migrate volume)
updateStoragePool (Updates a storage pool.)
authorizeSecurityGroupEgress (Authorizes a particular egress rule for this security group)
revokeSecurityGroupEgress (Deletes a particular egress rule from this security group)
createNetworkOffering (Creates a network offering.)
deleteNetworkOffering (Deletes a network offering.)
createProject (Creates a project)
deleteProject (Deletes a project)
updateProject (Updates a project)
activateProject (Activates a project)
suspendProject (Suspends a project)
listProjects (Lists projects and provides detailed information for listed projects)
addAccountToProject (Adds acoount to a project)
deleteAccountFromProject (Deletes account from the project)
listProjectAccounts (Lists project's accounts)
listProjectInvitations (Lists an account's invitations to join projects)
updateProjectInvitation (Accepts or declines project invitation)
deleteProjectInvitation (Deletes a project invitation)
updateHypervisorCapabilities (Updates a hypervisor capabilities.)
listHypervisorCapabilities (Lists all hypervisor capabilities.)
createPhysicalNetwork (Creates a physical network)
deletePhysicalNetwork (Deletes a Physical Network.)
listPhysicalNetworks (Lists physical networks)
updatePhysicalNetwork (Updates a physical network)
listSupportedNetworkServices (Lists all network services provided by CloudStack or for the given Provider.)
addNetworkServiceProvider (Adds a network serviceProvider to a physical network)
deleteNetworkServiceProvider (Deletes a Network Service Provider.)
listNetworkServiceProviders (Lists network serviceproviders for a given physical network.)
updateNetworkServiceProvider (Updates a network serviceProvider of a physical network)
addTrafficType (Adds traffic type to a physical network)
deleteTrafficType (Deletes traffic type of a physical network)
listTrafficTypes (Lists traffic types of a given physical network.)
updateTrafficType (Updates traffic type of a physical network)
listTrafficTypeImplementors (Lists implementors of implementor of a network traffic type or implementors of all network traffic types)
createStorageNetworkIpRange (Creates a Storage network IP range.)
deleteStorageNetworkIpRange (Deletes a storage network IP Range.)
listStorageNetworkIpRange (List a storage network IP range.)
updateStorageNetworkIpRange (Update a Storage network IP range, only allowed when no IPs in this range have been allocated.)
listUsageTypes (List Usage Types)
addF5LoadBalancer (Adds a F5 BigIP load balancer device)
configureF5LoadBalancer (configures a F5 load balancer device)
deleteF5LoadBalancer ( delete a F5 load balancer device)
listF5LoadBalancers (lists F5 load balancer devices)
listF5LoadBalancerNetworks (lists network that are using a F5 load balancer device)
addSrxFirewall (Adds a SRX firewall device)
deleteSrxFirewall ( delete a SRX firewall device)
listSrxFirewalls (lists SRX firewall devices in a physical network)
listSrxFirewallNetworks (lists network that are using SRX firewall device)
addNetscalerLoadBalancer (Adds a netscaler load balancer device)
deleteNetscalerLoadBalancer ( delete a netscaler load balancer device)
configureNetscalerLoadBalancer (configures a netscaler load balancer device)
listNetscalerLoadBalancers (lists netscaler load balancer devices)
listNetscalerLoadBalancerNetworks (lists network that are using a netscaler load balancer device)
createVirtualRouterElement (Create a virtual router element.)
configureVirtualRouterElement (Configures a virtual router element.)
listVirtualRouterElements (Lists all available virtual router elements.)

3.2.6. Added CloudStack Error Codes

You can now find the CloudStack-specific error code in the exception response for each type of exception. The following list of error codes is added to the new class named CSExceptionErrorCode. These codes are applicable in CloudStack 3.0.3 and later versions.
4250 : "com.cloud.utils.exception.CloudRuntimeException"
4255 : "com.cloud.utils.exception.ExceptionUtil"
4260 : "com.cloud.utils.exception.ExecutionException"
4265 : "com.cloud.utils.exception.HypervisorVersionChangedException"
4270 : "com.cloud.utils.exception.RuntimeCloudException"
4275 : "com.cloud.exception.CloudException"
4280 : "com.cloud.exception.AccountLimitException"
4285 : "com.cloud.exception.AgentUnavailableException"
4290 : "com.cloud.exception.CloudAuthenticationException"
4295 : "com.cloud.exception.CloudExecutionException"
4300 : "com.cloud.exception.ConcurrentOperationException"
4305 : "com.cloud.exception.ConflictingNetworkSettingsException"
4310 : "com.cloud.exception.DiscoveredWithErrorException"
4315 : "com.cloud.exception.HAStateException"
4320 : "com.cloud.exception.InsufficientAddressCapacityException"
4325 : "com.cloud.exception.InsufficientCapacityException"
4330 : "com.cloud.exception.InsufficientNetworkCapacityException"
4335 : "com.cloud.exception.InsufficientServerCapacityException"
4340 : "com.cloud.exception.InsufficientStorageCapacityException"
4345 : "com.cloud.exception.InternalErrorException"
4350 : "com.cloud.exception.InvalidParameterValueException"
4355 : "com.cloud.exception.ManagementServerException"
4360 : "com.cloud.exception.NetworkRuleConflictException"
4365 : "com.cloud.exception.PermissionDeniedException"
4370 : "com.cloud.exception.ResourceAllocationException"
4375 : "com.cloud.exception.ResourceInUseException"
4380 : "com.cloud.exception.ResourceUnavailableException"
4385 : "com.cloud.exception.StorageUnavailableException"
4390 : "com.cloud.exception.UnsupportedServiceException"
4395 : "com.cloud.exception.VirtualMachineMigrationException"
4400 : "com.cloud.exception.AccountLimitException"
4405 : "com.cloud.exception.AgentUnavailableException"
4410 : "com.cloud.exception.CloudAuthenticationException"
4415 : "com.cloud.exception.CloudException"
4420 : "com.cloud.exception.CloudExecutionException"
4425 : "com.cloud.exception.ConcurrentOperationException"
4430 : "com.cloud.exception.ConflictingNetworkSettingsException"
4435 : "com.cloud.exception.ConnectionException"
4440 : "com.cloud.exception.DiscoveredWithErrorException"
4445 : "com.cloud.exception.DiscoveryException"
4450 : "com.cloud.exception.HAStateException"
4455 : "com.cloud.exception.InsufficientAddressCapacityException"
4460 : "com.cloud.exception.InsufficientCapacityException"
4465 : "com.cloud.exception.InsufficientNetworkCapacityException"
4470 : "com.cloud.exception.InsufficientServerCapacityException"
4475 : "com.cloud.exception.InsufficientStorageCapacityException"
4480 : "com.cloud.exception.InsufficientVirtualNetworkCapcityException"
4485 : "com.cloud.exception.InternalErrorException"
4490 : "com.cloud.exception.InvalidParameterValueException"
4495 : "com.cloud.exception.ManagementServerException"
4500 : "com.cloud.exception.NetworkRuleConflictException"
4505 : "com.cloud.exception.PermissionDeniedException"
4510 : "com.cloud.exception.ResourceAllocationException"
4515 : "com.cloud.exception.ResourceInUseException"
4520 : "com.cloud.exception.ResourceUnavailableException"
4525 : "com.cloud.exception.StorageUnavailableException"
4530 : "com.cloud.exception.UnsupportedServiceException"
4535 : "com.cloud.exception.VirtualMachineMigrationException"
9999 : "com.cloud.api.ServerApiException"