Deployment scripts allow you to execute custom logic as part of your deployment process. You can pass information about your infrastructure to the script and grant it permissions to interact with other resources in your stack.

Under the hood, a deployment script is packaged as an AWS Lambda function and triggered during the deployment or delete process. Deployment scripts are not executed during hot-swap deployments.

When to use them

Deployment scripts are useful for tasks that need to run as part of your infrastructure provisioning, such as:

• Seeding a database with initial data.
• Running database migrations.
• Running smoke tests to ensure that your application is running correctly after a deployment.

Basic usage

This example uses a deployment script to test a public API endpoint after a deployment.

import fetch from 'node-fetch';

export default async (event) => {
  const { apiURL } = event;

  // do whatever you want with apiURL ...
  const result = await fetch(apiURL);

  // fail the script if the test fails
  if (result.statusCode === 404) {
    throw Error('API test failed');
  }
};

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')

Trigger

The trigger property determines when the script is executed.

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')

Packaging

Deployment scripts are packaged and executed as Lambda functions. For more information, see the documentation on packaging Lambda functions.

Parameters

You can pass parameters to your deployment script.

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')
        testPaths:
          - my/path/1
          - my/path/2

Environment variables

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('my-database-password')
      engine:
        type: aurora-postgresql-serverless

  testDatabase:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      environment:
        - name: DATABASE_URL
          value: $ResourceParam('myDatabase', 'connectionString')

Accessing other resources

By default, AWS resources cannot communicate with each other. Access must be granted using IAM permissions.

Stacktape automatically handles the necessary permissions for the services it manages. For example, it allows a deployment script to write logs to CloudWatch.

However, if your script needs to access other resources, you must grant permissions manually. You can do this in two ways:

Using connectTo

The connectTo property lets you grant access to other Stacktape-managed resources by simply listing their names. Stacktape automatically configures the required IAM permissions and injects connection details as environment variables into your script.

resources:
  myScript:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-script.ts
      environment:
        - name: MY_BUCKET_NAME
          value: $ResourceParam('myBucket', 'name')
      connectTo:
        # access to the bucket
        - myBucket
        # access to AWS SES
        - aws:ses

  myBucket:
    type: bucket

Using iamRoleStatements

For more granular control, you can provide a list of raw IAM role statements. These statements are added to the script's IAM role, allowing you to define precise permissions for any AWS resource.

resources:
  myScript:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-script.ts
      environment:
        - name: TOPIC_ARN
          value: $CfResourceParam('NotificationTopic', 'Arn')
      iamRoleStatements:
        - Resource:
            - $CfResourceParam('NotificationTopic', 'Arn')
          Effect: 'Allow'
          Action:
            - 'sns:Publish'

cloudformationResources:
  NotificationTopic:
    Type: AWS::SNS::Topic

API reference