Amazon EC2 API

Qstack offers an Amazon EC2™-compatible API for users to control compute resources via compliant 3rd party tools.

Qstack’s API controls are compatible with the official Amazon EC2™ CLI tools. Qstack does not implement the full Amazon EC2™ API stack, but rather a relevant subset specifically related to manage "Compute" transactions.

This reference outlines which commands are available with which parameters, and how these commands are to be used.

Operations and options not referenced in this document are considered unsupported in Qstack. Any help text available when running the commands may not be relevant, as it is not provided as part of Qstack

The latest version of the command line tools is available on https://aws.amazon.com/developertools/ .

A list of currently supported EC2 API commands

AMIs

 

ec2-create-image

Create an image (template) from an instance. The instance must be stopped.

Usage:
ec2-create-image <instance> -n <name>
Options:
  • --name, -n <name>, name to assign the image.

  • --description, -d <description>, description of the image.

Unsupported options:
  • --no-reboot

  • --block-device-mapping, -b //not actually tested, but seems useless in the context.

 

ec2-describe-image-attribute

List attributes for the given image(s). Currently only the launch attribute is supported.

Usage:
ec2-describe-image-attribute <image> -l
Options:
  • --launch-permission, -l, permission to create an instance from the image.

Unsupported options:
  • --block-device-mapping, -B

  • --product-code, -p

  • --kernel

  • --ramdisk

  • --sriov

 

ec2-deregister

Deregister an image.

Usage:
ec2-deregister <image>
 

ec2-describe-images

List images (templates) including ISO images. If an image name is provided attributes for that image are listed.

Usage:
ec2-describe-images [<image>]
Options:
  • <image>, list all attributes for a specific image.

  • --all, -a, list all images which the account has access to.

  • --executable, -x <user>, list all images which the specified user can launch.

  • --owner, -o <user>, maps to --executable, -x.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

Qstack will ignore Amazon options, e.g. specifying -o aws-marketplace will yield the same results as the -a option. QstackHybrid has configured lists of Amazon images which will be returned unless either -o self or -x all is specified, in which case the request is redirected to the Amazon cloud leaf.

 

ec2-modify-image-attribute

Alter an attribute for a given image. Currently on the launch attribute is supported.

Usage:
ec2-modify-image-attribute <image> -l [-a <entity>| -r <entity>]
Options:
  • --launch-permission, -l, permission to create an instance from the image.

  • --add, -a <entity>, add the permission to the specified account.

  • --remove, -r <entity>, remove the permission from the account.

Unsupported options:
  • --product-code, -p

 

ec2-register

Register an image (template).

Usage:
ec2-register <manifest> --name <name>
Options:
  • --name, -n <name>, name to assign the image.

  • --architecture, -a <architecture>, either i386 or x86_64.

  • --description, -d <description>, description of the image

  • --snapshot, -s <snapshot>, snapshot to use for creating the image.

Unsupported options:

  • --kernel

  • --ramdisk

  • --sriov

  • --virtualization-type

  • --block-device-mapping, -b

 

ec2-reset-image-attribute

Reset the launch permission for a given image.

Usage:
ec2-reset-image-attribute <image> -l
Options:
  • --launch-permission, -l, permission to create an instance from the image.

 

Instances

 

ec2-describe-instance-attribute

Describes instance attributes.

Options:
  • --type, --instance-type, the type of the instance.

 Unsupported options:
  • --block-device-mapping, -b

  • --disable-api-termination

  • --instance-initiated-shutdown-behavior

  • --kernel

  • --ramdisk

  • --root-device-name

  • --user-data

  • --group-id, -g

  • --source-dest-check

  • --product-code, -p

  • --ebs-optimized

  • --sriov

 

ec2-describe-instances

Describes one or more of your instances. If you specify one or more instance IDs,

EC2 returns information only for those instances.

Usage:
ec2-describe-instances [<instance>...]
Options:
  • <instance>, provide one or more instance names to list only information regarding those instances.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 
 

ec2-get-password

Retrieves the encrypted administrator password for an instance.

The password is encrypted using public key of the key pair that was specified when launching the instance.

Upon retrieval the corresponding private key needs to be provided to decrypt the password.

Usage:
ec2-get-password instance -k <key-file>
Options:
  • --priv-launch-key, -k, private key file for decrypting the password.

 

ec2-modify-instance-attribute

Modify instance attributes. Can be used among other things to change the instance type as is shown in the usage example below.

Usage:
ec2-modify-instance-attribute <instance> [-t t1.nano]
Options:
  • -t --instance-type, The type of instance as defined within the availability zones, default scheme is [Tier.Size]

  • --user-data, User data to apply to an instance.

Unsupported options:
  • -b, --block-device-mapping

  • --disable-api-termination

  • --ebs-optimized

  • -g, --group-id

  • --instance-initiated-shutdown-behavior

  • --ramdisk

  • --source-dest-check

  • --sriov

 

ec2-reboot-instances

Reboots the instances specified as long as they are in started state.

Usage:
ec2-reboot-instances <instances>
 

ec2-run-instances

