aws sysops 02 use cli

Using the AWS Command Line Interface

Reference

Command Structure in the AWS Command Line Interface

$ aws <command> <subcommand> [options and parameters]

Getting Help with the AWS CLI

To get help when using the AWS CLI, you can simply add help to the end of a command.

# examples
$ aws help
$ aws ec2 help
$ aws ec2 describe-instances help

Generating/Using CLI JSON templates

• --generate-cli-skeleton: generate a parameters template in JSON for a given command
• --cli-input-json: read parameters from a JSON file instead of typing them at the command line

Most AWS CLI commands support --generate-cli-skeleton and --cli-input-json parameters.

# test the --generate-cli-skeleton parameter
$ aws ec2 run-instances --generate-cli-skeleton

# Direct the output to a file to save the template locally
$ aws ec2 run-instances --generate-cli-skeleton> ec2runinst_full.json

Create the following template for the ec2 run-instances command

NOTE:

• Adapt parameters values to your match your set-up

ec2runinst.json

{
    "DryRun": false,
    "ImageId": "ami-060cde69",
    "KeyName": "sysops",
    "InstanceType": "t2.micro",
    "Monitoring": {
        "Enabled": true
    },
    "SubnetId": "subnet-8a2a49f0",
    "SecurityGroupIds": [
        "sg-44b92f2f"
    ]
}

NOTE:

• The DryRun parameter set to true use EC2's dry run feature, which lets you test your configuration without creating resources.

Test the template

$ aws ec2 run-instances --cli-input-json file://ec2runinst.json
# A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.

The dry run error* indicates that the JSON is formed correctly and the parameter values are valid.

Run the run-instances command again to launch an instance (see: ./ec2runinst_result.json)

Controlling Command Output from the AWS Command Line Interface

• Using the output option in the configuration file

[default]
output=json

• Using the AWS_DEFAULT_OUTPUT environment variable

$ export AWS_DEFAULT_OUTPUT="table"

• Using the --output option on the command line

$ aws swf list-domains --registration-status REGISTERED --output text

• json: (default) best for handling the output programmatically
• txt: works well with traditional Unix text processing tools, such as sed, grep, and awk
• table: human-readable

Filter the Output

Reference

The AWS CLI provides built-in output filtering capabilities with the --query option.

JSON output

$ aws ec2 describe-instances --query \
  'Reservations[*].Instances[?InstanceId==`i-02579163d7c438f10`].{
    id:InstanceId,
    zone: Placement.AvailabilityZone,
    status: State.Name
  }'

[
  [
    {
      "status": "running",
      "id": "i-02579163d7c438f10",
      "zone": "eu-central-1b"
    }
  ]
]

query param	effect
Reservations[*]	Display all reservations
Instances[?InstanceId=='i-02579163d7c438f10']	Instances with InstanceId = i-02579163d7c438f10
{id:InstanceId, ..}	Display InstanceId as id
{.., status: State.Name}	Display State.Name as status

Text output

$ aws ec2 describe-instances --query \
  'Reservations[*].Instances[?InstanceId==`i-02579163d7c438f10`].{
    id:InstanceId,
    zone: Placement.AvailabilityZone,
    status: State.Name
  }' \
  --output text

result

i-02579163d7c438f10	running	eu-central-1b

Table output

$ aws ec2 describe-instances --query \
  'Reservations[*].Instances[?InstanceId==`i-02579163d7c438f10`].{
    id:InstanceId,
    zone: Placement.AvailabilityZone,
    status: State.Name
  }' \
  --output table

result

------------------------------------
|         DescribeInstances        |
+----------------------+-----------+
|          id          |  status   |
+----------------------+-----------+
|  i-02579163d7c438f10 |  running  |
+----------------------+-----------+

Filtering the results only

Some commands also offer the possibility to use the --filter command to filter the result. Unlike --query, --filter does not allow to filter the parameters returned.

NOTE:

• --query and --filter can be used together.

$ aws ec2 describe-instances --filters `Name=instance-type,Values=t2.micro`

$ aws ec2 describe-instances \
  --filters `Name=instance-type,Values=t2.micro` \
  --query 'Reservations[*].Instances[*].[
    State.Name,
    InstanceId,
    InstanceType
  ]'

Shell scripting

Below is an example of how grep/awk can be used along with a text output from aws ec2 describe-instances command filtered with the --query parameter.

First, stop any running t2.micro instance

$ aws ec2 describe-instances \
  --query 'Reservations[*].Instances[*].[State.Name, InstanceId, InstanceType]' \
  --output text |
  awk '/running/ && /t2.micro/'|
  awk '{print $2}' |
  while read line;
    do aws ec2 stop-instances --instance-ids $line;
  done

Then, modify stopped t2.micro instances type to t2.nano

$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId, InstanceType]' --output text |
  awk '/stopped/ && /t2.micro/'|
  awk '{print $2}' |
  while read line;
   do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "t2.nano"}';
  done

Shorthand syntax

List of key/value pairs

--option key1=value1,key2=value2,key3=value3

# is equivalent to
--option '{"key1":"value1","key2":"value2","key3":"value3"}'

NOTE:

• There must be no whitespace between each comma-separated key/value pair
• Only simple type values are supported: string, number, non-nested structures

example:

$ aws dynamodb update-table --provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 --table-name MyDDBTable

# is equivalent to
$ aws dynamodb update-table --provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' --table-name MyDDBTable

List of parameters

--option value1 value2 value3

# is equivalent to
--option '[value1,value2,value3]'

NOTE:

• Values in the list are separated by a single space

example:

$ aws ec2 stop-instances --instance-ids i-1486157a i-1286157c i-ec3a7e87

# is equivalent to
$ aws ec2 stop-instances --instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]'

Mixing shorthands

Shorthands for list of key/value pairs and list of non-nested parameters can be mixed.

$ aws ec2 create-tags --resources i-1286157c --tags \
  Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3

# is equivalent to
$ aws ec2 create-tags --resources i-1286157c --tags '[
  {"Key": "My1stTag", "Value": "Value1"},
  {"Key": "My2ndTag", "Value": "Value2"},
  {"Key": "My3rdTag", "Value": "Value3"}
]'

Pagination

Reference

AWS CLI also support pagination for commands that can return a large list of items.

• --page-size Specify a smaller page size (default: 1000)

• --max-items Retrieve fewer items

• --starting-token The output can include a NextToken that you can pass in a subsequent command to retrieve the next set of items NOTE: The value of the token varies per service

example:

$ aws s3api list-objects --bucket my-bucket \
  --max-items 100 --starting-token None___100
{
    "NextToken": "None___200",
    "Contents": [
...