@lumigo/serverless-crossaccount-ssm
Version:
Serverless framework plugin to access the system and secrets managers at isolated account
127 lines (92 loc) • 3.6 kB
Markdown
# lumigo-serverless-crossaccount-ssm
[](http://www.serverless.com)
[](https://circleci.com/gh/lumigo-io/lumigo-serverless-crossaccount-ssm-plugin/tree/master)
Serverless framework plugin to access the system and secrets managers at isolated account.
Currently only the AWS provider is supported.
## Usage
**NOTE**: secrets must be deployed by the `lumigo-secure-store` repository and their values set before they can be used.
### Installing the plugin
Run `npm install` in your Serverless project.
```shell
npm install --save-dev @lumigo/serverless-crossaccount-ssm
```
If you're using the Lumigo shared scripts (ie. `utils/common_bash/defaults/deploy.sh`), ensure that all relevant `package.json` files in your project's `create_aws_resources` sub-folders include the following:
```json
"devDependencies": {
"@lumigo/serverless-crossaccount-ssm": "^1.3.4",
...
}
```
### Configuring the plugin
Add the plugin to the top of the plugins list in your `serverless.yml` file:
```yml
plugins:
- "@lumigo/serverless-crossaccount-ssm"
...
```
You will now need to provide a `custom.crossaccount-ssm` entry:
```yml
custom:
crossaccount-ssm:
enable: true
profile: PROFILE_NAME # for ssm references resolution
regions:
- us-west-2
- us-west-1 # failover replica
- us-east-1 # failover replica
#...
```
If no entry is configured, the following default configuration will be used:
```yml
custom:
crossaccount-ssm:
enable: true
profile: default
regions:
- us-east-1
```
In this case, the `default` profile must have permissions to access the secret manager or the resolution will fail.
#### Configuration Options
Key | Required | Type | Default | Description
-|-|-|-|-
`enable` | no | `Union[bool,str]` | `true` | Resolution enabling switch (if `false`, then the variable will be always resolved to the originally passed string)
`profile` | yes | `str` | `default` | AWS profile name
`regions` | yes | `List[str]` | `["us-east-1"]` | Regions with secrets replicas (including the master)
If `enable` switch is defined, it is considered `false` only if not equal to:
* `true`
* `"True"`, `"true"`
* `"Yes"`, `"yes"`
The primary region for the secret manager is Oregon (`us-west-2`), with N. California (`us-west-1`) and N. Virginia (`us-east-1`) replicating. The choice of region order for resolving secrets is up to you.
#### The 'Not-Available' marker
The secret reference will not be resolved if the secret reference includes the not-available marker `NA`, e.g. `${ssm:/aws/reference/secretsmanager/secret_NA~true}`
#### Example configuration
All variables are resolved and set through the environment during CloudFormation template generation:
```yml
service:
name: client-demo
custom:
crossaccount-ssm:
profile: PROFILE
regions:
- MASTER_REGION
- FAILOVER_REGION_1
# ...
- FAILOVER_REGION_N
provider:
name: aws
region: us-east-1
functions:
client:
description: Isolated AWS SecretsManager' secrets client
handler: ...
environment:
CLIENT_SECRET: ${ssm:/aws/reference/secretsmanager/secret~true}
package:
include:
- ...
plugins:
- "@lumigo/serverless-crossaccount-ssm"
```
## Testing your plugin changes
* Run `npm run test:all`