Task

Reference doc for the `sst.aws.Task` component.

The Task component lets you create containers that are used for long running asynchronous work, like data processing. It uses Amazon ECS on AWS Fargate.

Create a Task

Add a task to your cluster.

const vpc = new sst.aws.Vpc("MyVpc");
const cluster = new sst.aws.Cluster("MyCluster", { vpc });
const task = new sst.aws.Task("MyTask", { cluster });

Configure the container image

By default, the task will look for a Dockerfile in the root directory. Optionally configure the image context and dockerfile.

new sst.aws.Task("MyTask", {
  cluster,
  image: {
    context: "./app",
    dockerfile: "Dockerfile"
  }
});

To add multiple containers in the task, pass in an array of containers args.

new sst.aws.Task("MyTask", {
  cluster,
  containers: [
    {
      name: "app",
      image: "nginxdemos/hello:plain-text"
    },
    {
      name: "admin",
      image: {
        context: "./admin",
        dockerfile: "Dockerfile"
      }
    }
  ]
});

This is useful for running sidecar containers.

Link resources

Link resources to your task. This will grant permissions to the resources and allow you to access it in your app.

const bucket = new sst.aws.Bucket("MyBucket");

new sst.aws.Task("MyTask", {
  cluster,
  link: [bucket]
});

You can use the SDK to access the linked resources in your task.

import { Resource } from "sst";

console.log(Resource.MyBucket.name);

Task SDK

With the Task JS SDK, you can run your tasks, stop your tasks, and get the status of your tasks.

For example, you can link the task to a function in your app.

new sst.aws.Function("MyFunction", {
  handler: "src/lambda.handler",
  link: [task]
});

Then from your function start the task.

import { Resource } from "sst";
import { task } from "sst/aws/task";

const runRet = await task.run(Resource.MyTask);
const taskArn = runRet.arn;

If you are not using Node.js, you can use the AWS SDK instead. Here’s how to run a task.

By default, this uses a Linux/X86 Fargate container with 0.25 vCPUs at $0.04048 per vCPU per hour and 0.5 GB of memory at $0.004445 per GB per hour. It includes 20GB of Ephemeral Storage for free with additional storage at $0.000111 per GB per hour. Each container also gets a public IPv4 address at $0.005 per hour.

It works out to $0.04048 x 0.25 + $0.004445 x 0.5 + $0.005. Or $0.02 per hour your task runs for.

Adjust this for the cpu, memory and storage you are using. And check the prices for Linux/ARM if you are using arm64 as your architecture.

The above are rough estimates for us-east-1, check out the Fargate pricing and the Public IPv4 Address pricing for more details.

Constructor

new Task(name, args, opts?)

Parameters

name string
args TaskArgs
opts? ComponentResourceOptions

TaskArgs

architecture?

Type Input<“x86_64” | “arm64”>

Default “x86_64”

The CPU architecture of the container.

{
  architecture: "arm64"
}

cluster

Type Cluster

The cluster to use for the service.

Create a Cluster component.

const vpc = new sst.aws.Vpc("MyVpc");
const myCluster = new sst.aws.Cluster("MyCluster", { vpc });

And pass it in.

{
  cluster: myCluster
}

command?

Type Input<Input<string>[]>

The command to override the default command in the container.

{
  command: ["npm", "run", "start"]
}

containers?

Type Input<Object>[]

command?
cpu?
entrypoint?
environment?
image? Input<string | Object>
logging? Input<Object>
- name?
- retention?
memory?
name
ssm?
volumes? Input<Object>[]
- efs Input<Efs | Object>
  - accessPoint
  - fileSystem
- path

The containers to run in the task.

By default this starts a single container. To add multiple containers in the task, pass in an array of containers args.

{
  containers: [
    {
      name: "app",
      image: "nginxdemos/hello:plain-text"
    },
    {
      name: "admin",
      image: {
        context: "./admin",
        dockerfile: "Dockerfile"
      }
    }
  ]
}

If you specify containers, you cannot list the above args at the top-level. For example, you cannot pass in image at the top level.

{
  image: "nginxdemos/hello:plain-text",
  containers: [
    {
      name: "app",
      image: "nginxdemos/hello:plain-text"
    },
    {
      name: "admin",
      image: "nginxdemos/hello:plain-text"
    }
  ]
}

You will need to pass in image as a part of the containers.

containers[].command?

Type Input<string[]>

The command to override the default command in the container. Same as the top-level command.

containers[].cpu?

Type “${number} vCPU”

The amount of CPU allocated to the container.

By default, a container can use up to all the CPU allocated to all the containers. If set, this container is capped at this allocation even if more idle CPU is available.

