Scripts

Introduction

Scripts are used to specify and execute your custom scripts. Specifying a script in the Stacktape config can be beneficial for multiple reasons:
- scripts will be easily reusable by all members of your team,
- scripts can be executed automatically within lifecycle hooks (before/after deploy/delete etc.) or manually using script:run command,
- you can use connectTo property to easily inject environment variables needed for connecting to resources of your stack,
- you can leverage bastion scripts and bastion tunneling to access resources which are only accessible within VPC.
There are 3 types of scripts and based on the type of script there are differences on how the script is executed:
1. local-script - script is executed locally (from the same host from which the stacktape command is being executed),
2. local-script-with-bastion-tunneling - same as local-script, and additionally: Connections to selected resources listed in connectTo list are tunneled through bastion resource of your stack. This allows you to connect to resources (databases, redis-clusters...) which are only accessible within VPC from your local script (requires bastion resource),
3. bastion-script - script is executed on the bastion host (requires bastion resource).
Scripts can specify either execute shell commands or scripts written in Javascript,Typescript or Python.


Copy
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

Executes the specified command in a separate shell process. Uses /bin/bash on UNIX systems and default shell(usually cmd.exe) on Windows systems.
The command will be executed on the machine running the Stacktape command. If the command works on your machine, it doesn't mean it works for people or machines with different OSes or shells.
Only one of executeScript, executeScripts, executeCommand or executeCommands can be configured.


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

Using executeScript

The script can be written in Javascript, Typescript or Python.
The script is executed in a separate process.
The script is executed using an executable configured using defaults:configure command or a default executable on your machine:
- node for Javascript and Typescript
- python for Python
Only one of executeScript, executeScripts, executeCommand or executeCommands can be configured.


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


Copy
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

Commands are executed in sequential order.
Each command is executed in a separate shell process. Uses /bin/bash on UNIX systems and default shell(usually cmd.exe) on Windows systems.
Commands will be executed on the machine running the Stacktape command. If a command works on your machine, it doesn't mean it works for people or machines with different OSes or shells.
Only one of executeScript, executeScripts, executeCommand or executeCommands can be configured.


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

Using executeScripts

Scripts are executed in sequential order.
Script can be written in Javascript, Typescript or Python.
Each script is executed in a separate process.
Each script is executed using an executable configured using defaults:configure command or a default executable on your machine:
- node for Javascript and Typescript
- python for Python
Only one of executeScript, executeScripts, executeCommand or executeCommands can be configured.


Copy
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.

Your stack must contain bastion resource to use this type of script.

Example script with tunneling


Copy
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

Stacktape config using the migration script with tunneling


Copy
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();

Example pseudo migration script

Bastion tunneling is supported for following resource types:

relational-database
redis-cluster
application-load-balancer
private-service (with loadBalancing type application-load-balancer)

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


Copy
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

Example bastion script executing commands on database

Connecting to resources

By referencing resources in connectTo list, Stacktape automatically injects environment variables (containing information about resources in the list) into the script:

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 the injected environment variables depends on the resource type:

Bucket: NAME, ARN
DynamoDB table: NAME, ARN, STREAM_ARN
MongoDB Atlas cluster: CONNECTION_STRING
Relational(SQL) database: 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: HOST, READER_HOST, PORT
Event bus: ARN
Function: ARN
Batch job: JOB_DEFINITION_ARN, STATE_MACHINE_ARN
User auth pool: ID, CLIENT_ID, ARN
SNS Topic: ARN, NAME
SQS Queue: ARN, NAME, URL
Upstash Kafka topic: TOPIC_NAME, TOPIC_ID, USERNAME, PASSWORD, TCP_ENDPOINT, REST_URL
Upstash Redis: HOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
Private service: ADDRESS
Web service: URL


Copy
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

Example config using script with connectTo

If you are using local-script-with-bastion-tunneling script, connections to selected resources listed in connectTo are tunneled through bastion host. This allows for accessing resources, which are only accessible from within the VPC and increases security of connection. Refer to bastion tunneling docs for more information.

Executing script

The script can be executed in 2 ways:

using script:run command


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

inside a hook

Environment

Most commonly used types of environment variables:

Static - string, number or boolean (will be stringified).
Result of a custom directive.
Referenced property of another resource (using $ResourceParam directive). To learn more, refer to referencing parameters guide. If you are using environment variables to inject information about resources into your script, see also property connectTo which simplifies this process.
Value of a secret (using $Secret directive).


Copy
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.

If specified, the script will be executed with the permissions of the specified resource.
Resource must already be deployed when the script is executed.
On the background, the script is injected with AWS environment variables which are automatically picked up by most of the AWS SDKs and CLIs.
Supported resource types include:
- function
- batch-job
- worker-service
- web-service
- private-service
- multi-container-workload
- nextjs-web


Copy
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

Script will have same AWS IAM permissions as myFunction

API reference

LocalScript API reference

type

Required

properties.executeScript

properties.executeCommand

properties.executeScripts

properties.executeCommands

properties.cwd

properties.pipeStdio

Default: true

properties.connectTo

properties.environment

properties.assumeRoleOfResource

LocalScriptWithBastionTunneling API reference

type

Required

properties.bastionResource

properties.executeScript

properties.executeCommand

properties.executeScripts

properties.executeCommands

properties.cwd

properties.pipeStdio

Default: true

properties.connectTo

properties.environment

properties.assumeRoleOfResource

BastionScript API reference

type

Required

properties.bastionResource

properties.executeCommand

properties.executeCommands

properties.cwd

properties.connectTo

properties.environment

properties.assumeRoleOfResource

EnvironmentVar API reference

Parent:LocalScript

name

Required

value

Required