Introduction

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommand: npx gatsby build

hooks:
  beforeDeploy:
    - scriptName: buildWeb

Local script

Local script is executed locally (from the same host from which the stacktape command is being executed):

• The script must define one of executeCommand, executeScript, executeCommands or executeScripts properties.
• Use connectTo property for listing resources of your stack which you will be accessing from your script. Stacktape will then automatically inject environment variables needed for connecting to those resources into your script. For more details, see section Using connectTo.

Using executeCommand

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommand: npx gatsby build

Using executeScript

scripts:
  sendSlackNotification:
    type: local-script
    properties:
      executeScript: scripts/send-slack-notification.ts

import { WebClient } from "@slack/web-api";

// An access token (from your Slack app or custom integration - xoxp, xoxb)
const token = "my-access-token";
// This argument can be a channel ID, a DM ID, a MPDM ID, or a group ID
const conversationId = "my-conversation-id";
const slackClient = new WebClient(token);
const errorData = JSON.parse(process.env.STP_ERROR);

(async () => {
  await slackClient.chat.postMessage({
    channel: conversationId,
    text: errorData.message
  });
})();

Using executeCommands

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommands:
        - poetry run python manage.py makemigrations
        - poetry run python manage.py migrate

Using executeScripts

scripts:
  sendSlackNotification:
    type: local-script
    properties:
      executeScripts:
        - scripts/run-migration.ts
        - scripts/send-slack-notification.ts

Local script with bastion tunneling

Local script with bastion tunneling executes in the same way as local script.

In addition, when using local script with bastion tunneling, connections to selected resources listed in connectTo list, are tunneled through bastion server:

• When using tunneled connection, you are using secured encrypted connection running through the bastion server of your stack (instead of connecting to the resource directly over the internet).
• Tunneled connection allows you to connect to resources which do not have public endpoint and are only accessible within stack's default VPC such as private relational-database or redis-cluster from your local host (where script is executed).
• To use the tunneled endpoint of the resource (instead of using direct endpoint) in your script/command, use environment variables injected by connectTo property. These environment variables are automatically adjusted to use the tunneled endpoints.

Example script with tunneling

scripts:
  migrateDb:
    type: local-script-with-bastion-tunneling
    properties:
      executeScript: migrate.ts
      connectTo:
        - myDatabase

hooks:
  afterDeploy:
    - scriptName: migrateDb

resources:
  myBastion:
    type: bastion

  myDatabase:
    type: relational-database
    properties:
      # database is only accessible from withing VPC
      accessibility:
        accessibilityMode: vpc
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      credentials:
        masterUserPassword: my_secret_pass

import { DbClient } from './db';

// using environment variable which was automatically injected thanks to connectTo property
// injected environment variables are using tunneled endpoint
const databaseConnectionString = process.env.STP_MY_DATABASE_CONNECTION_STRING;

const client = new DbClient({ connectionString: databaseConnectionString });

// perform migrations with the client

client.close();

Bastion script

Bastion script is executed remotely on bastion server:

• Logs from the script execution are fetched real-time and printed to your local host.
• Executing commands directly on bastion server gives you unified way to execute set of commands from anywhere.
• Use connectTo property for listing resources of your stack which you will be accessing from your commands. Stacktape will then automatically inject environment variables needed for connecting to those resources into your script. For more details, see section Using connectTo.

Example bastion script

scripts:
  dbScript:
    type: bastion-script
    properties:
      executeCommands:
        - psql $STP_MY_DATABASE_CONNECTION_STRING -c "SELECT 1 where 1=1"
      connectTo:
        - myDatabase

hooks:
  afterDeploy:
    - scriptName: dbScript

resources:
  myBastion:
    type: bastion
    properties:
      runCommandsAtLaunch:
        - yum update
        - yum install postgresql.x86_64 -y

  myDatabase:
    type: relational-database
    properties:
      accessibility:
        accessibilityMode: vpc
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      credentials:
        masterUserPassword: my_secret_pass

Connecting to resources

scripts:
  dbScript:
    type: local-script
    properties:
      # environment variable $STP_MY_DATABASE_CONNECTION_STRING is injected thanks to connectTo
      executeCommands:
        - psql $STP_MY_DATABASE_CONNECTION_STRING -c "SELECT * FROM users"
      connectTo:
        - myDatabase

resources:
  myDatabase:
    type: relational-database
    properties:
      engine:
        type: postgres
        properties:
          primaryInstance:
            instanceSize: db.t3.micro

Executing script

The script can be executed in 2 ways:

• using script:run command

  stacktape script:run --scriptName <<scriptName>> --stage <<stage>>

• inside a hook

Environment

scripts:
  migrateDb:
    executeScript: scripts/migrate-db.ts
    environment:
      - name: DB_CONNECTION_STRING
        value: $ResourceParam('mainDatabase', 'connectionString')

resources:
  mainDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: my_secret_password
      engine:
        type: mysql
        properties:
          primaryInstance:
            instanceSize: db.t2.micro

Giving permissions to script

You can use property assumeRoleOfResource to grant script AWS permissions.

scripts:
  seedDb:
    executeScript:
      scripts/seed-db.ts
    assumeRoleOfResource: myFunction
    environment:
      - name: TABLE_NAME
        value: $ResourceParam('dynamoTable', 'name')

resources:
  dynamoTable:
    type: dynamo-db-table

  myFunction:
    type: function
    properties:
      allowAccessTo:
        - dynamoTable

API reference