README.md

serverless-cloudformation-sub-variables

Serverless framework plugin for easily supporting AWS CloudFormation Sub function variables

Add AWS CloudFormation Fn::Sub superpowers to your serverless.yml.

This includes:

• Template parameter names e.g. ${SomeParameter}
• Resource logical IDs e.g. ${SomeResource}
• Resource attributes e.g. ${SomeResource.Attribute}
• Pseudo parameters e.g. ${AWS::Region}
• Literal variables e.g. ${!LiteralVariable}
• Sub functions with key-value maps

The trick is to use #{Something} instead of ${Something} in your serverless.yml.

The plugin, during the package command, converts all the Sub function variables after the serverless variables are referenced and resolved, but before the CloudFormation template is packaged.

As part of the conversion, the Fn::Sub wrapper is also added to the string. That is, something like #{Foo}-Bar-#{AWS::Region} is converted to {"Fn::Sub": "${Foo}-Bar-${AWS::Region}"}. If Fn::Sub is already included in the direct parent node that contains the string with Sub function variables, then the Fn::Sub wrapper is not added (this is the case when declaring Sub functions with key-value maps or when you want to be more explicit in your serverless.yml).

This means that you can turn something like this:

service: awesome-service

plugins:
  - serverless-cloudformation-sub-variables
...
resources:
...
  Resources:
    SomeResource:
      Properties:
        SomeProperty:
          Fn::Sub:
          - '#{CustomVariable}-XYZ'
          - CustomVariable:
              Fn::ImportValue: ABC-#{AWS::StackName}
  Outputs:
    MyBaseURL:
      Value: https://#{ApiGatewayRestApi}.execute-api.#{AWS::Region}.amazonaws.com/${self:provider.stage}
      Export:
        Name: MyBaseURL
...

Into something like this:

...
  "Resources": {
    "SomeResource": {
      "Properties": {
        "SomeProperty": {
          "Fn::Sub": [
            "${CustomVariable}-XYZ",
            {
              "CustomVariable": {
                "Fn::ImportValue": {
                  "Fn::Sub": "ABC-${AWS::StackName}"
                }
              }
            }
          ]
        }
      }
    }
  }
  "Outputs": {
    "MyBaseURL": {
      "Value": {
        "Fn::Sub": "https://${ApiGatewayRestApi}.execute-api.${AWS::Region}.amazonaws.com/dev"
      },
      "Export": {
        "Name": "MyBaseURL"
      }
    }
  }
...

This works with anything in your serverless.yml that ends up in the Serverless service's CloudFormation template, including the Resources and Outputs sections (and virtually every other location where Fn::Sub is supported).

Getting Started

1. Install plugin from npm:

npm install serverless-cloudformation-sub-variables

2. Add to the plugins section of your serverless.yml:

plugins:
  - serverless-cloudformation-sub-variables

3. Include strings in your serverless.yml that have Sub variables as #{Something} instead of ${Something}

More Info

Took a bit of inspiration from the following Serverless plugins, while looking for a more generic and simpler way to convert all kinds of non-custom Fn::Sub variables, anywhere in the Serverless service's CloudFormation template:

• serverless-pseudo-parameters
• serverless-cf-vars