Init

The first CLI command you may use, especially when getting started, is aegis init. This will create a main.go and aegis.yaml file in the current directory.

Note that if you already have either of these files present, the command will not replace or touch your existing files.

The contents of main.go include a short boilerplate example Aegis application with API Gateway event handling via the Router.

The aegis.yaml then includes configuration for creating an API Gateway upon deploy.

This is your basic “hello world” type example and it’s designed to get you started quickly. You need not use this if you don’t want, but often times it’s saves a few steps. You’ll likely run the command then go into the aegis.yaml file to change some names around.

Deploy

The aegis deploy command will likely be the next command you’re after. Running it anywhere there is buildable Go code (that handle Lambda events of course) as well as an aegis.yaml will result in a deployment to AWS.

This includes building your Go binary, uploading it to AWS, and creating resources in AWS.

Again, Aegis’ CLI tools and the framework package are mutually exclusive. Deploying a Lambda that handles events using the vanilla aws-lambda-go package from Amazon should work just fine. The CLI tools and framework are designed to work together of course, so you’ll get the most benefit from using both.

Upon deploying, Aegis will create an Aegis IAM role (if it doesn’t already exist and if you didn’t specify to use a different IAM role in your aegis.yaml config). It’s someone permissive by default because there’s no introspection into your code to see what you’re doing.

In the future, there is some intent for auditing and reporting back a summary of permissions. However, this command is mainly intended to be a development tool – not part of a production work flow. You might reach for other tools that let your IAM roles and other cloud resources remain under revision control. For example Terraform is a great tool in this case.

However, Aegis does consider DevSecOps, so there are some considerations around security. For example, when the deploy command runs, it will look into AWS Secret Manager in order to get sensitive values to configure in Lambda environemt variables or API Gateway stage variables.

The deploy command will also report back some helpful information to your console as it goes along creating resources.

Update

The update command is similar deploy, but it just updates the Lambda function itself.

A full deploy will set create resources and configure things in AWS. While an update will only build your Go binary, zip, and then upload to AWS Lambda.

It saves a little bit of time when you have some code changes because it doesn’t need to check for existing resources using the AWS SDK which can make a few HTTP requests.

More than likely the slowest part about deployment will be the time it takes to upload the binary. However, this command is still available if you prefer.

Secret

The aegis secret command is a very important command. It’s a lightweight wrapper around AWS Secret Manager. It will let you store and read values in AWS Secret Manager from your CLI. A nice feature about it is that by default, read, will show parts of values hidden by asterisks.

The entire point is that you don’t log or expose in the open (other people maybe looking at your screen), sensitive credentials.

If you don’t provide a key, it will display all values in a table.

Of course you can read the actual values as well if you use the full command instead of read. It just makes you think first.

You can use store to store key values. You’ll want to provide the secret name, key and then value. There are some additional flags as well with this command. You can use custom KMS keys and more.

Like every other CLI command, there is help available from the CLI.

How Aegis Uses Secrets

aegis.yaml example (partial)

api:
  name: Example Cognito Aegis API
  description: An example API with auth using Cognito
  stages:
    prod:
      name: prod
      variables:
        poolid:
          key: PoolID
          value: <cognitoExample.PoolID>
        clientid:
          key: ClientID
          value: <cognitoExample.ClientID>
          # set the above using Aegis CLI, ex. 

Back to deploy here. Remember that when deploying, there’s the aegis.yaml file. It is in here that sensitive credentials (keys) in AWS Secret Manager are referenced.

You’ll see in the Cognito example that <cognitoExample.PoolID> is used for a poolid key that is used as an API Gateway stage variable. The value for that key (and ultimately, stage variable) is pulled from AWS Secret Manager during deploy and used.

An interesting thing about API Gateway stage variables…They do not support certain special characters. AWS Lambda environment variables don’t have as many character restrictions, but stage variables can be problematic.

So what does Aegis do here? It base64 encodes the stage variables. You can decode them yourself in your code or you can use Aegis’ helpers to get the values.

Aegis has helpers and this concept of Aegis Variables which is really just a fancy way of saying, go check:

• AWS Lambda environment variables
• API Gateway stage variable
• actual environment variables

The helper tries a few places to find the variable you’re after and it will then ensure the string is base64 decoded if it was encoded at all. It works regardless.

See the Aegis Variables section for more information about the helper function and where these variables are available within your application.