Serverless Colocate Plugin

Colocate your Configuration and Code

Requirements:

Serverless v1.12.x or higher.
AWS provider

How it works

Colocate allows you to keep your infrastructure configuration and code in the same place. Making it easier to reason and refactor your project.

Setup

Install via npm in the root of your Serverless service:

npm install serverless-plugin-colocate --save-dev

Add the plugin to the plugins array in your Serverless serverless.yml:

plugins:
  - serverless-plugin-colocate

Configuration Options

custom:
  colocate:
    defaultInclude:         # Optional: For very edge cases where these includes don't meet your needs
      - "**/*.yml"
      - "**/*.yaml"
    defaultExclude:         # Optional: For very edge cases where these includes don't meet your needs
      - "serverless.yml"
      - "node_modules/**"
    exclude:                # Optional: Exclude additional patterns from fragment search
      - "**/goodbye.yml"

Example

Project Structure

<project_root>
- package1
  - hello.js
  - hello.yml
- package2
  - goodbye.js
  - goodbye.yml
- serverless.yml

serverless.yml

service: ServerlessColocateExample
plugins:
  - serverless-plugin-colocate
provider:
  name: aws
  stage: ${opt:stage, "Test"}
  runtime: nodejs8.10
  role: DefaultRole
resources:
  Resources:
    DefaultRole:
      Type: AWS::IAM::Role
      Properties:
        Path: /
        RoleName: ${self:service}-${self:provider.stage}
        AssumeRolePolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Principal:
                Service:
                  - lambda.amazonaws.com
              Action: sts:AssumeRole
        Policies:
          - PolicyName: ${self:service}-${self:provider.stage}
            PolicyDocument:
              Version: "2012-10-17"
              Statement:
                - Effect: Allow
                  Action:
                    - logs:CreateLogGroup
                    - logs:CreateLogStream
                    - logs:PutLogEvents
                  Resource: arn:aws:logs:${self:provider.region}:*:log-group:/aws/lambda/*:*:*

package1/hello.yml

provider:
  environment:
    HELLO_MESSAGE: Mholo
    
functions:
  Hello:
    handler: hello.handle
    events:
      - http:
          path: hello
          method: get
          cors: true
          
resources:
  Resources:
    HelloPolicy:
      Type: AWS::IAM::Policy
      DependsOn: DefaultRole
      Properties:
        PolicyName: ${self:service}-${self:provider.stage}-Hello
        PolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action:
                - s3:GetObject
              Resource:
                - arn:aws:s3:::package2/*
        Roles:
          - ${self:service}-${self:provider.stage}

package2/goodbye.yml

provider:
  environment:
    GOODBYE_MESSAGE: Hamba kakuhle
    
functions:
  Goodbye:
    handler: goodbye.handle
    events:
      - http:
          path: goodbye
          method: get
          cors: true
resources:  
  Resources:
    GoodbyePolicy:
      Type: AWS::IAM::Policy
      DependsOn: DefaultRole
      Properties:
        PolicyName: ${self:service}-${self:provider.stage}-Goodbye
        PolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action:
                - s3:GetObject
              Resource:
                - arn:aws:s3:::package1/*
        Roles:
          - ${self:service}-${self:provider.stage}

Effective serverless.yml


service: ServerlessColocateExample
plugins:
  - serverless-plugin-colocate
provider:
  name: aws
  stage: ${opt:stage, "Test"}
  runtime: nodejs8.10
  role: DefaultRole
  environment:
    HELLO_MESSAGE: Mholo
    GOODBYE_MESSAGE: Hamba kakuhle 
    
functions:
  Hello:
    handler: package1/hello.handle     
    events:
      - http:
          path: hello
          method: get
          cors: true
  Goodbye:
    handler: package2/goodbye.handle
    events:
      - http:
          path: goodbye
          method: get
          cors: true
    
resources:
  Resources:
    DefaultRole:
      Type: AWS::IAM::Role
      Properties:
        Path: /
        RoleName: ${self:service}-${self:provider.stage}
        AssumeRolePolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Principal:
                Service:
                  - lambda.amazonaws.com
              Action: sts:AssumeRole
        Policies:
          - PolicyName: ${self:service}-${self:provider.stage}
            PolicyDocument:
              Version: "2012-10-17"
              Statement:
                - Effect: Allow
                  Action:
                    - logs:CreateLogGroup
                    - logs:CreateLogStream
                    - logs:PutLogEvents
                  Resource: arn:aws:logs:${self:provider.region}:*:log-group:/aws/lambda/*:*:*
    HelloPolicy:
      Type: AWS::IAM::Policy
      DependsOn: DefaultRole
      Properties:
      PolicyName: ${self:service}-${self:provider.stage}-Hello
        PolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action:
                - s3:GetObject
              Resource:
                - arn:aws:s3:::package1/*
        Roles:
          - ${self:service}-${self:provider.stage}
    GoodbyePolicy:
      Type: AWS::IAM::Policy
      DependsOn: DefaultRole        
      Properties:
        PolicyName: ${self:service}-${self:provider.stage}-Goodbye
        PolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action:
                - s3:GetObject
              Resource:
                - arn:aws:s3:::package2/*
        Roles:
          - ${self:service}-${self:provider.stage}

The plugin will prepend the correct path to function handler: ie. in the hello.yml the handler is simply handler: hello.handle but in the effective serverless.yml the Hello function handler is handler: package1/hello.handle

Skip a specific configuration file

If you want the plugin to ignore a particular configuration file, simply add ignore: true to the root of the configuration file. This is simpler than commenting out the entire file.

ignore: true
functions:
  Hello:
    handler: hello.handle

Contribute

Help us making this plugin better and future proof.

Clone the code
Install the dependencies with npm install
Create a feature branch git checkout -b new_feature
Lint with standard npm run lint

License

This software is released under the MIT license. See the license file for more details.