Code Navigation

Code is the truth and uncompiled documentation is a guy chasing the truth.

Anyway the following will help you understand how the awless code is organized and to locate things more easily.

Importantly: do not see the current implementation of awless (or what is described below) as definite and permanent. Things can be moved, reduced, simplified, re-design and there is plenty of room for improvement (as long as it is test driven ;) )

Template processing

Let's say you issue the cloud command create instance name=redis-prod either from the CLI (i.e. awless create instance name=redis-prod) or from running a template file containing the actual line.

Both end up being processing the same way:

• Lexing, parsing and AST representation of this line starts in template/parser.go the bulk of it being in template/internal/ast

• Compilation and passes made on the AST in template/compile.go. Note that the compiler is cloud agnostic.

• template/params abstract logic and interfaces are used within the compiler to process incoming commands params. This package bridges the AWS incoming params and the compiler making sure no cloud logic leaks into the compiler.

• template/env defines the interfaces for the template's compile environment (i.e. cenv) and a template's running environment (i.e. renv)

• template/runner.go allows you to wrap context and hooks around a template run.

• template/template.go is where the core of it happens i.e. where the template runner delegate at some point to retrieve, load and execute the actual corresponding cloud specs (i.e. AWS drivers).

AWS specs

Within aws/spec (we call them AWS specs) are the actual AWS drivers, meaning the actual runtime implementation of each command to be run.

A spec is basically a Golang struct with some metadata (i.e. Golang struct field tags), that implements methods which either statisfy hooks and/or interfaces.

This way an AWS spec captures at the same time:

• metadata information: useful to capture all the needed AWS API info and to generate code from it.
• actual implementation and runnnable methods: useful when instantiating a struct a calling methods on it

Some of the implementations are generated code, some of them are manually written

Have a look at the user AWS spec which is quite straight forward to understand.

So within this aws/spec directory:

• all AWS cloud entities (users, instances, etc.) that awless supports and manage are represented
• each spec file (ex: subnet.go) has its corresponding test file (ex: subnet_test.go)

Importantly, within this directory there is 3 generated files:

• aws/spec/gen_cmds_defs.go: generated command and template definitions
• aws/spec/gen_inits.go: factories to build and instantiate new AWS spec
• aws/spec/gen_runs.go: each command runnable code with implemented hooks