base2/awsenv repository overview

⁠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.
• FORMAT [Optional] - Format of the .env file.
  • unset

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

  Copy
  • shell

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

  Copy
  • unquoted-shell

  DB_HOST=mysql
  DB_USERNAME=Username
  DB_PASSWORD=SecretPassword
  

  Copy

⁠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

• to .env file
  • set FORMAT to shell, unquoted-shell
  • optionally set the output directory of the .env file with DIRECTORY
• eval from the .env 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)