Stacktape
Stacktape

Deployment Scripts



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.

DeploymentScript  API reference
type
Required
properties.trigger
Required
properties.packaging
Required
properties.runtime
properties.environment
properties.parameters
properties.memory
properties.timeout
Default: 10
properties.joinDefaultVpc
properties.storage
Default: 512
properties.connectTo
properties.iamRoleStatements
overrides
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');
  }
};

A deployment script in TypeScript (test-url.ts).

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')

The Stacktape configuration for the deployment script.

Trigger

The trigger property determines when the script is executed.

  • after:deploy: Executes after all resources in the stack have been successfully deployed. If the script fails, the entire deployment will be rolled back.
  • before:delete: Executes before the stack's resources begin to be deleted. If the script fails, the deletion process will still proceed.

You can also trigger the script manually using the stacktape deployment-script:run command.

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')

Scripts that are triggered before a stack is deleted before:delete must have been present during the last deployment to be executed.

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.

This allows you to pass structured data to your script.

Note: You cannot pass secrets using this property. Use environment variables for secrets.

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

This is useful for providing configuration details, such as database connection strings or secrets.

EnvironmentVar  API reference
Parent:DeploymentScript
name
Required
value
Required
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

Configures access to other resources in your stack and AWS services. By specifying resources here, Stacktape automatically:

  • Configures IAM role permissions.
  • Sets up security group rules to allow network traffic.
  • Injects environment variables with connection details into the compute resource.

Environment variables are named STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).

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

StpIamRoleStatement  API reference
Parent:DeploymentScript
Resource
Required
Sid
Effect
Default: Allow
Action
Condition

Contents