{"id":6422,"library":"pulumi-docker","title":"Pulumi Docker","description":"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.","status":"active","version":"4.11.2","language":"en","source_language":"en","source_url":"https://github.com/pulumi/pulumi-docker","tags":["pulumi","docker","iac","infrastructure-as-code","container","orchestration"],"install":[{"cmd":"pip install pulumi-docker","lang":"bash","label":"Install Pulumi Docker"}],"dependencies":[{"reason":"Core Pulumi SDK is required for any Pulumi provider.","package":"pulumi","optional":false}],"imports":[{"symbol":"docker","correct":"import pulumi_docker as docker"},{"note":"Resources are directly available under the `pulumi_docker` namespace or via `pulumi_docker.RemoteImage` rather than deeper module paths.","wrong":"from pulumi_docker.remoteimage import RemoteImage","symbol":"RemoteImage","correct":"from pulumi_docker import RemoteImage"},{"symbol":"Container","correct":"from pulumi_docker import Container"}],"quickstart":{"code":"import pulumi\nimport pulumi_docker as docker\nimport os\n\n# Pull a remote Docker image (e.g., NGINX latest)\nnginx_image = docker.RemoteImage(\"nginx-image\",\n    name=\"nginx:latest\"\n)\n\n# Create a Docker container from the pulled image\nnginx_container = docker.Container(\"nginx-container\",\n    image=nginx_image.image_id,\n    ports=[docker.ContainerPortArgs(\n        internal=80,\n        external=8080,\n    )],\n    # Example of setting environment variables for a private registry if needed\n    # registry=docker.RegistryArgs(\n    #     server=\"your.private.registry\",\n    #     username=os.environ.get('DOCKER_REGISTRY_USER', ''),\n    #     password=os.environ.get('DOCKER_REGISTRY_PASS', ''),\n    # )\n)\n\n# Export the container ID and the external port\npulumi.export(\"container_id\", nginx_container.id)\npulumi.export(\"external_port\", 8080)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Breaking change in `v4.7.0`: The `RemoteImageBuild` resource's `buildArg` property was removed. Programs using this property will fail upon upgrade.","severity":"breaking","affected_versions":">=4.7.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.6.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}