logoStacktape docs




Container workloads

Overview and basic concepts

  • Container workload is a computing resource - it runs your code. Unlike functions and batch jobs, container workloads run continuously and scale based on the CPU and RAM usage.

  • Container workload can be composed of 1 or multiple running containers.

  • Similarly to functions and batch jobs, container workloads are serverless and fully managed. This means you don't have to worry about administration tasks such as provisioning and managing servers, scaling, VM secority, OS security & much more.

  • The container image can be supplied in 3 different ways:

    • built automatically from your source code by Stacktape
    • built using a supplied Dockerfile by Stacktape
    • pre-built images
  • Containers workloads are running securely within a Virtual Private Cloud (VPC). You can expose ports of your containers by routing traffic from HTTP API Gateways and Load balancers using event integrations.

When to use

Advantages

  • Control over underlying environment - Container workloads can run any Docker image or image built using your own Dockerfile.
  • Price for workloads with predictable load - Compared to functions, container workloads are cheaper if your workload has a predictable load.
  • Load-balanced and auto-scalable - Container workloads can automatically horizontally scale based on the CPU and Memory utilization.
  • High availability - Container workloads run in multiple Availability Zones.
  • Secure by default - Underlying environment is securely managed by AWS.

Disadvantages

  • Scaling speed - Unlike lambda functions that scale almost instantly, container workloads require more time - from several seconds to few minutes to add another container.

  • Not fully serverless - While container workloads can automatically scale up and down, they can't scale to 0. This means, if your workload is unused, you are still paying for at least one instance (minimum ~$5/month)

Basic usage

import express from 'express';
const app = express();
app.get('/', async (req, res) => {
res.send({ message: 'Hello' });
});
app.listen(process.env.PORT, () => {
console.info(`Server running on port ${process.env.PORT}`);
});

Example server container written in Typescript

resources:
mainGateway:
type: http-api-gateway
apiServer:
type: container-workload
properties:
resources:
cpu: 2
memory: 2048
scaling:
minInstances: 1
maxInstances: 5
containers:
- name: api-container
imageConfig:
filePath: src/main.ts
environment:
- name: PORT
value: 3000
events:
- type: http-api-gateway
properties:
method: '*'
path: /{proxy+}
containerPort: 3000
httpApiGatewayName: mainGateway

Container connected to HTTP API Gateway

Containers

Every container workload consists of 1 or multiple containers.

You can configure the following properties of your container:

name
Required

Arbitrary name of the container

Type: string

  • Must be unique within the container workload

imageConfig
Required

Configures an image used for this container

Type: (FilePathBasedImage or ContainerWorkloadDockerfileBasedImage or ContainerWorkloadPrebuiltImage)

essential

Determines if the container is essential (required for the workload to be considered healthy) within the workload

Type: boolean

  • If an essential container fails or stops for any reason, all containers of container workload instance are stopped.
  • As a result, this container workload instance is killed and replaced with a new instance.

logging

Configures logging behavior for this container

Type: ContainerWorkloadContainerLogging

  • Container logs (stdout and stderr) are automatically sent to a pre-created CloudWatch log group.
  • By default, logs are retained for 180 days..
  • You can browse your logs in 2 ways:
    • go to the log group page in the AWS CloudWatch console. You can use stacktape stack-info command to get a direct link.
    • use stacktape logs command to print logs to the console

dependsOn

List of other container that this container depends on

Type: Array of ContainerDependency

  • Defines relationship between the containers
  • Example: Another container needs to successfully start/finish before this container is started.

environment

Environment variables injected to the batch job's environment

Type: Array of EnvironmentVar

  • Environment variables are often used to inject information about other parts of the infrastrucutre (such as database URLs, secrets, etc.).

events

Configures events that will be routed to this container

Type: Array of (ContainerWorkloadLoadBalancerIntegration or ContainerWorkloadHttpApiIntegration or ContainerWorkloadInternalIntegration)

Event integrations can be used to:

  • Enable communication between different containers of this container workload instance (Internal integration)
  • Deliver events (requests) from other infrastructure components to the container (HTTP API/Application Load Balancer integration)

internalHealthCheck

Configuration of internal healthcheck (used to determine, if the container workload instance is healthy)

