# Command: export cloudformation

Command kl export cloudformation creates AWS cloud formation script that will support creation of cloud formation stack with kumologica flow lambda function and other relevant resources.

Depending on events definition passed to the command, cloud formation script may contain other resources like: api gateway methods, resources and permissions, dynamodb stream references ect.

# IAM Role

Kumologica flow may reference various aws resources using env. prefix. in such a case it is required to pass environment variables as a parameter to the export command, so the generated iam policy will contain correct actions and resources associated with lambda function. If environment variables are not provided then command will return error message specifying what environment variable is missing.

If option --role-name is provided then command does not generate IAM role and the --environment, --strict-mode and --policy options are ignored and trigger related permissions will also be ignored.

It is also possible to attach explicit policy to the IAM role that is being generated. Use --policy parameter to add the policy definition, for example: --policy '[{"Action": ["dynamodb:Query"], "Effect":"Allow", "Resource": ["*"]}]'

# Usage

Usage: kl export cloudformation [options]

The options extend the set provided by aws cli: aws lambda create-function command.

# Options

  • -d, --project-directory - The root directory of kumologica project

  • -f, --flow-file-name - The name of kumologica flow file. Command will search for flow if parameter not provided.

  • -l, --lambda-name - The name of lambda function, default to flow name

  • -z, --zip-file-name - The name of lambda zip file, default value: lambda.zip

  • -o, --role-name - The name of lambda role, default to {lambda-name}-role.

  • -b, --bucket-name - The name of bucket where zipped lambda is loaded

  • -t, --timeout - The time in seconds lambda is allowed to run, default: 3, max: 900

  • -m, --memory-size - The amount of memory allocated to function, default 128 (MB), must be multiple of 64 (MB)

  • --description - The description of a function, optional

  • -e, --environment - Environment variables, JSON Syntax: '{"Variables": {"name1": "value1", "name2": "value2", ...}}'. See: IAM Role for explanation when environment variables are required

  • -g, --tags - Tags, JSON Syntax: '{"string": "string" ...}', optional

  • -x, --tracing-config - X-Ray config, JSON Syntax: '{"Mode": "Active" | "PassThrough"}', optional. To enable X-ray use "Active" value. Command will additionally add x-ray permissions to IAM role.

  • -v, --vpc-config - The list of security groups and subnets of VPC, JSON syntax: '{ "SubnetIds": ["string", ...],"SecurityGroupIds": ["string", ...]}', optional.

  • -r, --runtime - The NodeJS runtime version, only nodejs runtimes are allowed: nodejs20.x| ... . Refer to aws documentation for updated list of supported node js runtime values. When cli detects use of @kumologica/runtime version 3.4.0 or less then default value is set to nodejs16.x, otherwise nodejs20.x is used.

  • -q, --dead-letter-config - The arn of the dead letter queue or topic JSON Syntax: '{"TargetArn": "string"}', optional

  • --file-system-configs - AWS EFS config details, JSON Syntax: [{"Arn":"string","LocalMountPath": "string"} ...], optional

  • --architectures - The instruction set architecture that the function supports, a string array with one of the valid values: arm64 or x86_64. The default value is [x86_64].

  • --log-retention-days - Number of days logs to be retained, numeric value, optional. If provided, then cloud formation script will contain AWS::Logs::LogGroup with name: "/aws/lambda/{lambda-name}". If not provided then default log group name will be used and "Never Expire" will be set.

  • --strict-mode - Fails script creation if insufficient resource definition is provided (string values or environment reference). If set to false, then missing resource will be substituted with "*"

  • --role-arn - The arn of IAM role to assign to lambda, otherwise this command will generate role. Important! This parameter should only be used if this command is not able to generate sufficient role based on flow details.

  • --layers - List of arns of lambda layers to use.

  • --policy - Additional iam policy to add to the role. It must be in valid aws policy format, for example: '{"Effect": "Allow", "Resource": ["*"],"Action": ["sns:Publish"]}'. if policy is invalid, cloudformation stack will fail. The value can be single policy statement or array of statements if required. This parameter is ignored if role-arn is provided.

  • --triggers - Array of triggers, JSON Syntax: '[{"api": {"apiId": "..",..}}, {"sqs": {"queueArn": ""}}, ..] Supported triggers:

    • PartnerEvent AWS EventBridge partner event

      • partnerEventBusName - the name of partner event bus
      • name - the name of the rule, if not provided then rule will be named: Event{timestamp}
      • detailType - the optional detail-type value of the partner event that is used by the rule for matching and forwarding event. The value of detailType must exactly match the value of event's detail-type to be forwarded. If detailType is not provided then Rule will forward all events from the event bus.

    • Event Cloud watch event or event bridge event. The event is callable by both: scheduler and explicitly via cli for example:

      aws events put-events --entries '[{"DetailType": "kumologica event","Source": "kumologica","Detail": "{\"type\": \"kumologica-event\",\"reference\": \"REFERENCE HERE\" }"}]'
      • expression - either cron expression or rule, required
      • name - the name of the event, The Rule will be named: Event{name}, optional
      • state - either: ENABLED or DISABLED, ENABLED if not provided, optional
      • reference - unique identifier for event listener and event. Required if flow contains more that one cloud watch event listener

    • SQS

      • queueArn - the ARN of sqs queue, required
      • batchSize - the size of batch, optional

    • SNS

      • topicArn - the ARN of sns topic, required

    • DynamoDB Stream

      • streamArn - the ARN of dynamodb stream, required
      • batchSize - the size of batch, optional
      • batchWindow - maximum batching window in seconds, optional
      • startingPosition - either LATEST or TRIM_HORIZON, optional

    • Kinesis Stream

      • streamArn - the ARN of kinesis stream, required
      • batchSize - the size of batch, optional
      • batchWindow - maximum batching window in seconds, optional
      • startingPosition - either LATEST or TRIM_HORIZON, optional

    • S3

      • bucket - the name of the bucket, required
      • sourceAccount - the source account id, optional
      • eventType - the type of s3 event, required
      • prefix - filter for keys starting with prefix, optional
      • suffix - filter for keys ending with suffix, optional

    • # Websockets

    • Rest api gateway

      • apiId - the id of rest api, required
      • apiName - api gateway name if new api gateway is created otherwise ignored, optional
      • stage - the stage name of api gateway, required
      • parentId - the id of parent resource where lambda {proxy+} should be added. It can be root resource id or specific resource id. required
      • resource - the name of resource linked to lambda, required if parentId is not root or lambda linked to non root in api gw
      • authorizerId - the id of authorizer, optional
      • authorizerType - the type of authorizer either: CUSTOM or COGNITO_USER_POOLS, optional
      • scopes - array of scopes, optional
      • apiKeyRequired - true if api key presence to be enforced, false otherwise, optional

