From e1ebf57add72e8678cd5c21db879ee24aa41193a Mon Sep 17 00:00:00 2001 From: subash adhikari Date: Mon, 6 Feb 2023 17:27:44 +1100 Subject: [PATCH] update readme (#22) --- README.md | 110 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 70 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index ab40a5d..ca28649 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ secret: 2. Use `safebox` CLI tool to deploy your configuration. ```bash -$ safebox deploy --stage --config path/to/safebox.yml --prompt missing +$ safebox deploy --stage --config path/to/safebox.yml --prompt="missing" ``` You can then run list command to view the pushed configurations. @@ -62,44 +62,9 @@ The variables under 1. `defaults` is deployed with path prefix of `//` 1. `shared` is deployed with path prefix of `//shared/` -### Config File +### CLI Reference -Following is the configuration file will all possible options: - -```yaml -service: my-service -provider: secrets-manager # ssm OR secrets-manager -prefix: "/custom/prefix/{{.stage}}/" # Optional. Defaults to ///. Prefix all parameters. Does not apply for shared - -stacks: # Outputs from cloudformation stacks that needs to be interpolated. - - some-cloudformation-stack - -config: - defaults: # Default parameters. Can be overwritten in different environments. - DB_NAME: my-database - DB_HOST: 3200 - KEY_VALUE_SECRET: '{"hello": "world"}' # JSON body can be passed when provider is secrets-manager. This will create key value secret - production: # If keys are deployed to production stage, its value will be overwritten by following - DB_NAME: my-production-database - shared: # shared configuartions deployed under //shared/ path - DB_TABLE: "table-{{.stage}}" - -secret: - defaults: - DB_PASSWORD: "secret database password" # Value in quote is deployed as description of the ssm parameter. -``` - -**Variables available for interpolation** -- stage - Stage used for deployment -- service - Name of service as configured in the config file -- account - AWS Account number -- region - AWS Region - -If using `stacks` then the outputs of that Cloudformation stack is also available for interpolation. - -### CLI - -Following is all options available in `safebox` CLI. +Following are all options available in `safebox` CLI. ```bash A Fast and Flexible secret manager built with love by adikari in Go. @@ -133,17 +98,82 @@ Use "safebox [command] --help" for more information about a command. set -euo pipefail echo "📦 deploying configs to ssm" -yarn safebox deploy --stage $STAGE # ensures all configs are deployed. throws error if ay configs are missings +safebox deploy --stage $STAGE # ensures all configs are deployed. throws error if ay configs are missings -configs=$(yarn safebox export --stage $STAGE) +configs=$(safebox export --stage $STAGE) CONFIG1=$(echo "$configs" | jq -r ".CONFIG1") CONFIG2=$(echo "$configs" | jq -r '.CONFIG2') echo $CONFIG1 echo $CONFIG2 +``` + +### Generating dotenv files + +This is quite handy when your build process or application requires configuration in a dotenv file. The command reads all your configs defined in `safebox.yml` and outputs the dotenv file. + +```bash +safebox export --stage --format="dotenv" --output-file=".env" +``` + +### Replacing existing configuration + +To replace the configuration simply update the value in the `safebox.yml` file and redeploy. +To replace the existing secrets run the following command +```bash +safebox deploy --stage --prompt="all" +``` + +This will display a prompt with the secret and its existing values. You can press enter to retain the old value for secrets that you don't want to update. +For the secret that you want to replace, remove the old value from the prompt then provide the new value. + +### Deploy new configuration + +To deploy the new configuration, simply add the new key value in `safebox.yml` +To deploy new secret value, run the following command + +```bash +safebox deploy --stage --prompt="missing" +``` + +The missing flag will only prompt you for the new secrets. + +### Configuration File Reference + +Following is the configuration file will all possible options: + +```yaml +service: my-service +provider: secrets-manager # ssm OR secrets-manager +prefix: "/custom/prefix/{{.stage}}/" # Optional. Defaults to ///. Prefix all parameters. Does not apply for shared + +stacks: # Outputs from cloudformation stacks that needs to be interpolated. + - some-cloudformation-stack + +config: + defaults: # Default parameters. Can be overwritten in different environments. + DB_NAME: my-database + DB_HOST: 3200 + KEY_VALUE_SECRET: '{"hello": "world"}' # JSON body can be passed when provider is secrets-manager. This will create key value secret + production: # If keys are deployed to production stage, its value will be overwritten by following + DB_NAME: my-production-database + shared: # shared configuartions deployed under //shared/ path + DB_TABLE: "table-{{.stage}}" + +secret: + defaults: + DB_PASSWORD: "secret database password" # Value in quote is deployed as description of the ssm parameter. ``` +**Variables available for interpolation** +- stage - Stage used for deployment +- service - Name of service as configured in the config file +- account - AWS Account number +- region - AWS Region + +If using `stacks` then the outputs of that Cloudformation stack is also available for interpolation. + ### Release 1. Update version number [npm/package.json](https://github.com/monebag/safebox/blob/main/npm/package.json).