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 can 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.

  • 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.

  • authorize-security-group-egress – Adds one or more egress rules to a security group for use with a Snowball Edge device. Specifically, this action permits instances to send traffic to one or more destination IPv4 CIDR address ranges. For more information, see Security Groups in Snowball Edge Devices.

    • --group-id value – The ID of the security group

    • [--ip-permissions value] – One or more sets of IP permissions.

  • authorize-security-group-ingress – Adds one or more ingress rules to a security group. When calling authorize-security-group-ingress, you must specify a value either for group-name or group-id.

    • [--group-name value] – The name of the security group.

    • [--group-id value] – The ID of the security group

    • [--ip-permissions value] – One or more sets of IP permissions.

    • [--protocol value] The IP protocol. Possible values are tcp, udp, and icmp. The --port argument is required unless the "all protocols" value is specified (-1).

    • [--port value] – For TCP or UDP, the range of ports to allow. This value can be a single integer or a range (minimum–maximum).

      For ICMP, a single integer or a range (type-code) in which type represents the ICMP type number and code represents the ICMP code number. A value of -1 indicates all ICMP codes for all ICMP types. A value of -1 just for type indicates all ICMP codes for the specified ICMP type.

    • [--cidr value] – The CIDR IP range.

  • 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

    • Security group

  • create-security-group – Creates a security group on your Snowball Edge. You can create up to 50 security groups. When you create a security group, you specify a friendly name of your choice:

    • --group-name value – The name of the security group.

    • --description value – A description of the security group. This is informational only. This value can be up to 255 characters in length.

  • delete-security-group – Deletes a security group.

    If you attempt to delete a security group that is associated with an instance, or is referenced by another security group, the operation fails with DependencyViolation.

    • --group-name value – The name of the security group.

    • --description value – A description of the security group. This is informational only. This value can be up to 255 characters in length.

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

  • 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.

  • 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

  • describe-instances – Describes one or more of your instances. The response returns any security groups that are assigned to the 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, 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 value from a previously truncated response.

  • describe-security-groups – Describes one or more of your security groups.

    describe-security-groups is a paginated operation. You can issue multiple API calls to retrieve the entire data set of results.

    • [--group-name value] – The name of the security group.

    • [--group-id value] – The ID of the security group.

    • [--page-size value] – The size of each page to get in the AWS service call. This size doesn't affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the AWS service, retrieving fewer items in each call. This approach can help prevent the AWS service calls from timing out. For usage examples, see Pagination in the AWS Command Line Interface User Guide.

    • [--max-items value] – 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, NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. Don't use the NextToken response element directly outside of the AWS CLI. For usage examples, see Pagination in the AWS Command Line Interface User Guide.

    • [--starting-token value] – A token to specify where to start paginating. This token is the NextToken value from a previously truncated response. For usage examples, see Pagination in the AWS Command Line Interface User Guide.

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

    • resource-id

    • resource-type – image or instance

    • key

    • value

  • 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 from your instance.

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

  • revoke-security-group-egress – Removes one or more egress rules from a security group:

    • [--group-id value] – The ID of the security group

    • [--ip-permissions value] – One or more sets of IP permissions.

  • revoke-security-group-ingress – Revokes one or more ingress rules to a security group. When calling revoke-security-group-ingress, you must specify a value for either group-name or group-id.

    • [--group-name value] – The name of the security group.

    • [--group-id value] – The ID of the security group.

    • [--ip-permissions value] – One or more sets of IP permissions.

    • [--protocol value] The IP protocol. Possible values are tcp, udp, and icmp. The --port argument is required unless the "all protocols" value is specified (-1).

    • [--port value] – For TCP or UDP, the range of ports to allow. A single integer or a range (minimum–maximum).

      For ICMP, a single integer or a range (type-code) in which type represents the ICMP type number and code represents the ICMP code number. A value of -1 indicates all ICMP codes for all ICMP types. A value of -1 just for type indicates all ICMP codes for the specified ICMP type.

    • [--cidr value] – The CIDR IP range.

  • run-instances – Launches a number of compute instances by 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.

    • --security-group-ids – One or more security group IDs. You can create a security group using CreateSecurityGroup. If no value is provided, the ID for the default security group is assigned to created instances.

  • start-instances – Starts an sbe1.xxxx instance that you've previously stopped. All resources attached to the instance persist through starts and stops, but are 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 are 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.

Supported Amazon EC2 API Operations

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.

  • AssociateAddress – Associates an Elastic IP address with an instance or a network interface.

  • AuthorizeSecurityGroupEgress – Adds one or more egress rules to a security group for use with a Snowball Edge device. Specifically, this action permits instances to send traffic to one or more destination IPv4 CIDR address ranges.

  • AuthorizeSecurityGroupIngress – Adds one or more ingress rules to a security group. When calling AuthorizeSecurityGroupIngress, you must specify a value either for GroupName or GroupId.

  • CreateTags – The following resources are supported:

    • AMI

    • Instance

    • Security group

  • CreateSecurityGroup – Creates a security group on your Snowball Edge. You can create up to 50 security groups. When you create a security group, you specify a friendly name of your choice.

  • DeleteSecurityGroup – Deletes a security group. If you attempt to delete a security group that is associated with an instance, or is referenced by another security group, the operation fails with DependencyViolation.

  • DeleteTags – Deletes the specified set of tags from the specified set of resources.

  • DescribeAddresses

  • DescribeImages

  • DescribeInstanceAttribute – The following attributes are supported:

    • instanceType

    • userData

  • DescribeInstances

  • DescribeSecurityGroups – Describes one or more of your security groups. DescribeSecurityGroups is a paginated operation. You can issue multiple API calls to retrieve the entire data set of results.

  • DescribeTags – With this command, the following filters are supported:

    • resource-id

    • resource-type – AMI or compute instance only

    • key

    • value

  • DisassociateAddress

  • ModifyInstanceAttribute – Only the userData attribute is supported.

  • RevokeSecurityGroupEgress – Removes one or more egress rules from a security group.

  • RevokeSecurityGroupIngress – Revokes one or more ingress rules to a security group. When calling RevokeSecurityGroupIngress, you must specify a value either for group-name or group-id.

  • RunInstances

    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.

  • StartInstances

  • StopInstances – Resources associated with a stopped instance persist. You can terminate the instance to free up these resources. However, any associated data is deleted.

  • TerminateInstances