Job

The Job construct is a higher level CDK construct that makes it easy to perform long running jobs.

Examples

Creating a Job

import { Job } from "sst/constructs";

new Job(stack, "MyJob", {
  handler: "src/job.main",
});

Creating a Container Job

To create a container job, set runtime to "container" and point the handler to the directory containing the Dockerfile.

import { Job } from "sst/constructs";

new Job(stack, "MyJob", {
  runtime: "container",
  handler: "src/job",
  container: {
    cmd: ["python3", "/var/task/my-script.py"]
  }
});

Here's an example of my-script.py. Note that the payload is accessible via the environment variable SST_PAYLOAD.

src/job/my-script.py

import json
import numpy
import sys

payload = json.loads(os.getenv("SST_PAYLOAD"))
number = payload["number"]
print(f"Square root of {number} is {numpy.sqrt(number)}")

In this example, the Dockerfile would look like this:

src/job/Dockerfile

# Start from Python 3.8 base image
FROM python:3.8-slim

# Install the dependencies
COPY requirements.txt .
RUN pip3 install -r requirements.txt --target /var/task

# Copy our function code
COPY my-script.py /var/task

Here, the Docker container uses the Python 3.8 slim image, installs the dependencies specified in the requirements.txt, and copies the script code into the container. The command to run the script is passed as cmd in the docker property of the Job construct.

Setting additional props

new Job(stack, "MyJob", {
  handler: "job.main",
  srcPath: "services",
  timeout: "30 minutes",
  memorySize: "3 GB",
  config: [STRIPE_KEY, API_URL],
  permissions: ["ses", bucket],
});

Create a job in a VPC

import { Job } from "sst/constructs";
import { Vpc } from "aws-cdk-lib/aws-ec2";

new Job(stack, "MyJob", {
  handler: "src/job.main",
  cdk: {
    vpc: Vpc.fromLookup(stack, "VPC", {
      vpcId: "vpc-xxxxxxxxxx",
    }),
  },
});

Constructor

new Job(scope, id, props)

Parameters

• scope Construct
• id string
• props JobProps

JobProps

architecture?

Type : "x86_64" | "arm_64"

Default : "x86_64"

The CPU architecture of the job.

new Job(stack, "MyJob", {
  architecture: "arm_64",
  handler: "src/job.handler",
})

bind?

Type : Array<BindingResource>

Bind resources for the job

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  bind: [STRIPE_KEY, bucket],
})

container?

Type : JobContainerProps

Used to configure container properties

copyFiles?

Type : Array<FunctionCopyFilesProps>

Used to configure additional files to copy into the function bundle

new Job(stack, "job", {
  copyFiles: [{ from: "src/index.js" }]
})

enableLiveDev?

Type : boolean

Default : true

Can be used to disable Live Lambda Development when using sst start . Useful for things like Custom Resources that need to execute during deployment.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  enableLiveDev: false
})

environment?

Type : Record<string, string>

Configure environment variables for the job

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  environment: {
    DEBUG: "*",
  }
})

handler

Type : string

For "nodejs" runtime, point to the entry point and handler function. Of the format: /path/to/file.function .

new Job(stack, "MyJob", {
  handler: "src/job.handler",
})

For "container" runtime, point the handler to the directory containing the Dockerfile.

new Job(stack, "MyJob", {
  runtime: "container",
  handler: "src/job", // Dockerfile is at "src/job/Dockerfile"
})

logRetention?

Type : "one_day" | "three_days" | "five_days" | "one_week" | "two_weeks" | "one_month" | "two_months" | "three_months" | "four_months" | "five_months" | "six_months" | "one_year" | "thirteen_months" | "eighteen_months" | "two_years" | "three_years" | "five_years" | "six_years" | "seven_years" | "eight_years" | "nine_years" | "ten_years" | "infinite"

Default : Logs retained indefinitely

The duration logs are kept in CloudWatch Logs.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  logRetention: "one_week"
})

memorySize?

Type : "3 GB" | "7 GB" | "15 GB" | "145 GB"

Default : "3 GB"

The amount of memory in MB allocated.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  memorySize: "3 GB",
})

nodejs?

Type : JobNodeJSProps

Used to configure nodejs function properties

permissions?

Type : Permissions

Attaches the given list of permissions to the job. Configuring this property is equivalent to calling attachPermissions() after the job is created.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  permissions: ["ses"]
})

runtime?

Type : "container" | "nodejs16.x" | "nodejs18.x" | "nodejs20.x" | "nodejs"

Default : "nodejs18.x"

The runtime environment for the job.

new Job(stack, "MyJob", {
  runtime: "container",
  handler: "src/job",
})

