Worker Services



A worker service is a continuously running container that is not directly accessible from outside your stack. It's ideal for background jobs, such as processing items from a message queue or handling other asynchronous tasks.

Key features include:

  • Automatic scaling: Scales based on CPU or memory usage.
  • Zero-downtime deployments: New versions are deployed without interrupting the service.
  • Flexible container images: Supports various methods for providing a container image, including auto-packaging for popular languages.
  • Fully managed: No need to manage servers, operating systems, or virtual machines.
  • Seamless connectivity: Easily connects to other resources within your stack.

How it works

Stacktape uses AWS Elastic Container Service (ECS) to run your containers on either Fargate or EC2 instances.

  • Fargate is a serverless compute engine that runs containers without requiring you to manage the underlying servers.
  • EC2 instances are virtual servers that give you more control over the computing environment.

ECS services are self-healing, automatically replacing any container that fails. They also scale automatically based on the rules you define.

When to use it

This table helps you choose the right container-based resource for your needs:

Resource typeDescriptionUse-cases
web-serviceA container with a public endpoint and URL.Public APIs, websites
private-serviceA container with a private endpoint, accessible only within your stack.Private APIs, internal services
worker-serviceA container that runs continuously but is not directly accessible.Background processing, message queue consumers
multi-container-workloadA customizable workload with multiple containers, where you define the accessibility of each one.Complex, multi-component services
batch-jobA container that runs a single job and then terminates.One-off or scheduled data processing tasks

Advantages

  • Control over the environment: Runs any Docker image or an image built from a Dockerfile.
  • Cost-effective for predictable loads: Cheaper than Lambda functions for services with steady traffic.
  • Load-balanced and scalable: Automatically scales horizontally based on CPU and memory usage.
  • Highly available: Runs across multiple Availability Zones to ensure resilience.
  • Secure by default: The underlying environment is managed and secured by AWS.

Disadvantages

  • Slower scaling: Adding new container instances can take several seconds to a few minutes, which is slower than the nearly-instant scaling of Lambda functions.
  • Not fully serverless: Cannot scale down to zero. You pay for at least one running instance (starting at ~$8/month), even if it's idle.

Basic usage

Here's a basic example of a worker service configuration:

resources:
  myWorkerService:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048

Example worker service configuration.

And here's the corresponding application code:

import myContinuouslyRunningApp from './my-app';

const app = myContinuouslyRunningApp();

app.run();

Example worker container in TypeScript (main.ts).


WorkerServiceAPI reference
typeRequired
No description

Type: string "worker-service"

properties.packagingRequired

Configures the container image for the service.

Type: ContainerWorkloadContainerPackaging

properties.resourcesRequired

CPU, memory, and compute engine for the container.

Type: ContainerWorkloadResourcesConfig

Two compute engines:

  • Fargate (default): Serverless — just specify cpu and memory.
  • EC2: Specify instanceTypes for more control and potentially lower cost.
properties.environment

Environment variables injected into the container at runtime.

Type: Array of EnvironmentVar

Use for configuration like API keys, feature flags, or secrets. Variables from connectTo (e.g., STP_MY_DATABASE_CONNECTION_STRING) are added automatically.

properties.logging

Logging configuration.

Type: ContainerWorkloadContainerLogging

Container output (stdout/stderr) is automatically sent to CloudWatch and retained for 90 days. View logs with stacktape logs or in the Stacktape Console.

properties.scaling

Auto-scaling: add/remove container instances based on demand.

Type: ContainerWorkloadScaling

Traffic is automatically distributed across all running containers.

properties.internalHealthCheck

Health check that auto-replaces unhealthy containers.

Type: ContainerHealthCheck

If a container fails the health check, it's terminated and replaced automatically.

properties.stopTimeoutDefault: 2

Seconds to wait for graceful shutdown before force-killing the container.

Type: number

The container receives SIGTERM first, then SIGKILL after this timeout. Must be 2-120.

properties.enableRemoteSessions

Allow SSH-like access to running containers for debugging.

Type: boolean

Enables stacktape container:session to open an interactive shell inside the container. Adds a small SSM agent that uses minimal CPU/memory.

properties.volumeMounts

Persistent EFS volumes shared across containers and restarts.

