Last updated March 12, 2009 06:24, by Tim Bray
Cloud API - Command Line Client
This page documents a command line client that can be used to perform all of the operations on a server implementing the Cloud API Specification.
Command Line Client for the Sun Cloud Computing API
This script lets you perform operations against the cloud computing service in a
"command line interface" (CLI) style, suitable for inclusion in shell scripts.
The general form of a command is:
cloud_command (env_options) (context_options) (command) (command_options)
with the following available options in each category (default values in []):
ENVIRONMENT OPTIONS (specify server and user credentials):
These options establish your the "well known" URI of the cloud service
instance you will be communicating with, as well as your authentication
credentials. To avoid the need to include these values on every request
in a script, this tool will look for a configuration file in either a
default location ($HOME/.cloud.sun.com.json), or in a location specified
by the "--config" option. The content of this file is treated as a JSON
resource, and any value present for fields named "uri", "name", and
"password" defines a default value that is used if a corresponding option
is *not* included in the command line. If you *do* specify these options,
you are overriding the default values.
The following environment options may be specified (--config must be first
if present, others may be in any order):
--config xxxxxxxxx Pathname to a JSON configuration
file potentially containing settings
for "uri", "username", and "password"
fields that establish defaults.
[$HOME/.cloud.sun.com.json if it exists].
--uri xxxxxxx URI of the service instance
(default from config).
--username xxxxxxxx Your username (default from config).
--password xxxxxxxx Your password (default from config).
CONTEXT OPTIONS (select the target of the command execution):
These options (if present) must follow the environment options (but in
any order within the group). If none are specified, commands will be
directed to the overall space. In all cases, the "xxxxxxxx" represents
the "name" field of the resource to be selected.
--vdc xxxxxxxx VDC to receive commands, or parent of
the public address, cluster, VNet,
or volume that will receive the command
[First VDC returned by the "get cloud"
request].
--address xxxxxxxx Public Address within the selected VDC
to receive commands (--vdc allowed,
--cluster/--vnet/--volume not allowed).
--cluster xxxxxxxx Cluster within the selected VDC
to receive commands.
--vnet xxxxxxxx VNet within the selected VNet to
receive commands (--vdc allowed,
--address/--cluster/--volume not
allowed).
--volume xxxxxxxx Volume within the selected VDC
to receive commands (--vdc allowed,
--address/--cluster/--vnet not allowed).
--vm xxxxxxxx VM within the selected cluster
to receive commands (--vdc allowed,
--cluster required).
COMMANDS TO A VIRTUAL DATA CENTER (VDC):
These options must follow the context options (if any), when you have
specified either no context options at all (to select the default VDC),
or specified only a --vdc option. Each command may have required or
optional sub-options (listed below the command but indented) that *must*
follow the command option in the command line, but *may* be specified
in any order:
--get Write a JSON view of the VDC to stdout.
--update Update following fields on this address,
completely replacing any previous value:
--name xxxxxxxx Logical name of this VDC.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this VDC.
--delete Delete this VDC and any related
resources. (RESERVED FOR FUTURE USE).
--create-address Create a new Public Address based on:
--name xxxxxxxx (Required) Logical name of the new
public address.
--domain-names xxxxxxxx Comma delimited list of domain names
associated with this address
(informational only).
--dns xxxxxxxx Comma-delimited list of IP addresses
for DNS servers to be used for outboud
DNS lookups via this address.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with the new address.
--create-cluster Create a new Cluster based on:
--name xxxxxxxx (Required) Logical name of the new
cluster.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with the new cluster.
--from-cluster xxxxxxxx Get default values for the new cluster
from the existing cluster with this
name.
--create-vnet Create a new Virtual Network (VNet)
based on:
--name xxxxxxxx (Required) Logical name of the new
virtual network.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with the new VNet.
--create-volume Create a WebDAV volume on the
storage service based on:
--name xxxxxxxx (Required) Logical name of the new
storage volume.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with the new volume.
COMMANDS TO A PUBLIC ADDRESS:
These options must follow the context options (if any), when you have
(optionally) specifed a --vdc option, and have specified an --address
option. Each command may have required or optional sub-options (listed
below the command but indented) that *must* follow the command option
in the command line, but *may* be specified in any order:
--get Write a JSON view of this public
address to stdout.
--update Update following fields on this address,
completely replacing any previous value:
--name xxxxxxxx Logical name of this address.
--domain-names xxxxxxxx Comma delimited list of domain names
associated with this address
(informational only).
--dns xxxxxxxx Comma-delimited list of IP addresses
for DNS servers to be used for outboud
DNS lookups via this address.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this address.
--delete Delete this public address and
any related resources.
COMMANDS TO A CLUSTER:
These options must follow the context options (if any), when you have
(optionally) specifed a --vdc option, and have specified a --cluster
option. Each command may have required or optional sub-options (listed
below the command but indented) that *must* follow the command option
in the command line, but *may* be specified in any order:
--get Write a JSON view of this cluster
to stdout.
--update Update following fields on this cluster,
completely replacing any previous value:
--name xxxxxxxx Logical name of this cluster.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this cluster.
--delete Delete this cluster and
any related resources.
--create-vm Create a new VM in this cluster,
based on:
--name xxxxxxxx (Required) Name of the new VM.
--from-template xxxxxxxx Clone configuration defaults from this
template.
--from-vm xxxxxxxx Clone configuration defaults from this
existing VM.
--description xxxxxxxx Human friendly description of this VM.
--type xxxxxxxx CPU type of the VM.
--os xxxxxxxx Operating system of the VM.
--cpu xxxxxxxx CPU speed (Mhz) of the VM.
--memory xxxxxxxx Main memory size (GB) of the VM.
--boot-disk xxxxxxxx Boot disk space (GB) for this VM.
--data-disk xxxxxxxx Data disk space (GB) for this VM.
--temp-disk xxxxxxxx Temporary disk space (GB) for this VM.
--params xxxxxxxx Comma-delimited name=value pairs
representing configuration parameters
used to initialize this VM.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this VM.
--deploy Cause undeployed VMs to be deployed.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--start Cause deployed VMs to be started.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--stop Cause started VMs to be stopped.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--undeploy Cause deployed (i.e. stopped) VMs
to be undeployed.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
COMMANDS TO A VIRTUAL NETWORK (VNet):
These options must follow the context options (if any), when you have
(optionally) specifed a --vdc option, and have specified a --vnet
option. Each command may have required or optional sub-options (listed
below the command but indented) that *must* follow the command option
in the command line, but *may* be specified in any order:
--get Write a JSON view of this VNet
to stdout.
--update Update following fields on this VNet,
completely replacing any previous value:
--name xxxxxxxx Logical name of this VNet.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this VNet.
--delete Delete this VNet and
any related resources.
COMMANDS TO A VOLUME:
These options must follow the context options (if any), when you have
(optionally) specifed a --vdc option, and have specified a --volume
option. Each command may have required or optional sub-options (listed
below the command but indented) that *must* follow the command option
in the command line, but *may* be specified in any order:
--get Write a JSON view of this volume
to stdout.
--update Update following fields on this volume,
completely replacing any previous value:
--name xxxxxxxx Logical name of this volume.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this volume.
--delete Delete this volume and
any related resources.
--create-snapshot Create a snapshot of this volume,
based on:
--name xxxxxxxx (Required) Logical name of the
new snapshot
COMMANDS TO A VIRTUAL MACHINE (VM):
These options must follow the context options (if any), when you have
(optionally) specifed a --vdc option, and have specified a --cluster
option and a --vm option. Each command may have required or optional
sub-options (listed below the command but indented) that *must* follow
the command option in the command line, but *may* be specified in any order:
--get Write a JSON view of this VM
to stdout.
--update Update following fields on this cluster,
completely replacing any previous value:
--name xxxxxxxx Logical name of this VM.
--description xxxxxxxx Human friendly description of this VM.
--params xxxxxxxx Comma-delimited name=value pairs
representing configuration parameters
used to initialize this VM.
--tags xxxxxxxx Comma-delimited list of tags to be
associated with this VM.
--delete Delete this VM and
any related resources.
--attach Attach this VM to a Public Address
or VNet
--address xxxxxxxx Logical name of the Public Address
to attach to (one of --address or --vnet
is requried).
--vnet xxxxxxxx Logical name of the VNet to attach to
(one of --address or --vnet is required).
Address to attach to (o
--note xxxxxxxx Note for logging to an audit trail.
--detach Detach this VM from a Public Address
or VNet
--address xxxxxxxx Logical name of the Public Address
to attach to (one of --address or --vnet
is requried).
--vnet xxxxxxxx Logical name of the VNet to attach to
(one of --address or --vnet is required).
Address to attach to (o
--note xxxxxxxx Note for logging to an audit trail.
--deploy Deploy this undeployed VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--start Start this deployed VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--stop Stop this started VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--undeploy Undeploy this stopped VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--reboot Reboot this started VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--hibernate Hibernate this started VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
--resume Resume this asleep VM.
--note xxxxxxxxxxxxxxxxx Note for logging to an audit trail.
