aws-env - Secure way to handle environment variables in Docker

Forked from Droplr/aws-env

Published as a docker image

How it works

Searches for SSM Parameters in your AWS account based on the variables provided and places them in a .env file

Parameters

Environment Variables

• SSM_PATH [Required] - Complete path structure created in SSM Parameter store
• AWS_REGION [Required] - Region in which the SSM Parameters are stored
• DIRECTORY [Optional] - Directory path of the .env file. Can contain child directories. Default is /ssm. NOTE: The default cannot be changed if used in a side car configuration.
• LOG_LEVEL [Optional] - Levels such as fatal, error, warn, info, debug, or disable. Default is info
• TO_STDOUT [Optional] - (boolean) prints the parameters to stdout to be evaled. NOTE: LOG_LEVEL needs to be set to warn or above.
• AWSENV_FILENAME [Optional] - File name to write the output to, defaults to .env
• AWSENV_MAX_RETRIES [Optional] - number value for AWS SDK retries, defaults to 3
• FORMAT [Optional] - Format of the file, defaults to export
  • export

  export DB_HOST=$'mysql'
  export DB_USERNAME=$'Username'
  export DB_PASSWORD=$'SecretPassword'

  • shell

  DB_HOST='mysql'
  DB_USERNAME='Username'
  DB_PASSWORD='SecretPassword'

  • unquoted-shell

  DB_HOST=mysql
  DB_USERNAME=Username
  DB_PASSWORD=SecretPassword

  • json

  {
    "db_host": "mysql",
    "db_username": "Username",
    "db_password": "SecretPassword"
  }

  • json-nested - splits keys on _ and creates a nested json structure

  {
    "db": {
      "host": "mysql",
      "username": "Username",
      "password": "SecretPassword"
    }
  }

Command Line

• -v [Optional] - Show version and exit 0

Parameter Hierarchy

Provide the hierachy structure using the SSM_PATH environment variable

SSM_PATH: /my-app/production/prod1

This path can be completely dynamic and the hierarchy can have a maximum depth of five levels. You can define a parameter at any level of the hierarchy.
Both of the following examples are valid:
/Level-1/Level-2/Level-3/Level-4/Level-5/parameter-name
/Level-1/parameter-name

Higher levels of the hierarchy will override the lower levels if the same parameter name is found.
Example: /my-app/production/prod1/EMAIL would override the value of /my-app/EMAIL for the prod1 environment
/my-app/production/API_KEY would override the value of /my-app/API_KEY for the environment type production
/my-app/develop/test/API_KEY would override the value of /my-app/develop/API_KEY for the test environment

Add parameters to Parameter Store using hierarchy structure:

$ aws ssm put-parameter --name /my-app/DB_HOST --value "mysql" --type SecureString --key-id "alias/aws/ssm" --region ap-southeast-2
$ aws ssm put-parameter --name /my-app/production/DB_USERNAME --value "Username" --type SecureString --key-id "alias/aws/ssm" --region ap-southeast-2
$ aws ssm put-parameter --name /my-app/production/prod1/DB_PASSWORD --value "SecretPassword" --type SecureString --key-id "alias/aws/ssm" --region ap-southeast-2

Output

awsenv can output the parameters in different ways

• write to file
  • set FORMAT to export, shell, unquoted-shell, json, json-nested
  • optionally set the output directory of the file with DIRECTORY
  • optionally change the default file name from .env with AWSENV_FILENAME
• eval from a file
  • leave all optional defaults and eval the outputted /ssm/.env file. eval $(cat /ssm/.env)
• eval from stdout (for readonly filesystems)
  • set TO_STDOUT to true and eval awsenv. eval $(awsenv)
  • set LOG_LEVEL to warn or above to stop log outputs from being evaled.

Usage

Sidecar

Include base2/awsenv as a side car container

• volume mount the /ssm directory
• eval the /ssm/.env file to export the environment parameters

awsenv:
  image: base2/awsenv
  environment:
    SSM_PATH: /my-app/production/prod1
    AWS_REGION: ap-southeast-2

test:
  image: my-app
  volumes_from:
    - awsenv
  entrypoint: eval $(cat /ssm/.env)

Copy Binary

Build FROM base2/awsenv as awsenv and extract the binary

• extract the binary from the base2/awsenv image to your PATH
• run the awsenv binary in your entrypoint script

FROM base2/awsenv as awsenv

FROM debian:jessie

COPY --from=awsenv /awsenv /bin/awsenv

ENTRYPOINT awsenv && eval $(cat /ssm/.env)

Windows

Download and extract the windows binary from the release page

Invoke-WebRequest -Uri https://github.com/base2Services/aws-env/releases/download/0.3.0/aws-env_0.3.0_windows_amd64.zip -UseBasicParsing -OutFile C:\awsenv.zip
Expand-Archive C:\awsenv.zip]

Set up the environment

mkdir C:/temp
$env:DIRECTORY = "C:\temp"
$env:AWSENV_FILENAME = "override.json"
$env:SSM_PATH = "/my-app/production/prod1"
$env:AWS_REGION = "ap-southeast-2"
$env:FORMAT = "json"

Execute the binary

PS C:\> \awsenv\awsenv.exe
[INFO] 2022/02/17 04:04 Retrieving parameters in path /my-app
[INFO] 2022/02/17 04:04 Retrieving parameters in path /my-app/production
[INFO] 2022/02/17 04:04 Retrieving parameters in path /my-app/production/prod1