AWS Snowball
Developer Guide

This guide is for the Snowball Edge. If you are looking for documentation for the Snowball, see the AWS Snowball User Guide.

Using the Amazon EC2 Endpoint

Following, you'll find an overview of the Amazon Elastic Compute Cloud (Amazon EC2) endpoint, which allows you to manage your Amazon Machine Images (AMIs) and compute instances programmatically using Amazon EC2 API actions.

Specifying the Amazon EC2 endpoint as the AWS CLI Endpoint

When you use the AWS CLI to issue a command to the AWS Snowball Edge device, you can specify that the endpoint is the Amazon EC2 endpoint. You have the choice of using the HTTPS endpoint, or an unsecured HTTP endpoint, as shown following.

HTTPS secured endpoint

aws ec2 describe-instances --endpoint https://192.0.2.0:8243 --ca-bundle path/to/certificate

HTTP unsecured endpoint

>aws ec2 describe-instances --endpoint http://192.0.2.0:8008

If you use the HTTPS endpoint of 8243, your data in transit is encrypted. This encryption is ensured with a certificate that's generated by the Snowball Edge whenever it is unlocked. After you have your certificate, you can save it to a local ca-bundle.pem file. Then you can configure your AWS CLI profile to include the path to your certificate, as described following.

To associate your certificate with the Amazon EC2 endpoint

  1. Connect the Snowball Edge to power and network, and turn it on.

  2. After the device has finished unlocking, make a note of its IP address on your local network.

  3. From a terminal on your network, make sure you can ping the Snowball Edge.

  4. Run the snowballEdge get-certificate command in your terminal. For more information on this command, see Getting Your Certificate for Transferring Data.

  5. Save the output of the snowballEdge get-certificate command to a file, for example ca-bundle.pem.

  6. Run the following command from your terminal.

    aws configure set snowballEdge.ca_bundle /path/to/ca-bundle.pem

After you complete the procedure, you can run CLI commands with these local credentials, your certificate, and your specified endpoint.

Unsupported Amazon EC2 Features for Snowball Edge

Using the Amazon EC2 endpoint, you can programmatically manage your AMIs and compute instances on a Snowball Edge with Amazon EC2 API actions. However, not all features and API actions are supported for use with a Snowball Edge device.

Any features or actions not explicitly listed as supported in this guide are not supported. For example, the following Amazon EC2 actions are not supported for use with Snowball Edge:

Supported AWS CLI Commands for Amazon EC2 on a Snowball Edge

Following, you can find information about how to specify the Amazon EC2 endpoint for applicable AWS CLI commands. For information on installing and setting up the AWS CLI, including specifying what regions you want to make AWS CLI calls against, see the AWS Command Line Interface User Guide.

List of Supported Amazon EC2 AWS CLI Commands on a Snowball Edge

Following, you can find a description of the subset of AWS CLI commands and options for Amazon EC2 that are supported on Snowball Edge devices. If a command or option isn't listed following, it's not supported. You can declare some unsupported options along with a command, however, these are ignored.

  • run-instances – Launches a number of compute instances using a Snowball AMI ID for an AMI.

    Note

    It can take up to an hour and a half to launch a compute instance on a Snowball Edge, depending on the size and type of the instance.

    • --image-id – The Snowball AMI ID of the AMI, which you can get by calling describe-images. An AMI is required to launch an instance.

    • --count – Number of instances to launch. If a single number is provided, it is assumed to be the minimum to launch (defaults to 1). If a range is provided in the form min:max then the first number is interpreted as the minimum number of instances to launch and the second is interpreted as the maximum number of instances to launch.

    • --instance-type – The sbe1.xxxx instance type.

    • --user-data – The user data to make available to the instance. If you are using the AWS CLI, base64-encoding is performed for you, and you can load the text from a file. Otherwise, you must provide base64-encoded text.

    • --tag-specifications – The tags to apply to the resources during launch. You can only tag instances on launch. The specified tags are applied to all instances that are created during launch. To tag a resource after it has been created, use create-tags.

  • start-instances – Starts an sbe1.xxxx instance that you've previously stopped. All resources attached to the instance persist through starts and stops, but is erased if the instance is terminated.

    • --instance-ids – The IDs of one or more sbe1.xxxx instances that were stopped on the device.

  • stop-instances – Stops an sbe1.xxxx instance that is running. All resources attached to the instance persist through starts and stops, but is erased if the instance is terminated.

    • --instance-ids – The IDs of one or more sbe1.xxxx instances to be stopped on the device.

  • terminate-instances – Shuts down one or more instances. This operation is idempotent; if you terminate an instance more than once, each call succeeds. All resources attached to the instance persist through starts and stops, but data is erased if the instance is terminated.

    • --instance-ids – The IDs of one or more sbe1.xxxx instances to be terminated on the device. All associated data stored for those instances will be lost.

  • create-tags – Adds or overwrites one or more tags for the specified resource. Each resource can have a maximum of 50 tags. Each tag consists of a key and optional value. Tag keys must be unique for a resource. The following resources are supported:

    • AMI

    • Instance

  • describe-tags – Describes one or more of the tags for specified resource (image or instance). With this command, the following filters are supported:

    • resource-id

    • resource-type – image or instance

    • key

    • value

  • delete-tags – Deletes the specified set of tags from the specified resource (AMI or compute instance).

  • describe-instances – Describes one or more of your instances.

    • --instance-ids – The IDs of one or more sbe1.xxxx instances that were stopped on the device.

    • --page-size – The size of each page to get in the call. This value doesn't affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the device, retrieving fewer items in each call. Doing this can help prevent the calls from timing out.

    • --max-items – The total number of items to return in the command's output. If the total number of items available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command.

    • --starting-token – A token to specify where to start paginating. This token is the NextToken from a previously truncated response.

  • describe-images – Describes one or more of the images (AMIs) available to you. Images available to you are added to the Snowball Edge device during job creation.

    • --image-id – The Snowball AMI ID of the AMI.

  • describe-instance-attribute – Describes the specified attribute of the specified instance. You can specify only one attribute at a time. The following attributes are supported:

    • instanceType

    • userData

  • modify-instance-attribute – Modifies the userData attribute of the specified instance. Only the userData attribute is supported.

  • associate-address – Associates a virtual IP address with an instance for use on one of the three physical network interfaces on the device:

    • --instance-id – The ID of a single sbe1.xxxx instance.

    • --public-ip – The virtual IP address that you want to use to access your instance.

  • disassociate-address – Disassociates a virtual IP address from the instance it's associated with.

    • --public-ip – The virtual IP address that you want to disassociate with your instance.

  • describe-address – Describes one or more of your virtual IP addresses associated with the same number of sbe1.xxxx instances on your device.

    • --public-ips – One or more of the virtual IP addresses associated with your instances.

Supported Amazon EC2 API Actions

Following, you can find Amazon EC2 API operations that you can use with a Snowball Edge, with links to their descriptions in the Amazon EC2 API Reference. Amazon EC2 API calls require Signature Version 4 (SigV4) signing. If you're using the AWS CLI or an AWS SDK to make these API calls, the SigV4 signing is handled for you. Otherwise, you need to implement your own SigV4 signing solution. For more information, see Getting and Using Local Amazon S3 Credentials.