Type: Array of ContainerEfsMount

Data stored in EFS volumes persists even when containers are replaced. Multiple containers can mount the same volume. All data is encrypted in transit.

properties.sideContainers

Helper containers that run alongside the main container.

Type: Array of ServiceHelperContainer

  • run-on-init: Runs to completion before the main container starts (e.g., database migrations).
  • always-running: Runs for the entire lifecycle (e.g., log forwarders, monitoring agents). Can reach the main container via localhost.
properties.usePrivateSubnetsWithNAT

Deploy in private subnets with a static outbound IP via NAT Gateway.

Type: boolean

The container won't have a public IP. All outbound traffic routes through a NAT Gateway, giving you a static IP you can whitelist in external services (APIs, payment gateways, etc.).

Configure the number of NAT Gateways in stackConfig.vpc.nat.

Adds cost: NAT Gateway ~$32/month + data processing fees.

properties.connectTo

Give this resource access to other resources in your stack.

Type: Array of string

List the names of resources this workload needs to communicate with. Stacktape automatically:

  • Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
  • Opens network access (security group rules for databases, Redis)
  • Injects environment variables with connection details: STP_[RESOURCE_NAME]_[PARAM]

Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.

properties.iamRoleStatements

Raw IAM policy statements for permissions not covered by connectTo.

Type: Array of StpIamRoleStatement

Added as a separate policy alongside auto-generated permissions. Use this for accessing AWS services directly (e.g., Rekognition, Textract, Bedrock).

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true

Image

A worker service runs a Docker image. You can provide this image in four ways:

Environment variables

A list of environment variables to pass to the script or command.

Values can be:

resources:
  myWorkerService:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      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')
      resources:
        cpu: 2
        memory: 2048
EnvironmentVarAPI referenceParent:WorkerService or ServiceHelperContainer
nameRequired

Environment variable name (e.g., DATABASE_URL, API_KEY).

Type: string

valueRequired

Environment variable value. Numbers and booleans are converted to strings.

Type: string or number or boolean


Health check

Health checks monitor your container to ensure it's running correctly. If a container fails its health check, it's automatically terminated and replaced with a new one.

ContainerHealthCheckAPI referenceParent:WorkerService or ServiceHelperContainer
healthCheckCommandRequired

Command to check health. E.g., ["CMD-SHELL", "curl -f http://localhost/ || exit 1"]. Exit 0 = healthy.

Type: Array of string

intervalSecondsDefault: 30

Seconds between health checks (5-300).

Type: number

timeoutSecondsDefault: 5

Seconds before a check is considered failed (2-60).

Type: number

retriesDefault: 3

Consecutive failures before marking unhealthy (1-10).

Type: number

startPeriodSeconds

Grace period (seconds) before counting failures. Gives the container time to start (0-300).

Type: number


For example, this health check uses curl to send a request to the service every 20 seconds. If the request fails or takes longer than 5 seconds, the check is considered failed.

resources:
  myWorkerService:
    type: worker-service
    properties:
      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 service instance is shut down (for example, during a deployment or when the stack is deleted), all of its containers receive a SIGTERM signal. This gives your application a chance to shut down gracefully.

By default, the application has 2 seconds to clean up before it's forcefully stopped with a SIGKILL signal. You can change this with the stopTimeout property (from 2 to 120 seconds).

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

Example of a cleanup function that runs before the container shuts down.

Logging

Anything your application writes to stdout or stderr is captured and stored in AWS CloudWatch.

You can view logs in a few ways:

  • Stacktape Console: Find a direct link to the logs in the Stacktape Console.
  • Stacktape CLI: Use the stacktape logs command to stream logs to your terminal.
  • AWS Console: Browse logs directly in the AWS CloudWatch console. The stacktape stack-info command can provide a link.

Log storage can be expensive. To manage costs, you can configure retentionDays to automatically delete logs after a certain period.

ContainerWorkloadContainerLoggingAPI referenceParent:WorkerService or ServiceHelperContainer
disabled

Disable logging to CloudWatch.

Type: boolean

retentionDaysDefault: 90

How many days to keep logs.

Type: number ENUM

Possible values: 13571430609012015018036540054573118273653

logForwarding