timeout?

Type : ${number} second | ${number} seconds | ${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} day | ${number} days

Default : "8 hours"

The execution timeout. Minimum 5 minutes. Maximum 8 hours.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  timeout: "30 minutes",
})

cdk?

Type :

cdk.id?

Type : string

Allows you to override default id for this construct.

cdk.securityGroups?

Type : Array<ISecurityGroup>

Default : A new security group is created.

The list of security groups to associate with the Job's network interfaces.

import { SecurityGroup } from "aws-cdk-lib/aws-ec2";

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  cdk: {
    vpc,
    securityGroups: [
      new SecurityGroup(stack, "MyJobSG", { vpc })
    ]
  }
})

cdk.vpc?

Type : IVpc

Runs codebuild job in the specified VPC. Note this will only work once deployed.

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  cdk: {
    vpc: Vpc.fromLookup(stack, "VPC", {
      vpcId: "vpc-xxxxxxxxxx",
    }),
  }
})

cdk.vpcSubnets?

Type : SubnetSelection

Default : All private subnets.

Where to place the network interfaces within the VPC.

import { SubnetType } from "aws-cdk-lib/aws-ec2";

new Job(stack, "MyJob", {
  handler: "src/job.handler",
  cdk: {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS }
  }
})

Properties

An instance of Job has the following properties.

id

Type : string

cdk

Type :

cdk.codeBuildProject

Type : Project

Methods

An instance of Job has the following methods.

addEnvironment

addEnvironment(name, value)

Parameters

• name string
• value string

Attaches additional environment variable to the job.

fn.addEnvironment({
  DEBUG: "*"
});

attachPermissions

attachPermissions(permissions)

Parameters

• permissions Permissions

Attaches the given list of permissions to the job. This allows the job to access other AWS resources.

job.attachPermissions(["ses"]);

bind

bind(constructs)

Parameters

• constructs Array<BindingResource>

Binds additional resources to job.

job.bind([STRIPE_KEY, bucket]);

JobNodeJSProps

banner?

Type : string

Use this to insert an arbitrary string at the beginning of generated JavaScript and CSS files.

nodejs: {
  banner: "console.log('Function starting')"
}

esbuild?

Type : BuildOptions

This allows you to customize esbuild config.

format?

Type : "esm" | "cjs"

Default : "esm"

Configure format

nodejs: {
  format: "cjs"
}

install?

Type : Array<string>

Packages that will be excluded from the bundle and installed into node_modules instead. Useful for dependencies that cannot be bundled, like those with binary dependencies.

nodejs: {
  install: ["pg"]
}

loader?

Type : Record<string, Loader>

Configure additional esbuild loaders for other file extensions

nodejs: {
  loader: {
   ".png": "file"
  }
}

minify?

Type : boolean

Default : false

Enable or disable minification

nodejs: {
  minify: true
}

sourcemap?

Type : boolean

Default : false

Configure if sourcemaps are generated when the function is bundled for production. Since they increase payload size and potentially cold starts they are not generated by default. They are always generated during local development mode.

nodejs: {
  sourcemap: true
}

splitting?

Type : boolean

Default : false

If enabled, modules that are dynamically imported will be bundled as their own files with common dependencies placed in shared chunks. This can help drastically reduce cold starts as your function grows in size.

nodejs: {
  splitting: true
}

JobContainerProps

buildArgs?

Type : Record<string, string>

Default : No build args

Build args to pass to the docker build command.

container: {
  buildArgs: {
    FOO: "bar"
  }
}

buildSsh?

Type : string

Default : No --ssh flag is passed to the build command

SSH agent socket or keys to pass to the docker build command. Docker BuildKit must be enabled to use the ssh flag

container: {
  buildSsh: "default"
}

cacheFrom?

Type : Array<JobContainerCacheProps>

Default : No cache from options are passed to the build command

Cache from options to pass to the docker build command. DockerCacheOption[].

container: {
  cacheFrom: [{ type: 'registry', params: { ref: 'ghcr.io/myorg/myimage:cache' }}],
}

cacheTo?

Type : JobContainerCacheProps

Default : No cache to options are passed to the build command

Cache to options to pass to the docker build command. DockerCacheOption[].

container: {
  cacheTo: { type: 'registry', params: { ref: 'ghcr.io/myorg/myimage:cache', mode: 'max', compression: 'zstd' }},
}

cmd

Type : Array<string>

Specify or override the CMD on the Docker image.

container: {
  cmd: ["python3", "my_script.py"]
}

file?

Type : string

Name of the Dockerfile.

container: {
  file: "path/to/Dockerfile.prod"
}

JobContainerCacheProps