A multi-container workload is a compute resource that runs one or more containers continuously. Unlike functions and batch jobs, which are event-driven, container workloads are designed for long-running applications and scale based on CPU and memory usage.

Like other Stacktape compute resources, container workloads are serverless, meaning you don't need to manage the underlying infrastructure. You can provide your container image by building it from source code, using a Dockerfile, or pulling a pre-built image.

Workloads run securely within a VPC, and you can expose container ports to the internet using integrations with HTTP API Gateways and Load Balancers.

Under the hood

Stacktape uses AWS Elastic Container Service (ECS) to orchestrate containers. You can run your containers using two launch types:

• Fargate: A serverless compute engine that runs containers without requiring you to manage servers.
• EC2 instances: Virtual machines that give you more control over the operating environment.

ECS services are self-healing, automatically replacing any unhealthy container instances. They also provide auto-scaling out of the box.

When to use

If you're unsure which compute resource to use, this table provides a comparison of container-based resources in Stacktape:

Resource type	Description	Use-cases
web-service	continuously running container with public endpoint and URL	public APIs, websites
private-service	continuously running container with private endpoint	private APIs, services
worker-service	continuously running container not accessible from outside	continuous processing
multi-container-workload	custom multi container workload - you can customize accessibility for each container	more complex use-cases requiring customization
batch-job	simple container job - container is destroyed after job is done	one-off/scheduled processing jobs

Advantages

• Control over environment: You can run any Docker image or build from your own Dockerfile.
• Cost-effective for predictable loads: More economical than functions for applications with consistent traffic.
• Load-balanced and auto-scalable: Automatically scales horizontally based on CPU and memory utilization.
• High availability: Runs in multiple Availability Zones for resilience.
• Secure by default: The underlying environment is securely managed by AWS.

Disadvantages

