Pulumi Docker Build

Common errors

• Error: authorization failed: authorization required

  cause Missing or incorrect Docker registry credentials when attempting to push an image to a private or public registry (e.g., Docker Hub).
  fix Provide valid `registry` arguments to `dockerbuild.Image` (e.g., `ImageRegistryArgs(server="docker.io", username=os.environ.get("DOCKER_USERNAME"), password=os.environ.get("DOCKER_PASSWORD"))`) or ensure your Docker client is logged in via `docker login` before running `pulumi up`.

• Error: failed to solve: failed to parse dockerfile: ... syntax error

  cause The provided Dockerfile contains syntax errors, is malformed, or references an unsupported `# syntax=` directive (less common after v0.0.8 fixed a specific issue).
  fix Carefully review your Dockerfile for any syntax mistakes. If using custom syntax directives, ensure they are valid and compatible with the BuildKit version in use.

• Error: multiple exports are not allowed

  cause You are attempting to use the `exports` argument with multiple export types (e.g., `local` and `image`) but your BuildKit daemon version is older than 0.13.
  fix Upgrade your Docker daemon (e.g., Docker Desktop) to a version that includes BuildKit 0.13 or newer. Alternatively, specify only a single export type in your `exports` argument.

• Error: failed to solve: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing dial unix /var/run/docker.sock: connect: no such file or directory"

  cause The Docker daemon or BuildKit instance is not running or is inaccessible from where Pulumi is executed.
  fix Ensure your Docker daemon is running and accessible. For Linux, check `systemctl status docker`. For Docker Desktop, ensure the application is open and running. Verify `DOCKER_HOST` environment variable if using a remote Docker instance.

Warnings

• breaking Upgrades 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.
• gotcha Some 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.
• gotcha Incorrect 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`.
• gotcha Older 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.
• gotcha Refreshing `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.

Install

• pip install pulumi-docker-build pulumi Install Pulumi Docker Build and Pulumi SDK

Imports

• Image

  from pulumi_dockerbuild import Image

• Index

  from pulumi_dockerbuild import Index

• ImageRegistryArgs

  from pulumi_dockerbuild import ImageRegistryArgs

Quickstart

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.