The sum of all the containers’ CPU must be less than or equal to the total available CPU.

{
  cpu: "0.25 vCPU"
}

containers[].entrypoint?

Type Input<string[]>

The entrypoint to override the default entrypoint in the container. Same as the top-level entrypoint.

containers[].environment?

Type Input<Record<string, Input<string>>>

Key-value pairs of values that are set as container environment variables. Same as the top-level environment.

containers[].image?

Type Input<string | Object>

Configure the Docker image for the container. Same as the top-level image.

containers[].image.args?

Type Input<Record<string, Input<string>>>

Key-value pairs of build args. Same as the top-level image.args.

containers[].image.context?

Type Input<string>

The path to the Docker build context. Same as the top-level image.context.

containers[].image.dockerfile?

Type Input<string>

The path to the Dockerfile. Same as the top-level image.dockerfile.

containers[].image.target?

Type Input<string>

The stage to build up to. Same as the top-level image.target.

containers[].logging?

Type Input<Object>

Configure the logs in CloudWatch. Same as the top-level logging.

containers[].logging.name?

Type Input<string>

The name of the CloudWatch log group. Same as the top-level logging.name.

containers[].logging.retention?

The duration the logs are kept in CloudWatch. Same as the top-level logging.retention.

containers[].memory?

Type “${number} GB”

The amount of memory allocated to the container.

By default, a container can use up to all the memory allocated to all the containers. If set, the container is capped at this allocation. If exceeded, the container will be killed even if there is idle memory available.

The sum of all the containers’ memory must be less than or equal to the total available memory.

{
  memory: "0.5 GB"
}

containers[].name

Type Input<string>

The name of the container.

This is used as the --name option in the Docker run command.

containers[].ssm?

Type Input<Record<string, Input<string>>>

Key-value pairs of AWS Systems Manager Parameter Store parameter ARNs or AWS Secrets Manager secret ARNs. The values will be loaded into the container as environment variables. Same as the top-level ssm.

containers[].volumes?

Type Input<Object>[]

Mount Amazon EFS file systems into the container. Same as the top-level efs.

containers[].volumes[].efs

Type Input<Efs | Object>

The Amazon EFS file system to mount.

containers[].volumes[].efs.accessPoint

Type Input<string>

The ID of the EFS access point.

containers[].volumes[].efs.fileSystem

Type Input<string>

The ID of the EFS file system.

containers[].volumes[].path

Type Input<string>

The path to mount the volume.

cpu?

Default “0.25 vCPU”

The amount of CPU allocated to the container. If there are multiple containers, this is the total amount of CPU shared across all the containers.

{
  cpu: "1 vCPU"
}

dev?

Type false | Object

command?
directory?

Configure how this component works in sst dev.

By default, your task in not deployed in sst dev. Instead, you can set the dev.command and it’ll run locally in a Tasks tab in the sst dev multiplexer.

Here’s what happens when you run sst dev:

A stub version of your task is deployed. This is a minimal image that starts up faster.
When your task is started through the SDK, the stub version is provisioned. This can take roughly 10 - 20 seconds.
The stub version proxies the payload to your local machine using the same events system used by Live.
The dev.command is called to run your task locally. Once complete, the stub version of your task is stopped as well.

The advantage with this approach is that you can test your task locally even it’s invoked remotely, or through a cron job.

Since the stub version runs while your task is running, you are charged for the time it takes to run. This is roughly $0.02 per hour.

To disable this and deploy your task in sst dev, pass in false. Read more about Live and sst dev.

dev.command?

Type Input<string>

The command that sst dev runs in dev mode.

dev.directory?

Type Input<string>

Default Uses the image.dockerfile path

Change the directory from where the command is run.

entrypoint?

Type Input<string[]>

The entrypoint that overrides the default entrypoint in the container.

{
  entrypoint: ["/usr/bin/my-entrypoint"]
}

environment?

Type Input<Record<string, Input<string>>>

Key-value pairs of values that are set as container environment variables. The keys need to:

Start with a letter.
Be at least 2 characters long.
Contain only letters, numbers, or underscores.

{
  environment: {
    DEBUG: "true"
  }
}

executionRole?

Type Input<string>

Default Creates a new role

Assigns the given IAM role name to AWS ECS to launch and manage the containers. This allows you to pass in a previously created role.

By default, a new IAM role is created.

{
  executionRole: "my-execution-role"
}

image?

Type Input<string | Object>

args?
context?
dockerfile?
tags?
target?

Default Build a Docker image from the Dockerfile in the root directory.

Configure the Docker build command for building the image or specify a pre-built image.

Building a Docker image.

