Launching a VM Instance Using AWS CLI

This flow and the code snippets in this section are for Linux or Mac OS X. If you are using Windows, you can use the Windows Subsystem for Linux and use the bash shell (where you will be in Ubuntu Linux).

A comprehensive set of example bash scripts for automating the AWS CLI, and a Terraform configuration, are provided at https://github.com/nvidia/ngc-examples/ . You can download the scripts and modify them to meet your requirements. The code examples that follow use similar environment variables and structure as the scripts.

Setting Up Environment Variables

Set up the following environment variables which can be used in the commands for launching the VM instance:

Security Group ID (NVAWS_SG_ID)

The Security Group ID is used as part of the instance creation process. Once created the Group ID can be looked up in the AWS Console, or retrieved by name with the following snippet, and stored in the $NVAWS_SG_ID environment variable.

NVAWS_SG_NAME='my-sg'
NVAWS_SG_ID=$(aws ec2 describe-security-groups --group-name "$NVAWS_SG_NAME" | jq .SecurityGroups[0].GroupId | sed 's/\"//g') && echo NVAWS_SG_ID=$NVAWS_SG_ID

Image ID (NVAWS_IMAGE_ID)

The following snippet will list the current "NVIDIA Volta Deep Learning AMI" Image ID, and stored in the $NVAWS_IMAGE_ID environment variable.

NVAWS_IMAGE_NAME='NVIDIA Volta Deep Learning AMI'
NVAWS_IMAGE_ID=$(aws ec2 describe-images --filters "Name=name,Values=$NVAWS_IMAGE_NAME" | jq .Images[0].ImageId | sed 's/\"//g') && echo NVAWS_IMAGE_ID=$NVAWS_IMAGE_ID

Other Environment Variables

Set up other env variables as follows, using your information:

NVAWS_KEYNAME=my-key-pair
NVAWS_KEYPATH=~/.ssh/
NVAWS_REGION=us-west-2
NVAWS_INSTANCE_TYPE=p3.2xlarge
NVAWS_EBS_GB=32
NVAWS_NAME_TAG='My Volta 1GPU'

Be sure to set a unique NVAWS_NAME_TAG for each instance you launch.

Launching Your VM Instance

Launch the instance and capture the resulting JSON:
NVAWS_LAUNCH_JSON=$(aws ec2 run-instances --image-id $NVAWS_IMAGE_ID \
  --instance-type $NVAWS_INSTANCE_TYPE \
  --region $NVAWS_REGION \
  --key-name $NVAWS_KEYNAME \
  --security-group-ids $NVAWS_SG_ID \
  --block-device-mapping
 "[{\"DeviceName\":\"/dev/sda1\",\"Ebs\":{\"VolumeSize\":$NVAWS_EBS_GB}}]" \
  --tag-specifications
 "ResourceType=instance,Tags=[{Key=Name,Value=$NVAWS_NAME_TAG}]")
NVAWS_INSTANCE_ID=$(echo $NVAWS_LAUNCH_JSON | jq .Instances[0].InstanceId | sed 's/\"//g') && echo NVAWS_INSTANCE_ID=$NVAWS_INSTANCE_ID

The resulting Instance ID is stored in the NVAWS_INSTANCE_ID environment variable.

The launch process can take several minutes once a machine is available, and can be watched in the AWS Console Instances page or with the CLI using:

aws ec2 describe-instance-status --instance-id $NVAWS_INSTANCE_ID | jq '.InstanceStatuses[0].InstanceState.Name + " " + .InstanceStatuses[0].SystemStatus.Status'

Once the instance is "running initializing", you will be able to get the Public DNS name with:

NVAWS_DNS=$(aws ec2 describe-instances --instance-id $NVAWS_INSTANCE_ID | jq '.Reservations[0].Instances[0].PublicDnsName' | sed 's/\"//g') && \  echo NVAWS_DNS=$NVAWS_DNS

Connecting To Your VM Instance

SSH should work shortly after the instance reaches "running ok".

If started with CLI snippets and environment variables above, the command to SSH to your instance is:

ssh -i $NVAWS_KEYPATH/$NVAWS_KEYNAME.pem ubuntu@$NVAWS_DNS

Otherwise use your .pem key filename and the Public DNS name from the AWS Console to connect:

ssh -i my-key-pair.pem ubuntu@public-dns-name

If these instructions for SSH login do not work, see the AWS Connect to Your Linux Instance documentation for additional information.

When logging into your VM instance using SSH, you are prompted for your NGC API Key. If you supply the API Key at the prompt, the VM will automatically log you into the NGC container registry so that you can run containers from the registry. You can choose not to supply the API Key at the prompt and still log in to the instance. You can then log in later to the NGC container registry (see Logging in to the NGC Container Registry) .

Starting, Stopping, and Terminating Your VM Instance

Once you are done with your instance you can stop (to be started again later) or terminate (delete) it. Refer to the Instance Lifecycle in the AWS documentation for more information.

Stop:

aws ec2 stop-instances --instance-ids $NVAWS_INSTANCE_ID

Start:

aws ec2 start-instances --instance-ids $NVAWS_INSTANCE_ID

Terminate:

aws ec2 terminate-instances --instance-ids $NVAWS_INSTANCE_ID