Using AWS Snow Device Management to Manage Devices - AWS Snowball Edge Developer Guide

Using AWS Snow Device Management to Manage Devices

AWS Snow Device Management allows you to manage your Snow Family device and local AWS services remotely. All Snow Family devices support Snow Device Management, and it comes installed on new devices in most AWS Regions where Snow Family devices are available.

With Snow Device Management, you can perform the following tasks:

  • Create a task

  • Check task status

  • Check task metadata

  • Cancel a task

  • Check device info

  • Check Amazon EC2-compatible instance state

  • List commands and syntax

  • List remote-manageable devices

  • List task status across devices

  • List available resources

  • List tasks by status

  • List device or task tags

  • Apply tags

  • Remove tags

Choosing the Snow Device Management state when ordering a Snow Family device

When you create a job to order a Snow device, you can choose which state Snow Device Management will be in when you receive the device: installed but not activated or installed and activated. If it is installed but not activated, you will need to use AWS OpsHub or the Snowball Edge client to activate it before using it. If it is installed and activated, you can use Snow Device Management after receiving the device and connecting it to your local network. You can choose the Snow Device Management state when creating a job to order a device through the AWS Snow Family Management Console, the Snowball Edge client, the AWS CLI, or the Snow job management API.

To choose the Snow Device Management state from the AWS Snow Family Management Console
  1. To choose for Snow Device Management to be installed and activated, choose Manage your Snow device remotely with AWS OpsHub or Snowball client.

  2. To choose for Snow Device Management to be installed but not activated, do not select Manage your Snow device remotely with AWS OpsHub or Snowball client.

For more information, see Step 3: Choose your features and options in this guide.

To choose the Snow Device Management state from the AWS CLI, Snowball Edge client, or Snow job management API:
  • Use the remote-management parameter to specify the Snow Device Management state. The INSTALLED_ONLY value of the parameter means Snow Device Management is installed but not activated. The INSTALLED_AUTOSTART value of the parameter means Snow Device Management is installed and activated. If you don't specify a value for this parameter, INSTALLED_ONLY is the default value.

Example of the syntax of the remote-management parameter of the create-job command
aws snowball create-job \ --job-type IMPORT \ --remote-management INSTALLED_AUTOSTART --device-configuration '{"SnowconeDeviceConfiguration": {"WirelessConnection": {"IsWifiEnabled": false} } }' \ --resources '{"S3Resources":[{"BucketArn":"arn:aws:s3:::bucket-name"}]}' \ --description "Description here" \ --address-id ADID00000000-0000-0000-0000-000000000000 \ --kms-key-arn arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --role-arn arn:aws:iam::000000000000:role/SnowconeImportGamma \ --snowball-capacity-preference T8 \ --shipping-option NEXT_DAY \ --snowball-type SNC1_HDD \ --region us-west-2 \

For more information, see Job Management API Reference in the AWS Snowball API Reference.

Activating Snow Device Management

Follow this procedure to activate Snow Device Management using the Snowball Edge client.

Before using this procedure, do the following:

snowballEdge set-features / --remote-management-state INSTALLED_AUTOSTART / --manifest-file JID1717d8cc-2dc9-4e68-aa46-63a3ad7927d2_manifest.bin / --unlock-code 7c0e1-bab84-f7675-0a2b6-f8k33 / --endpoint https://192.0.2.0:9091

The Snowball Edge client returns the following when the command is successful.

{ "RemoteManagementState" : "INSTALLED_AUTOSTART" }

Adding permissions for Snow Device Management to an IAM role

On the AWS account from which the device was ordered, create an AWS Identity and Access Management (IAM) role, and add the following policy to the role. Then, assign the role to the IAM user who will log in to remotely manage your device with Snow Device Management. For more information, see Creating IAM roles and Creating an IAM user in your AWS account.

Policy

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "snow-device-management:ListDevices", "snow-device-management:DescribeDevice", "snow-device-management:DescribeDeviceEc2Instances", "snow-device-management:ListDeviceResources", "snow-device-management:CreateTask", "snow-device-management:ListTasks", "snow-device-management:DescribeTask", "snow-device-management:CancelTask", "snow-device-management:DescribeExecution", "snow-device-management:ListExecutions", "snow-device-management:ListTagsForResource", "snow-device-management:TagResource", "snow-device-management:UntagResource" ], "Resource": "*" } ] }

