Serverless plugin for Kumologica

Serverless plugin that allows deployment of kumologica flow into aws account.

• Dependencies
• Installation
  • New Kumologica flow: using template
  • Existing Kumologica flow: changes to serverless.yaml
• Development
• How It Works
• Usage
  • IAM Policy
  • Test cases
• Examples
  • Most Basic example
  • Use of Lambda's Environment variables
  • Explicit IAM Role statements
• License

Dependencies

• NPM
• Serverless
• Kumologica Designer

Installation

New Kumologica flow: using template

1. Use kumologica serverless template

Create new kumologica project with hello world flow using serverless template:

sls create --template-url https://github.com/KumologicaHQ/serverless-templates/tree/master/helloworld-api --path helloworld-api

This will create new directory: helloworld-api with following files:

• hello-world-flow.json
• package.json
• serverless.yml

2. Install kumologica-serverless-plugin

sls plugin install --name kumologica-serverless-plugin

Flow is ready to edit with kumologica designer and use by serverless.

Existing Kumologica flow: changes to serverless.yaml

1. Add plugin to serverless.yml

plugins:
  - kumologica-serverless-plugin

2. Install kumologica-serverless-plugin

sls plugin install --name kumologica-serverless-plugin

3. Update functions

Replace function name with the flow file name (without .json extension). For example for flow: demo-flow.json the functions declaration will look like:

functions:
  demo-flow: # name of your flow file (without .json extension)
 

Development

Download Kumologica Designer to edit flow, implement business logic and unit tests.

This is the only tool you will need to build serverless integrations to run on your cloud.

How it Works

Kumologica executes flows on aws lambda node.js runtime. Artefacts like lambda source file and package.json are generated by kumologica-serverless-plugin. The only file required is the kumologica json flow file.

Kumologica flow may interact with several aws services. In such a case correct permissions must be added to policies that are assigned to lambda's role. Kumologica serverless plugin will introspect flow and create policy with all required permissions and attach policy to the lambda role generated by serverless. This feature may be disabled if required.

Usage

IAM Policy

IAM Policy with all required permissions is added to lambda role by default. To disable policy creation, add custom property inferIamPolicies into serverless.yml file and set it to false:

custom:
  kumologica:
    inferIamPolicies: false # true by default

Policy creation by plugin is possible if resources used by flow are defined as:

• static string values provided inside flow properties
• resources are defined in environment variables and referenced in flow using env.{name} expression.

The resources may also be referenced using input message or calculated using variables. In such a case the exact value is unknown and policy can not be created. In this scenario:

• the policy must be defined within serverless.yml file or arn of policy must be provided for the flow/function see
• the inferIamPolicies custom parameter must be set to false;

Test cases

Kumologica flow is internally divided into two sections: main and test. The test section should contain test cases and are not needed for correctly running flow in aws lambda. To remove test related nodes from flow during deployment use excludeTest custom property in serverless.yml and set it to true. The kumologica-serverless plugin will remove test nodes from flow during deployment:

custom:
  kumologica:
    excludeTest: true      # false by default

Examples

Most Basic example

Below is a serverless.yml file that will automatically update Role's policies. In this scenario flow has ARNs entered as a string values in flow properties.

service: hello-world

provider:
  name: aws
  runtime: nodejs12.x

functions:
  demo-flow: # name of your flow file (without .json extension)
    events:
      - http:
          path: hello
          method: get

plugins:
  - kumologica-serverless-plugin

Use of Lambda's Environment variables

Below example shows flow that references ARNs via lambda's environment variables (the arn of dynamo db table that flow uses). This allows greater flexibility in allowing the same flow to be deployed into multiple accounts or configurations without need of flow change.

The kumologica-serverless-plugin will add specific actions from flows for resource arn:aws:dynamodb:ap-southeast-2:{account}:table/contacts to the lambda's role during deployment.

service: hello-world

provider:
  name: aws
  runtime: nodejs12.x

functions:
  demo-flow: # name of your flow file (without .json extension)
    environment:
      dynamodbArn: arn:aws:dynamodb:{self:provider.region}:{accountId}:table/contacts
    events:
      - http:
          path: hello
          method: get

plugins:
  - kumologica-serverless-plugin

Explicit IAM Role statements

Below example relates to flow that uses ARN of resource from input message or is calculated at run time. In such a case the ARN is not known at deploy time. This requires disabling inferIamPolicies.

Additionally, the example shows that all test cases that are added into test parts of flow will be removed.

service: hello-world

provider:
  name: aws
  runtime: nodejs12.x
  iamRoleStatements:
    - Effect: "Allow"
      Action:
      - dynamodb:Query
      - dynamodb:Scan
      Resource: "arn:aws:dynamodb:{self:provider.region}:{accountId}:table/contacts"

functions:
  demo-flow: # name of your flow file (without .json extension)
    events:
      - http:
          path: hello
          method: get

custom:
  kumologica:
    inferIamPolicies: false # true by default
    excludeTest: true       # false by default

plugins:
  - kumologica-serverless-plugin

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Copyright 2020 Kumologica.com