Skip to main content

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

JobProps​

architecture?​

Type : "x86_64" | "arm_64"

The CPU architecture of the job.

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

bind?​

Type : Array<SSTConstruct>

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

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"

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"

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

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

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>

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

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

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

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

Binds additional resources to job.

job.bind([STRIPE_KEY, bucket]);

JobNodeJSProps​

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"

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

Enable or disable minification

nodejs: {
  minify: false
}

sourcemap?​

Type : boolean

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

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>

Build args to pass to the docker build command.

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

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