# Example: simple export

Export cloudformation script with lambda binaries in zip file lambda.zip to be placed in s3 bucket deployment-bucket file with lambda binaries.

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket

# Example: multiple options export

Export cloudformation script with lambda binaries in zip file lambda.zip to be placed in s3 bucket deployment-bucket file with lambda binaries. project files are in current working directory. Flow to be deployed into VPC, references dynamodb table with arn provided in environment parameter. The trigger contains api gateway settings and flow will be under accounts resource attached to the parent resource id vfgd24d. All calls to the flow are secured by authorizer 3dgfd42

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --environment '{"Variables": {"Environment": "test", "tableArn": {"Fn:Sub": "arn:aws:dynamodb:${AWS::Region"}:${AWS::AccountId}:table/table-name"} }}' \
    --vpc-config '{"SubnetIds": ["subnet-aaaaaaa", "subnet-bbbbbbbbbbb",  "subnet-cccccccccc"], "SecurityGroupIds": ["sg-dddddddd"]}' \
    --tags '{"OWNER": "DEVTEAM"}' \
      --triggers '[ \
        { \
            "api": { \
                "apiId": "fg4wsf", \
                "stage": "test", \
                "parentId": "vfgd24d", \
                "resource": "accounts", \
                "authorizerId": "3dgfd42", \
            } \
        } \
  ]'