Forward logs to an external service (Datadog, Highlight.io, or any HTTP endpoint).

Type: HttpEndpointLogForwarding or HighlightLogForwarding or DatadogLogForwarding

Uses Kinesis Data Firehose (~$0.03/GB). Failed deliveries go to a backup S3 bucket.

Forwarding logs

You can forward logs to third-party services. See Forwarding Logs for more information.


Compute resources

In the resources section, you configure the CPU, memory, and instance types for your service. You can run your containers using either Fargate or EC2 instances.

  • Fargate is a serverless option that lets you run containers without managing servers. You only need to specify the cpu and memory your service requires. It's a good choice for applications that need to meet high security standards like PCI DSS Level 1 and SOC 2.
  • EC2 instances are virtual servers that give you more control. You choose the instance types that best fit your needs, and ECS places your containers on them.

Regardless of whether you use Fargate or EC2 instances, your containers run securely within a VPC.

Two compute engines:

  • Fargate (default): Serverless — just specify cpu and memory.
  • EC2: Specify instanceTypes for more control and potentially lower cost.
ContainerWorkloadResourcesConfigAPI referenceParent:WorkerService
cpu

VCPUs for the workload (Fargate). Ignored when using instanceTypes.

Type: number ENUM

Possible values: 0.250.5124816

memory

Memory in MB. Must be compatible with the vCPU count on Fargate.

Type: number

Fargate valid combos: 0.25 vCPU → 512-2048 MB, 0.5 → 1024-4096, 1 → 2048-8192, 2 → 4096-16384, 4 → 8192-30720, 8 → 16384-61440, 16 → 32768-122880. For EC2: auto-detected from instance type if omitted.

instanceTypes

EC2 instance types for the workload (e.g., t3.medium, c6g.large). Use instead of cpu/memory.

Type: Array of string

First type in the list is preferred. Instances auto-scale and are refreshed weekly for patching. Tip: specify a single type and omit cpu/memory for optimal sizing.

enableWarmPool

Keep pre-initialized EC2 instances ready for faster scaling. Only works with a single instance type.

Type: boolean

architectureDefault: 'x86_64'

CPU architecture for Fargate. arm64 is ~20% cheaper. Ignored when using instanceTypes.

Type: string ENUM

Possible values: arm64x86_64

Using Fargate

To use Fargate, specify cpu and memory in the resources section without including instanceTypes.

resources:
  myWorkerService:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        cpu: 0.25
        memory: 512

Example of a service running on Fargate.

Using EC2 instances

To use EC2 instances, specify a list of instanceTypes in the resources section.

First type in the list is preferred. Instances auto-scale and are refreshed weekly for patching. Tip: specify a single type and omit cpu/memory for optimal sizing.

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

Example of a service running on EC2 instances.

Container placement on EC2

Stacktape tries to use your EC2 instances as efficiently as possible.

  • If you specify instanceTypes without cpu and memory, Stacktape configures each service instance to use the full resources of one EC2 instance. When the service scales out, a new EC2 instance is added for each new service instance.
  • If you specify cpu and memory, AWS will place multiple service instances on a single EC2 instance if there's enough capacity, maximizing utilization.

Default CPU and memory for EC2

  • If cpu is not specified, containers on an EC2 instance share its CPU capacity.
  • If memory is not specified, Stacktape sets the memory to the maximum amount available on the smallest instance type in your instanceTypes list.

Using a warm pool

A warm pool keeps pre-initialized EC2 instances in a stopped state, allowing your service to scale out much faster. This is useful for handling sudden traffic spikes. You only pay for the storage of stopped instances, not for compute time.

To enable it, set enableWarmPool to true. This feature is only available when you specify exactly one instance type.

For more details, see the AWS Auto Scaling warm pools documentation.

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

Scaling

The scaling section lets you control how your service scales. You can set the minimum and maximum number of running instances and define a policy that triggers scaling actions.

ContainerWorkloadScalingAPI referenceParent:WorkerService
minInstancesDefault: 1

Minimum running instances. Set to 0 is not supported — minimum is 1.

Type: number

maxInstancesDefault: 1

Maximum running instances. Traffic is distributed across all instances.

Type: number

scalingPolicy

When to scale: CPU and/or memory utilization targets.