Launches the specified number of instances from the specified template. When you launch an instance, it enters the pending state. When the instance is ready it enters the running state.

To check the state of your instance, use the ec2-describe-instances command.

If no security group is specified when launching an instance Qstack uses the default security group.

Usage:
ec2-run-instances <image>
Options:
  • --availability-zone, -z <zone>, Zone in which to launch the instance. The specified image must be availabe in this zone.

  • --key, -k <key>, the keypair which should be used for connecting to the instance.

  • --user-data, -d <data> Specifies the user data to be made available to the instance(s) in this reservation.

  • --user-data-file, -f <data-file> Specifies the file containing user data to be made available to the instance(s) in this reservation.

  • --block-device-mapping, -b <mapping>, allows for mapping a block device into the instance at creation time. The mapping has the form <device>=<volume>.

  • --group, -g <group>, security group to which the instance shall be connected. Only one security group can be associated with an instance, and that choice can not be modified at a later time.

  • --instance-count, -n <number>, the number of the specific instance to launch.

  • --type, -t <type>, the type of instance. Must be one of the predefined types.

  • --private-ip-address <ip-address>, the private ip address for the instance, must be within the defined subnet.

  • --subnet, -s <subnet>, the subnet to which the instance should be assigned.

Unsupported options:
  • --monitor, -m

  • --disable-api-termination

  • --instance-initiated-shutdown-behavior

  • --kernel

  • --ramdisk

  • --license-pool

  • --placement-group

  • --iam-profile, -p

  • --client-token

  • --tenancy

  • --ebs-optimized

  • --network-attachment, -a

  • --secondary-private-ip-address

  • --associate-public-ip-address

ec2-start-instances

Starts stopped instance(s).

Usage: 
ec2-start-instances <instances>
 

ec2-stop-instances

Stops started instance(s)

Usage: 
ec2-stop-instances <instances>
Options:

--force, -f, Stops the image even if it is not started.

 

ec2-terminate-instances

Shuts down and removes instances. This operation is idempotent; if you terminate an instance more than once, each call succeeds.

Usage: 
ec2-terminate-instances <instances>
 

Regions and Zones

 

ec2-describe-availability-zones

List the availability of zones and their status. If no zone name is specified then all zones in all regions, which the current user has access to, are listed. The information contains the availability, the state and the region for each listed zone.

Usage:
ec2-describe-availability-zones [<zone>]
Options:
  • <zone>, List all attributes for the zone.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given, e.g. -F region-name=region1 -F region-name=region2 -F state=available The avilable filters are: message Information about the Availability Zone.

    region-name
    The region for the Availability Zone (for example, us-east-1).
    state
    The state of the Availability Zone
    Valid values: available | impaired | unavailable
    zone-name
    The name of the zone.

This command is only available in Qstack Hybrid

 

Key Pairs

 

ec2-create-keypair

Creates a 1024-bit RSA key pair with the specified name. Qstack stores the public key and displays the private key for you to save to a file.

The private key is returned as an unencrypted PEM encoded PKCS#8 private key.

Usage:
ec2-create-keypair <key>
Error Messages:
  • If a key with the specified name already exists, an error of the type Client.InvalidKeyPair. Duplicate is returned.

 

ec2-delete-keypair

Deletes the specified key pair, by removing the public key from Qstack.

Usage:
ec2-delete-keypair <key>
 

ec2-describe-keypairs

Describes one or more of your key pairs.

Usage:
ec2-describe-keypairs
Options:
  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.
 

ec2-import-keypair

Imports the public key from an RSA key pair that the user has created with a third-party tool.

Usage:
ec2-import-keypair <key> -f <key-file>
Options:
  • --public-key-file, -f <key-file>, the public key file to upload.

 

Elastic IP Addresses

 

c2-allocate-address

Allocates a new public IP address for the account.

Usage:
ec2-allocate-address

Unsupported options:
  • --domain, -d

Error messages:

  • If the IP pool is exhausted the user receives: Service.InsufficientAddressCapacity: Not enough available addresses to satisfy your minimum request

 

ec2-associate-address

Associates an allocated IP address to an instance.

Usage:
ec2-associate-address <IP> -i <instance>
Mandatory options:
  • --instance, -i <instance> , Instance with which to associate the IP.

Unsupported options:
  • --network-interface, -n

  • --allocation-id, -a

  • --private-ip-address, -p

  • --allow-reassociation

 

ec2-describe-addresses

List IP addresses that are allocated to the account/project.

Usage:

ec2-describe-addresses
Options:
  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 

ec2-disassociate-address

Disassociate an IP address from the instance it is currently attached to.

Usage:

ec2-disassociate-address <IP>
 

ec2-release-address

Release an IP address previously allocated to the account.

Usage:
ec2-release-address <IP>
Options:
  • --instance, -i <instance> , Instance with which to associate the IP.

Unsupported options:
  • --network-interface, -n

  • --allocation-id, -a

  • --private-ip-address, -p

  • --allow-reassociation

 

Security Groups (firewalls)

 

ec2-authorize

Authorizes ingress or egress permissions to a security group.

