kumologica-serverless-plugin

    1.0.9 • Public • Published

    Serverless plugin for Kumologica

    serverless npm npm npm

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

    Dependencies

    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
    1. 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
    1. Install kumologica-serverless-plugin
    sls plugin install --name kumologica-serverless-plugin
    1. 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.

    Kumologica Designer Screenshot

    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

    Install

    npm i kumologica-serverless-plugin

    DownloadsWeekly Downloads

    0

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    47.2 kB

    Total Files

    9

    Last publish

    Collaborators

    • kumologica-admin