Type: ContainerWorkloadScalingPolicy

Scaling policy

A scaling policy defines the CPU and memory thresholds that trigger scaling.

  • Scaling out (adding instances): The service scales out if either the average CPU or memory utilization exceeds the target you set.
  • Scaling in (removing instances): The service scales in only when both CPU and memory utilization are below their target values.

The scaling process is more aggressive when adding capacity than when removing it. This helps ensure your application can handle sudden increases in load, while scaling in more cautiously to prevent flapping (scaling in and out too frequently).

ContainerWorkloadScalingPolicyAPI referenceParent:ContainerWorkloadScaling
keepAvgCpuUtilizationUnderDefault: 80

Scale out when avg CPU exceeds this %, scale in when it drops below.

Type: number

keepAvgMemoryUtilizationUnderDefault: 80

Scale out when avg memory exceeds this %, scale in when it drops below.

Type: number

resources:
  myWorkerService:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        cpu: 0.5
        memory: 1024
      scaling:
        minInstances: 1
        maxInstances: 5
        scalingPolicy:
          keepAvgMemoryUtilizationUnder: 80
          keepAvgCpuUtilizationUnder: 80

Example of a scaling configuration.

Storage

Each service instance has its own temporary, or ephemeral storage, with a fixed size of 20GB. This storage is deleted when the instance is removed. Different instances of the same service do not share their storage.

For persistent data storage, use Buckets.

Accessing other resources

By default, AWS resources cannot communicate with each other. Access must be granted using IAM permissions.

Stacktape automatically configures the necessary permissions for the services it manages. For example, it allows a worker service to write logs to CloudWatch.

However, if your application needs to access other resources, you must grant permissions manually. You can do this in two ways:

Using connectTo

The connectTo property lets you grant access to other Stacktape-managed resources by simply listing their names. Stacktape automatically configures the required IAM permissions and injects connection details as environment variables into your service.

resources:
  photosBucket:
    type: bucket

  myWorkerService:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      connectTo:
        # access to the bucket
        - photosBucket
        # access to AWS SES
        - aws:ses
      resources:
        cpu: 0.25
        memory: 512

List the names of resources this workload needs to communicate with. Stacktape automatically:

  • Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
  • Opens network access (security group rules for databases, Redis)
  • Injects environment variables with connection details: STP_[RESOURCE_NAME]_[PARAM]

Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.

Using iamRoleStatements

For more granular control, you can provide a list of raw IAM role statements. These statements are added to the service's IAM role, allowing you to define precise permissions for any AWS resource.

resources:
  myWorkerService:
    type: worker-service
    properties:
      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'
StpIamRoleStatementAPI referenceParent:WorkerService
ResourceRequired

ARNs of the AWS resources this statement applies to. Use "*" for all resources.

Type: Array of string

Sid

Optional identifier for this statement (for readability).

Type: string

EffectDefault: Allow

Whether to allow or deny the specified actions.

Type: string

Action

AWS actions to allow or deny (e.g., s3:GetObject, sqs:SendMessage).

Type: Array of string

Condition
No description

Type: UNSPECIFIED

Default VPC connection

Some AWS services, like relational databases, must be deployed within a VPC. If your stack includes such resources, Stacktape automatically creates a default VPC and connects them to it.

Worker services are connected to this default VPC by default, allowing them to communicate with other VPC-based resources without extra configuration.

To learn more, see the documentation on VPCs and resource accessibility.

Pricing

When using Fargate, you are charged for:

  • vCPU per hour: ~$0.04 - $0.07, depending on the region.
  • Memory (GB) per hour: ~$0.004 - $0.008, depending on the region.

Usage is billed by the second, with a one-minute minimum. For more details, see AWS Fargate pricing.

API reference

StpIamRoleStatementAPI referenceParent:WorkerService
ResourceRequired

ARNs of the AWS resources this statement applies to. Use "*" for all resources.

Type: Array of string

Sid

Optional identifier for this statement (for readability).

Type: string

EffectDefault: Allow

Whether to allow or deny the specified actions.

Type: string

Action

AWS actions to allow or deny (e.g., s3:GetObject, sqs:SendMessage).

Type: Array of string

Condition
No description

Type: UNSPECIFIED