npm package: @lumigo/serverless-crossaccount-ssm
Description: Serverless framework plugin to access the system and secrets managers at isolated account
Author: Lumigo LTD
Latest version: 1.3.6

# lumigo-serverless-crossaccount-ssm

[![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)
![Version](https://img.shields.io/badge/version-1.0.2-green.svg)
[![CircleCI](https://circleci.com/gh/lumigo-io/lumigo-serverless-crossaccount-ssm-plugin/tree/master.svg?style=svg&circle-token=40489e02416815ff9e6a37f8574e303368dfe03a)](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`