Stacktape
Stacktape

Custom Resource Definition

This example shows a basic custom resource definition configuration.

Custom resource definition

  • Allows you to define your custom resource provisioning logic.
  • Can be used to create resources inside your stack that are not natively supported by AWS Cloudformation, or to provision services from other providers.

Basic example

resources:
  myCustomResourceDefinition:
    type: custom-resource-definition
    properties:
      # Configures the lambda function deployment package (lambda artifact) used for this custom resource
      #
      # - Custom resource are managed using lambda functions.
      # - Lambda function is executed during custom resource events: `create`, `update` and `delete`.
      #
      # - Type: union (anyOf)
      # - Required: true
      #
      # - Type: object
      # - Required: true
      packaging:
        #
        # - Type: string
        # - Required: true
        type: stacktape-lambda-buildpack
        #
        # - Type: object
        # - Required: true
        properties:
          # Path to the entry point of your compute resource (relative to the stacktape config file)
          #
          # - Stacktape tries to bundle all your source code with its dependencies into a single file.
          # - If a certain dependency doesn't support static bundling (because it depends on binary executable, uses dynamic require() calls, etc.),
          # Stacktape will install it and copy it to the bundle
          #
          # - Type: string
          # - Required: true
          entryfilePath: ./src/index.ts
          # The handler function (method) ran when the lambda function is invoked.
          #
          # - Type: string
          # - Required: false
          handlerFunction: example-value
          # Files that should be explicitly included in the deployment package (glob pattern)
          #
          # - Example glob pattern: `images/*.jpg`
          # - The path is relative to the stacktape configuration file location or to `cwd` if configured using `--currentWorkingDirectory` command line option.
          #
          # - Type: array<string>
          # - Required: false
          includeFiles:
            - public/**/*
            - assets/*.png
          # Files that should be explicitly excluded from deployment package (glob pattern)
          #
          # Example glob pattern: `images/*.jpg`
          #
          # - Type: array<string>
          # - Required: false
          excludeFiles:
            - *.test.ts
            - node_modules/**
          # Dependencies to ignore.
          #
          # - These dependencies won't be a part of your deployment package.
          #
          # - Type: array<string>
          # - Required: false
          excludeDependencies:
            - example-value
          # Configuration of packaging properties specific to given language
          #
          # - Type: union (anyOf)
          # - Required: false
      # Environment variables injected to the batch job's environment
      #
      # - Environment variables are often used to inject information about other parts of the infrastructure (such as database URLs, secrets, etc.).
      #
      # - Type: array<object (reference)>
      # - Required: false
      environment:
        - name: NODE_ENV
          value: production
        - name: DATABASE_URL
          value: $ResourceParam(myDatabase, connectionString)
      # Runtime used to execute the custom resource lambda function
      #
      # - Stacktape automatically detects the function's language and uses the latest runtime version associated with that language.
      # - Example: uses `nodejs22.x` for all files ending with `.js` and `.ts`.
      # - For the list of all available lambda runtimes, refer to [AWS docs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
      #
      # - Type: enum: [dotnet6, dotnet7, java11, java17, java8, java8.al2, nodejs18.x, nodejs20.x, nodejs22.x, provided.al2, provided.al2023, python3.10, python3.11, python3.12, python3.13, python3.8, python3.9, ruby3.2]
      # - Required: false
      # - Allowed values: [dotnet6, dotnet7, java11, java17, java8, java8.al2, nodejs18.x, nodejs20.x, nodejs22.x, provided.al2, provided.al2023, python3.10, python3.11, python3.12, python3.13, python3.8, python3.9, ruby3.2]
      runtime: dotnet6
      # Maximum amount of time (in seconds) the custom resource lambda function is allowed to run
      #
      # Maximum allowed time is 900 seconds.
      #
      # - Type: number
      # - Required: false
      # - Default: 10
      timeout: 3600
      # Amount of memory (in MB) available to the function during execution
      #
      # - Must be between 128 MB and 10,240 MB in 1-MB increments.
      # - Amount of CPU power available to the function is also set using memory property - it's proportionate to the amount of available memory.
      # Function with 1797MB has a CPU power equal to 1 virtual CPU. Lambda function can have a maximum of 6 vCPUs (at 10,240 MB of RAM).
      #
      # - Type: number
      # - Required: false
      memory: 2048
      # Configures access to other resources of your stack (such as databases, buckets, event-buses, etc.) and aws services
      #
      # By referencing resources (or services) in `connectTo` list, Stacktape automatically:
      # - configures correct compute resource's **IAM role permissions** if needed
      # - sets up correct **security group rules** to allow access if needed
      # - **injects relevant environment variables** containing information about resource you are connecting to into the compute resource's runtime
      # - names of environment variables use upper-snake-case and are in form `STP_[RESOURCE_NAME]_[VARIABLE_NAME]`,
      # - examples: `STP_MY_DATABASE_CONNECTION_STRING` or `STP_MY_EVENT_BUS_ARN`,
      # - list of injected variables for each resource type can be seen below.
      #
      #
      # Granted permissions and injected environment variables are different depending on resource type:
      #
      #
      # `Bucket`
      # - **Permissions:**
      # - list objects in a bucket
      # - create / get / delete / tag object in a bucket
      # - **Injected env variables**: `NAME`, `ARN`
      #
      #
      # `DynamoDB table`
      # - **Permissions:**
      # - get / put / update / delete item in a table
      # - scan / query a table
      # - describe table stream
      # - **Injected env variables**: `NAME`, `ARN`, `STREAM_ARN`
      #
      #
      # `MongoDB Atlas cluster`
      # - **Permissions:**
      # - Allows connection to a cluster with `accessibilityMode` set to `scoping-workloads-in-vpc`. To learn more about
      # MongoDB Atlas clusters accessibility modes, refer to
      # [MongoDB Atlas cluster docs](https://docs.stacktape.com/3rd-party-resources/mongo-db-atlas-clusters/#accessibility).
      # - Creates access "user" associated with compute resource's role to allow for secure credential-less access to the the cluster
      # - **Injected env variables**: `CONNECTION_STRING`
      #
      #
      # `Relational(SQL) database`
      # - **Permissions:**
      # - Allows connection to a relational database with `accessibilityMode` set to `scoping-workloads-in-vpc`. To learn more about
      # relational database accessibility modes, refer to [Relational databases docs](https://docs.stacktape.com/resources/relational-databases#accessibility).
      # - **Injected env variables**: `CONNECTION_STRING`, `JDBC_CONNECTION_STRING`, `HOST`, `PORT`
      # (in case of aurora multi instance cluster additionally: `READER_CONNECTION_STRING`, `READER_JDBC_CONNECTION_STRING`, `READER_HOST`)
      #
      #
      # `Redis cluster`
      # - **Permissions:**
      # - Allows connection to a redis cluster with `accessibilityMode` set to `scoping-workloads-in-vpc`. To learn more about
      # redis cluster accessibility modes, refer to [Redis clusters docs](https://docs.stacktape.com/resources/redis-clusters#accessibility).
      # - **Injected env variables**: `HOST`, `READER_HOST`, `PORT`
      #
      #
      # `Event bus`
      # - **Permissions:**
      # - publish events to the specified Event bus
      # - **Injected env variables**: `ARN`
      #
      #
      # `Function`
      # - **Permissions:**
      # - invoke the specified function
      # - invoke the specified function via url (if lambda has URL enabled)
      # - **Injected env variables**: `ARN`
      #
      #
      # `Batch job`
      # - **Permissions:**
      # - submit batch-job instance into batch-job queue
      # - list submitted job instances in a batch-job queue
      # - describe / terminate a batch-job instance
      # - list executions of state machine which executes the batch-job according to its strategy
      # - start / terminate execution of a state machine which executes the batch-job according to its strategy
      # - **Injected env variables**: `JOB_DEFINITION_ARN`, `STATE_MACHINE_ARN`
      #
      #
      # `User auth pool`
      # - **Permissions:**
      # - full control over the user pool (`cognito-idp:*`)
      # - for more information about allowed methods refer to [AWS docs](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazoncognitouserpools.html)
      # - **Injected env variables**: `ID`, `CLIENT_ID`, `ARN`
      #
      #
      #
      # `SNS Topic`
      # - **Permissions:**
      # - confirm/list subscriptions of the topic
      # - publish/subscribe to the topic
      # - unsubscribe from the topic
      # - **Injected env variables**: `ARN`, `NAME`
      #
      #
      #
      # `SQS Queue`
      # - **Permissions:**
      # - send/receive/delete message
      # - change visibility of message
      # - purge queue
      # - **Injected env variables**: `ARN`, `NAME`, `URL`
      #
      #
      # `Upstash Kafka topic`
      # - **Injected env variables**: `TOPIC_NAME`, `TOPIC_ID`, `USERNAME`, `PASSWORD`, `TCP_ENDPOINT`, `REST_URL`
      #
      #
      # `Upstash Redis`
      # - **Injected env variables**: `HOST`, `PORT`, `PASSWORD`, `REST_TOKEN`, `REST_URL`, `REDIS_URL`
      #
      #
      # `Private service`
      # - **Injected env variables**: `ADDRESS`
      #
      #
      # `aws:ses`(Macro)
      # - **Permissions:**
      # - gives full permissions to aws ses (`ses:*`).
      # - for more information about allowed methods refer to [AWS docs](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonses.html)
      #
      # - Type: array<string>
      # - Required: false
      connectTo:
        - myDatabase
        - myBucket
      # Raw AWS IAM role statements appended to your resources's role.
      #
      # - Type: array<object (reference)>
      # - Required: false
      iamRoleStatements:
        - Resource: ["example-value"]
          Sid: example-value

Packaging alternatives

stacktape-lambda-buildpack

This example shows how to configure packaging using stacktape-lambda-buildpack.

resources:
  myCustomResourceDefinition:
    type: custom-resource-definition
    properties:
      # Configures the lambda function deployment package (lambda artifact) used for this custom resource
      #
      # - Custom resource are managed using lambda functions.
      # - Lambda function is executed during custom resource events: `create`, `update` and `delete`.
      #
      # - Type: object
      # - Required: true
      packaging:
        #
        # - Type: string
        # - Required: true
        type: stacktape-lambda-buildpack
        #
        # - Type: object
        # - Required: true
        properties:
          # Path to the entry point of your compute resource (relative to the stacktape config file)
          #
          # - Stacktape tries to bundle all your source code with its dependencies into a single file.
          # - If a certain dependency doesn't support static bundling (because it depends on binary executable, uses dynamic require() calls, etc.),
          # Stacktape will install it and copy it to the bundle
          #
          # - Type: string
          # - Required: true
          entryfilePath: ./src/index.ts
          # The handler function (method) ran when the lambda function is invoked.
          #
          # - Type: string
          # - Required: false
          handlerFunction: example-value
          # Files that should be explicitly included in the deployment package (glob pattern)
          #
          # - Example glob pattern: `images/*.jpg`
          # - The path is relative to the stacktape configuration file location or to `cwd` if configured using `--currentWorkingDirectory` command line option.
          #
          # - Type: array<string>
          # - Required: false
          includeFiles:
            - public/**/*
            - assets/*.png
          # Files that should be explicitly excluded from deployment package (glob pattern)
          #
          # Example glob pattern: `images/*.jpg`
          #
          # - Type: array<string>
          # - Required: false
          excludeFiles:
            - *.test.ts
            - node_modules/**
          # Dependencies to ignore.
          #
          # - These dependencies won't be a part of your deployment package.
          #
          # - Type: array<string>
          # - Required: false
          excludeDependencies:
            - example-value
          # Configuration of packaging properties specific to given language
          #
          # - Type: union (anyOf)
          # - Required: false

custom-artifact

This example shows how to configure packaging using custom-artifact.

resources:
  myCustomResourceDefinition:
    type: custom-resource-definition
    properties:
      # Configures the lambda function deployment package (lambda artifact) used for this custom resource
      #
      # - Custom resource are managed using lambda functions.
      # - Lambda function is executed during custom resource events: `create`, `update` and `delete`.
      #
      # - Type: object
      # - Required: true
      packaging:
        #
        # - Type: string
        # - Required: true
        type: custom-artifact
        #
        # - Type: object
        # - Required: true
        properties:
          # Path to the lambda package to use as the source for this lambda function
          #
          # - If the specified package path is a directory or an non-zip file, it will be automatically zipped.
          #
          # - Type: string
          # - Required: true
          packagePath: ./path/to/packagePath
          # The handler function (method) ran when the lambda function is invoked.
          #
          # - Path to the entryfile and method inside your package.
          # - The syntax is `{{filepath}}:{{functionName}}`.
          # - Example: `my-lambda/index.js:default`
          #
          # - Type: string
          # - Required: false
          handler: example-value

Contents