Overview

Deployment script resources enable you to execute custom script as a part of deployment process. You can pass information about your infrastructure into the script by using parameters and environment variables and grant script permissions to stack resources. This gives the script ability to interact with other parts of deployed infrastructure.

Under the hood

On the background, script is bundled into AWS Lambda function which is triggered during stack deployment or delete process. Deployment scripts are NOT executed when using hotSwap deployment.

When to use

Performing provisioning steps related to infrastructure - Deployment of infrastructure is only a part of having the application successfully running. You might need to seed the database or run migrations, both of which are a great fit for a deployment script. Another example might be running a smoke test from your deployment script to ensure that everything is running correctly after deployment.

Basic usage

In this example we are using deployment-script to test public API endpoint and integrations after 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

Trigger property determines when is the script triggered.

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

Scripts are during deployment packaged and executed as lambda functions. Refer to lambda functions packaging docs.

Parameters

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

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

• For most of the AWS resources, resource-to-resource communication is not allowed by default. This helps to enforce security and resource isolation. Access must be explicitly granted using IAM (Identity and Access Management) permissions.

• Access control of Relational Databases is not managed by IAM. These resources are not "cloud-native" by design and have their own access control mechanism (connection string with username and password). They are accessible by default, and you don't need to grant any extra IAM permissions. You can further restrict the access to your relational databases by configuring their access control mode.

• Stacktape automatically handles IAM permissions for the underlying AWS services that it creates (i.e. granting script permission to write logs to Cloudwatch).

If your script needs to communicate with other infrastructure components, you need to add permissions manually. You can do this in 2 ways:

Using connectTo

• List of resource names or AWS services that this script will be able to access (basic IAM permissions will be granted automatically). Granted permissions differ based on the resource.
• Works only for resources managed by Stacktape in resources section (not arbitrary Cloudformation resources)
• This is useful if you don't want to deal with IAM permissions yourself. Handling permissions using raw IAM role statements can be cumbersome, time-consuming and error-prone. Moreover, when using connectTo property, Stacktape automatically injects information about resource you are connecting to 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

• IAM Role statements are a low-level, granular and AWS-native way of controlling access to your resources.
• IAM Role statements can be used to add permissions to any Cloudformation resource.
• Configured IAM role statement objects will be appended to the script's role.

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