Prior to building the image, SST will automatically add the .sst directory to the .dockerignore if not already present.

{
  image: {
    context: "./app",
    dockerfile: "Dockerfile",
    args: {
      MY_VAR: "value"
    }
  }
}

Alternatively, you can pass in a pre-built image.

{
  image: "nginxdemos/hello:plain-text"
}

image.args?

Type Input<Record<string, Input<string>>>

Key-value pairs of build args to pass to the Docker build command.

{
  args: {
    MY_VAR: "value"
  }
}

image.context?

Type Input<string>

Default ”.”

The path to the Docker build context. The path is relative to your project’s sst.config.ts.

To change where the Docker build context is located.

{
  context: "./app"
}

image.dockerfile?

Type Input<string>

Default “Dockerfile”

The path to the Dockerfile. The path is relative to the build context.

To use a different Dockerfile.

{
  dockerfile: "Dockerfile.prod"
}

image.tags?

Type Input<Input<string>[]>

Tags to apply to the Docker image.

{
  tags: ["v1.0.0", "commit-613c1b2"]
}

image.target?

Type Input<string>

The stage to build up to in a multi-stage Dockerfile.

{
  target: "stage1"
}

link?

Type Input<any[]>

Link resources to your containers. This will:

Grant the permissions needed to access the resources.
Allow you to access it in your app using the SDK.

Takes a list of components to link to the containers.

{
  link: [bucket, stripeKey]
}

logging?

Type Input<Object>

name?
retention?

Default { retention: “1 month” }

Configure the logs in CloudWatch.

{
  logging: {
    retention: "forever"
  }
}

logging.name?

Type Input<string>

Default “/sst/cluster/${CLUSTER_NAME}/${SERVICE_NAME}/${CONTAINER_NAME}”

The name of the CloudWatch log group. If omitted, the log group name is generated based on the cluster name, service name, and container name.

logging.retention?

Default “1 month”

The duration the logs are kept in CloudWatch.

memory?

Type “${number} GB”

Default “0.5 GB”

The amount of memory allocated to the container. If there are multiple containers, this is the total amount of memory shared across all the containers.

{
  memory: "2 GB"
}

permissions?

Type Input<Object[]>

actions
effect?
resources

Permissions and the resources that you need to access. These permissions are used to create the task role.

Allow the container to read and write to an S3 bucket called my-bucket.

{
  permissions: [
    {
      actions: ["s3:GetObject", "s3:PutObject"],
      resources: ["arn:aws:s3:::my-bucket/*"]
    },
  ]
}

Allow the container to perform all actions on an S3 bucket called my-bucket.

{
  permissions: [
    {
      actions: ["s3:*"],
      resources: ["arn:aws:s3:::my-bucket/*"]
    },
  ]
}

Granting the container permissions to access all resources.

{
  permissions: [
    {
      actions: ["*"],
      resources: ["*"]
    },
  ]
}

permissions[].actions

Type string[]

The IAM actions that can be performed.

{
  actions: ["s3:*"]
}

permissions[].effect?

Type “allow” | “deny”

Default “allow”

Configures whether the permission is allowed or denied.

{
  effect: "deny"
}

permissions[].resources

Type Input<string>[]

The resourcess specified using the IAM ARN format.

{
  resources: ["arn:aws:s3:::my-bucket/*"]
}

ssm?

Type Input<Record<string, Input<string>>>

Key-value pairs of AWS Systems Manager Parameter Store parameter ARNs or AWS Secrets Manager secret ARNs. The values will be loaded into the container as environment variables.

{
  ssm: {
    DATABASE_PASSWORD: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-123abc"
  }
}

storage?

Type “${number} GB”

Default “20 GB”

The amount of ephemeral storage (in GB) allocated to the container.

{
  storage: "100 GB"
}

taskRole?

Type Input<string>

Default Creates a new role

Assigns the given IAM role name to the containers. This allows you to pass in a previously created role.

By default, a new IAM role is created. It’ll update this role if you add permissions or link resources.

However, if you pass in a role, you’ll need to update it manually if you add permissions or link resources.

{
  taskRole: "my-task-role"
}

transform?

Type Object

executionRole?
image?
logGroup?
taskDefinition?
taskRole?

Transform how this component creates its underlying resources.

transform.executionRole?

Type RoleArgs | (args: RoleArgs, opts: ComponentResourceOptions, name: string) => void

Transform the ECS Execution IAM Role resource.

transform.image?