Usage:
ec2-authorize <group> <options>
Options:
  • --egress, to specify that this is an egress rule.

  • --protocol, -P <protocol>, can be one of tcp, udp and icmp.

  • --port-range, -p <port-range>, range of tcp or udp ports.

  • --icmp-type-code, -t <type>:<code>, icmp type and codes to enable. --protocol must be set to icmp.

  • --cidr, -s <cidr>, subnet for ingress or egress authorization. Defaults to 0.0.0.0/0.

  • --source-subnet <subnet>, subnet for ingress rules.

  • --dest-subnet <subnet>, subnet for egress rules.

Unsupported options:
  • --source-or-dest-group, -o

  • --source-or-dest-group-user, -u

 

ec2-create-group

Create a new security group for the account, the security group will be created within the region that user is currently connected to.

Usage:
ec2-create-group <group> -d <description>
Options:
  • --description, -d <description>, a description of the group.

Unsupported options:
  • --vpc, -c

 

ec2-delete-group

Deletes a security group from the account.

Usage:
ec2-delete-group <group>
Error Messages:
  • If a security group which has an instance attached to it is attempted to be removed a Client.InvalidGroup.InUse is returned. Please note that a terminated instance which was attached to a security group counts as attached until the instance has been expunged.

 

ec2-describe-group

Gives information on the security groups available to the user.

Usage:
ec2-describe-group [<group>]
Options:
  • <group>, display information about a specific group.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 

ec2-revoke

Revoke ingress or egress permissions from a security group.

Usage:
ec2-revoke <group> <options>

 

See ec2-authorize for options.

 

Elastic Block Store

 

ec2-attach-volume

Attaches a volume to a running or stopped instance and exposes it to the instance with the specified device name.

Usage:
ec2-attach-volume <volume> -i <instance> -d <device>
Options:
  • --instance, -i <instance>, the instance to which the volume should be attached.

  • --device, -d <device>, the device name which the volume shall be assigned to inside the VM.

 

ec2-create-snapshot

Create a snapshot from a volume.

Usage:
ec2-create-snapshot <volume>
Options:
  • --description, -d <description>, a description for the snapshot.

 

ec2-create-volume

Creates a volume that can be attached to any instance in the same Availability Zone. If a snapshot is specified then a new volume is created from the snapshot.

Usage:
ec2-create-volume <options> -z <zone>
Options:
  • --size, -s <size>, the size of the volume. This can not be combined with specifying a snapshot.

  • --snapshot <snapshot>, a snapshot from which the volume is to be created. Can not be combined with the --size option.

  • --availability-zone, -z <zone>, the zone in which the volume is to be created.

Unsupported options:
  • --type, -t <type>

  • --encrypted

 

ec2-delete-snapshot

Delete a snapshot.

Usage:
ec2-delete-snapshot <snapshot>
 

ec2-delete-volume

Deletes the specified volume. The volume must be in the available state (not attached to an instance).

Usage:
ec2-delete-volume <volume>
 

ec2-describe-snapshots

Gives information on the snapshots available to the user.

Usage:
ec2-describe-snapshots [<snapshots...>]
Options:
  • <snapshots>, show information about specific snapshots.

  • --all, -a, show all snapshots.

  • --owner, -o <owner>, show all snapshots owned by a specific user.

  • --restorable-by, -r <user>, show all snapshots which can be restored from by a specific user.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 

ec2-describe-volumes

Shows descriptive information for one or more of volumes in a specified region.

Usage:
ec2-describe-volumes [<volumes...>]
Options:
  • <volumes>, select which volumes the information should be displayed for.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 

ec2-describe-volumes

Shows descriptive information for one or more of volumes in a specified region.

Usage:
ec2-describe-volumes [<volumes...>]
Options:
  • <volumes>, select which volumes the information should be displayed for.

  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 

ec2-detach-volume

Detach a volume from an instance.

Usage:
ec2-detach-volume <volume>
Options:
  • --instance, -i <instance>, instance from which to detach the volumex.

  • --device, -d <device>, device on the instance on which the volume is attached.

  • --force, -f, force a detach. 

 

Tags

 

ec2-create-tags

 Creates a new metadata tag for the specified resource id('s).

Usage:
ec2-create-tags <ResourceType>:<ResourceID> --tag key=value
Options:
  • --tag, -t <tag>, tags to add to the resource. Many tags may be added.

Examples:
ec2-create-tags instance:i-1234abcd --tag tags=tag
ec2-create-tags image:qmi-1234abcd --tag tags=tag

If a tag is supplied without enclosing the key:value a generic tag is applied containing the key:value as values.

 

ec2-delete-tags

Deletes metadata tags for specified resource id('s).

Usage:
ec2-delete-tags <resources> --tag <tag> [--tag <tag>...]
Options:
  • --tag, -t <tag>, tags to add to the resource. Many tags may be added.

 

ec2-describe-tags

Displays all tags belonging to resources on the account.

Usage:
ec2-describe-tags
Options:
  • --filter, -F <name-of-filter>=<value-of-filter>, filter the results. Multiple filters may be given.

 
  • No labels
Breyta takkanum