Skip to content

Getting Started

Jump to bottom Edit New page
Simon Caplette edited this page Jan 31, 2018 · 31 revisions

This document will guide you through a tour of awless features:

Setup your AWS account with awless

If you have no prior set up (AWS, ...) and nothing in your env, you can just run an awless command:

awless list vpcs

awless will detect a first install. It will take care of the configuration, prompting you for your tokens AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and region. Your can get them from the IAM console.

You can do it differently if needed.

Basically you need an AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY exported in your environment.

Also if you have previously used aws CLI or aws-shell, you don't need to do anything! Your credentials will be automatically loaded by awless from the ~/.aws/credentials folder.

For more options, see Installation (wiki).

Changing AWS region or profile

You can change your profile and/or region with:

awless switch us-west-1       # configure awless to use us-west-1 region
awless switch admin           # configure awless to use the admin profile

awless switch admin us-west-1 # both at once
awless switch us-west-1 admin # order does not matter

... or ephemerally using the global flags:

awless list subnets -p default    # ephemeral change to default profile
awless list subnets -r eu-west-3  # ephemeral change to region eu-west-3

To know your current awless profile/region you can view awless config or use the -v verbose flag on any command.

In details, in order to define your AWS region and profile at runtime awless use the following in that order of precedence:

  1. Global awless CLI flags --aws-region, --aws-profile (or shortcuts -r, -p)
  2. AWS env variables AWS_DEFAULT_REGION/AWS_DEFAULT_PROFILE
  3. Region embedded in a profile through AWS shared config files (i.e. ~/.aws/{credentials,config})
  4. profile/region from awless config (updated through awless switch)

For instance, flag -r overwrites AWS_DEFAULT_REGION which overwrites awless config.

Setup shell autocompletion

Awless has commands, subcommands and flag completion. It becomes really useful for CRUD one-liners when managing resources, for example.

Read the wiki page for setting up autocompletion for bash or zsh.

First awless commands

awless works by performing commands, which query either the AWS services or a local snapshot of the cloud services.

Listing resources

You can list various resources:

awless list buckets
awless list instances --sort uptime

# ls is an alias for list
awless ls users --format csv             
awless ls roles --sort name,id
awless ls vpcs --format=json

Listing resources by default performs queries directly to AWS.

On your first install of awless, the cloud resources (for which you have AWS read access) were synchronized locally. So if you want, you can also query offline this local snapshot by adding the --local flag:

awless list subnets --local

(You can get more info on how the sync operates in the sync section of this documentation)

Use awless list, awless list -h or awless help list to see all resources that can be listed.

Listing and filtering via properties

When dealing with long lists of resources you can filter by property with the --filter flag like this:

awless list volumes --filter state=in-use --filter type=gp2

# or with a csv notation
awless list instances --filter state=running,type=t2.micro 

# when dealing with a name with spaces use double quotes
awless list instances --filter "private ip"=127.0.0.1

For instance, you could list all storage objects in a given bucket using only local data with:

awless --local ls s3objects --filter bucket=pdf-bucket

also

awless ls buckets --filter id=static-website

...or fetching Route53 records for a specific zone:

awless ls records --filter name=io

When possible (i.e. AWS API) this filters are sent to AWS to optimize resource fetching (less throttling, etc...) so that we bring back only useful resources. Otherwise, resources are fetched in bulk and filtering is done locally.

Note also that filters:

  1. ignore case when matching
  2. will match when result string contains the search string (ex: --filter state=Run will match instances with state running)

Listing and filtering via tags

Listing also support searching resources with tags (mostly AWS EC2 resources have tags):

awless list instances --tag Env=Production,Dept=Marketing
awless list volumes --tag-value Purchased
awless list vpcs --tag-key Dept --tag-key Internal
awless list vpcs --tag-key Dept,Internal

Note that tags:

  1. are case sensitive on both the key and the value

Showing resources

awless show is quite useful to get a good overview on a resource and to show where it stands in your cloud.

The show command needs only one arg which is a reference to a resource. It first searches the resource by id. If found it stops. Otherwise it looks up by name and then arn. To force a lookup by name prefix the reference with a '@'.

# show instance via its id: relations to subnets, vpcs, region, ...
awless show i-34vgbh23jn        

# show bucket forcing search by name: objects, siblings, ...
awless show @my-bucket          

# show user using local data: user's policies, ...
# snappy! will not refetch but work with the local graph
awless show admin-user --local

Basically awless show tries to maximize the info nicely on your terminal for a given resource.

Creating, updating and deleting resources

awless provides a powerful template system to interact with cloud infrastructures.

awless templates can be used through oneliner shortcut commands:

Using the help:

awless create                # show what resource can be created
awless delete -h             # same as above
awless create instance -h    # show required & extra params for instance creation

Then:

awless create instance       # will start a prompt for any missing params
awless delete subnet id=subnet-12345678
awless attach volume id=vol-12345678 instance=i-12345678

Check out more examples at Examples

You can also run an awless template from a predefined template file with:

awless run awless-templates/create_instance_ssh.aws

In each case, the CLI guides you through any running of a template (file template or one-liner) so you always have the opportunity to confirm or quit.

For instance, you will get id/name autocompletion to fill in any missing info.

Note that you can get inspired with our in progress repo of pre-existing templates

You can also run remote templates with:

awless run repo:create_instance_ssh.aws       # from official awless repo
awless run http://mydomain.com/mytemplate.aws # from a remote url

