goss is a tool for managing AWS SSM parameters from the CLI. It was mainly developed to manage batches of secrets / parameters stored in local env files for application and infrastructure deployment.
Contents
Installation
Using go get
To install use go get with or without -u to have goss installed in your $GOBIN.
go get -u github.com/kevinglasson/gossTo remove after installing with go get run the following command - this will NOT remove the source code from $GOPATH/src/...
go clean -i github.com/kevinglasson/gossPre-built binaries
Download the appropriate binary for your system from the releases page.
Authentication
Manual
Authentication with AWS is pretty standard as this uses the AWS go SDK. More information can be found here. The gist of it is:
A region must be set in one of these ways:
- Set the
AWS_REGIONenvironment variable to the default Region - Set the
AWS_SDK_LOAD_CONFIGenvironment variable to true to get the Region value from the config file in the.aws/config
The places that the SDK looks for credentials are:
- Environment vairables
- Shared credentials file
Using aws-vault
It is advised to use goss in conjuction with aws-vault so that your credentials are stored encrypted locally and you just inject them each time you run goss. E.g. to run with your 'prod' profile:
aws-vault exec prod -- gossIt may also be useful to alias this command in some useful way so that it isn't so painful to write out every time!
alias gprod='aws-vault exec prod -- goss'If you are going to run multiple goss commands in a session you can start a shell that holds your credentials with:
# This will put your AWS credentials / region etc. into the environment
aws-vault exec prod -- bash
# Now proceed to use goss without the aws-vault prefix
goss list -p /Usage
goss is used to interact with the AWS SSM Parameter Store in a
variety of helpful ways.
You can interact in bulk through the 'import' sub-command to import parameters
directly from a local file.
You can also interact with paths individually to list, put and delete
parameters.
Usage:
goss [command]
Available Commands:
completion Generate completion script
delete Delete parameters
env Load parameters into the environment and run a command
help Help about any command
import Import parameters from a file
list List parameters
put Put a parameter
Flags:
-h, --help help for goss
--json output as json
Use "goss [command] --help" for more information about a command.List
List all parameters at a given path, by default the output is a table with a subset of all of the fields AWS returns (the important ones).
- Parameters can be output as a JSON using the
--jsonflag which facilitates interaction with other CLI tools such as jq. - Parameters are returned encrypted by default, use the
-dflag to have them decrypted. - Parameters in sub-paths of the specified path are not returned by default, use the
-rparameter to recursively list the parameters.
Default
goss list -p /dev/test-env -r+------------------------+--------------------------------------+---------+----------------------+
| NAME | VALUE | VERSION | LAST MOD |
+------------------------+--------------------------------------+---------+----------------------+
| /dev/test-env/COMMENT | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:10Z |
| /dev/test-env/MORE | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:10Z |
| /dev/test-env/MiXeD | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:09Z |
| /dev/test-env/UPPER | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:09Z |
| /dev/test-env/lower | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:09Z |
| /dev/test-env/oddChars | AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...¨ | 1 | 2020-09-19T03:35:10Z |
+------------------------+--------------------------------------+---------+----------------------+JSON
goss list -p /dev/test-env -r --json[
{
"ARN": "arn:aws:ssm:ap-southeast-2:XXXXXXXXXXXX:parameter/dev/test-env/COMMENT",
"DataType": "text",
"LastModifiedDate": "2020-09-19T03:35:10.111Z",
"Name": "/dev/test-env/COMMENT",
"Selector": null,
"SourceResult": null,
"Type": "SecureString",
"Value": "AQICAHhEgSOjHIIiYIkJp/zSBm7c5cy7...",
"Version": 1
},
//...
]
Put
Put a single named parameter into the store. Note that the name, -n is the full path to the parameter.
goss put -n /test/param -v somevalue -t SecureStringDelete
Delete a single named parameter from the store. Note that the name, -n is the full path to the parameter.
goss delete -n /test/paramObligatory fancy jq pipe
Just some fanciness showing interop with other Unix tools, such as the popular jq. This will use goss to list the parameters in the store, output as json, filter to the names and pass them to goss again to delete.
goss list -p / --json | jq '.[].Name' | xargs -n1 -- goss delete -nImport
Import allows reading a file into the parameter store.
- All parameters from the file must be stored as the same type i.e. String or SecretString etc.
- Multiple file formats are supported through the
--formatwhich is by default set todotenv. Other supported formats includejson,tomlandyaml. See the table below for an overview. - Only flat data structures are supported currently
File format support
| File format | Currently supported |
|---|---|
| dotenv | yes |
| json | yes |
| toml | yes |
| yaml | yes |
An example command using the default dotenv import type.
goss import -f test.env -p /envs/dev -t SecureStringAn example using a toml file
goss import -f test.toml -p /envs/dev -t SecureString --format tomlWhy?
I made this tool because although chamber is an excellent tool - it uses viper underneath and the problem with viper is that the keys are CASE INSENSITIVE which for me was unacceptable. So I decided to roll-my-own using the wonderful koanf library to manage the deserialisation of various config files.