Type ImageArgs | (args: ImageArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Docker Image resource.

transform.logGroup?

Type LogGroupArgs | (args: LogGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the CloudWatch log group resource.

transform.taskDefinition?

Type TaskDefinitionArgs | (args: TaskDefinitionArgs, opts: ComponentResourceOptions, name: string) => void

Transform the ECS Task Definition resource.

transform.taskRole?

Type RoleArgs | (args: RoleArgs, opts: ComponentResourceOptions, name: string) => void

Transform the ECS Task IAM Role resource.

volumes?

Type Input<Object>[]

efs Input<Efs | Object>
- accessPoint
- fileSystem
path

Mount Amazon EFS file systems into the container.

Create an EFS file system.

const vpc = new sst.aws.Vpc("MyVpc");
const fileSystem = new sst.aws.Efs("MyFileSystem", { vpc });

And pass it in.

{
  volumes: [
    {
      efs: fileSystem,
      path: "/mnt/efs"
    }
  ]
}

Or pass in a the EFS file system ID.

{
  volumes: [
    {
      efs: {
        fileSystem: "fs-12345678",
        accessPoint: "fsap-12345678"
      },
      path: "/mnt/efs"
    }
  ]
}

volumes[].efs

Type Input<Efs | Object>

The Amazon EFS file system to mount.

volumes[].efs.accessPoint

Type Input<string>

The ID of the EFS access point.

volumes[].efs.fileSystem

Type Input<string>

The ID of the EFS file system.

volumes[].path

Type Input<string>

The path to mount the volume.

Properties

nodes

Type Object

executionRole
taskDefinition
taskRole

The underlying resources this component creates.

nodes.executionRole

Type Role

The Amazon ECS Execution Role.

nodes.taskDefinition

Type Output<TaskDefinition>

The Amazon ECS Task Definition.

nodes.taskRole

Type Role

The Amazon ECS Task Role.

taskDefinition

Type Output<string>

The ARN of the ECS Task Definition.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Links

This is accessible through the Resource object in the SDK.

assignPublicIp boolean

Whether to assign a public IP address to the task.
cluster string

The ARN of the cluster this task is deployed to.
containers string[]

The names of the containers in the task.
securityGroups string[]

The security groups for the task.
subnets string[]

The subnets for the task.
taskDefinition string

The ARN of the ECS Task Definition.

The task client SDK is available through the following.

import { task } from "sst/aws/task";

If you are not using Node.js, you can use the AWS SDK instead. For example, you can call RunTask to run a task.

describe

task.describe(resource, task, options?)

Parameters

resource Resource
task string
options? Options

Returns Promise<DescribeResponse>

Get the details of a given task.

For example, let’s say you had previously started a task.

const runRet = await task.run(Resource.MyTask);
const taskArn = runRet.tasks[0].taskArn;

You can use that to get the details of the task.

const describeRet = await task.describe(Resource.MyTask, taskArn);
console.log(describeRet.status);

If you are not using Node.js, you can use the AWS SDK and call DescribeTasks.

run

task.run(resource, environment?, options?)

Parameters

resource Resource
environment? Record<string, string>
options? RunOptions

Returns Promise<RunResponse>

Runs a task.

For example, let’s say you have defined a task.

new sst.aws.Task("MyTask", { cluster });

You can then run the task in your application with the SDK.

import { Resource } from "sst";
import { task } from "sst/aws/task";

const runRet = await task.run(Resource.MyTask);
const taskArn = runRet.tasks[0].taskArn;

This internally calls an AWS SDK API that returns an array of tasks. But in our case, there’s only one task.

The taskArn is the ARN of the task. You can use it to call the describe or stop functions.

You can also pass in any environment variables to the task.

await task.run(Resource.MyTask, {
  MY_ENV_VAR: "my-value"
});

If you are not using Node.js, you can use the AWS SDK and call RunTask.

stop

task.stop(resource, task, options?)

Parameters

resource Resource
task string
options? Options

Returns Promise<StopResponse>

Stops a task.

For example, let’s say you had previously started a task.

const runRet = await task.run(Resource.MyTask);
const taskArn = runRet.tasks[0].taskArn;

You can stop the task with the following.

const stopRet = await task.stop(Resource.MyTask, taskArn);

Stopping a task is asnychronous. When you call stop, AWS marks a task to be stopped, but it may take a few minutes for the task to actually stop.

In most cases you probably don’t need to check if it has been stopped. But if necessary, you can use the describe function to get a task’s status.

If you are not using Node.js, you can use the AWS SDK and call StopTask.

DescribeResponse

Type Object

arn
response
status

aws? Object

assignPublicIp
cluster
containers
securityGroups
subnets
taskDefinition

aws? Object
capacity?

Configure the capacity provider; regular Fargate or Fargate Spot, for this task.

RunResponse

Type Object

arn
response
status

arn
response
status