lumigo-serverless-crossaccount-ssm

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.

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:

  "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:

plugins:
  - "@lumigo/serverless-crossaccount-ssm"
  ...

You will now need to provide a custom.crossaccount-ssm entry:

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:

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:

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