Snow Device Management CLI commands

This section describes the AWS CLI commands that you can use to manage your Snow Family devices remotely with Snow Device Management. You can also perform some remote management tasks using AWS OpsHub for Snow Family. For more information, see Managing AWS services on your device.

Note

Before managing your device, make sure it is powered on, connected to your network, and can connect to the AWS Region where it was provisioned.

Create a task

To instruct one or more target devices to perform a task, such as unlocking or rebooting, use create-task. You specify target devices by providing a list of managed device IDs with the --targets parameter, and specify the tasks to perform with the --command parameter. Only a single command can be run on a device at a time.

Supported commands:

  • unlock (no arguments)

  • reboot (no arguments)

To create a task to be run by the target devices, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management create-task --targets smd-fictbgr3rbcjeqa5 --command reboot={}

Exceptions

ValidationException ResourceNotFoundException InternalServerException ThrottlingException AccessDeniedException ServiceQuotaExceededException

Output

{ "taskId": "st-ficthmqoc2pht111", "taskArn": "arn:aws:snow-device-management:us-west-2:000000000000:task/st-cjkwhmqoc2pht111" }

Check task status

To check the status of a remote task running on one or more target devices, use the describe-execution command.

A task can have one of the following states:

  • QUEUED

  • IN_PROGRESS

  • CANCELED

  • FAILED

  • COMPLETED

  • REJECTED

  • TIMED_OUT

To check the status of a task, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management describe-execution \ --taskId st-ficthmqoc2phtlef \ --managed-device-id smd-fictqic6gcldf111

Output

{ "executionId": "1", "lastUpdatedAt": "2021-07-22T15:29:44.110000+00:00", "managedDeviceId": "smd-fictqic6gcldf111", "startedAt": "2021-07-22T15:28:53.947000+00:00", "state": "SUCCEEDED", "taskId": "st-ficthmqoc2pht111" }

Check device info

To check device-specific information, such as the device type, software version, IP addresses, and lock status, use the describe-device command. The output also includes the following:

  • lastReachedOutAt – When the device last contacted the AWS Cloud. Indicates that the device is online.

  • lastUpdatedAt – When data was last updated on the device. Indicates when the device cache was refreshed.

To check device info, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management describe-device \ --managed-device-id smd-fictqic6gcldf111

Exceptions

ValidationException ResourceNotFoundException InternalServerException ThrottlingException AccessDeniedException

Output

{ "associatedWithJob": "JID2bf11d5a-ea1e-414a-b5b1-3bf7e6a6e111", "deviceCapacities": [ { "available": 158892032000, "name": "HDD Storage", "total": 158892032000, "unit": "Byte", "used": 0 }, { "available": 0, "name": "SSD Storage", "total": 0, "unit": "Byte", "used": 0 }, { "available": 3, "name": "vCPU", "total": 3, "unit": "Number", "used": 0 }, { "available": 5368709120, "name": "Memory", "total": 5368709120, "unit": "Byte", "used": 0 }, { "available": 0, "name": "GPU", "total": 0, "unit": "Number", "used": 0 } ], "deviceState": "UNLOCKED", "deviceType": "SNC1_HDD", "lastReachedOutAt": "2021-07-23T21:21:56.120000+00:00", "lastUpdatedAt": "2021-07-23T21:21:56.120000+00:00", "managedDeviceId": "smd-fictqic6gcldf111", "managedDeviceArn": "arn:aws:snow-device-management:us-west-2:000000000000:managed-device/smd-fictqic6gcldf111" "physicalNetworkInterfaces": [ { "defaultGateway": "10.0.0.1", "ipAddress": "10.0.0.2", "ipAddressAssignment": "DHCP", "macAddress": "ab:cd:ef:12:34:56", "netmask": "255.255.252.0", "physicalConnectorType": "RJ45", "physicalNetworkInterfaceId": "s.ni-530f866d526d4b111" }, { "defaultGateway": "10.0.0.1", "ipAddress": "0.0.0.0", "ipAddressAssignment": "STATIC", "macAddress": "ab:cd:ef:12:34:57", "netmask": "0.0.0.0", "physicalConnectorType": "RJ45", "physicalNetworkInterfaceId": "s.ni-8abc787f0a6750111" } ], "software": { "installState": "NA", "installedVersion": "122", "installingVersion": "NA" }, "tags": { "Project": "PrototypeA" } }

