Image
Image builds a Docker image and pushes it Docker and OCI compatible registries. This resource enables running Docker builds as part of a Pulumi deployment. Note: We recommend you migrate your images to the more modern [Docker
Build](https://www.pulumi.com/registry/packages/docker-build/) provider to get the best possible support, features, and performance. Note: This resource does not delete tags, locally or remotely, when destroyed.
Image name
The Image resource uses imageName to refer to a fully qualified Docker image name, by the format repository:tag. Note that this does not include any digest information and thus will not cause any updates when passed to dependencies, even when using latest tag. To trigger such updates, e.g. when referencing pushed images in container orchestration and management resources, please use the repoDigest Output instead, which is of the format repository@<algorithm>:<hash> and unique per build/push. As of Docker v4.4, repoDigest is now available for local Images.
Cross-platform builds
The Image resource supports cross-platform builds when the Docker engine has cross-platform support enabled via emulators. The Image resource currently supports providing only a single operating system and architecture in the platform field, e.g.: linux/amd64. To enable this support, you may need to install the emulators in the environment running your Pulumi program. If you are using Linux, you may be using Docker Engine or Docker Desktop for Linux, depending on how you have installed Docker. The FAQ for Docker Desktop for Linux describes the differences and how to select which Docker context is in use.
For local development using Docker Desktop, this is enabled by default.
For systems using Docker Engine, install the QEMU binaries and register them with using the docker image from github.com/tonistiigi/binfmt:
docker run --privileged --rm tonistiigi/binfmt --install allIn a GitHub Actions workflow, the docker/setup-qemu-action can be used instead by adding this step to your workflow file. Example workflow usage:
name: Pulumi
on:
push:
branches:
- master
jobs:
up:
name: Preview
runs-on: ubuntu-latest
steps:
# This is the step added:
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
# The ordinary pulumi/actions workflow:
- uses: actions/checkout@v3
- uses: pulumi/actions@v4
with:
command: preview
stack-name: org-name/stack-name
env:
PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}Example Usage
A Docker image build
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.docker.Image;
import com.pulumi.docker.ImageArgs;
import com.pulumi.docker.inputs.DockerBuildArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var demoImage = new Image("demoImage", ImageArgs.builder()
.build(DockerBuildArgs.builder()
.context(".")
.dockerfile("Dockerfile")
.platform("linux/amd64")
.build())
.imageName("username/image:tag1")
.skipPush(true)
.build());
ctx.export("imageName", demoImage.imageName());
}
}A Docker image build and push
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.docker.Image;
import com.pulumi.docker.ImageArgs;
import com.pulumi.docker.inputs.DockerBuildArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var demoPushImage = new Image("demoPushImage", ImageArgs.builder()
.build(DockerBuildArgs.builder()
.context(".")
.dockerfile("Dockerfile")
.build())
.imageName("docker.io/username/push-image:tag1")
.build());
ctx.export("imageName", demoPushImage.imageName());
ctx.export("repoDigest", demoPushImage.repoDigest());
}
}Docker image build using caching with AWS Elastic Container Registry
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecr.Repository;
import com.pulumi.aws.ecr.RepositoryArgs;
import com.pulumi.aws.ecr.EcrFunctions;
import com.pulumi.aws.ecr.inputs.GetAuthorizationTokenArgs;
import com.pulumi.docker.Image;
import com.pulumi.docker.ImageArgs;
import com.pulumi.docker.inputs.DockerBuildArgs;
import com.pulumi.docker.inputs.CacheFromArgs;
import com.pulumi.docker.inputs.RegistryArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var ecrRepository = new Repository("ecrRepository", RepositoryArgs.builder()
.name("docker-repository")
.build());
final var authToken = EcrFunctions.getAuthorizationToken(GetAuthorizationTokenArgs.builder()
.registryId(ecrRepository.registryId())
.build());
var myAppImage = new Image("myAppImage", ImageArgs.builder()
.build(DockerBuildArgs.builder()
.args(Map.of("BUILDKIT_INLINE_CACHE", "1"))
.cacheFrom(CacheFromArgs.builder()
.images(ecrRepository.repositoryUrl().applyValue(_repositoryUrl -> String.format("%s:latest", _repositoryUrl)))
.build())
.context("app/")
.dockerfile("app/Dockerfile")
.build())
.imageName(ecrRepository.repositoryUrl().applyValue(_repositoryUrl -> String.format("%s:latest", _repositoryUrl)))
.registry(RegistryArgs.builder()
.password(Output.ofSecret(authToken.applyValue(_authToken -> _authToken.password())))
.server(ecrRepository.repositoryUrl())
.username(authToken.applyValue(_authToken -> _authToken.userName()))
.build())
.build());
ctx.export("imageName", myAppImage.imageName());
}
}Properties
The fully qualified image name that was pushed to the registry.
The location of the Dockerfile relative to the docker build context.
The name of the registry server hosting the image.
For pushed images: The manifest digest of an image pushed to a registry, of the format repository@username/demo-image@sha256:a6ae6dd8d39c5bb02320e41abf00cd4cb35905fec540e37d306c878be8d38bd3. This reference is unique per image build and push. Only available for images pushed to a registry. Use when passing a reference to a pushed image to container management resources. Local-only imagesFor local images, this field is the image ID of the built local image, of the format sha256:826a130323165bb0ccb0374ae774f885c067a951b51a6ee133577f4e5dbc4119