stash

Upload and sync new or modified configuration files to a cloud service.

Command:

stash sync [<file_path>|<regex>...] [flags]

Examples:

# file paths
$ stash sync config/dev/.env config/qa/.env

# regular expressions (escape \backslashes or 'quote' expressions)
$ stash sync .*\\.env$ .*\\.json$

Download and open configuration inside an editor. When the file is closed after modifications, sync with the cloud service.

Optionally set preferred editor. (default: vim)

$ export EDITOR="code"

Command:

stash edit [<file_path>...] [flags]

Examples:

# browse
$ stash edit

# file paths
$ stash edit config/dev/.env config/qa/.env

# file tags
$ stash edit -t config,dev

Download configuration files and apply optional transformations to the config. By default, the files are sent to stdout allowing the config to be piped anywhere including a new file location. The files can be restored to their original folder locations using the flag, -o file.

IMPORTANT: When restoring configuration for a service, make sure configuration is not printed anywhere or sent to logs via stdout.

Command:

stash get [<file_path>...] [flags]

Examples:

# by file paths
$ stash get config/dev/.env config/qa/.env 

# by file tags
$ stash get -t config,dev

# by cloud service
$ stash get -s s3

# restore original files
$ stash get -o file

# create new files
$ stash get >> .env

# apply data transformation
$ stash get -o json >> .env

# export environment variables
$ eval $( stash get -t dev -o terminal-export )

Configuration Outputs

Using the --output or -o flag, the stashed configuration can be downloaded, transformed or replaced, and sent to stdout. Each service supports specific outputs and file types as charted below. When the output flag is omitted, the original file data is sent to stdout.

Purge permanently deletes files stashed in a cloud service.

Command:

stash purge [<file_path>...] [flags]

Examples:

# by file names
$ stash purge config/dev/.env config/qa/.env 

# by file tags
$ stash purge -t config,dev

# by cloud service
$ stash purge -s s3

Clean deletes tracked local files to avoid secrets remaining on developer machines.

Command:

stash clean [<file_path>...] [flags]

Examples:

# by file names
$ stash clean config/dev/.env config/qa/.env 

# by file tags
$ stash clean -t config,dev

# by cloud service
$ stash clean -s s3

List displays tracked files, tags, and cloud service keys.

Command:

stash list [<file_path>...] [flags]

Examples:

# all
$ stash list

# by file names
$ stash list config/dev/.env config/qa/.env 

# by file tags
$ stash list -t config,dev

# by cloud service
$ stash list -s s3

Tags identify or group stashed files in the stash.yml catalog allowing actions to be performed against file groups.

Command:

stash tag [<file_path>...] [flags]

Examples:

# overwrite tags
$ stash tag config/dev/.env config/qa/.env -t app,non-prod

# add tag
$ stash tag -a non-prod

# delete tag
$ stash tag -d config

# add tag by tags
$ stash tag -t non-prod -a config

# add tag by service
$ stash tag -s s3 -a config

After updating Secrets Manager or Parameter Store through $ stash sync or manually in the AWS Console, the stashed values can be injected into a configuration file locally or in a running container.

Add tokens to any configuration file using ${SECRET_NAME::SECRET_KEY} for Secrets Manager or ${PARAM_PATH::PARAM_NAME} for Parameter Store.

Example config.json

{
  "db_user": "${app/dev/db::user}",
  "db_password": "${app/dev/db::password}",
}

Inject secrets from the specified stash, -s secrets-manager, into the configuration file, config.json. The inject command does not require a stash.yml catalog file.

Command:

stash inject [<file_path>...] [flags]

Examples:

$ stash inject config.json -s secrets-manager

Any field in stash.yml can be overridden when exported before using $ stash get. (use "_" to access children)

S3 Bucket Example

files:
  sample_dev__env:
    path: sample/dev/.env
    type: env
    stash: s3
    opt:
      s3_bucket: configs

$ export STASH_FILES_SAMPLE_DEV__ENV_OPT_S3_BUCKET=new-configs

Additional template files can be added to the catalog to allow environment variable expansion when getting configuration for an application. This is useful when the stash.yml file cannot be aware of all application environments during the artifact/image build step.

$ export ENV=dev
$ export VERSION=v1.0.0

files:
  template:
    path: sample/${VERSION}/${ENV}/.env
    type: env
    stash: s3
    tags:
    - config

$ stash get -t config

When syncing files, setting environment variables will override prompts.

package main

import (
	"log"

	"github.com/dabblebox/stash"
	"github.com/dabblebox/stash/component/output"
)

config, err := stash.GetMap(stash.GetOptions{})
if err != nil {
  log.Fatal(err)
}

for k, v := range config {
  log.Printf("%s=%s\n", k, v)
}

package main

import (
	"log"

	"github.com/dabblebox/stash"
	"github.com/dabblebox/stash/component/output"
)

files, err := stash.Inject(stash.InjectOptions{
  Files: []string{"config.json"}
})
if err != nil {
  log.Fatal(err)
}

for _, f := range files {
  log.Printf("%s\n", string(f.Data))
}