# Example: API Gateway trigger

  • existing api gateway id: "fg4wsf"
  • stage "test"
  • parent resource id: "vfgd24d"
$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "api": { \
                "apiId": "fg4wsf", \
                "stage": "test",  \
                "parentId": "vfgd24d" \
            } \
        } \
  ]'

# Example: API Gateway trigger

  • Existing api gateway id: fg4wsf
  • stage: test
  • new resource to create: users
  • parent resource id vfgd24d
  • authorizer id to assign: 3dgfd42
  • scopes to assign: ["example.com/user.create", "example.com/user.update"]
$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "api": { \
                "apiId": "fg4wsf", \
                "stage": "test", \
                "parentId": "vfgd24d", \
                "resource": "users", \
                "authorizerId": "3dgfd42", \
                "scopes": ["example.com/user.create", "example.com/user.update"] \
            } \
        } \
  ]'

# Example: API Gateway trigger

  • Create new api gateway
  • create test stage
  • create /users resource
$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "api": { \
                "apiId": "create new", \
                "apiName": "users api", \
                "resource": "users" \
            } \
        } \
  ]'

# Example: API Gateway trigger

  • create new api gateway
  • create stage: test
  • flow attached to the root '/' resource
$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "api": { \
                "apiId": "create new", \
                "apiName": "booking api" \
            } \
        } \
  ]'

# Example: S3 trigger

Kumologica flow listening to the event ObjectCreated.* on S3 bucket named testBucket

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "s3": { \
                "bucket": "testBucket", \
                "eventType": "ObjectCreated.*" \
            } \
        } \
  ]'

# Example: Kinesis stream trigger

Kumologica flow listening to the kinesis stream with arn arn:aws: ... and with starting position LATEST

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "kinesis": { \
                "streamArn": "arn:aws: ...", \
                "startingPosition": "LATEST" \
            } \
        } \
  ]'

# Example: DynamoDB Stream trigger

Kumologica flow listening to the dynamo db stream with arn "arn:aws: ..." and with starting position LATEST

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "dynamodb": { \
                "streamArn": "arn:aws: ...", \
                "startingPosition": "LATEST" \
            } \
        } \
  ]'

# Example: SQS trigger

Kumologica flow listening to the sqs queue arn "arn:aws: ..."

$ kl export cloudformation \
  --triggers '[ \
        { \
            "sqs": { \
                "queueArn": "arn:aws: ..." \
            } \
        } \
  ]'

# Example: Cloudwatch event trigger

Event trigger using cron expression that runs at 10am UTC every day

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "event": { \
                "expression": "cron(0 10 * * ? *)" \
            } \
        } \
  ]'

# Example: Cloudwatch event trigger

Event trigger using rate expression that runs every minute:

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "event": { \
               "expression": "rate(1 minute)" \
            } \
        } \
  ]'

# Example: Multiple cloudwatch events triggers

Event trigger using rate expression that runs every minute for event listener with reference process and every 20 minutes for event listener with reference cleanup

For kumologica flows with multiple event listeners for cloud watch events, each such an event listener must have unique reference value set.

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "event": { \
                "expression": "rate(1 minute)", \
                "reference": "process" \
            } \
        }, \
        { \
            "event": { \
                "expression": "rate(20 minutes)", \
                "reference": "cleanup" \
            } \
        } \
  ]'

# Example: AWS EventBridge partner event trigger

Event triggered by Salesforce on Opportunity change

$ kl export cloudformation \
    --zip-file lambda.zip \
    --bucket-name deployment-bucket \
    --project-directory . \
    --triggers '[ \
        { \
            "partnerEvent": { \
                "partnerEventBusName": "aws.partner/salesforce.com/00045dser54555445/546435300000GHT" \
                "name": "OpportunityChange" \
                "detailType": "OpportunityChangeEvent" \
            } \
        } \
  ]'

← Export Github AWS →