Registry / devops / pulumi-docker-build

pulumi-docker-build

JSON →
library0.0.18pypypiunverified

Pulumi Docker Build is a Pulumi provider for building modern Docker images. It leverages Docker Buildx and BuildKit to provide advanced image building capabilities, including multi-platform builds and caching. The current version is 0.0.15, and it typically sees minor updates every few weeks to months, often reflecting updates to underlying Docker components or bug fixes.

pip install pulumi-docker-build pulumi
INSTALL
IMPORT
SIG · PULUMI-DOCKER-BUIL
P
pulumi-docker-build
devopspythonv0.0.18
Install
6.5s avg
Import
Disk
80MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.18 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 88MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 6.5s · import 0.000s · 74MB
80MB installed
● package 80MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image
from pulumi_dockerbuild import Image
Index
from pulumi_dockerbuild import Index
ImageRegistryArgs
from pulumi_dockerbuild import ImageRegistryArgs

This quickstart demonstrates how to build a Docker image using `pulumi-docker-build`. It creates a simple `Dockerfile` in the current directory, then defines an `Image` resource to build and optionally push the image to Docker Hub. Remember to replace 'yourusername' with your actual Docker Hub username and set `DOCKER_USERNAME` and `DOCKER_PASSWORD` environment variables for pushing.

import pulumi import pulumi_dockerbuild as dockerbuild import os # For this quickstart, we'll create a simple Dockerfile temporarily. # In a real project, this Dockerfile would be part of your source code. with open("Dockerfile", "w") as f: f.write(""" FROM alpine:latest RUN echo "Building with Pulumi Docker Build!" > /tmp/build-status.txt CMD ["cat", "/tmp/build-status.txt"] """) # Define a Docker image resource. This will build the image. # To push to Docker Hub, replace 'yourusername' with your Docker Hub username # and ensure DOCKER_USERNAME and DOCKER_PASSWORD environment variables are set. # For local builds only, you can omit the 'registry' argument. image = dockerbuild.Image("my-first-image", context=".", dockerfile="Dockerfile", image_name=f"yourusername/my-first-image:v1.0.0", # IMPORTANT: Replace 'yourusername' registry=dockerbuild.ImageRegistryArgs( server="docker.io", # Default for Docker Hub username=os.environ.get("DOCKER_USERNAME", ""), password=os.environ.get("DOCKER_PASSWORD", ""), ), # If you want to export the image to a local tarball instead of pushing: # exports=[dockerbuild.ImageExportArgs( # local=dockerbuild.ImageExportLocalArgs( # dest="./my-first-image.tar" # ) # )] ) # Export the resulting image name pulumi.export("image_name", image.image_name) # Note: Remember to delete the 'Dockerfile' created by this quickstart # after you are done, as it's a temporary artifact for demonstration.
pulumi --version
Debug
Known issues
breakingUpgrades to underlying `buildx` and BuildKit versions (e.g., in v0.0.8, v0.0.11) may subtly change build behavior, introduce new features, or require updated Docker daemon capabilities. Always test new versions in a non-production environment first.
fix
Review release notes for changes in `buildx` versions. Ensure your Docker daemon is compatible with the `buildx` version used by the provider, and test your build process.
affects: All versions, especially with major BuildKit updates.
gotchaSome advanced features, like specifying multiple exports for an image build, require BuildKit daemon version 0.13 or newer. Using these features with an older daemon will result in an error.
fix
Ensure your Docker daemon has BuildKit version 0.13 or newer enabled. Check Docker Desktop settings or update your Docker Engine installation.
affects: <=0.0.7
gotchaIncorrect or missing Docker registry authentication details can prevent images from being pushed. This is a common pitfall when working with private registries or Docker Hub.
fix
Ensure `ImageRegistryArgs` are correctly configured with valid `server`, `username`, and `password` (e.g., from environment variables like `DOCKER_USERNAME`, `DOCKER_PASSWORD`). Alternatively, ensure your Docker client is logged in via `docker login` before `pulumi up`.
affects: All versions
gotchaOlder versions (pre-0.0.11) had an issue where upgrading `pulumi-docker-build` itself could unintentionally cause `Image` resources to be replaced, leading to downtime or re-pushes. While a specific instance was fixed in v0.0.11, always review `pulumi up` previews carefully for unexpected replacements.
fix
Always review `pulumi up` previews for unexpected resource replacements. If observed, investigate the cause or pin to an older provider version temporarily. Upgrading to v0.0.11+ is recommended.
affects: <=0.0.10
gotchaRefreshing `Index` resources (used for multi-architecture images) might fail if the stored credentials for the associated registry have expired. This can lead to issues with maintaining multi-arch manifests.
fix
For long-lived deployments, ensure registry tokens used for `Index` resources have sufficient validity or implement a mechanism to re-authenticate as needed. Upgrading to v0.0.7+ resolves some refresh issues.
affects: <=0.0.6
Upgrade
Version history
0.0.18latest on PyPI · released May 27, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
35 hits · last 30 days
node
30
OpenAI (training)
1
Resources
pulumi-docker-build — pip install pulumi-docker-build · libregistry