Also more info on the design of the templates is at Templates (wiki).

Log and revert template commands

To list a detailed account of the last actions you have run on your cloud:

awless log

Each awless command that changes the cloud infrastructure is associated with an unique id referencing the (un)successful actions. Using this id you can revert a executed template with:

awless revert 01B89ZY529E5D7WKDTQHFC0RPA

The CLI will guide you through a revert action and you will have the chance to confirm or quit.

Sync

awless automatically syncs (autosync) the remote cloud resources locally as RDF graphs.

Basically the autosync runs after resource creation, deletion and before you want to explore resources (awless show)

More precisely, the sync automatically runs:

  • post awless first install
  • post the awless run command
  • post the template one-liners awless create, awless delete, etc.
  • pre the awless show command

Note that the sync is not running during the listing of resources.

You can disable autosync with awless config set autosync false

You can also manually run a sync with awless sync. The command output will show in details what has been done. Add the -e extra verbose flag to see what it is doing behind the scenes.

Note that you can configure the sync per service and per resource. For example:

# disable sync for queue service (sqs) entirely
awless config set aws.queue.sync false 

# enable sync for s3object resources in the storage service (s3)
awless config set aws.storage.s3object.sync true 

# disable sync for load balancing resources (elbv2) in the infra service
awless config set aws.infra.loadbalancer.sync false 
awless config set aws.infra.targetgroup.sync false 
awless config set aws.infra.listener.sync false

Smart SSH

awless ssh provides an easy way to connect via SSH to public and private instances via the instance's name, without needing either the AWS ID, public IP, key name, or account username.

If your local host has a SSH client installed, awless will use it to connect. Otherwise, it falls back on the Golang embedded SSH client (ex: some Windows machines or minimalistic cloud instances that pilot awless).

When connecting to an instance through SSH the key and default SSH user are deduced automatically by awless.

So you can simply and directly ssh to a public instance with:

awless ssh my-instance-name  # with a name
awless ssh i-abcd1234        # with an id

You can still specify an SSH user or a SSH key though with:

awless ssh ubuntu@i-abcd1234
awless ssh -i ~/.ssh/mykey ubuntu@i-abcd1234

Also useful, you can print the SSH config or SSH CLI for any valid instances with:

awless ssh my-instance --print-config >> ~/.ssh/config
# or 
awless ssh my-instance --print-cli

Using the --through flag you can connect to a private instance through a public one - both residing in the same VPC - (i.e. internally using ssh ProxyCommand). Note that for that effect, you need a valid SSH key on both instances. Example:

awless ssh my-private-instance --through my-public-instance

Resolving AMIs identifier

Amazon Machine Images are region specific. It sometimes becomes impractical to dynamically resolve a specific image distribution or architecture.

To alleviate this issue, the command awless search images -h fetches bares & public & available AMIs info as JSON against a specific image query.

It is mostly used to render some templates that need to be AMI-specification-agnostic in the region.

The command uses a simple image query string that will be resolved against your current region (i.e. the one from your current CLI session). The image query string format is as follows:

owner:distro:variant:arch:virtualization:store

With this format:

  • only the owner field is mandatory.
  • owner value has to be from the list of supported ones (ex: canonical, redhat, debian, amazonlinux, suselinux, microsoftserver).

Run the help on the command to know exactly which owners are supported.

Here are some usage examples:

# output JSON info on official ubuntu AMIS
awless search images canonical   

# output the unique AMI id (latest sorted by AMIs creation date) on Ubuntu Trusty 
awless search images canonical::trusty  --id-only  

# output all the AMI ids of RedHat 6.8 distribution
awless search images redhat::6.8  --ids-only  

# output all AMI ids for debian with a storage type of instance-store (i.e. not ebs but transient AWS instance storage) 
awless search images debian:::::instance-store --ids-only

When you want to create instance with a specific distribution and you want your template to be valid across regions, you can do:

awless create instance type=t2.macro image=$(awless search images redhat::7.3 --id-only)

Aliasing

When it makes sense we provide the concept of alias. Cloud resources ids can be a bit cryptic. An alias is just an already existing name of a resource. Given an alias we resolve the proper resource id. For instance:

awless ssh my-instance         # ssh to the instance by name. awless resolves its id
awless delete id=@my-instance  # delete an instance using its name

Inspectors

Inspectors are small CLI utilities that leverage awless graph modeling of cloud resources. Basically an inspector is a program that implements the following interface:

type Inspector interface {
    Inspect(*graph.Graph) error
    Print(io.Writer)
    Name() string            # name of the inspector
}

Using awless cloud resources local synchronisation functionality, you can analyse your data offline (i.e: on your local graphs). There are some built-in inspectors that serve as examples: pricer, bucket_sizer, port_scanner, etc...

For example, you would run the bucket_sizer inspector with:

$ awless inspect -i bucket_sizer --local
Bucket           Object count    S3 total storage
--------         ----------      -----------------
my-first-bucket     4            0.0035 Gb
my-other-bucket     1            3.4946 Gb
third-bucket        422          0.0000 Gb
fouth-bucket        1000         0.0077 Gb
                                 3.5059 Gb

Note that - as a upcoming feature - using the local infrastructure snapshots (automatically synced), we will be able to run inspectors through time very fast (i.e: all done locally)! For instance, in this case you would see your bucket sizing evolve!

Add a custom footer

awless wiki

User Manual

Contributing

Clone this wiki locally