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
.
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:
# 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
- 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<SSTConstruct>
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"
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"
}