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

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

Containers

Every container workload consists of 1 or multiple containers.

You can configure the following properties of your container:

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.

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

Built from a Dockerfile

• Stacktape builds the image using the specified Dockerfile.
• During the deployment, Stacktape pushes the image to the stack's private AWS container registry.
• If you are not familiar with Docker or writing Dockerfiles, you can refer to Docker's official guide on writing Dockerfiles.

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

Pre-built ahead of time

• Pre-built image from the Docker registry is used. Stacktape does not build the image for you.

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:

• static - any value (will be stringified)
• result of a custom directive Learn more about directives
• referenced property of another resource (using $Param directive) Learn more about referencing resources
• secret (using $Secret directive) Learn more about using secrets

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')"

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.

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

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

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.

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

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

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

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.

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

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

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'

Default VPC connection

• Certain AWS services (such as MongoDb Atlas Clusters) must be connected to a VPC (Virtual private cloud) to be able to run. For stacks that include these resources, Stacktape does 2 things:
  • creates a default VPC
  • connects the VPC-requiring resources to the default VPC.
• Container workloads are connected to the default VPC of your stack by default. This means that container workloads can communcate with resources that have their accessibility mode set to vpc without any extra configuration.
• To learn more about VPCs and accessibility modes, refer to VPC docs, accessing relational databases, accessing redis clusters and accessing MongoDb Atlas clusters.

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