Scripts
Introduction
- Scripts are used to execute your custom scripts - either shell commands or scripts written in
Javascript
,Typescript
orPython
. - Scripts are executed either by script:run command or inside a hook.
- Benefits of running scripts using Stacktape instead of directly:
- Scripts can be reused by all your team members.
- You can inject the result of a directive to the script's environment variable.
- Scripts are executed on the same host from which the stacktape command was executed. If you want to execute a script remotely as a part of the stack operation, use a stack-script.
Defining script action
The script must define either executeCommand
or executeScript
property.
executeCommand
- Executes the specified command in a separate shell process. Uses
/bin/bash
on UNIX systems and default shell(usuallycmd.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
orexecuteCommands
can be configured.
Copy
scripts:buildWeb:executeCommand: npx gatsby build
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 Typescriptpython
for Python
- Only one of
executeScript
,executeScripts
,executeCommand
orexecuteCommands
can be configured.
Copy
scripts:sendSlackNotification: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 IDconst 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});})();
Executing script
The script can be executed in 2 ways:
using script:run command
Copy
stacktape script:run --scriptName <<scriptName>>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.
- Value of a secret (using $Secret directive).
Copy
scripts:migrateDb:executeScript: scripts/migrate-db.tsenvironment:- name: DB_CONNECTION_STRINGvalue: $ResourceParam('mainDatabase', 'connectionString')resources:mainDatabase:type: relational-databaseproperties:credentials:masterUserName: admin_usermasterUserPassword: my_secret_passwordengine:type: mysqlproperties:primaryInstance:instanceSize: db.t2.micro
Accessing private resources in VPC
Some resources, such as relational databases, redis clusters, might not have public endpoint, but you still need to access them from your scripts or to perform management tasks.
For these cases, you can use bastion resource together with bastion tunnel.
You can use bastion tunnels to give your script/command access to resources, which are only accessible from within the VPC (private network of your stack).
- When using bastion tunnel, Stacktape sets up port-forwarding tunnel through the specified bastion host.
- To use bastion tunnels, your stack must contain
bastion
resource. - Tunneling is performed using secure SSM session.
- Environment variables passed to the script are automatically adjusted to use the tunneled endpoints.
Copy
scripts:migrateDb:executeCommands:- python manage.py makemigrations- python manage.py migratebastionTunnels:- bastion: myBastiontarget: mainDatabase# injected environment variables are automatically adjusted during the script/command execution to use the tunneled endpointenvironment:- name: STP_MAIN_DATABASE_CONNECTION_STRINGvalue: $ResourceParam('mainDatabase', 'connectionString')hooks:afterDeploy:- executeNamedScript: migrateDbresources:myBastion:type: bastionmainDatabase:type: relational-databaseproperties:accessibility:accessibilityMode: vpccredentials:masterUserName: admin_usermasterUserPassword: my_secret_passwordengine:type: aurora-postgresql-serverless
Using bastion tunnel to perform migration on VPC protected database
API reference
Script API reference
executeScript
executeCommand
executeScripts
executeCommands
environment
bastionTunnels
cwd
pipeStdio
Default: true
EnvironmentVar API reference
Parent:Script
name
Required
value
Required