Docs Home
docker-build v0.0.13 published on Wednesday, Aug 27, 2025 by Pulumi
Docker Build
The Docker Build provider leverages buildx and BuildKit to build modern Docker images with Pulumi.
Not to be confused with the earlier Docker provider, which is still appropriate for managing resources unrelated to building images.
| Provider | Use cases |
|---|---|
@pulumi/docker-build | Anything related to building images with docker build. |
@pulumi/docker | Everything else – including running containers and creating networks. |
Example
If your Pulumi program has a directory called app alongside it, containing a
file named “Dockerfile” (which can be as simple as FROM alpine for the
purpose of example), then the code below shows how to build a multi-platform
image, publish it to a remote AWS ECR registry, and use an inline
cache to speed up
subsequent builds.
<div>
<pulumi-choosable type="language" values="typescript" mode="">
import * as aws from "@pulumi/aws";
import * as docker_build from "@pulumi/docker-build";
// Create an ECR repository for pushing.
const ecrRepository = new aws.ecr.Repository("ecr-repository", {});
// Grab auth credentials for ECR.
const authToken = aws.ecr.getAuthorizationTokenOutput({
registryId: ecrRepository.registryId,
});
// Build and push an image to ECR with inline caching.
const myImage = new docker_build.Image("my-image", {
// Tag our image with our ECR repository's address.
tags: [pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`],
context: {
location: "./app",
},
// Use the pushed image as a cache source.
cacheFrom: [{
registry: {
ref: pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`,
},
}],
// Include an inline cache with our pushed image.
cacheTo: [{
inline: {},
}],
// Build a multi-platform image manifest for ARM and AMD.
platforms: [
"linux/amd64",
"linux/arm64",
],
// Push the final result to ECR.
push: true,
// Provide our ECR credentials.
registries: [{
address: ecrRepository.repositoryUrl,
password: authToken.password,
username: authToken.userName,
}],
});
// Export a ref for the pushed images so we can deploy it.
export const ref = myImage.ref;
<div>
<pulumi-choosable type="language" values="python" mode="">
import pulumi
import pulumi_aws as aws
import pulumi_docker_build as docker_build
# Create an ECR repository for pushing.
ecr_repository = aws.ecr.Repository("ecr-repository")
# Grab auth credentials for ECR.
auth_token = aws.ecr.get_authorization_token_output(registry_id=ecr_repository.registry_id)
# Build and push an image to ECR with inline caching.
my_image = docker_build.Image("my-image",
# Tag our image with our ECR repository's address.
tags=[ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest")],
context=docker_build.BuildContextArgs(
location="./app",
),
# Use the pushed image as a cache source.
cache_from=[docker_build.CacheFromArgs(
registry=docker_build.CacheFromRegistryArgs(
ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest"),
),
)],
# Include an inline cache with our pushed image.
cache_to=[docker_build.CacheToArgs(
inline=docker_build.CacheToInlineArgs(),
)],
# Build a multi-platform image manifest for ARM and AMD.
platforms=[
docker_build.Platform.LINUX_AMD64,
docker_build.Platform.LINUX_ARM64,
],
# Push the final result to ECR.
push=True,
# Provide our ECR credentials.
registries=[docker_build.RegistryArgs(
address=ecr_repository.repository_url,
password=auth_token.password,
username=auth_token.user_name,
)],
)
# Export a ref for the pushed images so we can deploy it.
pulumi.export("ref", my_image.ref)