Check Amazon EC2-compatible instance state

To check the current state of the Amazon EC2 instance, use the describe-ec2-instances command. The output is similar to that of the describe-device command, but the results are sourced from the device cache in the AWS Cloud and include a subset of the available fields.

To check the state of the Amazon EC2-compatible instance, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management describe-device-ec2-instances \ --managed-device-id smd-fictbgr3rbcje111 \ --instance-ids s.i-84fa8a27d3e15e111

Exceptions

ValidationException ResourceNotFoundException InternalServerException ThrottlingException AccessDeniedException

Output

{ "instances": [ { "instance": { "amiLaunchIndex": 0, "blockDeviceMappings": [ { "deviceName": "/dev/sda", "ebs": { "attachTime": "2021-07-23T15:25:38.719000-07:00", "deleteOnTermination": true, "status": "ATTACHED", "volumeId": "s.vol-84fa8a27d3e15e111" } } ], "cpuOptions": { "coreCount": 1, "threadsPerCore": 1 }, "createdAt": "2021-07-23T15:23:22.858000-07:00", "imageId": "s.ami-03f976c3cadaa6111", "instanceId": "s.i-84fa8a27d3e15e111", "state": { "name": "RUNNING" }, "instanceType": "snc1.micro", "privateIpAddress": "34.223.14.193", "publicIpAddress": "10.111.60.160", "rootDeviceName": "/dev/sda", "securityGroups": [ { "groupId": "s.sg-890b6b4008bdb3111", "groupName": "default" } ], "updatedAt": "2021-07-23T15:29:42.163000-07:00" }, "lastUpdatedAt": "2021-07-23T15:29:58. 071000-07:00" } ] }

Check task metadata

To check the metadata for a given task on a device, use the describe-task command. The metadata for a task includes the following items:

  • The target devices

  • The status of the task

  • When the task was created

  • When data was last updated on the device

  • When the task was completed

  • The description (if any) that was provided when the task was created

To check a task's metadata, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management describe-task \ --task-id st-ficthmqoc2pht111

Exceptions

ValidationException ResourceNotFoundException InternalServerException ThrottlingException AccessDeniedException

Output

{ "completedAt": "2021-07-22T15:29:46.758000+00:00", "createdAt": "2021-07-22T15:28:42.613000+00:00", "lastUpdatedAt": "2021-07-22T15:29:46.758000+00:00", "state": "COMPLETED", "tags": {}, "targets": [ "smd-fictbgr3rbcje111" ], "taskId": "st-ficthmqoc2pht111", "taskArn": "arn:aws:snow-device-management:us-west-2:000000000000:task/st-ficthmqoc2pht111" }

Cancel a task

To send a cancel request for a specific task, use the cancel-task command. You can cancel only tasks in the QUEUED state that have not yet run. Tasks that are already running can't be canceled.

Note

A task that you're attempting to cancel might still run if it is processed from the queue before the cancel-task command changes the task's state.

To cancel a task, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management cancel-task \ --task-id st-ficthmqoc2pht111

Exceptions

ValidationException ResourceNotFoundException InternalServerException ThrottlingException AccessDeniedException

Output

{ "taskId": "st-ficthmqoc2pht111" }

List commands and syntax

To return a list of all supported commands for the Snow Device Management API, use the help command. You can also use the help command to return detailed information about and syntax for a given command.

To list all the supported commands, use the following command.

Command

aws snow-device-management help

To return detailed information and syntax for a command, use the following command. Replace command with the name of the command that you're interested in.

Command

aws snow-device-management command help

List remote-manageable devices

To return a list of all devices on your account that have Snow Device Management enabled in the AWS Region where the command is run, use the list-devices command. --max-results and --next-token are optional. For more information, see Using AWS CLI pagination options in the "AWS Command Line Interface User Guide".

To list remote-manageable devices, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management list-devices \ --max-results 10

Exceptions

ValidationException InternalServerException ThrottlingException AccessDeniedException

Output

{ "devices": [ { "associatedWithJob": "ID2bf11d5a-ea1e-414a-b5b1-3bf7e6a6e111", "managedDeviceId": "smd-fictbgr3rbcjeqa5", "managedDeviceArn": "arn:aws:snow-device-management:us-west-2:000000000000:managed-device/smd-fictbgr3rbcje111" "tags": {} } ] }

