Serverless Discovery Plugin

NPM

npm license CircleCI Coveralls

A serverless plugin to register AWS micro-service endpoints with a discovery service at serverless deploy or serverless remove time, or to pass the output to a JavaScript function for further processing.

See the Ad Astra Serverless Discovery project for more information.

Usage

Install

$ > yarn add serverless-discovery-plugin

$ > npm install serverless-discovery-plugin

Configuration

plugins:
  - serverless-discovery-plugin

custom:
  discovery:
    discoveryServiceUri: 'https://abcdefghij.execute-api.us-east-1.amazonaws.com/dev'
    accessKeyId: ${env:DISCOVERY_KEY_ID} # optional, if separate keys are needed
    secretAccessKey: ${env:DISCOVERY_SECRET_ACCESS_KEY} # optional, if separate keys are needed
    deployHandler: scripts/deploy.handler # Same syntax as you already know
    removeHandler: scripts/remove.handler # Same syntax as you already know
    file: .build/stack.toml # toml, yaml, yml, and json format is available

Authentication

If the service under development is deployed into the same account as the discovery service, serverless-discovery-plugin will use the same credentials from AWS environment variables at pipeline run time to authenticate to the discovery service for registration purposes. Otherwise, you can designate explicit credentials that should be used in the configuration.

Handler

Based on the configuration above the plugin will search for a file scripts/deploy.js with the following content:

// async declaration here implicitly returns a Promise<void>
async function handler (data, serverless, options) {
  console.log('Received Stack Output', data)
}

module.exports = { handler }

File Formats

Just name your file with a .json, .toml, .yaml, or .yml extension, and the plugin will take care of formatting your output. Please make sure the location where you want to save the file exists!

License

Feel free to use the code, it's released using the MIT license.

Contribution

You are more than welcome to contribute to this project! 😘 🙆

To make sure you have a pleasant experience, please read the code of conduct. It outlines core values and believes and will make working together a happier experience.

Example

The plugins works fine with serverless functions, as well as when using custom CloudFormation resources. The following example configuration will deploy an AWS Lambda function, API Gateway, SQS Queue, IAM User with AccessKey and SecretKey, and a static value:

Serverless.yml

service: sls-stack-output-example

plugins:
  - serverless-discovery-plugin

package:
  exclude:
    - node_modules/**

custom:
  discovery:
    discoveryServiceUri: 'https://DiscoveryServiceID.execute-api.us-east-1.amazonaws.com/prod'
    deployHandler: scripts/output.handler
    file: .build/stack.toml

provider:
  name: aws
  runtime: nodejs6.10

functions:
  example:
    handler: functions/example.handle
    events:
      - http:
          path: example
          method: get
          cors: true

resources:
  Resources:
    ExampleQueue:
      Type: AWS::SQS::Queue
      Properties:
        QueueName: example-queue
    ExampleUser:
      Type: "AWS::IAM::User"
      Properties:
        UserName: example-user
        Policies:
          - PolicyName: ExampleUserSQSPolicy
            PolicyDocument:
              Version: '2012-10-17'
              Statement:
                - Effect: "Allow"
                  Action:
                    - sqs:SendMessage
                  Resource:
                    - {"Fn::Join": [":", ["arn:aws:sqs:*", {"Ref": "AWS::AccountId"}, "example-queue"]]}
    ExampleUserKey:
      Type: AWS::IAM::AccessKey
      Properties:
        UserName:
          Ref: ExampleUser
  Outputs:
    ExampleUserKey:
      Value:
        Ref: ExampleUserKey
    ExampleUserSecret:
      Value: {"Fn::GetAtt": ["ExampleUserKey", "SecretAccessKey"]}
    ExampleStaticValue:
      Value: example-static-value

Stack Output

Console

Serverless: Stack update finished...
Service Information
service: sls-stack-output-example
stage: dev
region: us-east-1
stack: sls-stack-output-example-dev
api keys:
  None
endpoints:
  GET - https://APIGatewayID.execute-api.us-east-1.amazonaws.com/dev/example
...
-------------------
Serverless: Registering service endpoint with service: https://DiscoveryServiceID.execute-api.us-east-1.amazonaws.com/prod
Serverless: Stack Output saved to file: test/system/lib/outputs.json

TOML

ExampleUserSecret = "YourUserSecretKey"
ExampleUserKey = "YourUserAccessKey"
ExampleLambdaFunctionQualifiedArn = "arn:aws:lambda:us-east-1:AccountID:function:sls-stack-output-example-dev-example:9"
ExampleStaticValue = "example-static-value"
ServiceEndpoint = "https://APIGatewayID.execute-api.us-east-1.amazonaws.com/dev"
ServerlessDeploymentBucketName = "sls-stack-output-example-serverlessdeploymentbuck-BucketID"

YAML

ExampleUserSecret: YourUserSecretKey
ExampleUserKey: YourUserAccessKey
ExampleLambdaFunctionQualifiedArn: 'arn:aws:lambda:us-east-1:AccountID:function:sls-stack-output-example-dev-example:9'
ExampleStaticValue: example-static-value
ServiceEndpoint: 'https://APIGatewayID.execute-api.us-east-1.amazonaws.com/dev'
ServerlessDeploymentBucketName: sls-stack-output-example-serverlessdeploymentbuck-BucketID

JSON

{
  "ExampleUserSecret": "YourUserSecretKey",
  "ExampleUserKey": "YourUserAccessKey",
  "ExampleLambdaFunctionQualifiedArn": "arn:aws:lambda:us-east-1:AccountID:function:sls-stack-output-example-dev-example:9",
  "ExampleStaticValue": "example-static-value",
  "ServiceEndpoint": "https://APIGatewayID.execute-api.us-east-1.amazonaws.com/dev",
  "ServerlessDeploymentBucketName": "sls-stack-output-example-serverlessdeploymentbuck-BucketID"
}