Pulumi Docker

4.11.2 · active · verified Wed Apr 15

Pulumi Docker is a Pulumi package for interacting with Docker in Pulumi programs, allowing users to define, deploy, and manage Docker containers, images, networks, and volumes using general-purpose programming languages. It is currently at version 4.11.2 and maintains an active release cadence with frequent minor updates, often incorporating bridge upgrades and GitHub Actions workflow improvements.

Warnings

breaking Breaking change in `v4.7.0`: The `RemoteImageBuild` resource's `buildArg` property was removed. Programs using this property will fail upon upgrade.
Fix: Review your `RemoteImageBuild` configurations and update them to reflect the removal of `buildArg`. Consult the specific v4.7.0 release notes for alternatives or updated schema.
breaking Significant overhaul of the `docker.Image` resource in `v4.0.0`. This included breaking changes to its behavior, supporting types, and minor name changes. Existing programs using `docker.Image` might require code adjustments.
Fix: Refer to the v4.0.0 release notes for a detailed migration guide. Update your Pulumi program code to align with the new `docker.Image` resource API and types.
gotcha When configuring `registryAuth` for the Docker provider, passing `config_file` (e.g., `~/.docker/config.json`) may trigger a type checking warning (as of v4.6.1) that indicates it will become a hard error. This is a discrepancy between documentation and type definitions.
Fix: While `config_file` is documented, consider using `configFileContent` to provide the content directly, or rely on `DOCKER_REGISTRY_USER` and `DOCKER_REGISTRY_PASS` environment variables, which have lower precedence but avoid this type-checking issue. Always check the latest provider documentation for the officially supported method.
gotcha When using `pulumi-docker` with a remote Docker host, the remote daemon's default configuration might apply settings (e.g., log options) that are not explicitly defined in your Pulumi program. This can cause spurious diffs during `pulumi preview` or `pulumi up` on subsequent runs.
Fix: Utilize Pulumi's `ignoreChanges` lifecycle meta-argument for attributes prone to such external modifications (e.g., `opts=pulumi.ResourceOptions(ignore_changes=['container.log_driver', 'container.log_opts'])`). Alternatively, ensure the Docker daemon on the remote host is configured precisely to avoid unexpected defaults.
gotcha `docker build` operations within Pulumi programs, especially when using `cacheFrom: true` or specific credential helpers (like for Google Container Registry), can significantly slow down `pulumi preview` and `pulumi up`, even if all layers are cached locally.
Fix: For performance-critical or frequently changing images, consider pre-building Docker images as part of an external CI/CD pipeline and then having Pulumi deploy these pre-built images from a container registry. If building within Pulumi, ensure Docker's build cache is effectively utilized and review builder configuration.
gotcha While `pulumi-docker` supports building images, for production environments and complex applications, it's often recommended to separate concerns by using dedicated CI/CD pipelines for building and pushing Docker images. Pulumi should then consume these pre-built images from a container registry.
Fix: Implement a CI/CD pipeline (e.g., GitHub Actions, GitLab CI) to handle `docker build`, testing, tagging, and pushing images to a registry. Your Pulumi program can then reference these images by their immutable tags or digests, enhancing modularity, reusability, and deployment speed.

Install

pip install pulumi-docker Install Pulumi Docker

Imports

docker
```
import pulumi_docker as docker
```
RemoteImage
```
from pulumi_docker import RemoteImage
```
Resources are directly available under the `pulumi_docker` namespace or via `pulumi_docker.RemoteImage` rather than deeper module paths.
Container
```
from pulumi_docker import Container
```

Quickstart

This quickstart program pulls the `nginx:latest` Docker image and then creates a container, exposing port 8080 on the host mapped to port 80 internally in the container. It then exports the container ID and the external port. For private registries, uncomment and configure the `registry` arguments within `RemoteImage` using environment variables for sensitive credentials.

import pulumi
import pulumi_docker as docker
import os

# Pull a remote Docker image (e.g., NGINX latest)
nginx_image = docker.RemoteImage("nginx-image",
    name="nginx:latest"
)

# Create a Docker container from the pulled image
nginx_container = docker.Container("nginx-container",
    image=nginx_image.image_id,
    ports=[docker.ContainerPortArgs(
        internal=80,
        external=8080,
    )],
    # Example of setting environment variables for a private registry if needed
    # registry=docker.RegistryArgs(
    #     server="your.private.registry",
    #     username=os.environ.get('DOCKER_REGISTRY_USER', ''),
    #     password=os.environ.get('DOCKER_REGISTRY_PASS', ''),
    # )
)

# Export the container ID and the external port
pulumi.export("container_id", nginx_container.id)
pulumi.export("external_port", 8080)

view raw JSON →