README.md
1
2
3[](https://travis-ci.org/wallix/awless)
4[](https://goreportcard.com/report/github.com/wallix/awless)
5
6<img src="https://user-images.githubusercontent.com/808274/33351381-5b9a0d00-d458-11e7-91ed-cf7ada7237c1.png" alt="terminal icon" width="48"> `awless` is a powerful, innovative and small surface command line interface (CLI) to manage Amazon Web Services.
7
8[Twitter](http://twitter.com/awlessCLI) | [Wiki](https://github.com/wallix/awless/wiki) | [Changelog](https://github.com/wallix/awless/blob/master/CHANGELOG.md#readme)
9
10# Why awless
11
12`awless` stands out by having the following characteristics:
13
14- small and hierarchical set of commands
15- a simple/powerful text [templating language](https://github.com/wallix/awless/wiki/Templates) to create and **revert** fully-fledged infrastructures
16- wrapping/composing AWS API calls when necessary to enrich behaviour. Ex: ensure smart defaults, security best practices, etc.
17- local log of all your cloud modifications done through `awless` to list/revert past actions
18- sync to a local graph storage of your cloud representation
19- exploration of your cloud infrastructure and resources interrelations, **even offline** using the local graph storage
20- clearer and flexible terminal output's with: numerous formats (machine/human friendly), enriched resources's properties/relations when feasible
21- connect easily using awless' **smart SSH** to your private & public instances
22
23For more read our [FAQ](#faq) below (how `awless` compares to other tools, etc.)
24
25# Install
26
27Choose one of the following options:
28
291. On macOS, use [homebrew](http://brew.sh): `brew tap wallix/awless; brew install awless`
302. With `curl` (macOS/Linux), run: `curl https://raw.githubusercontent.com/wallix/awless/master/getawless.sh | bash`
313. Download the latest `awless` binaries (Windows/Linux/macOS) [from Github](https://github.com/wallix/awless/releases/latest)
324. If you have Golang already installed, install from the source with: `go get -u github.com/wallix/awless`
33
34If you have previously used the AWS CLI or aws-shell, you don't need to configure anything! Your config will be automatically loaded (i.e. ~/.aws/{credentials,config}) and `awless` will prompt for any missing info (more at our [getting started](https://github.com/wallix/awless/wiki/Getting-Started)).
35
36# Main features
37
38<p align="center">
39 <a href="https://raw.githubusercontent.com/wiki/wallix/awless/apng/awless-demo.png"><img src="https://raw.githubusercontent.com/wiki/wallix/awless/apng/awless-demo.png" alt="video of a few awless commands"></a>
40<br/>
41<em>Note that the video above is in <a href="https://en.wikipedia.org/wiki/APNG">APNG</a> and requires a recent browser.</em>
42</p>
43
44- **Aliasing of resources through their natural name** so you don't have to always use cryptic ids that are impossible to remember
45- `awless show` : Explore the properties, relations, dependencies of a specific resource (even offline thanks to the sync) given only a *name* (or id/arn).
46
47 $ awless show jsmith --local
48
49- `awless list` : Clear and easy listing of multi-region cloud resources (subnets, instances, users, buckets, records, etc.) on AWS EC2, IAM, S3, RDS, AutoScaling, SNS, SQS, Route53, CloudWatch, CloudFormation, Lambda, etc. Listing filters via *resources properties* or *resources tags*.
50
51 $ awless list instances --sort uptime --local
52 $ awless list users --format csv --columns name,created
53 $ awless list volumes --filter state=use --filter type=gp2
54 $ awless list volumes --tag-value Purchased
55 $ awless ls vpcs --tag-key Dept --tag-key Internal --format tsv
56 $ awless ls instances --tag Env=Production,Dept=Marketing
57 $ awless ls instances --filter state=running,type=micro --format json
58 $ awless ls s3objects --filter bucket=pdf-bucket -r us-west-2
59 $ ...
60 (see awless ls -h)
61
62- `awless run` : Create, update and delete complex infrastructures with smart defaults and sound auto-complete through awless templates.
63
64 $ awless run ~/templates/my-infra.aws
65 $ awless run https://raw.githubusercontent.com/wallix/awless-templates/master/linux_bastion.aws
66 etc.
67
68- **Hundreds of powerful CRUD CLI one-liners** integrated in the awless templating engine:
69
70 $ awless create instance -h
71 $ awless create vpc -h
72 $ awless attach policy -h
73 $ ...
74 (see awless -h)
75
76- `awless log` : Detailled and easy reporting of all the CLI template executions
77- `awless revert` : Revert of executed templates and resources creation
78- Create instances straight from a distro name. No need to know the region or AMI ;) (_free tier community bare distro only_, see `awless create instance -h`)
79
80 $ awless create instance distro=debian
81 $ awless create instance distro=coreos
82 $ awless create instance distro=redhat::7.2 type=t2.micro
83 $ awless create instance distro=debian:debian:jessie lock=true
84 $ awless create instance distro=amazonlinux:amzn2
85 etc.
86
87- Leveraging AWS `userdata` to provision instance on creation from remote (i.e http) or local scripts: `awless create instance ... userdata=/home/john/...`
88- `awless ssh` : Clean and simple SSH to public & private instances using only a name
89
90 $ awless ssh my-production-instance
91 $ awless ssh redis-prod --through jump-server
92 $ awless ssh 34.215.29.221
93 $ awless ssh db-private --private
94 $ awless ssh 172.31.77.151 --port 2222 --through my-proxy --through-port 23
95 $ ...
96 (see awless ssh -h)
97
98- `awless switch` : Switch easily between AWS accounts (i.e. profile) and regions
99
100 $ awless switch admin eu-west-2
101 $ awless switch us-west-1
102 $ awless switch mfa
103 etc.
104
105- `awless` transparently syncs cloud resources locally to a graph representation in order for the CLI to leverage data and their relations in other awless commands and in an offline manner ([more on the sync](https://github.com/wallix/awless/wiki/Getting-Started#sync))
106- `awless sync` : Explicit and manual command to fetch & store resources locally. Then query & inspect your cloud offline
107- Output listing formats either human (**default display is Markdown-compatible tables**) or machine readable (csv, tsv, json, ...): `--format`
108- `awless inspect` : Leverage **experimental** and community inspectors which are interface implementation utilities to run analysis on your cloud resources graphs
109
110 $ awless inspect -i bucket_sizer
111 (see awless inspect -h)
112
113- `awless completion` : CLI autocompletion for Unix/Linux's bash and zsh
114
115# Getting started
116
117Take the tour at [Getting Started (wiki)](https://github.com/wallix/awless/wiki/Getting-Started) or read the [introductory blog post about awless](https://medium.com/@hbbio/awless-io-a-mighty-cli-for-aws-a0d48bdb59a4).
118
119More articles:
120
121 - [Simplified user management for AWS](https://medium.com/@awlessCLI/simplified-user-management-for-aws-6f828ccab387)
122 - [InfoWorld: Production-grade deployment of WordPress](https://www.infoworld.com/article/3230547/cloud-computing/awless-tutorial-try-a-smarter-cli-for-aws.html)
123 - [Easy create & tear down of a multi-AZ CockroachDB cluster](https://github.com/wallix/awless-templates/tree/master/cockroachdb)
124 - [Deploy Vuls.io to an AWS instance and scan for vulnerabilities](https://github.com/wallix/awless-templates/tree/master/vuln_scanners)
125
126# Awards
127
128- [Top 50 Developer Tools of 2017](https://stackshare.io/posts/top-developer-tools-2017)
129- [InfoWorld Bossie Awards 2017](https://www.infoworld.com/article/3227920/cloud-computing/bossie-awards-2017-the-best-cloud-computing-software.html#slide12)
130
131# FAQ
132
133Here is a compilation of the question we often answer (thanks for asking them so that we can make things clearer!):
134
135**There are already some AWS CLIs. What is `awless` unique approach?**
136
137Three things that differentiates `awless` from other AWS CLIs:
138
139* It has its own **compiled and very simple templating language** to build AWS infrastructures.
140* Commands are made of _VERB + ENTITY [+ param=value]_ and are actually valid lines of the template language.
141* It transparently syncs to a local graph a representation of the cloud resources and their relations.
142
143Leveraging and combining the points above, `awless` lays some strong foundations for plenty of current/future features/characteristic such as:
144
145- Wrapping AWS API calls to enrich them with before/after behaviour when interacting with the cloud
146- Having a small and hierarchical set of commands to intuitively interact with AWS
147- Enriching listing of resources using the local model and relations that are not calculated with other CLIs
148- Referencing and finding resources quickly avoiding cryptic IDs in favor of names, etc.
149- Exposing in the terminal relation between resources: lineage, siblings, etc.
150- Performing local analysis of your cloud
151- Having a smart SSH to easily connect to instances
152- etc.
153
154**How do you create infrastructure with `awless`?**
155
156You build infrastructure using `template files` or `command one-liners` that get compiled and run through `awless` builtin engine. See [what the templating language looks like](https://github.com/wallix/awless-templates/blob/master/cockroachdb/cockroach_insecure_cluster.aws). Learn [more about the way templates work](https://github.com/wallix/awless/wiki/Templates)
157
158Note that all your actions against the cloud are logged. Templates are revertible/rollbackable.
159
160**How does `awless` compares to `aws-shell` or `saws`?**
161
162(Points above should also help answering this question)
163
164`aws-shell` and `saws` are directly mapped to the official AWS CLI. Their **only** objective is to make you productive and help you manage exhaustively the sheer number of AWS services, options, etc.
165
166`awless` addresses this UI/productivity concern differently: small and hierarchical set of commands; favoring enriched listing with relations showing over AWS exhaustive outputting of properties; more useful human/machine formats.
167
168The main point is that **the UI/productivity concern is just a feature of awless and not its primary or only one**, so there is much more to the tool.
169
170Also `aws-shell` and `saws` are exhaustive in their support of AWS services. `awless` is so far more infrastructure centric, with an emphasis on enriching the information about your real infrastructure. `awless` is able to add any new AWS service quickly if that fits and make sense (see wiki on how to add a new AWS service).
171
172**How does `awless` compares to Terraform?**
173
174Terraform is a great product! `awless` is much younger than Terraform and Terraform is much broader in scope.
175
176The approach is different though. When creating insfrastructure `awless`:
177
178- favors simplicity with a straight forward, compiled and simple deployment language
179- employs an all-or-nothing deployment: do not keep state, etc.
180- `awless` does provide a rollback on any ran template.
181
182**Does `awless` handles state when creating infrastructure (i.e. keep track of the changes)?**
183
184Quoting from a [logz.io/blog entry](https://logz.io/blog/terraform-ansible-puppet/): _"Terraform is an amazing tool but a major challenge is managing the state file. Whenever you apply changes to your infrastructure, the entire managed body of code and created objects are tracked in the Terraform State file (.tfstate), which can reach hundreds of thousands of lines and must be managed carefully lest you incur large merge conflicts or unwanted resource changes"_, Ofer Velich.
185
186As for now with `awless`, we have taken a different path: `awless` does not keep state of your cloud; it is more of an all-or-nothing deployment solution.
187
188Note that `awless` logs (through rich and revertable logs) all your actions against the cloud and that you can revert any template ran.
189
190# About
191
192`awless` is an open source project created by Henri Binsztok, Quentin Bourgerie, Simon Caplette and François-Xavier Aguessy at WALLIX.
193`awless` is released under the Apache License and sponsored by [Wallix](https://github.com/wallix).
194
195 Disclaimer: Awless allows for easy resource creation with your cloud provider;
196 we will not be responsible for any cloud costs incurred (even if you create a
197 million instances using awless templates).
198
199Contributors are welcome! Please head to [Contributing (wiki)](https://github.com/wallix/awless/wiki/Contributing) to learn more.
200Note that `awless` uses [triplestore](https://github.com/wallix/triplestore) another project developped at WALLIX.
201
){kind=link}
