Stacktape


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 security, 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

Copy

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

Copy

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

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
packaging
Required
essential
logging
dependsOn
environment
events
internalHealthCheck

Image

Environment variables

Most commonly used types of environment variables:

Copy

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

EnvironmentVar  API reference
Parent API reference: ContainerWorkloadContainer
name
Required
value
Required

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
condition
Required

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

Copy

resources:
myApiGateway:
type: http-api-gateway
myMultiContainerWorkload:
type: 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

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
intervalSeconds
Default: 30
timeoutSeconds
Default: 5
retries
Default: 3
startPeriodSeconds

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

Copy

resources:
myContainerWorkload:
type: 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 running container workload instance is deregistered (removed), all running containers receive a SIGTERM signal.
  • You then have 30 seconds to clean up. After 30 seconds, your process recives a SIGKILL signal.

Copy

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

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
ContainerWorkloadContainerLogging  API reference
Parent API reference: ContainerWorkloadContainer
disabled
retentionDays
Default: 90

Events

  • Events are used to route events (requests) from the configured integration to the specified port of your container.
  • Stacktape supports 3 different event sources (integrations):

HTTP API event

Forwards requests from the specified HTTP API Gateway.

ContainerWorkloadHttpApiIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required
properties.containerPort
Required
properties.httpApiGatewayName
Required
properties.method
Required
properties.path
Required
properties.authorizer
properties.payloadFormat
Default: '1.0'

  • Example: all incoming GET requests to myApiGateway with path /my-path will be routed to the port 80 of the api-container in myApp workload.

Copy

resources:
myApiGateway:
type: http-api-gateway
myApp:
type: 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

  • When the container-workload scales (i.e. there is more than one instance of workload), http-api-gateway distributes incoming requests to the instances randomly.

Application Load Balancer event

Forwards requests from the specified Application load balancer. Application load balancer integration allows you to filter and forward incoming requests based on any part of request including path, query params, headers and others.

ContainerWorkloadLoadBalancerIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required
properties.containerPort
Required
properties.loadBalancerName
Required
properties.priority
Required
properties.listenerPort
properties.paths
properties.methods
properties.hosts
properties.headers
properties.queryParams
properties.sourceIps
LbHeaderCondition  API reference
headerName
Required
values
Required
LbQueryParamCondition  API reference
paramName
Required
values
Required

Copy

resources:
myLoadBalancer:
type: application-load-balancer
myApp:
type: 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

All incoming requests will be routed to the port 80 of the api-container in myApp workload.

  • When the container-workload scales (i.e. there is more than one instance of workload), application-load-balancer distributes incoming requests to the instances in a round robin fashion.

Internal event

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

ContainerWorkloadInternalIntegration  API reference
Parent API reference: ContainerWorkloadContainer
type
Required
properties.containerPort
Required
  • 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.

Copy

resources:
myApiGateway:
type: http-api-gateway
myApp:
type: 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

Resources

  • You must configure computing resources (CPU and RAM) for your container workload.
  • Configured resources are valid for every container instance 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
memory

Copy

resources:
myContainerWorkload:
type: container-workload
properties:
containers:
- name: api-container
packaging:
type: stacktape-image-buildpack
properties:
entryfilePath: 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
maxInstances
Default: 1
initialInstances
Default: 1
scalingPolicy

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
keepAvgMemoryUtilizationUnder
Default: 80

Copy

resources:
myContainerWorkload:
type: 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

Example usage of scaling configuration

Graphical representation of scaling flow for above configuration
Graphical representation of scaling flow for above configuration

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" by design 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. You can further restrict the access to your relational databases by configuring their access control mode.

  • Stacktape automatically handles IAM permissions for the underlying AWS services that it creates (i.e. granting container workloads permission to write logs to Cloudwatch, allowing container workloads 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 container workload 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.

Copy

resources:
photosBucket:
type: bucket
myContainerWorkload:
type: container-workload
properties:
containers:
- name: apiContainer
packaging:
type: stacktape-image-buildpack
properties:
entryfilePath: sr/index.ts
accessControl:
allowAccessTo:
- photosBucket
resources:
cpu: 0.25
memory: 512

AccessControl  API reference
Parent API reference: ContainerWorkload
iamRoleStatements
allowAccessTo

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 container workload's role.
  • Allow you to set granular control over your container workload's permissions.
  • Can be used to give access to any Cloudformation resource

Copy

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

StpIamRoleStatement  API reference
Parent API reference: AccessControl
Resource
Required
Sid
Effect
Action
Condition

Default VPC connection

Referenceable parameters

Currently, no parameters can be referenced.

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
properties.containers
Required
properties.resources
Required
properties.scaling
properties.accessControl
overrides
CognitoAuthorizer  API reference
type
Required
properties.userPoolName
Required
properties.identitySources
LambdaAuthorizer  API reference
type
Required
properties.functionName
Required
properties.iamResponse
properties.identitySources
properties.cacheResultSeconds
StpIamRoleStatement  API reference
Parent API reference: AccessControl
Resource
Required
Sid
Effect
Action
Condition
Need help? Ask a question on SlackDiscord or info@stacktape.com.