Type: ContainerHealthCheck

  • If the container is essential and considered unhealthy, the entire container workload instance is killed and replaced with a new instance.

Image

  • Docker container is a running instance of an Docker image.
  • The image for your container can be supplied in 3 different ways:

Built from source code

  • Stacktape bundles your source code with all of its dependencies and builds the image for you.
  • During deployment, Stacktape pushes the image to the stack's private AWS container registry.
FilePathBasedImage  API reference
Parent API reference: ContainerWorkloadContainer
filePath
Required

Path to the entry point of your workload (relative to the stacktape config file)

Type: string

  • Stacktape tries to bundle all your source code with its dependencies into a single file.
  • If a certain dependency doesn't support static bundling (because it has binary, uses dynamic require() calls, etc.), Stacktape will install it copy it to the bundle

languageSpecificConfig

Configuration of packaging properties specific to given language

Type: ContainerLanguageSpecificConfig

includeFiles

Files that should be explicitly included in the deployment package (glob pattern)

Type: Array of string

  • Example glob pattern: images/*.jpg

excludeFiles

Files that should be explicitly excluded from deployment package (glob pattern)

Type: Array of string

Example glob pattern: images/*.jpg

dependenciesToIgnore

Dependencies to ignore.

Type: Array of string

  • These dependencies won't be a part of your deployment package.

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
filePath: src/index.ts

Built from a Dockerfile

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
dockerfilePath: src/Dockerfile
buildContextPath: src

ContainerWorkloadDockerfileBasedImage  API reference
Parent API reference: ContainerWorkloadContainer
buildContextPath
Required

Path to directory (relative to stacktape config file) used as build context

Type: string

entryPoint

Script to be executed when the container starts. Overrides ENTRYPOINT instruction in the Dockerfile.

Type: Array of string

dockerfilePath

Path to Dockerfile (relative to buildContextPath) used to build application image.

Type: string

buildArgs

List of arguments passed to the docker build command when building the image

Type: Array of DockerBuildArg

command

Command to be executed when the container starts. Overrides CMD instruction in the Dockerfile.

Type: Array of string

Pre-built ahead of time

  • Pre-built image from the Docker registry is used. Stacktape does not build the image for you.
ContainerWorkloadPrebuiltImage  API reference
Parent API reference: ContainerWorkloadContainer
image
Required

Name or the URL of the image used in this workload.

Type: string

repositoryCredentialsSecretArn

ARN (Amazon resource name) of the secret containing credentials for the private registry containing the image.

  • The body of the secret should have the following format: {"username" : "privateRegistryUsername", "password" : "privateRegistryPassword"}
  • Secrets can be managed directly using Stacktape with stacktape secrete-create, stacktape secrete-get and stacktape secrete-delete commands.

Type: string

entryPoint

Script to be executed when the container starts. Overrides ENTRYPOINT instruction in the Dockerfile.

Type: Array of string

command

Command to be executed when the container starts. Overrides CMD instruction in the Dockerfile.

Type: Array of string

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
image: my-repo/my-container

Environment variables

Most commonly used types of environment variables:

environment:
STATIC_ENV_VAR: 'my-env-var'
DYNAMICALLY_SET_ENV_VAR: "$MyCustomDirective('input-for-my-directive')"
DB_HOST: "$Param('myPgSql', 'DbInstance::Endpoint.Address')"
DB_PASSWORD: "$Secret('dbSecret.password')"

EnvironmentVar  API reference
Parent API reference: ContainerWorkloadContainer
name
Required

Name of the environment variable

Type: string

value
Required

Value of the environment variable

Type: (string or number or boolean)

Dependencies between containers

Containers in a workload often rely on each other. In many cases, one needs to be started or successfully finish its execution before the other container can start.

ContainerDependency  API reference
Parent API reference: ContainerWorkloadContainer
containerName
Required

Name of the container this container depends on

Type: string

condition
Required

State that the container must reach

Type: string ENUM

Possible values: COMPLETEHEALTHYSTARTSUCCESS

List of available conditions (states):

  • START: container has started its execution
  • COMPLETE: container completes it's execution (successfully or unsuccessfully). Process exit code is not taken into account.
  • SUCCESS: container successfully completes it's execution (with an exit code 0)
  • HEALTHY: container successfully passes it's first healthcheck. Requires healhchecks to be enabled


The following example shows:
  • usage of container dependency
  • frontend container won't start until the backend container has successfully starter.

resources:
myApiGateway:
type: http-api-gateway
myMultiContainerWorkload:
type: container-workload
properties:
containers:
- name: frontend-container
imageConfig:
filePath: src/client/index.ts
dependsOn:
- containerName: backend
condition: START
environment:
- name: PORT
value: 80
- name: API_COINTAINER_PORT
value: 3000
events:
- type: http-api-gateway
properties:
httpApiGatewayName: myApiGateway
containerPort: 80
path: '*'
method: '*'
- name: api-container
imageConfig:
filePath: src/server/index.ts
environment:
- name: PORT
value: 3000
events:
- type: workload-internal
properties:
containerPort: 3000

Healthcheck

The purpose of the container health check is to monitor the health of the container from the inside.

Once an essential container of an instance is determined UNHEALTHY, the instance is automatically replaced with a new one.

ContainerHealthCheck  API reference
Parent API reference: ContainerWorkloadContainer
healthCheckCommand
Required

Command to run that determines if the container is healthy

Type: Array of string

  • Must start with either:
    • CMD to execute the command arguments directly
    • CMD-SHELL to run the command with the container's default shell.
  • An exit code 0 indicates success, and non-zero exit code indicates failure.
  • Example: [ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]`

intervalSeconds
Default: 30

Time period in seconds between health check executions

Type: number

  • Must be between 5 and 300 seconds.

timeoutSeconds
Default: 5

The time period in seconds to wait for a health check to succeed before it is considered failed

Type: number

  • Must be between 2 and 60 seconds.

retries
Default: 3

The number of times to retry a failed health check before the container is considered unhealthy.

Type: number

  • Must be between 1 and 10 retries.

startPeriodSeconds

"Grace" period to give the container to bootstrap before failed health checks count towards the maximum number of retries.

Type: number

  • Must be between 0 and 300 seconds.
  • Disabled by default.


  • Example: A shell command sends a curl request every 20 seconds to determine if the service is available. If the request fails (or doesn't return in 5 seconds), the command returns with non-zero exit code, and the healtcheck is considered failed.

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
filePath: src/index.ts
internalHealthCheck:
healthCheckCommand: ['CMD-SHELL', 'curl -f http://localhost/ || exit 1']
intervalSeconds: 20
timeoutSeconds: 5
startPeriodSeconds: 150
retries: 2

Shutdown

  • When a running container workload instance is deregistered (removed), all running containers receives a SIGTERM signal.
  • You then have 30 seconds to clean up. After 30 seconds, your process recives a SIGKILL signal.

process.on('SIGTERM', () => {
console.info('Received SIGTERM signal. Cleaning up and exitting process...');
// Finish any outstanding requests, or close a database connection...
process.exit(0);
});

Cleaning up before container shutodown.

Logging

  • Every time your code outputs (prints) something to the stdout or stderr, your log will be captured and stored in a AWS CloudWatch log group.
  • You can browse your logs in 2 ways:
    • go to your container workload's log-group in the AWS CloudWatch console. You can use stacktape stack-info command to get a direct link.
    • use stacktape logs command that will print logs to the console

Trigger events

Events are used to router events (requests) to the specified port of your container.

There are 3 different event sources that can be routed to your container:

HTTP API Gateway

Forwards requests from the specified HTTP Api Gateway.

ContainerWorkloadHttpApiIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required

Type of the event integration

Type: string "http-api-gateway"

properties.containerPort
Required

Port of the container that will receive the traffic from this integration.

Type: number

properties.httpApiGatewayName
Required

Name of the HTTP API Gateway

Type: string

properties.method
Required

HTTP method that the request should match to be routed by this event integration

Type: string ENUM

Possible values: *DELETEGETHEADOPTIONSPATCHPOSTPUT

Can be either:

  • exact method (e.g. GET or PUT)
  • wildcard matching any method (*)

properties.path
Required

URL path that the request should match to be routed by this event integration

Type: string

Can be either:

  • Exact URL Path - e.g. /post
  • Path with a positional parameter - e.g. /post/{id}. This matches any id parameter, e.g. /post/6. The parameter will be available to the workload using event.pathParameters.id
  • Greedy path variable - e.g. /pets/{anything+}. This catches all child resources of the route. Example: /post/{anything+} catches both /post/something/param1 and /post/something2/param

properties.authorizer

Configures authorization rules for this event integration

Type: (CognitoAuthorizer or LambdaAuthorizer)

  • Only the authorized requests will be forwarded to the workload.
  • All other requests will receive { "message": "Unauthorized" }

properties.payloadFormat
Default: "1.0"

The format of the payload that the workload will receiveed with this integration.

Type: string ENUM

Possible values: 1.02.0

  • To learn more about the differences between the formats, refer to AWS Docs


  • Example: all incoming GET requests to myApiGw with path /my-path will be routed to the port 80 of myAppContainer

resources:
myApiGateway:
type: http-api-gateway
singleContainer:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
filePath: src/index.ts
events:
- type: http-api-gateway
properties:
httpApiGatewayName: myApiGateway
containerPort: 80
path: '/my-path'
method: GET

Application Load Balancer

Forwards requests from the specified Application load balancer. You can configure many aspects of this integration.

ContainerWorkloadLoadBalancerIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required

Type of the event integration

Type: string "application-load-balancer"

properties.containerPort
Required

Port of the container that will receive the traffic from this integration.

Type: number

properties.loadBalancerName
Required

Name of the Load balancer

Type: string

properties.listenerPort
Required

Port of the Load balancer listener

Type: number

properties.priority
Required

Priority of the integration

Type: number

  • Load balancers evaluate integrations according to priority.
  • If multiple event integrations match the same conditions (paths, methods ...), request will be forwarded to the event integration with the highest priority.

properties.paths

List of URL paths that the request should match to be routed by this event integration

Type: Array of string

  • The condition is satisfied if any of the paths matches the request URL
  • The maximum size is 128 characters
  • The comparison is case sensitive

The following patterns are supported:

  • basic URL path, i.e. /post
  • * - wildcard (matches 0 or more characters)
  • ? - wildcard (matches 1 or more characters)

properties.methods

List of HTTP methods that the request should match to be routed by this event integration

Type: Array of string

properties.hosts

List of hostnames that the request should match to be routed by this event integration

Type: Array of string

  • Hostname is parsed from the host header of the request

The following wildcard patterns are supported:

  • * - wildcard (matches 0 or more characters)
  • ? - wildcard (matches 1 or more characters)

properties.headers

List of header conditions that the request should match to be routed by this event integration

Type: Array of LbHeaderCondition

  • All conditions must be satisfied.

properties.queryParams

List of query parameters conditions that the request should match to be routed by this event integration

Type: Array of LbQueryParamCondition

  • All conditions must be satisfied.

properties.sourceIps

List of IP addresses that the request should match to be routed by this event integration

Type: Array of string

  • IP addresses must be in a CIDR format.
  • If a client is behind a proxy, this is the IP address of the proxy, not the IP address of the client.

LbHeaderCondition  API reference
headerName
Required

Header name

Type: string

values
Required

List of header values

Type: Array of string

  • The Condition is satisfied if at least one of the request headers matches the values in this list.

LbQueryParamCondition  API reference
paramName
Required

Name of the query parameter

Type: string

values
Required

List of query parameter values

Type: Array of string

  • The Condition is satisfied if at least one of the request query parameters matches the values in this list.

  • Example: all incoming requests to myLoadBalancer's port 443 (default HTTPS port) will be routed to the port 80 of the myAppContainer

resources:
myLoadBalancer:
type: application-load-balancer
properties:
interface: internet
listeners:
- port: 443
protocol: HTTPS
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
filePath: src/index.ts
events:
- type: application-load-balancer
properties:
loadBalancerName: myLoadBalancer
listenerPort: 443
containerPort: 80
priority: 1
paths: ['*']

Internal

Opens the specified port of the container for communication with other containers within this container workload.

ContainerWorkloadInternalIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required

Type of the event integration

Type: string "workload-internal"

properties.containerPort
Required

Port of the container that will receive the traffic from this integration.

Type: number

  • Example: backend container exposes port 3000, which is reachable from the frontend container, but not from the internet. Frontend container exposes its port 80 to the internet through the HTTP Api Gateway.

resources:
myApiGateway:
type: http-api-gateway
multiContainer:
type: container-workload
properties:
containers:
- name: frontend
imageConfig:
filePath: src/frontend/index.ts
dependsOn:
- containerName: backend
condition: START
environment:
- name: PORT
value: 80
- name: BACKEND_PORT
value: 3000
events:
- type: http-api-gateway
properties:
httpApiGatewayName: myApiGateway
containerPort: 80
path: /my-path
method: GET
- name: backend
imageConfig:
filePath: src/backend/index.ts
environment:
- name: PORT
value: 3000
events:
- type: workload-internal
properties:
containerPort: 3000

Resources

  • You must configure computing resources (CPU and RAM) for your container workload.
  • Configured resources are valid for every container instane in the container workload (if there are more than 1 instance running).
  • If your container workload has multiple containers, the assigned resources are shared between them.
ContainerWorkloadResourcesConfig  API reference
Parent API reference: ContainerWorkload
cpu

Number of virtual CPUs to use

Type: number ENUM

Possible values: 0.250.5124

  • CPU power is shared by all the containers in the container workload.
  • 1 vCPU costs ~$29/month (0.04$ per hour)

memory

Amount of memory in MB available to use

Type: number

  • Memory is shared by all the containers in the container workload.
  • Allowed memory configurations are dependent on the vCPU used:
    • 0.25 vCPU: 512, 1024, 2048
    • 0.5 vCPU: 1024, 2048, 3072, 4096
    • 1 vCPU: 2048, 3072, 4096, 5120, 6144, 7168, 8192
    • 2 vCPU: Between 4096 and 16384 GB in 1024-MB increments
    • 4 vCPU: Between 8192 and 30720 in 1024-MB increments

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
imageConfig:
filePath: src/index.ts
resources:
cpu: 0.25
memory: 512

Scaling

  • Configures scaling behavior of your container workload. You can configure:
    • Initial, minimum and maximum amount of concurrently running instances in your workload.
    • Conditions which trigger the scaling (up or down) using a scaling policy.
ContainerWorkloadScaling  API reference
Parent API reference: ContainerWorkload
minInstances
Default: 1

Minimum number of parallel instances that run your workload.

Type: number

maxInstances
Default: 1

Maximum number of parallel instances that run your workload.

Type: number

initialInstances
Default: 1

Initial number of parallel instances that run your workload.

Type: number

  • Amount of instances running your workload right after the deployment finishes.

scalingPolicy

Configures when the scaling is triggered

Type: ContainerWorkloadScalingPolicy

Scaling policy

  • A scaling policy specifies CPU and memory metric thresholds which trigger the scaling process.

  • Depending on the thresholds, the workload can either scale out (add instances) or scale in (remove instances).

  • If both keepAvgCpuUtilizationUnder and keepAvgMemoryUtilizationUnder are used, the workload will scale-out if one of the metrics is above the target value. However, to scale in, both of these metrics need to be below their respective target values.

  • Scaling policy is more aggressive in adding capacity then removing capacity. For example, if the policy's specified metric reaches its target value, the policy assumes that your application is already heavily loaded. So it responds by adding capacity proportional to the metric value as fast as it can. The higher the metric, the more capacity is added.

  • When the metric falls below the target value, the policy expects that utilization will eventually increase again. Therefore it slows down the scale-in process by removing capacity only when utilization passes a threshold that is far enough below the target value (usually 20% lower).

ContainerWorkloadScalingPolicy  API reference
Parent API reference: ContainerWorkloadScaling
keepAvgCpuUtilizationUnder
Default: 80

Maximum amount for CPU utilization after which the scale out (adding new instance) is triggered

Type: number

  • Utilization is calculated as an average utilization of all instances running in this container workload
  • Metrics are collected in 1 minute intervals
  • If average CPU utilization metric is below this value, the scale in is triggered (removing an instance)

keepAvgMemoryUtilizationUnder
Default: 80

Maximum amount for memory utilization after which the scale out is triggered (adding new instance)

Type: number

  • Utilization is calculated as an average utilization of all instances running in this container workload
  • Metrics are collected in 1 minute intervals
  • If average memory utilization metric is below this value, the scale in is triggered (removing an instance)

Storage

  • Each container workload instance has access to its own ephemeral storage. It's removed after the container workload instances is removed.
  • It has a fixed size of 20GB.
  • This storage is shared between all containers running in the container workload instance. However, if you have 2 concurrently running container workload intances, they do not share this storage.
  • To store data persistently, consider using Buckets.

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" 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. If the default, connection-string-based access-control is not sufficient for your use case, you can restrict connection to only resources in the same VPC. In that case, your function must join that VPC to access them.

  • Stacktape automatically handles IAM permissions for the underlying AWS services that it creates (i.e. granting functions permission to write logs to Cloudwatch, allowing functions to communicate with their event source and many others).


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

Using allowAccessTo

  • List of resource names that this function 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 (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.

resources:
photosBucket:
type: bucket
myContainerWorkload:
type: container-workload
properties:
containers:
- name: apiContainer
imageConfig:
filePath: sr/index.ts
accessControl:
allowAccessTo:
- photosBucket

AccessControl  API reference
Parent API reference: ContainerWorkload
iamRoleStatements

Raw AWS IAM role statements appended to your resources's role.

Type: Array of StpIamRoleStatement

allowAccessTo

Names of the resources that will recieve basic permissions.

Type: Array of string

Granted permissions:

Bucket

  • list objects in a bucket
  • create / get / delete / tag object in a bucket

DynamoDb Table

  • get / put / update / delete item in a table
  • scan / query a table
  • describe table stream

MongoDb Atlas Cluster

  • Allows connection to a cluster with accessibilityMode set to scoping-workloads-in-vpc. To learn more about MongoDb Atlas clusters accessibility modes, refer to MongoDB Atlas cluster docs.

Relational database

  • Allows connection to a relational database with accessibilityMode set to scoping-workloads-in-vpc. To learn more about relational database accessibility modes, refer to Relational databases docs.

Redis cluster

  • Allows connection to a redis cluster with accessibilityMode set to scoping-workloads-in-vpc. To learn more about redis cluster accessibility modes, refer to Redis clusters docs.

Event bus

  • publish events to the specified Event bus

Function

  • invoke the specified function

Batch job

  • submit batch-job instance into batch-job queue
  • list submitted job instances in a batch-job queue
  • describe / terminate a batch-job instance
  • list executions of state machine which executes the batch-job according to its strategy
  • start / terminate execution of a state machine which executes the batch-job according to its strategy


Granted permissions:

Bucket

  • list objects in a bucket
  • create / get / delete / tag object in a bucket

DynamoDb Table

  • get / put / update / delete item in a table
  • scan / query a table
  • describe table stream

MongoDb Atlas Cluster

  • Allows connection to a cluster with accessibilityMode set to scoping-workloads-in-vpc. To learn more about MongoDb Atlas clusters accessibility modes, refer to MongoDB Atlas cluster docs.

Relational database

  • Allows connection to a relational database with accessibilityMode set to scoping-workloads-in-vpc. To learn more about relational database accessibility modes, refer to Relational databases docs.

Redis cluster

  • Allows connection to a redis cluster with accessibilityMode set to scoping-workloads-in-vpc. To learn more about redis cluster accessibility modes, refer to Redis clusters docs.

Event bus

  • publish events to the specified Event bus

Function

  • invoke the specified function

Batch job

  • submit batch-job instance into batch-job queue
  • list submitted job instances in a batch-job queue
  • describe / terminate a batch-job instance
  • list executions of state machine which executes the batch-job according to its strategy
  • start / terminate execution of a state machine which executes the batch-job according to its strategy

Using iamRoleStatements

  • List of raw IAM role statement objects. These will be appended to the function's role.
  • Allow you to set granular control over your function's permissions.
  • Can be used to give access to any Cloudformation resource

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: apiContainer
imageConfig:
filePath: server/index.ts
accessControl:
iamRoleStatements:
- Resource:
- $Param('NotificationTopic', 'Arn')
Effect: 'Allow'
Action:
- 'sns:Publish'
cloudformationResources:
NotificationTopic:
Type: 'AWS::SNS::Topic'

StpIamRoleStatement  API reference
Parent API reference: AccessControl
Resource
Required

List of resources we want to access

Type: Array of string

  • See AWS reference here.

Sid

Statement identifier.

Type: string

  • See AWS reference here.

Effect

Effect of the statement

Type: string

  • See AWS reference here.

Action

List of actions allowed/denied by the statement

Type: Array of string

see AWS reference here.

Condition

No description

Type: UNSPECIFIED

Default VPC connection

Pricing

You are charged for:

  • Virtual CPU / hour:

    • depending on the region $0.04048 - $0.0696
  • Memory GB / hour:

    • depending on the region $0.004445 - $0.0076

The duration is rounded to 1 second with a 1 minute minimum. To learn more, refer to AWS Fargate pricing.

API reference

ContainerWorkload  API reference
type
Required

No description

Type: string "container-workload"

properties.containers
Required

List of containers that will run in this container workload.

Type: Array of ContainerWorkloadContainer

  • Container workload can have one or more containers
  • Multiple containers in the same container workload share computing resources and scale together

properties.resources
Required

Configures computing resources (CPU and memory) for this container workload

Type: ContainerWorkloadResourcesConfig

properties.scaling

Configures scaling how your container workload will scale

Type: ContainerWorkloadScaling

  • Scaling is done horizontally (adding more parallel instances), instead of vertically (increasing the power of the instance)
  • Incoming requests to your container are split between all available instances

properties.accessControl

Configures access to other resources of your stack (such as relational-databases, buckets, event-buses, etc.).

Type: AccessControl

overrides

Overrides one or more properties of the specified child resource.

Type: Object

  • Child resouces are specified using their descriptive name (e.g. DbInstance or Events.0.HttpApiRoute).
  • To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
  • To see the list of properties that can be overriden, refer to AWS Cloudformation docs.

ContainerLanguageSpecificConfig  API reference
Parent API reference: FilePathBasedImage
requiresGlibcBinaries

Builds image with support for glibc-based binaries

Type: boolean

-

  • You can use this option to add support for glibc-based native dependencies.
  • This means that Stacktape will use different (and significantly larger) base-image for your container.
  • Stacktape uses alpine Docker images by default. These images use musl, instead of glibc.
  • Packages with C-based binaries compiled using glibc doesn't work with musl.

tsConfigPath

Path to tsconfig.json file to use.

Type: string

This is used mostly to resolve path aliases.

emitTsDecoratorMetadata

Emits decorator metadata to the final bundle.

Type: boolean

  • This is used by frameworks like NestJS or ORMs like TypeORM.
  • This is not turned on by default, because it can slow down the build process.

dependenciesToExcludeFromBundle

Dependencies to exclude from main bundle.

Type: Array of string

  • These dependencies will be treated as external and won't be statically built into the main bundle
  • Instead, they will be installed and copied to the deployment package.
  • Using * means all of the workload's dependencies will be treated as external

DockerBuildArg  API reference
argName
Required

Argument name

Type: string

value
Required

Argument value

Type: string

CognitoAuthorizer  API reference
type
Required

No description

Type: string "cognito"

properties.userPoolName
Required

No description

Type: string

properties.identitySources

No description

Type: Array of string

LambdaAuthorizer  API reference
type
Required

No description

Type: string "lambda"

properties.lambdaName
Required

No description

Type: string

properties.iamResponse

No description

Type: boolean

properties.identitySources

No description

Type: Array of string

properties.cacheResultSeconds

No description

Type: number

StpIamRoleStatement  API reference
Parent API reference: AccessControl
Resource
Required

List of resources we want to access

Type: Array of string

  • See AWS reference here.

Sid

Statement identifier.

Type: string

  • See AWS reference here.

Effect

Effect of the statement

Type: string

  • See AWS reference here.

Action

List of actions allowed/denied by the statement

Type: Array of string

see AWS reference here.

Condition

No description

Type: UNSPECIFIED