{"id":7525,"library":"pulumi-docker-build","title":"Pulumi Docker Build","description":"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.","status":"active","version":"0.0.15","language":"en","source_language":"en","source_url":"https://github.com/pulumi/pulumi-docker-build","tags":["pulumi","docker","buildkit","container","infrastructure as code"],"install":[{"cmd":"pip install pulumi-docker-build pulumi","lang":"bash","label":"Install Pulumi Docker Build and Pulumi SDK"}],"dependencies":[],"imports":[{"symbol":"Image","correct":"from pulumi_dockerbuild import Image"},{"symbol":"Index","correct":"from pulumi_dockerbuild import Index"},{"symbol":"ImageRegistryArgs","correct":"from pulumi_dockerbuild import ImageRegistryArgs"}],"quickstart":{"code":"import pulumi\nimport pulumi_dockerbuild as dockerbuild\nimport os\n\n# For this quickstart, we'll create a simple Dockerfile temporarily.\n# In a real project, this Dockerfile would be part of your source code.\nwith open(\"Dockerfile\", \"w\") as f:\n    f.write(\"\"\"\nFROM alpine:latest\nRUN echo \"Building with Pulumi Docker Build!\" > /tmp/build-status.txt\nCMD [\"cat\", \"/tmp/build-status.txt\"]\n\"\"\")\n\n# Define a Docker image resource. This will build the image.\n# To push to Docker Hub, replace 'yourusername' with your Docker Hub username\n# and ensure DOCKER_USERNAME and DOCKER_PASSWORD environment variables are set.\n# For local builds only, you can omit the 'registry' argument.\nimage = dockerbuild.Image(\"my-first-image\",\n    context=\".\",\n    dockerfile=\"Dockerfile\",\n    image_name=f\"yourusername/my-first-image:v1.0.0\", # IMPORTANT: Replace 'yourusername'\n    registry=dockerbuild.ImageRegistryArgs(\n        server=\"docker.io\", # Default for Docker Hub\n        username=os.environ.get(\"DOCKER_USERNAME\", \"\"),\n        password=os.environ.get(\"DOCKER_PASSWORD\", \"\"),\n    ),\n    # If you want to export the image to a local tarball instead of pushing:\n    # exports=[dockerbuild.ImageExportArgs(\n    #     local=dockerbuild.ImageExportLocalArgs(\n    #         dest=\"./my-first-image.tar\"\n    #     )\n    # )]\n)\n\n# Export the resulting image name\npulumi.export(\"image_name\", image.image_name)\n\n# Note: Remember to delete the 'Dockerfile' created by this quickstart\n# after you are done, as it's a temporary artifact for demonstration.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially with major BuildKit updates."},{"fix":"Ensure your Docker daemon has BuildKit version 0.13 or newer enabled. Check Docker Desktop settings or update your Docker Engine installation.","message":"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.","severity":"gotcha","affected_versions":"<=0.0.7"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.0.10"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.0.6"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"Missing or incorrect Docker registry credentials when attempting to push an image to a private or public registry (e.g., Docker Hub).","error":"Error: authorization failed: authorization required"},{"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.","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).","error":"Error: failed to solve: failed to parse dockerfile: ... syntax error"},{"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.","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.","error":"Error: multiple exports are not allowed"},{"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.","cause":"The Docker daemon or BuildKit instance is not running or is inaccessible from where Pulumi is executed.","error":"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\""}]}