ssmenv

README

ssmenv-go

ssmenv provides a way to replace environment variables with AWS Systems Manager Parameter Store values.

If the value of an environment variable begins with ssm://, it will be replaced by the corresponding SSM parameter value. If no environment variable starts with ssm://, no API calls are made, and the original environment variables are returned unchanged.

In the following example, ssmenv fetches the value stored under the /some_parameter/path key, and the returned map will contain the fetched value instead of the original key.

os.Setenv("SOME_ENV", "ssm:///some_parameter/path")

awsConfig, err := awsconfig.LoadDefaultConfig(ctx)
if err != nil {
  return errors.Wrap(err, "failed to load AWS config")
}
ssmClient := ssm.NewFromConfig(awsConfig)
replacedEnv, err := ssmenv.ReplacedEnv(ctx, ssmClient, os.Environ())
if err != nil {
  return errors.Wrap(err, "failed to fetch replaced env")
}
config, err := env.ParseAsWithOptions[appconfig.Config](env.Options{
  Environment: replacedEnv,
})
if err != nil {
  return errors.Wrap(err, "failed to process config from env")
}

An example with env package:

replacedEnv, err := ssmenv.ReplacedEnv(ctx, ssmClient, os.Environ())
if err != nil {
  return errors.Wrap(err, "failed to fetch replaced env")
}
config, err := env.ParseAsWithOptions[appconfig.Config](env.Options{
  Environment: replacedEnv,
})
if err != nil {
  return errors.Wrap(err, "failed to process config from env")
}

Acknowledgements

The approach of replacing environment variable values that start with the ssm:// format was inspired by remind101/ssm-env.

The approach used by ssmenv (this library) differs from ssm-env in that it avoids passing secrets through environment variables, as this is generally not considered a best practice for security. Environment variables can sometimes be exposed in logs, error messages, or system dumps, so it's safer to handle sensitive data directly within the application.

Documentation

Overview

ssmenv provides a way to replace environment variables with AWS Systems Manager Parameter Store values. If an environment variable value starts with "ssm://", it will be replaced with the value of the SSM parameter. If no environment variable starts with "ssm://", the original environment variables are returned.

Index

• func ReplacedEnv(ctx context.Context, cli ssmClient, envs []string) (map[string]string, error)
• type GetParametersError
  • func (e GetParametersError) Error() string
  • func (e GetParametersError) Unwrap() error
• type InvalidEnvVarFormatError
  • func (e InvalidEnvVarFormatError) Error() string
• type InvalidParametersError
  • func (e InvalidParametersError) Error() string
• type NullParameterError
  • func (e NullParameterError) Error() string
• type ParameterNotFoundError
  • func (e ParameterNotFoundError) Error() string

Functions

func ReplacedEnv

func ReplacedEnv(ctx context.Context, cli ssmClient, envs []string) (map[string]string, error)

ReplacedEnv replaces environment variable values with corresponding SSM parameter values. If the value of an environment variable begins with "ssm://", it is replaced by the corresponding SSM parameter value.

`cli` is the AWS SSM client used to retrieve the parameters. `envs` is a list of environment variables in the format "KEY=VALUE", similar to what is returned by os.Environ().

If no environment variable starts with "ssm://", no API calls are made, and the original environment variables are returned unchanged.

ReplacedEnv returns a map of environment variables, where values are replaced with SSM parameter values as needed.

This function may return an error. Refer to the package's error definitions for details.

Types

type GetParametersError

type GetParametersError struct {
	// Cause contains the original error which AWS SDK returned.
	Cause error
}

GetParametersError is returned when GetParameters operation fails.

func (GetParametersError) Error

func (e GetParametersError) Error() string

func (GetParametersError) Unwrap

func (e GetParametersError) Unwrap() error

type InvalidEnvVarFormatError

type InvalidEnvVarFormatError struct {
	OriginalEnvVar string
}

InvalidEnvVarFormatError is returned when given environment variables have an invalid format.

func (InvalidEnvVarFormatError) Error

func (e InvalidEnvVarFormatError) Error() string

type InvalidParametersError

type InvalidParametersError struct {
	InvalidParameters []string
}

InvalidParametersError is returned when AWS API returns invalid parameters response.

func (InvalidParametersError) Error

func (e InvalidParametersError) Error() string

type NullParameterError

type NullParameterError struct {
}

NullParameterError is returned when AWS API returns a parameter with null name or value.

func (NullParameterError) Error

func (e NullParameterError) Error() string

type ParameterNotFoundError

type ParameterNotFoundError struct {
	Key string
}

ParameterNotFoundError is returned when the SSM parameter is not found.

func (ParameterNotFoundError) Error

func (e ParameterNotFoundError) Error() string