Using Amazon Snow Device Management to Manage Devices
Amazon Snow Device Management allows you to manage your Snow Family device and local Amazon services remotely. All Snow Family devices support Snow Device Management, and it comes installed on new devices in most Amazon Web Services 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
Topics
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 Amazon 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 Amazon Snow Family Management Console, the Snowball Edge client, the Amazon CLI, or the Snow job management API.
To choose the Snow Device Management state from the Amazon Snow Family Management Console
To choose for Snow Device Management to be installed and activated, choose Manage your Snow device remotely with Amazon OpsHub or Snowball client.
To choose for Snow Device Management to be installed but not activated, do not select Manage your Snow device remotely with Amazon 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 Amazon CLI, Snowball Edge client, or Snow job management API:
Use the
remote-management
parameter to specify the Snow Device Management state. TheINSTALLED_ONLY
value of the parameter means Snow Device Management is installed but not activated. TheINSTALLED_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-managementINSTALLED_AUTOSTART
--device-configuration'{"SnowconeDeviceConfiguration": {"WirelessConnection": {"IsWifiEnabled": false} } }'
\ --resources'{"S3Resources":[{"BucketArn":"arn:aws:s3:::bucket-name"}]}'
\ --description"Description here"
\ --address-idADID00000000-0000-0000-0000-000000000000
\ --kms-key-arnarn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\ --role-arnarn:aws:iam::000000000000:role/SnowconeImportGamma
\ --snowball-capacity-preferenceT8
\ --shipping-optionNEXT_DAY
\ --snowball-typeSNC1_HDD
\ --regionus-west-2
\
For more information, see Job Management API Reference in the Amazon 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:
Download and install the latest version of the Snowball Edge client. For more information, see Downloading and Installing the Snowball Client.
Download the manifest file and get the unlock code for the Snow Family device. For more information, see Getting Your Credentials and Tools.
Connect the Snow Family device to your local network. For more information, see Amazon Snowcone Device Specifications.
Unlock the Snow Family device. For more information, see Unlocking a device locally.
snowballEdge set-features / --remote-management-state INSTALLED_AUTOSTART / --manifest-file
JID1717d8cc-2dc9-4e68-aa46-63a3ad7927d2_manifest.bin
/ --unlock-code7c0e1-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 Amazon Web Services account from which the device was ordered, create an Amazon 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 Amazon Web Services 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 Amazon 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 Amazon OpsHub for Snow Family. For more information, see Managing Amazon services on your device.
Note
Before managing your device, make sure it is powered on, connected to your network, and can connect to the Amazon Web Services Region where it was provisioned.
Topics
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
with your own
information.user input placeholder
Command
aws snow-device-management create-task --targets
smd-fictbgr3rbcjeqa5
--commandreboot
={}
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
with your own
information.user input placeholder
Command
aws snow-device-management describe-execution \ --taskId
st-ficthmqoc2phtlef
\ --managed-device-idsmd-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 Amazon Web Services 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
with your own
information.user input placeholder
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 Amazon Web Services 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
with your own
information.user input placeholder
Command
aws snow-device-management describe-device-ec2-instances \ --managed-device-id
smd-fictbgr3rbcje111
\ --instance-idss.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
with your own
information.user input placeholder
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
with your own
information.user input placeholder
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
with the name of
the command that you're interested in.command
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
Amazon Web Services Region where the command is run, use the list-devices
command. --max-results
and --next-token
are optional. For more information, see
Using Amazon CLI pagination options
in the "Amazon Command Line Interface User Guide".
To list remote-manageable devices, use the following command. Replace each
with your own
information.user input placeholder
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 Amazon CLI pagination options
in the "Amazon 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
with your own
information.user input placeholder
Command
aws snow-device-management list-executions \ --taskId
st-ficthmqoc2phtlef
\ --stateSUCCEEDED
\ --max-results10
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 Amazon 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 Amazon CLI pagination options
in the "Amazon Command Line Interface User Guide".
To list the available resources for a device, use the following command. Replace each
with your own
information.user input placeholder
Command
aws snow-device-management list-device-resources \ --managed-device-id
smd-fictbgr3rbcje111
\ --typeAWS::EC2::Instance
--next-tokenYAQGPwAT9l3wVKaGYjt4yS34MiQLWvzcShe9oIeDJr05AT4rXSprqcqQhhBEYRfcerAp0YYbJmRT=
--max-results10
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 Amazon 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 Amazon CLI pagination options
in the "Amazon Command Line Interface User Guide".
To list tasks by status, use the following command. Replace each
with your own
information.user input placeholder
Command
aws snow-device-management list-tasks \ --state
IN_PROGRESS
\ --next-tokenK8VAMqKiP2Cf4xGkmH8GMyZrgOF8FUb+d1OKTP9+P4pUb+8PhW+6MiXh4=
\ --max-results10
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
with your own
information.
user input placeholder
Command
aws snow-device-management tag-resource \ --resource-arn
arn:aws:snow-device-management:us-west-2:123456789012:managed-device/smd-fictbgr3rbcjeqa5
\ --tagsProject=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
with your own
information.
user input placeholder
Command
aws snow-device-management untag-resources \ --resource-arn
arn:aws:snow-device-management:us-west-2:123456789012:managed-device/smd-fictbgr3rbcjeqa5
\ --tag-keysProject
Exceptions
AccessDeniedException InternalServerException ResourceNotFoundException ThrottlingException