List task status across devices

To return the status of tasks for one or more target devices, use the list-executions command. To filter the return list to show tasks that are currently in a single specific state, use the --state parameter. --max-results and --next-token are optional. For more information, see Using AWS CLI pagination options in the "AWS Command Line Interface User Guide".

A task can have one of the following states:

  • QUEUED

  • IN_PROGRESS

  • CANCELED

  • FAILED

  • COMPLETED

  • REJECTED

  • TIMED_OUT

To list task status across devices, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management list-executions \ --taskId st-ficthmqoc2phtlef \ --state SUCCEEDED \ --max-results 10

Exceptions

ValidationException InternalServerException ThrottlingException AccessDeniedException

Output

{ "executions": [ { "executionId": "1", "managedDeviceId": "smd-fictbgr3rbcje111", "state": "SUCCEEDED", "taskId": "st-ficthmqoc2pht111" } ] }

List available resources

To return a list of the AWS resources available for a device, use the list-device-resources command. To filter the list by a specific type of resource, use the --type parameter. Currently, Amazon EC2-compatible instances are the only supported resource type. --max-results and --next-token are optional. For more information, see Using AWS CLI pagination options in the "AWS Command Line Interface User Guide".

To list the available resources for a device, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management list-device-resources \ --managed-device-id smd-fictbgr3rbcje111 \ --type AWS::EC2::Instance --next-token YAQGPwAT9l3wVKaGYjt4yS34MiQLWvzcShe9oIeDJr05AT4rXSprqcqQhhBEYRfcerAp0YYbJmRT= --max-results 10

Exceptions

ValidationException InternalServerException ThrottlingException AccessDeniedException

Output

{ "resources": [ { "id": "s.i-84fa8a27d3e15e111", "resourceType": "AWS::EC2::Instance" } ] }

List device or task tags

To return a list of tags for a managed device or task, use the list-tags-for-resource command.

To list the tags for a device, use the following command. Replace the example Amazon Resource Name (ARN) with the ARN for your device.

Command

aws snow-device-management list-tags-for-resource --resource-arn arn:aws:snow-device-management:us-west-2:123456789012:managed-device/smd-fictbgr3rbcjeqa5

Exceptions

AccessDeniedException InternalServerException ResourceNotFoundException ThrottlingException

Output

{ "tags": { "Project": "PrototypeA" } }

List tasks by status

Use the list-tasks command to return a list of tasks from the devices in the AWS Region where the command is run. To filter the results by IN_PROGRESS, COMPLETED, or CANCELED status, use the --state parameter. --max-results and --next-token are optional. For more information, see Using AWS CLI pagination options in the "AWS Command Line Interface User Guide".

To list tasks by status, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management list-tasks \ --state IN_PROGRESS \ --next-token K8VAMqKiP2Cf4xGkmH8GMyZrgOF8FUb+d1OKTP9+P4pUb+8PhW+6MiXh4= \ --max-results 10

Exceptions

ValidationException InternalServerException ThrottlingException AccessDeniedException

Output

{ "tasks": [ { "state": "IN_PROGRESS", "tags": {}, "taskId": "st-ficthmqoc2phtlef", "taskArn": "arn:aws:snow-device-management:us-west-2:000000000000:task/st-ficthmqoc2phtlef" } ] }

Apply tags

To add or replace a tag for a device, or for a task on a device, use the tag-resource command. The --tags parameter accepts a comma-separated list of Key=Value pairs.

To apply tags to a device, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management tag-resource \ --resource-arn arn:aws:snow-device-management:us-west-2:123456789012:managed-device/smd-fictbgr3rbcjeqa5 \ --tags Project=PrototypeA

Exceptions

AccessDeniedException InternalServerException ResourceNotFoundException ThrottlingException

Remove tags

To remove a tag from a device, or from a task on a device, use the untag-resources command.

To remove tags from a device, use the following command. Replace each user input placeholder with your own information.

Command

aws snow-device-management untag-resources \ --resource-arn arn:aws:snow-device-management:us-west-2:123456789012:managed-device/smd-fictbgr3rbcjeqa5 \ --tag-keys Project

Exceptions

AccessDeniedException InternalServerException ResourceNotFoundException ThrottlingException