• Slower scaling: Adding new container instances takes longer than scaling functions.
• Not fully serverless: Cannot scale to zero, meaning you will always pay for at least one running instance.

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}`);
});

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

Containers

Every workload consists of one or more containers. You can configure the following properties for each container:

Image

You can provide a container image in four ways:

• stacktape-image-buildpack
• external-buildpack
• custom-dockerfile
• prebuilt-images

Environment variables

environment:
  - name: STATIC_ENV_VAR
    value: my-env-var
  - name: DYNAMICALLY_SET_ENV_VAR
    value: $MyCustomDirective('input-for-my-directive')
  - name: DB_HOST
    value: $ResourceParam('myDatabase', 'host')
  - name: DB_PASSWORD
    value: $Secret('dbSecret.password')

Dependencies between containers

You can define dependencies between containers to control their startup order.

For example, the frontend container will only start after the backend container is running successfully.

resources:
  myApiGateway:
    type: http-api-gateway

  myMultiContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: frontend-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: 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
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/server/index.ts
          environment:
            - name: PORT
              value: 3000
          events:
            - type: workload-internal
              properties:
                containerPort: 3000
      resources:
        cpu: 2
        memory: 2048

Healthcheck

A health check monitors the container from within. If an essential container becomes unhealthy, the entire instance is automatically replaced.

resources:
  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
          internalHealthCheck:
            healthCheckCommand: ['CMD-SHELL', 'curl -f http://localhost/ || exit 1']
            intervalSeconds: 20
            timeoutSeconds: 5
            startPeriodSeconds: 150
            retries: 2
      resources:
        cpu: 2
        memory: 2048

Shutdown

When a container instance is shut down, all containers receive a SIGTERM signal, giving them a chance to clean up gracefully. By default, they have 2 seconds before a SIGKILL signal is sent. You can adjust this with the stopTimeout property.

process.on('SIGTERM', () => {
  console.info('Received SIGTERM signal. Cleaning up and exiting process...');

  // Finish any outstanding requests, or close a database connection...

  process.exit(0);
});

Logging

Any output to stdout or stderr is captured and stored in a CloudWatch log group. You can view logs through the Stacktape Console, the stacktape stack-info command, or by streaming them with the stacktape logs command.

Forwarding logs

You can forward logs to third-party services. See the Log Forwarding documentation for more details.

Events

Events route traffic from an integration to a specified port on your container.

HTTP API event

Forwards requests from an HTTP API Gateway.

resources:
  myApiGateway:
    type: http-api-gateway

  myApp:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
          events:
            - type: http-api-gateway
              properties:
                httpApiGatewayName: myApiGateway
                containerPort: 80
                path: '/my-path'
                method: GET
      resources:
        cpu: 2
        memory: 2048

Application Load Balancer event

Forwards requests from an Application Load Balancer. This allows for advanced routing based on path, query parameters, headers, and more.

resources:
  myLoadBalancer:
    type: application-load-balancer

  myApp:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
          events:
            - type: application-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                containerPort: 80
                priority: 1
                paths: ['*']
      resources:
        cpu: 2
        memory: 2048

Network Load Balancer event

Forwards traffic from a Network Load Balancer.

resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      listeners:
        - port: 8080
          protocol: TLS

  myWorkload:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: container1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: containers/ts-container.ts
          events:
            - type: network-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 8080
                containerPort: 8080
      resources:
        cpu: 0.25
        memory: 512

Internal port (workload-internal)

Opens a port for communication with other containers within the same workload.

resources:
  myApiGateway:
    type: http-api-gateway

  myApp:
    type: multi-container-workload
    properties:
      containers:
        - name: frontend
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: 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
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/backend/index.ts
          environment:
            - name: PORT
              value: 3000
          events:
            - type: workload-internal
              properties:
                containerPort: 3000
      resources:
        cpu: 2
        memory: 2048

Private port (service-connect)

Opens a port for communication with other workloads in the same stack.

resources:
  internalService:
    type: multi-container-workload
    properties:
      containers:
        - name: api
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/private/index.ts
          events:
            - type: service-connect
              properties:
                containerPort: 3000
      resources:
        cpu: 2
        memory: 2048

  publicService:
    type: multi-container-workload
    properties:
      containers:
        - name: api
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/public/index.ts
      resources:
        cpu: 2
        memory: 2048

Resources

You can specify the CPU, memory, and EC2 instance types for your workload.

Using Fargate

If you omit the instanceTypes property, your workload will run on Fargate.

resources:
  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
      resources:
        cpu: 0.25
        memory: 512

Using EC2 instances

If you specify instanceTypes, your workload will run on EC2 instances.

resources:
  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
      resources:
        instanceTypes:
          - c5.large

Placing containers on EC2

Stacktape optimizes for 100% utilization of your EC2 instances. If you specify cpu and memory, AWS uses a binpack strategy to place as many workload instances as possible onto the available EC2 instances.

Using warm pool

Enable a warm pool to keep pre-initialized EC2 instances in a stopped state, ready for faster scaling. This is only supported for workloads with a single instance type.

resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        instanceTypes:
          - c5.large
        enableWarmPool: true

Scaling

Configure the minimum and maximum number of concurrent workload instances and define a scaling policy based on CPU and memory utilization.

Scaling policy

A scaling policy triggers scaling actions when CPU or memory thresholds are crossed. The workload scales out aggressively when metrics are high and scales in more cautiously when they are low.

resources:
  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: container-1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/cont1/index.ts
          events:
            - type: http-api-gateway
              properties:
                httpApiGatewayName: myApiGateway
                containerPort: 80
                method: '*'
                path: '*'
        - name: container-2
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/cont1/index.ts
          events:
            - type: workload-internal
              properties:
                containerPort: 3000
      resources:
        cpu: 0.5
        memory: 1024
      scaling:
        minInstances: 1
        maxInstances: 5
        scalingPolicy:
          keepAvgMemoryUtilizationUnder: 80
          keepAvgCpuUtilizationUnder: 80

Storage

Each workload instance has 20GB of ephemeral storage, which is shared among all containers within that instance. This storage is deleted when the instance is removed. For persistent storage, use Buckets.

Accessing other resources

By default, workloads cannot access other AWS resources. You must grant permissions using IAM.

Using connectTo

The connectTo property is a simplified way to grant access to other Stacktape-managed resources.

resources:
  photosBucket:
    type: bucket

  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: apiContainer
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: sr/index.ts
      connectTo:
        # access to the bucket
        - photosBucket
        # access to AWS SES
        - aws:ses
      resources:
        cpu: 0.25
        memory: 512

Using iamRoleStatements

For fine-grained control, you can provide raw IAM role statements.

resources:
  myContainerWorkload:
    type: multi-container-workload
    properties:
      containers:
        - name: apiContainer
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: server/index.ts
      iamRoleStatements:
        - Resource:
            - $CfResourceParam('NotificationTopic', 'Arn')
          Effect: 'Allow'
          Action:
            - 'sns:Publish'
      resources:
        cpu: 2
        memory: 2048

cloudformationResources:
  NotificationTopic:
    Type: 'AWS::SNS::Topic'

Deployment strategies

By default, Stacktape uses a rolling update strategy. You can choose a different strategy using the deployment property.

resources:
  myLoadBalancer:
    type: application-load-balancer

  myApp:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
          events:
            - type: application-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                containerPort: 80
                priority: 1
                paths: ['*']
      resources:
        cpu: 2
        memory: 2048
      deployment:
        strategy: Canary10Percent5Minutes

Hook functions

You can use hook functions to perform checks during deployment, including sending test traffic to a new version before it receives production traffic.

resources:
  myLoadBalancer:
    type: application-load-balancer

  myApp:
    type: multi-container-workload
    properties:
      containers:
        - name: api-container
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: src/index.ts
          events:
            - type: application-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                containerPort: 80
                priority: 1
                paths: ['*']
      resources:
        cpu: 2
        memory: 2048
      deployment:
        strategy: Canary10Percent5Minutes
        afterTrafficShiftFunction: validateDeployment

  validateDeployment:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: src/validate-deployment.ts

import { CodeDeployClient, PutLifecycleEventHookExecutionStatusCommand } from '@aws-sdk/client-codedeploy';

const client = new CodeDeployClient({});

export default async (event) => {
  // read DeploymentId and LifecycleEventHookExecutionId from payload
  const { DeploymentId, LifecycleEventHookExecutionId } = event;

  // performing validations here

  await client.send(
    new PutLifecycleEventHookExecutionStatusCommand({
      deploymentId: DeploymentId,
      lifecycleEventHookExecutionId: LifecycleEventHookExecutionId,
      status: 'Succeeded' // status can be 'Succeeded' or 'Failed'
    })
  );
};

Default VPC connection

Container workloads are connected to the default VPC of your stack by default. This allows them to communicate with other VPC-enabled resources without extra configuration.

Referenceable parameters

Currently, no parameters can be referenced.

Pricing

You are charged for:

• Virtual CPU per hour
• Memory per hour

Pricing is rounded to the nearest second with a one-minute minimum. For details, see the Fargate pricing page.

API reference