{"id":18636185,"url":"https://github.com/kumologicahq/kumologica-serverless-plugin","last_synced_at":"2025-04-11T08:31:11.095Z","repository":{"id":51494008,"uuid":"245951985","full_name":"KumologicaHQ/kumologica-serverless-plugin","owner":"KumologicaHQ","description":"Serverless Plugin for Kumologica flow","archived":false,"fork":false,"pushed_at":"2021-05-11T16:12:53.000Z","size":583,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-06T14:34:34.242Z","etag":null,"topics":["aws","integration","kumologica","lambda","plugin","serverless"],"latest_commit_sha":null,"homepage":"https://www.kumologica.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KumologicaHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-09T05:33:02.000Z","updated_at":"2021-02-17T05:54:03.000Z","dependencies_parsed_at":"2022-08-21T11:40:31.240Z","dependency_job_id":null,"html_url":"https://github.com/KumologicaHQ/kumologica-serverless-plugin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KumologicaHQ%2Fkumologica-serverless-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KumologicaHQ%2Fkumologica-serverless-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KumologicaHQ%2Fkumologica-serverless-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KumologicaHQ%2Fkumologica-serverless-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KumologicaHQ","download_url":"https://codeload.github.com/KumologicaHQ/kumologica-serverless-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223463721,"owners_count":17149417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","integration","kumologica","lambda","plugin","serverless"],"created_at":"2024-11-07T05:28:33.211Z","updated_at":"2024-11-07T05:28:33.865Z","avatar_url":"https://github.com/KumologicaHQ.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless plugin for Kumologica\n\n[![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)\n[![npm](https://img.shields.io/npm/dm/kumologica-serverless-plugin.svg)](https://github.com/KumologicaHQ/kumologica-serverless-plugin)\n[![npm](https://img.shields.io/npm/v/kumologica-serverless-plugin.svg)](https://github.com/KumologicaHQ/kumologica-serverless-plugin)\n[![npm](https://img.shields.io/npm/l/kumologica-serverless-plugin)](https://github.com/KumologicaHQ/kumologica-serverless-plugin)\n\nServerless plugin that allows deployment of kumologica flow into aws account.\n\n- [Dependencies](#dependencies)\n- [Installation](#installation)\n  * [New Kumologica flow: using template](#new-kumologica-flow-using-template)\n  * [Existing Kumologica flow: changes to serverless.yaml](#existing-kumologica-flow-changes-to-serverless.yaml)\n- [Development](#development)\n- [How It Works](#how-it-works)\n- [Usage](#usage)\n  * [IAM Policy](#iam-policy)\n  * [Test cases](#test-cases)\n- [Examples](#examples)\n  * [Most Basic example](#most-basic-example)\n  * [Use of Lambda's Environment variables](#use-of-lambdas-environment-variables)\n  * [Explicit IAM Role statements](#explicit-iam-role-statements)\n- [License](#license)\n\n\n# Dependencies\n- [NPM](https://www.npmjs.com/get-npm)\n- [Serverless](https://serverless.com/framework/docs/getting-started/)\n- [Kumologica Designer](https://kumologica.com/download.html)\n\n# Installation\n\n## New Kumologica flow: using template\n\n1. Use kumologica serverless template\n\nCreate new kumologica project with hello world flow using serverless template:\n\n``` bash\nsls create --template-url https://github.com/KumologicaHQ/serverless-templates/tree/master/helloworld-api --path helloworld-api\n```\n\nThis will create new directory: helloworld-api with following files:\n- hello-world-flow.json\n- package.json\n- serverless.yml\n\n2. Install kumologica-serverless-plugin\n\n``` bash\nsls plugin install --name kumologica-serverless-plugin\n```\n\nFlow is ready to edit with kumologica designer and use by serverless.\n\n## Existing Kumologica flow: changes to serverless.yaml\n\n1. Add plugin to serverless.yml\n\n``` yaml\nplugins:\n  - kumologica-serverless-plugin\n```\n\n2. Install kumologica-serverless-plugin\n\n``` bash\nsls plugin install --name kumologica-serverless-plugin\n```\n\n3. Update functions\n\nReplace function name with the flow file name (without .json extension). For example for flow: demo-flow.json the functions declaration will look like:\n\n``` yaml\n\nfunctions:\n  demo-flow: # name of your flow file (without .json extension)\n \n```\n\n# Development\n\nDownload [Kumologica Designer](https://kumologica.com/download.html) to edit flow, implement business logic and unit tests. \n\n![Kumologica Designer Screenshot](https://kumologica.com/docs/assets/img/designer-explainer.png)\n\nThis is the only tool you will need to build serverless integrations to run on your cloud.\n\n# How it Works\n\nKumologica 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.\n\nKumologica 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.\n\n# Usage\n\n## IAM Policy\n\nIAM 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:\n\n``` yaml\ncustom:\n  kumologica:\n    inferIamPolicies: false # true by default\n```\n\nPolicy creation by plugin is possible if resources used by flow are defined as:\n- static string values provided inside flow properties\n- resources are defined in environment variables and referenced in flow using env.{name} expression.\n\nThe 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:\n- 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)\n- the inferIamPolicies custom parameter must be set to false;\n\n## Test cases\n\nKumologica 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.\nTo 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:\n\n``` yaml\ncustom:\n  kumologica:\n    excludeTest: true      # false by default\n```\n\n# Examples\n\n## Most Basic example\n\nBelow is a serverless.yml file that will automatically update Role's policies.\nIn this scenario flow has ARNs entered as a string values in flow properties.\n\n``` yaml\nservice: hello-world\n\nprovider:\n  name: aws\n  runtime: nodejs12.x\n\nfunctions:\n  demo-flow: # name of your flow file (without .json extension)\n    events:\n      - http:\n          path: hello\n          method: get\n\nplugins:\n  - kumologica-serverless-plugin\n```\n\n## Use of Lambda's Environment variables\n\nBelow 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.\n\nThe 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.\n\n``` yaml\nservice: hello-world\n\nprovider:\n  name: aws\n  runtime: nodejs12.x\n\nfunctions:\n  demo-flow: # name of your flow file (without .json extension)\n    environment:\n      dynamodbArn: arn:aws:dynamodb:{self:provider.region}:{accountId}:table/contacts\n    events:\n      - http:\n          path: hello\n          method: get\n\nplugins:\n  - kumologica-serverless-plugin\n```\n\n## Explicit IAM Role statements\n\nBelow example relates to flow that uses ARN of resource from input message or is calculated at run time. \nIn such a case the ARN is not known at deploy time. This requires disabling inferIamPolicies.\n\nAdditionally, the example shows that all test cases that are added into test parts of flow will be removed.\n\n``` yaml\nservice: hello-world\n\nprovider:\n  name: aws\n  runtime: nodejs12.x\n  iamRoleStatements:\n    - Effect: \"Allow\"\n      Action:\n      - dynamodb:Query\n      - dynamodb:Scan\n      Resource: \"arn:aws:dynamodb:{self:provider.region}:{accountId}:table/contacts\"\n\nfunctions:\n  demo-flow: # name of your flow file (without .json extension)\n    events:\n      - http:\n          path: hello\n          method: get\n\ncustom:\n  kumologica:\n    inferIamPolicies: false # true by default\n    excludeTest: true       # false by default\n\nplugins:\n  - kumologica-serverless-plugin\n```\n\n# License\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details. \n\nCopyright 2020 Kumologica.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumologicahq%2Fkumologica-serverless-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkumologicahq%2Fkumologica-serverless-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumologicahq%2Fkumologica-serverless-plugin/lists"}