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 enables you to manage your Amazon Machine Images (AMIs) and compute instances programmatically using Amazon EC2 API operations.

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 operations. However, not all features and API operations 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 sbe instance.

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

  • attach-volume – Attaches an EBS volume to a stopped instance on your device and exposes it to the instance with the specified device name. Attaching a volume to a running Amazon EC2 instance isn't supported.

    • --device value – The device name.

    • --instance-id – The ID of a target Amazon EC2 instance.

    • --volume-id value – The ID of the EBS volume.

  • 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-launch-template – Creates a launch template. A launch template contains the parameters to launch an instance. When you launch an instance using RunInstances, you can specify a launch template instead of providing the launch parameters in the request. You can create up to 100 templates per device.

    • --launch-template-name string – A name for the launch template.

    • --launch-template-data structure – The information for the launch template. The following attributes are supported:

      • ImageId

      • InstanceType

      • SecurityGroupIds

      • TagSpecifications

      • UserData

      JSON syntax:

      '{ "ImageId":"string", "InstanceType":"sbe-c.large", "SecurityGroupIds":["string", ...], "TagSpecifications":[{"ResourceType":"instance","Tags":[{"Key":"Name","Value":"Test"}, {"Key":"Stack","Value":"Gamma"}]}], "UserData":"this is my user data" }'
    • [--version-description string] – A description for the first version of the launch template.

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

  • create-launch-template-version – Creates a new version for a launch template. You can specify an existing version of a launch template from which to base the new version. Launch template versions are numbered in the order in which they are created. You can't specify, change, or replace the numbering of launch template versions. You can create up to 100 versions of each launch template.

    Specify either the launch template ID or launch template name in the request.

    • --launch-template-id string – The ID of the launch template.

    • --launch-template-name string – A name for the launch template.

    • --launch-template-data structure – The information for the launch template. The following attributes are supported:

      • ImageId

      • InstanceType

      • SecurityGroupIds

      • TagSpecifications

      • UserData

      JSON syntax:

      '{ "ImageId":"string", "InstanceType":"sbe-c.large", "SecurityGroupIds":["string", ...], "TagSpecifications":[{"ResourceType":"instance","Tags":[{"Key":"Name","Value":"Test"}, {"Key":"Stack","Value":"Gamma"}]}], "UserData":"this is my user data" }'
    • [--source-version string] – The version number of the launch template on which to base the new version. The new version inherits the same launch parameters as the source version, except for parameters that you specify in launch-template-data.

    • [--version-description string] – A description for the first version of the launch template.

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

  • 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

    • Launch template

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

  • create-volume – Creates an EBS volume that can be attached to an instance on your device.

    • [--size value] – The size of the volume in GiBs, which can be from 1 GiB to 1 TB (1000 GiBs).

    • [--snapshot-id value] – The snapshot from which to create the volume.

    • [--volume-type value] – The volume type. If no value is specified, the default is sbg1. Possible values include the following:

      • sbg1 for magnetic volumes

      • sbp1 for SSD volumes

    • [--tag-specification value – A list of tags to apply to the volume during creation.

  • delete-launch-template – Deletes a launch template. Deleting a launch template deletes all of its versions.

    Specify either the launch template ID or launch template name in the request.

    • --launch-template-id string – The ID of the launch template.

    • --launch-template-name string – A name for the launch template.

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

  • delete-launch-template-version – Deletes one or more versions of a launch template. You can't delete the default version of a launch template; you must first assign a different version as the default. If the default version is the only version for the launch template, delete the entire launch template by using the delete-launch-template command.

    Specify either the launch template ID or launch template name in the request.

    • --launch-template-id string – The ID of the launch template.

    • --launch-template-name string – A name for the launch template.

    • --versions (list) "string" "string" – The version numbers of one or more launch template versions to delete.

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

  • 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, launch template, or security group).

  • delete-volume – Deletes the specified EBS volume. The volume must be in the available state (not attached to an instance).

    • --volume-id value – The ID of the volume.

  • describe-addresses – Describes one or more of your virtual IP addresses associated with the same number of sbe 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 sbe 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-launch-templates – Describes one or more launch templates. The describe-launch-templates command is a paginated operation. You can make multiple calls to retrieve the entire dataset of results.

    Specify either the launch template IDs or launch template names in the request.

    • --launch-template-ids (list) "string" "string" – A list of IDs of the launch templates.

    • --launch-template-names (list) "string" "string" – A list of names for the launch templates.

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

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

  • describe-launch-template-versions – Describes one or more versions of a specified launch template. You can describe all versions, individual versions, or a range of versions. The describe-launch-template-versions command is a paginated operation. You can make multiple calls to retrieve the entire dataset of results.

    Specify either the launch template IDs or launch template names in the request.

    • --launch-template-id string – The ID of the launch template.

    • --launch-template-name string – A name for the launch template.

    • [--versions (list) "string" "string"] – The version numbers of one or more launch template versions to delete.

    • [--min-version string] – The version number after which to describe launch template versions.

    • [--max-version string] – The version number up to which to describe launch template versions.

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

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint

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

    The describe-security-groups command 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:

    • launch-template

    • resource-id

    • resource-type – image or instance

    • key

    • value

  • describe-volumes – Describes the specified EBS volumes.

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

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

    • [--volume-ids value] – One or more volume IDs.

  • detach-volume – Detaches an EBS volume from an instance. Detaching a volume that is attached to a running Amazon EC2 instance isn't supported.

    • [--device value] – The device name.

    • [--instance-id] – The ID of a target Amazon EC2 instance.

    • --volume-id value – The ID of the volume.

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

  • get-launch-template-data – Retrieves the configuration data of the specified instance. You can use this data to create a launch template.

  • modify-launch-template – Modifies a launch template. You can specify which version of the launch template to set as the default version. When you launch an instance without specifying a launch template version, the default version of the launch template applies.

    Specify either the launch template ID or launch template name in the request.

    • --launch-template-id string – The ID of the launch template.

    • --launch-template-name string – A name for the launch template.

    • --default-version string – The version number of the launch template to set as the default version.

    • --endpoint snowballEndpoint – A value that enables you to manage your compute instances programmatically using Amazon EC2 API operations. For more information, see Specifying the Amazon EC2 Endpoint as the AWS CLI Endpoint.

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

    • [--block-device-mappings (list)] – The block device mapping entries. The parameters DeleteOnTermination, VolumeSize, and VolumeType are supported. Boot volumes must be type sbg1.

      The JSON syntax for this command is as follows.

      { "DeviceName": "/dev/sdh", "Ebs": { "DeleteOnTermination": true|false, "VolumeSize": 100, "VolumeType": "sbp1"|"sbg1" } }
    • --launch-template structure – The launch template to use to launch the instances. Any parameters that you specify in the run-instances command override the same parameters in the launch template. You can specify either the name or ID of a launch template, but not both.

      { "LaunchTemplateId": "string", "LaunchTemplateName": "string", "Version": "string" }
    • --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 sbe 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 sbe 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 sbe instances that were stopped on the device.

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

    Note

    Shutting down an instance from within the operating system, for example by using the shutdown or reboot command, has the same effect as calling the terminate-instances command.

    • --instance-ids – The IDs of one or more sbe 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 sbe 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.

  • AttachVolume – Only volumes in the stopped state can be attached. The following request parameters are supported:

    • Device

    • InstanceId

    • VolumeId

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

  • CreateVolume – The following request parameters are supported:

    • SnapshotId

    • Size

    • VolumeType

    • TagSpecification.N

  • CreateLaunchTemplate – The following request parameters are supported:

    • ImageId

    • InstanceType

    • SecurityGroupIds

    • TagSpecifications

    • UserData

  • CreateLaunchTemplateVersion

  • CreateTags – The following request parameters are supported:

    • AMI

    • Instance

    • Launch template

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

  • DeleteLaunchTemplate

  • DeleteLaunchTemplateVersions

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

  • DeleteVolume – The following request parameters are supported:

    • VolumeId

  • DescribeAddresses

  • DescribeImages

  • DescribeInstanceAttribute – The following attributes are supported:

    • instanceType

    • userData

  • DescribeLaunchTemplates

  • DescribeLaunchTemplateVersions

  • 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

  • DescribeVolume – The following request parameters are supported:

    • MaxResults

    • NextToken

    • VolumeId.N

  • DetachVolume – Only volumes in the stopped state can be detached. The following request parameters are supported:

    • Device

    • InstanceId

    • VolumeId

  • DisassociateAddress

  • GetLaunchTemplateData

  • ModifyLaunchTemplate

  • 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