env-aws-params

env-aws-params is a tool that injects AWS EC2 Systems Manager (SSM) Parameter Store Key / Value pairs as Environment Variables when executing an application. It is intended to be used as a Docker Entrypoint, but can really be used to launch applications outside of Docker as well.

If no --prefix is set, the command is executed with the existing environment unchanged — env-aws-params will not contact SSM. This makes it safe to wire in as a Docker entrypoint that's only active when PARAMS_PREFIX is set.

The primary goal is to provide a way of injecting environment variables for 12 Factor applications that have their configuration defined in the SSM Parameter store. It was directly inspired by envconsul.

Installation

Pre-built binaries

Static binaries for linux/amd64, linux/arm64, and darwin/arm64 are attached to each GitHub Release.

VERSION=v1.1.0   # pick from the releases page
OS=$(uname | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

curl -fL "https://github.com/framer/env-aws-params/releases/download/${VERSION}/env-aws-params_${OS}-${ARCH}" \
  -o /usr/local/bin/env-aws-params
chmod +x /usr/local/bin/env-aws-params

Example Usage

Create parameters in Parameter Store:

aws ssm put-parameter --name /service-prefix/ENV_VAR1 --value example
aws ssm put-parameter --name /service-prefix/ENV_VAR2 --value test-value

Then use env-aws-params to have bash display the env vars it was called with:

env-aws-params --prefix /service-prefix bash -c set

The wrapped command is resolved against $PATH (so bare names like bash work); pass an absolute or relative path to skip the lookup.

If you want to include common and service specific values, --prefix can be specified multiple times:

env-aws-params --prefix /common /bin/bash -c set

To get a plaintext output of your environment variables to use with other utilities, we can use printenv:

env-aws-params --pristine --silent --prefix /service-prefix /usr/bin/printenv > ~/some-file.sh

Which will write your environment variables in plain text, for example:

# ~/some-file.sh Contents:
ENV_VAR1=example
ENV_VAR2=test-value

CLI Options

NAME:
   env-aws-params - Application entry-point that injects SSM Parameter Store values as Environment Variables

USAGE:
   env-aws-params [global options] -p prefix command [command arguments]

GLOBAL OPTIONS:
   --aws-region string                                        The AWS region to use for the Parameter Store API [$AWS_REGION]
   --profile string                                           Optional AWS profile to use for the Parameter Store API [$AWS_PROFILE]
   --prefix string, -p string [ --prefix string, -p string ]  Key prefix that is used to retrieve the environment variables - supports multiple use [$PARAMS_PREFIX]
   --pristine                                                 Only use values retrieved from Parameter Store, do not inherit the existing environment variables [$PARAMS_PRISTINE]
   --sanitize                                                 Replace invalid characters in keys to underscores [$PARAMS_SANITIZE]
   --strip                                                    Strip invalid characters in keys [$PARAMS_STRIP]
   --upcase                                                   Force keys to uppercase [$PARAMS_UPCASE]
   --debug                                                    Log additional debugging information [$PARAMS_DEBUG]
   --silent                                                   Silence all logs [$PARAMS_SILENT]
   --help, -h                                                 show help
   --version, -v                                              print the version

Exit codes

The wrapped command's exit code is passed through unchanged. env-aws-params itself uses:

• 125 — invalid usage or a Parameter Store error
• 126 — the command was found but could not be started
• 127 — the command was not found
• 128+N — the command was killed by signal N (e.g. 143 for SIGTERM)

Building from source

This project uses Go modules and requires Go 1.26.5+.

go mod download
go build