https://github.com/kumologicahq/kumologica-serverless-plugin
Serverless Plugin for Kumologica flow
https://github.com/kumologicahq/kumologica-serverless-plugin
aws integration kumologica lambda plugin serverless
Last synced: about 1 year ago
JSON representation
Serverless Plugin for Kumologica flow
- Host: GitHub
- URL: https://github.com/kumologicahq/kumologica-serverless-plugin
- Owner: KumologicaHQ
- License: mit
- Created: 2020-03-09T05:33:02.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-05-11T16:12:53.000Z (about 5 years ago)
- Last Synced: 2024-10-06T14:34:34.242Z (over 1 year ago)
- Topics: aws, integration, kumologica, lambda, plugin, serverless
- Language: JavaScript
- Homepage: https://www.kumologica.com
- Size: 569 KB
- Stars: 4
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Serverless plugin for Kumologica
[](http://www.serverless.com)
[](https://github.com/KumologicaHQ/kumologica-serverless-plugin)
[](https://github.com/KumologicaHQ/kumologica-serverless-plugin)
[](https://github.com/KumologicaHQ/kumologica-serverless-plugin)
Serverless plugin that allows deployment of kumologica flow into aws account.
- [Dependencies](#dependencies)
- [Installation](#installation)
* [New Kumologica flow: using template](#new-kumologica-flow-using-template)
* [Existing Kumologica flow: changes to serverless.yaml](#existing-kumologica-flow-changes-to-serverless.yaml)
- [Development](#development)
- [How It Works](#how-it-works)
- [Usage](#usage)
* [IAM Policy](#iam-policy)
* [Test cases](#test-cases)
- [Examples](#examples)
* [Most Basic example](#most-basic-example)
* [Use of Lambda's Environment variables](#use-of-lambdas-environment-variables)
* [Explicit IAM Role statements](#explicit-iam-role-statements)
- [License](#license)
# Dependencies
- [NPM](https://www.npmjs.com/get-npm)
- [Serverless](https://serverless.com/framework/docs/getting-started/)
- [Kumologica Designer](https://kumologica.com/download.html)
# Installation
## New Kumologica flow: using template
1. Use kumologica serverless template
Create new kumologica project with hello world flow using serverless template:
``` bash
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
``` bash
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
``` yaml
plugins:
- kumologica-serverless-plugin
```
2. Install kumologica-serverless-plugin
``` bash
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:
``` yaml
functions:
demo-flow: # name of your flow file (without .json extension)
```
# Development
Download [Kumologica Designer](https://kumologica.com/download.html) 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:
``` yaml
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](explicit-iam-role-statements)
- 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:
``` yaml
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.
``` yaml
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.
``` yaml
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.
``` yaml
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](LICENSE.md) file for details.
Copyright 2020 Kumologica.com