# coding=utf-8 # *** WARNING: this file was generated by pulumi-language-python. *** # *** Do not edit by hand unless you're certain you know what you are doing! *** import copy import warnings import pulumi import pulumi.runtime from typing import Any, Mapping, Optional, Sequence, Union, overload from . import _utilities from . import outputs from ._enums import * from ._inputs import * __all__ = ['ImageArgs', 'Image'] @pulumi.input_type class ImageArgs: def __init__(__self__, *, push: pulumi.Input[bool], add_hosts: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, build_args: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, build_on_preview: Optional[pulumi.Input[bool]] = None, builder: Optional[pulumi.Input['BuilderConfigArgs']] = None, cache_from: Optional[pulumi.Input[Sequence[pulumi.Input['CacheFromArgs']]]] = None, cache_to: Optional[pulumi.Input[Sequence[pulumi.Input['CacheToArgs']]]] = None, context: Optional[pulumi.Input['BuildContextArgs']] = None, dockerfile: Optional[pulumi.Input['DockerfileArgs']] = None, exec_: Optional[pulumi.Input[bool]] = None, exports: Optional[pulumi.Input[Sequence[pulumi.Input['ExportArgs']]]] = None, labels: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, load: Optional[pulumi.Input[bool]] = None, network: Optional[pulumi.Input['NetworkMode']] = None, no_cache: Optional[pulumi.Input[bool]] = None, platforms: Optional[pulumi.Input[Sequence[pulumi.Input['Platform']]]] = None, pull: Optional[pulumi.Input[bool]] = None, registries: Optional[pulumi.Input[Sequence[pulumi.Input['RegistryArgs']]]] = None, secrets: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, ssh: Optional[pulumi.Input[Sequence[pulumi.Input['SSHArgs']]]] = None, tags: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, target: Optional[pulumi.Input[str]] = None): """ The set of arguments for constructing a Image resource. :param pulumi.Input[bool] push: When `true` the build will automatically include a `registry` export. Defaults to `false`. Equivalent to Docker's `--push` flag. :param pulumi.Input[Sequence[pulumi.Input[str]]] add_hosts: Custom `host:ip` mappings to use during the build. Equivalent to Docker's `--add-host` flag. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] build_args: `ARG` names and values to set during the build. These variables are accessed like environment variables inside `RUN` instructions. Build arguments are persisted in the image, so you should use `secrets` if these arguments are sensitive. Equivalent to Docker's `--build-arg` flag. :param pulumi.Input[bool] build_on_preview: Setting this to `false` will always skip image builds during previews, and setting it to `true` will always build images during previews. Images built during previews are never exported to registries, however cache manifests are still exported. On-disk Dockerfiles are always validated for syntactic correctness regardless of this setting. Defaults to `true` as a safeguard against broken images merging as part of CI pipelines. :param pulumi.Input['BuilderConfigArgs'] builder: Builder configuration. :param pulumi.Input[Sequence[pulumi.Input['CacheFromArgs']]] cache_from: Cache export configuration. Equivalent to Docker's `--cache-from` flag. :param pulumi.Input[Sequence[pulumi.Input['CacheToArgs']]] cache_to: Cache import configuration. Equivalent to Docker's `--cache-to` flag. :param pulumi.Input['BuildContextArgs'] context: Build context settings. Defaults to the current directory. Equivalent to Docker's `PATH | URL | -` positional argument. :param pulumi.Input['DockerfileArgs'] dockerfile: Dockerfile settings. Equivalent to Docker's `--file` flag. :param pulumi.Input[bool] exec_: Use `exec` mode to build this image. By default the provider embeds a v25 Docker client with v0.12 buildx support. This helps ensure consistent behavior across environments and is compatible with alternative build backends (e.g. `buildkitd`), but it may not be desirable if you require a specific version of buildx. For example you may want to run a custom `docker-buildx` binary with support for [Docker Build Cloud](https://docs.docker.com/build/cloud/setup/) (DBC). When this is set to `true` the provider will instead execute the `docker-buildx` binary directly to perform its operations. The user is responsible for ensuring this binary exists, with correct permissions and pre-configured builders, at a path Docker expects (e.g. `~/.docker/cli-plugins`). Debugging `exec` mode may be more difficult as Pulumi will not be able to surface fine-grained errors and warnings. Additionally credentials are temporarily written to disk in order to provide them to the `docker-buildx` binary. :param pulumi.Input[Sequence[pulumi.Input['ExportArgs']]] exports: Controls where images are persisted after building. Images are only stored in the local cache unless `exports` are explicitly configured. Exporting to multiple destinations requires a daemon running BuildKit 0.13 or later. Equivalent to Docker's `--output` flag. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] labels: Attach arbitrary key/value metadata to the image. Equivalent to Docker's `--label` flag. :param pulumi.Input[bool] load: When `true` the build will automatically include a `docker` export. Defaults to `false`. Equivalent to Docker's `--load` flag. :param pulumi.Input['NetworkMode'] network: Set the network mode for `RUN` instructions. Defaults to `default`. For custom networks, configure your builder with `--driver-opt network=...`. Equivalent to Docker's `--network` flag. :param pulumi.Input[bool] no_cache: Do not import cache manifests when building the image. Equivalent to Docker's `--no-cache` flag. :param pulumi.Input[Sequence[pulumi.Input['Platform']]] platforms: Set target platform(s) for the build. Defaults to the host's platform. Equivalent to Docker's `--platform` flag. :param pulumi.Input[bool] pull: Always pull referenced images. Equivalent to Docker's `--pull` flag. :param pulumi.Input[Sequence[pulumi.Input['RegistryArgs']]] registries: Registry credentials. Required if reading or exporting to private repositories. Credentials are kept in-memory and do not pollute pre-existing credentials on the host. Similar to `docker login`. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] secrets: A mapping of secret names to their corresponding values. Unlike the Docker CLI, these can be passed by value and do not need to exist on-disk or in environment variables. Build arguments and environment variables are persistent in the final image, so you should use this for sensitive values. Similar to Docker's `--secret` flag. :param pulumi.Input[Sequence[pulumi.Input['SSHArgs']]] ssh: SSH agent socket or keys to expose to the build. Equivalent to Docker's `--ssh` flag. :param pulumi.Input[Sequence[pulumi.Input[str]]] tags: Name and optionally a tag (format: `name:tag`). If exporting to a registry, the name should include the fully qualified registry address (e.g. `docker.io/pulumi/pulumi:latest`). Equivalent to Docker's `--tag` flag. :param pulumi.Input[str] target: Set the target build stage(s) to build. If not specified all targets will be built by default. Equivalent to Docker's `--target` flag. """ pulumi.set(__self__, "push", push) if add_hosts is not None: pulumi.set(__self__, "add_hosts", add_hosts) if build_args is not None: pulumi.set(__self__, "build_args", build_args) if build_on_preview is None: build_on_preview = True if build_on_preview is not None: pulumi.set(__self__, "build_on_preview", build_on_preview) if builder is not None: pulumi.set(__self__, "builder", builder) if cache_from is not None: pulumi.set(__self__, "cache_from", cache_from) if cache_to is not None: pulumi.set(__self__, "cache_to", cache_to) if context is not None: pulumi.set(__self__, "context", context) if dockerfile is not None: pulumi.set(__self__, "dockerfile", dockerfile) if exec_ is not None: pulumi.set(__self__, "exec_", exec_) if exports is not None: pulumi.set(__self__, "exports", exports) if labels is not None: pulumi.set(__self__, "labels", labels) if load is not None: pulumi.set(__self__, "load", load) if network is None: network = 'default' if network is not None: pulumi.set(__self__, "network", network) if no_cache is not None: pulumi.set(__self__, "no_cache", no_cache) if platforms is not None: pulumi.set(__self__, "platforms", platforms) if pull is not None: pulumi.set(__self__, "pull", pull) if registries is not None: pulumi.set(__self__, "registries", registries) if secrets is not None: pulumi.set(__self__, "secrets", secrets) if ssh is not None: pulumi.set(__self__, "ssh", ssh) if tags is not None: pulumi.set(__self__, "tags", tags) if target is not None: pulumi.set(__self__, "target", target) @property @pulumi.getter def push(self) -> pulumi.Input[bool]: """ When `true` the build will automatically include a `registry` export. Defaults to `false`. Equivalent to Docker's `--push` flag. """ return pulumi.get(self, "push") @push.setter def push(self, value: pulumi.Input[bool]): pulumi.set(self, "push", value) @property @pulumi.getter(name="addHosts") def add_hosts(self) -> Optional[pulumi.Input[Sequence[pulumi.Input[str]]]]: """ Custom `host:ip` mappings to use during the build. Equivalent to Docker's `--add-host` flag. """ return pulumi.get(self, "add_hosts") @add_hosts.setter def add_hosts(self, value: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]]): pulumi.set(self, "add_hosts", value) @property @pulumi.getter(name="buildArgs") def build_args(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]: """ `ARG` names and values to set during the build. These variables are accessed like environment variables inside `RUN` instructions. Build arguments are persisted in the image, so you should use `secrets` if these arguments are sensitive. Equivalent to Docker's `--build-arg` flag. """ return pulumi.get(self, "build_args") @build_args.setter def build_args(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]): pulumi.set(self, "build_args", value) @property @pulumi.getter(name="buildOnPreview") def build_on_preview(self) -> Optional[pulumi.Input[bool]]: """ Setting this to `false` will always skip image builds during previews, and setting it to `true` will always build images during previews. Images built during previews are never exported to registries, however cache manifests are still exported. On-disk Dockerfiles are always validated for syntactic correctness regardless of this setting. Defaults to `true` as a safeguard against broken images merging as part of CI pipelines. """ return pulumi.get(self, "build_on_preview") @build_on_preview.setter def build_on_preview(self, value: Optional[pulumi.Input[bool]]): pulumi.set(self, "build_on_preview", value) @property @pulumi.getter def builder(self) -> Optional[pulumi.Input['BuilderConfigArgs']]: """ Builder configuration. """ return pulumi.get(self, "builder") @builder.setter def builder(self, value: Optional[pulumi.Input['BuilderConfigArgs']]): pulumi.set(self, "builder", value) @property @pulumi.getter(name="cacheFrom") def cache_from(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['CacheFromArgs']]]]: """ Cache export configuration. Equivalent to Docker's `--cache-from` flag. """ return pulumi.get(self, "cache_from") @cache_from.setter def cache_from(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['CacheFromArgs']]]]): pulumi.set(self, "cache_from", value) @property @pulumi.getter(name="cacheTo") def cache_to(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['CacheToArgs']]]]: """ Cache import configuration. Equivalent to Docker's `--cache-to` flag. """ return pulumi.get(self, "cache_to") @cache_to.setter def cache_to(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['CacheToArgs']]]]): pulumi.set(self, "cache_to", value) @property @pulumi.getter def context(self) -> Optional[pulumi.Input['BuildContextArgs']]: """ Build context settings. Defaults to the current directory. Equivalent to Docker's `PATH | URL | -` positional argument. """ return pulumi.get(self, "context") @context.setter def context(self, value: Optional[pulumi.Input['BuildContextArgs']]): pulumi.set(self, "context", value) @property @pulumi.getter def dockerfile(self) -> Optional[pulumi.Input['DockerfileArgs']]: """ Dockerfile settings. Equivalent to Docker's `--file` flag. """ return pulumi.get(self, "dockerfile") @dockerfile.setter def dockerfile(self, value: Optional[pulumi.Input['DockerfileArgs']]): pulumi.set(self, "dockerfile", value) @property @pulumi.getter(name="exec") def exec_(self) -> Optional[pulumi.Input[bool]]: """ Use `exec` mode to build this image. By default the provider embeds a v25 Docker client with v0.12 buildx support. This helps ensure consistent behavior across environments and is compatible with alternative build backends (e.g. `buildkitd`), but it may not be desirable if you require a specific version of buildx. For example you may want to run a custom `docker-buildx` binary with support for [Docker Build Cloud](https://docs.docker.com/build/cloud/setup/) (DBC). When this is set to `true` the provider will instead execute the `docker-buildx` binary directly to perform its operations. The user is responsible for ensuring this binary exists, with correct permissions and pre-configured builders, at a path Docker expects (e.g. `~/.docker/cli-plugins`). Debugging `exec` mode may be more difficult as Pulumi will not be able to surface fine-grained errors and warnings. Additionally credentials are temporarily written to disk in order to provide them to the `docker-buildx` binary. """ return pulumi.get(self, "exec_") @exec_.setter def exec_(self, value: Optional[pulumi.Input[bool]]): pulumi.set(self, "exec_", value) @property @pulumi.getter def exports(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['ExportArgs']]]]: """ Controls where images are persisted after building. Images are only stored in the local cache unless `exports` are explicitly configured. Exporting to multiple destinations requires a daemon running BuildKit 0.13 or later. Equivalent to Docker's `--output` flag. """ return pulumi.get(self, "exports") @exports.setter def exports(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['ExportArgs']]]]): pulumi.set(self, "exports", value) @property @pulumi.getter def labels(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]: """ Attach arbitrary key/value metadata to the image. Equivalent to Docker's `--label` flag. """ return pulumi.get(self, "labels") @labels.setter def labels(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]): pulumi.set(self, "labels", value) @property @pulumi.getter def load(self) -> Optional[pulumi.Input[bool]]: """ When `true` the build will automatically include a `docker` export. Defaults to `false`. Equivalent to Docker's `--load` flag. """ return pulumi.get(self, "load") @load.setter def load(self, value: Optional[pulumi.Input[bool]]): pulumi.set(self, "load", value) @property @pulumi.getter def network(self) -> Optional[pulumi.Input['NetworkMode']]: """ Set the network mode for `RUN` instructions. Defaults to `default`. For custom networks, configure your builder with `--driver-opt network=...`. Equivalent to Docker's `--network` flag. """ return pulumi.get(self, "network") @network.setter def network(self, value: Optional[pulumi.Input['NetworkMode']]): pulumi.set(self, "network", value) @property @pulumi.getter(name="noCache") def no_cache(self) -> Optional[pulumi.Input[bool]]: """ Do not import cache manifests when building the image. Equivalent to Docker's `--no-cache` flag. """ return pulumi.get(self, "no_cache") @no_cache.setter def no_cache(self, value: Optional[pulumi.Input[bool]]): pulumi.set(self, "no_cache", value) @property @pulumi.getter def platforms(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['Platform']]]]: """ Set target platform(s) for the build. Defaults to the host's platform. Equivalent to Docker's `--platform` flag. """ return pulumi.get(self, "platforms") @platforms.setter def platforms(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['Platform']]]]): pulumi.set(self, "platforms", value) @property @pulumi.getter def pull(self) -> Optional[pulumi.Input[bool]]: """ Always pull referenced images. Equivalent to Docker's `--pull` flag. """ return pulumi.get(self, "pull") @pull.setter def pull(self, value: Optional[pulumi.Input[bool]]): pulumi.set(self, "pull", value) @property @pulumi.getter def registries(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['RegistryArgs']]]]: """ Registry credentials. Required if reading or exporting to private repositories. Credentials are kept in-memory and do not pollute pre-existing credentials on the host. Similar to `docker login`. """ return pulumi.get(self, "registries") @registries.setter def registries(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['RegistryArgs']]]]): pulumi.set(self, "registries", value) @property @pulumi.getter def secrets(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]: """ A mapping of secret names to their corresponding values. Unlike the Docker CLI, these can be passed by value and do not need to exist on-disk or in environment variables. Build arguments and environment variables are persistent in the final image, so you should use this for sensitive values. Similar to Docker's `--secret` flag. """ return pulumi.get(self, "secrets") @secrets.setter def secrets(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]): pulumi.set(self, "secrets", value) @property @pulumi.getter def ssh(self) -> Optional[pulumi.Input[Sequence[pulumi.Input['SSHArgs']]]]: """ SSH agent socket or keys to expose to the build. Equivalent to Docker's `--ssh` flag. """ return pulumi.get(self, "ssh") @ssh.setter def ssh(self, value: Optional[pulumi.Input[Sequence[pulumi.Input['SSHArgs']]]]): pulumi.set(self, "ssh", value) @property @pulumi.getter def tags(self) -> Optional[pulumi.Input[Sequence[pulumi.Input[str]]]]: """ Name and optionally a tag (format: `name:tag`). If exporting to a registry, the name should include the fully qualified registry address (e.g. `docker.io/pulumi/pulumi:latest`). Equivalent to Docker's `--tag` flag. """ return pulumi.get(self, "tags") @tags.setter def tags(self, value: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]]): pulumi.set(self, "tags", value) @property @pulumi.getter def target(self) -> Optional[pulumi.Input[str]]: """ Set the target build stage(s) to build. If not specified all targets will be built by default. Equivalent to Docker's `--target` flag. """ return pulumi.get(self, "target") @target.setter def target(self, value: Optional[pulumi.Input[str]]): pulumi.set(self, "target", value) class Image(pulumi.CustomResource): @overload def __init__(__self__, resource_name: str, opts: Optional[pulumi.ResourceOptions] = None, add_hosts: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, build_args: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, build_on_preview: Optional[pulumi.Input[bool]] = None, builder: Optional[pulumi.Input[pulumi.InputType['BuilderConfigArgs']]] = None, cache_from: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheFromArgs']]]]] = None, cache_to: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheToArgs']]]]] = None, context: Optional[pulumi.Input[pulumi.InputType['BuildContextArgs']]] = None, dockerfile: Optional[pulumi.Input[pulumi.InputType['DockerfileArgs']]] = None, exec_: Optional[pulumi.Input[bool]] = None, exports: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['ExportArgs']]]]] = None, labels: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, load: Optional[pulumi.Input[bool]] = None, network: Optional[pulumi.Input['NetworkMode']] = None, no_cache: Optional[pulumi.Input[bool]] = None, platforms: Optional[pulumi.Input[Sequence[pulumi.Input['Platform']]]] = None, pull: Optional[pulumi.Input[bool]] = None, push: Optional[pulumi.Input[bool]] = None, registries: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['RegistryArgs']]]]] = None, secrets: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, ssh: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['SSHArgs']]]]] = None, tags: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, target: Optional[pulumi.Input[str]] = None, __props__=None): """ A Docker image built using buildx -- Docker's interface to the improved BuildKit backend. ## Stability **This resource is pre-1.0 and in public preview.** We will strive to keep APIs and behavior as stable as possible, but we cannot guarantee stability until version 1.0. ## Migrating Pulumi Docker v3 and v4 Image resources This provider's `Image` resource provides a superset of functionality over the `Image` resources available in versions 3 and 4 of the Pulumi Docker provider. Existing `Image` resources can be converted to the docker-build `Image` resources with minor modifications. ### Behavioral differences There are several key behavioral differences to keep in mind when transitioning images to the new `Image` resource. #### Previews Version `3.x` of the Pulumi Docker provider always builds images during preview operations. This is helpful as a safeguard to prevent "broken" images from merging, but users found the behavior unnecessarily redundant when running previews and updates locally. Version `4.x` changed build-on-preview behavior to be opt-in. By default, `v4.x` `Image` resources do _not_ build during previews, but this behavior can be toggled with the `buildOnPreview` option. Several users reported outages due to the default behavior allowing bad images to accidentally sneak through CI. The default behavior of this provider's `Image` resource is similar to `3.x` and will build images during previews. This behavior can be changed by specifying `buildOnPreview`. #### Push behavior Versions `3.x` and `4.x` of the Pulumi Docker provider attempt to push images to remote registries by default. They expose a `skipPush: true` option to disable pushing. This provider's `Image` resource matches the Docker CLI's behavior and does not push images anywhere by default. To push images to a registry you can include `push: true` (equivalent to Docker's `--push` flag) or configure an `export` of type `registry` (equivalent to Docker's `--output type=registry`). Like Docker, if an image is configured without exports you will see a warning with instructions for how to enable pushing, but the build will still proceed normally. #### Secrets Version `3.x` of the Pulumi Docker provider supports secrets by way of the `extraOptions` field. Version `4.x` of the Pulumi Docker provider does not support secrets. The `Image` resource supports secrets but does not require those secrets to exist on-disk or in environment variables. Instead, they should be passed directly as values. (Please be sure to familiarize yourself with Pulumi's [native secret handling](https://www.pulumi.com/docs/concepts/secrets/).) Pulumi also provides [ESC](https://www.pulumi.com/product/esc/) to make it easier to share secrets across stacks and environments. #### Caching Version `3.x` of the Pulumi Docker provider exposes `cacheFrom: bool | { stages: [...] }`. It builds targets individually and pushes them to separate images for caching. Version `4.x` exposes a similar parameter `cacheFrom: { images: [...] }` which pushes and pulls inline caches. Both versions 3 and 4 require specific environment variables to be set and deviate from Docker's native caching behavior. This can result in inefficient builds due to unnecessary image pulls, repeated file transfers, etc. The `Image` resource delegates all caching behavior to Docker. `cacheFrom` and `cacheTo` options (equivalent to Docker's `--cache-to` and `--cache-from`) are exposed and provide additional cache targets, such as local disk, S3 storage, etc. #### Outputs Versions `3.x` and `4.x` of the provider exposed a `repoDigest` output which was a fully qualified tag with digest. In `4.x` this could also be a single sha256 hash if the image wasn't pushed. Unlike earlier providers the `Image` resource can push multiple tags. As a convenience, it exposes a `ref` output consisting of a tag with digest as long as the image was pushed. If multiple tags were pushed this uses one at random. If you need more control over tag references you can use the `digest` output, which is always a single sha256 hash as long as the image was exported somewhere. #### Tag deletion and refreshes Versions 3 and 4 of Pulumi Docker provider do not delete tags when the `Image` resource is deleted, nor do they confirm expected tags exist during `refresh` operations. The `buidx.Image` will query your registries during `refresh` to ensure the expected tags exist. If any are missing a subsequent `update` will push them. When a `Image` is deleted, it will _attempt_ to also delete any pushed tags. Deletion of remote tags is not guaranteed because not all registries support the manifest `DELETE` API (`docker.io` in particular). Manifests are _not_ deleted in the same way during updates -- to do so safely would require a full build to determine whether a Pulumi operation should be an update or update-replace. Use the [`retainOnDelete: true`](https://www.pulumi.com/docs/concepts/options/retainondelete/) option if you do not want tags deleted. ### Example migration Examples of "fully-featured" `v3` and `v4` `Image` resources are shown below, along with an example `Image` resource showing how they would look after migration. The `v3` resource leverages `buildx` via a `DOCKER_BUILDKIT` environment variable and CLI flags passed in with `extraOption`. After migration, the environment variable is no longer needed and CLI flags are now properties on the `Image`. In almost all cases, properties of `Image` are named after the Docker CLI flag they correspond to. The `v4` resource is less functional than its `v3` counterpart because it lacks the flexibility of `extraOptions`. It it is shown with parameters similar to the `v3` example for completeness. ## Example Usage ## Example Usage ### Push to AWS ECR with caching ```python import pulumi import pulumi_aws as aws import pulumi_docker_build as docker_build ecr_repository = aws.ecr.Repository("ecr-repository") auth_token = aws.ecr.get_authorization_token_output(registry_id=ecr_repository.registry_id) my_image = docker_build.Image("my-image", cache_from=[docker_build.CacheFromArgs( registry=docker_build.CacheFromRegistryArgs( ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:cache"), ), )], cache_to=[docker_build.CacheToArgs( registry=docker_build.CacheToRegistryArgs( image_manifest=True, oci_media_types=True, ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:cache"), ), )], context=docker_build.BuildContextArgs( location="./app", ), push=True, registries=[docker_build.RegistryArgs( address=ecr_repository.repository_url, password=auth_token.password, username=auth_token.user_name, )], tags=[ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest")]) pulumi.export("ref", my_image.ref) ``` ### Multi-platform image ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), platforms=[ docker_build.Platform.PLAN9_AMD64, docker_build.Platform.PLAN9_386, ], push=False) ``` ### Registry export ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), push=True, registries=[docker_build.RegistryArgs( address="docker.io", password=docker_hub_password, username="pulumibot", )], tags=["docker.io/pulumi/pulumi:3.107.0"]) pulumi.export("ref", my_image["ref"]) ``` ### Caching ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", cache_from=[docker_build.CacheFromArgs( local=docker_build.CacheFromLocalArgs( src="tmp/cache", ), )], cache_to=[docker_build.CacheToArgs( local=docker_build.CacheToLocalArgs( dest="tmp/cache", mode=docker_build.CacheMode.MAX, ), )], context=docker_build.BuildContextArgs( location="app", ), push=False) ``` ### Docker Build Cloud ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", builder=docker_build.BuilderConfigArgs( name="cloud-builder-name", ), context=docker_build.BuildContextArgs( location="app", ), exec_=True, push=False) ``` ### Build arguments ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", build_args={ "SET_ME_TO_TRUE": "true", }, context=docker_build.BuildContextArgs( location="app", ), push=False) ``` ### Build target ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), push=False, target="build-me") ``` ### Named contexts ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", named={ "golang:latest": docker_build.ContextArgs( location="docker-image://golang@sha256:b8e62cf593cdaff36efd90aa3a37de268e6781a2e68c6610940c48f7cdf36984", ), }, ), push=False) ``` ### Remote context ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="https://raw.githubusercontent.com/pulumi/pulumi-docker/api-types/provider/testdata/Dockerfile", ), push=False) ``` ### Inline Dockerfile ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), dockerfile=docker_build.DockerfileArgs( inline=\"\"\"FROM busybox COPY hello.c ./ \"\"\", ), push=False) ``` ### Remote context ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="https://github.com/docker-library/hello-world.git", ), dockerfile=docker_build.DockerfileArgs( location="app/Dockerfile", ), push=False) ``` ### Local export ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), exports=[docker_build.ExportArgs( docker=docker_build.ExportDockerArgs( tar=True, ), )], push=False) ``` :param str resource_name: The name of the resource. :param pulumi.ResourceOptions opts: Options for the resource. :param pulumi.Input[Sequence[pulumi.Input[str]]] add_hosts: Custom `host:ip` mappings to use during the build. Equivalent to Docker's `--add-host` flag. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] build_args: `ARG` names and values to set during the build. These variables are accessed like environment variables inside `RUN` instructions. Build arguments are persisted in the image, so you should use `secrets` if these arguments are sensitive. Equivalent to Docker's `--build-arg` flag. :param pulumi.Input[bool] build_on_preview: Setting this to `false` will always skip image builds during previews, and setting it to `true` will always build images during previews. Images built during previews are never exported to registries, however cache manifests are still exported. On-disk Dockerfiles are always validated for syntactic correctness regardless of this setting. Defaults to `true` as a safeguard against broken images merging as part of CI pipelines. :param pulumi.Input[pulumi.InputType['BuilderConfigArgs']] builder: Builder configuration. :param pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheFromArgs']]]] cache_from: Cache export configuration. Equivalent to Docker's `--cache-from` flag. :param pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheToArgs']]]] cache_to: Cache import configuration. Equivalent to Docker's `--cache-to` flag. :param pulumi.Input[pulumi.InputType['BuildContextArgs']] context: Build context settings. Defaults to the current directory. Equivalent to Docker's `PATH | URL | -` positional argument. :param pulumi.Input[pulumi.InputType['DockerfileArgs']] dockerfile: Dockerfile settings. Equivalent to Docker's `--file` flag. :param pulumi.Input[bool] exec_: Use `exec` mode to build this image. By default the provider embeds a v25 Docker client with v0.12 buildx support. This helps ensure consistent behavior across environments and is compatible with alternative build backends (e.g. `buildkitd`), but it may not be desirable if you require a specific version of buildx. For example you may want to run a custom `docker-buildx` binary with support for [Docker Build Cloud](https://docs.docker.com/build/cloud/setup/) (DBC). When this is set to `true` the provider will instead execute the `docker-buildx` binary directly to perform its operations. The user is responsible for ensuring this binary exists, with correct permissions and pre-configured builders, at a path Docker expects (e.g. `~/.docker/cli-plugins`). Debugging `exec` mode may be more difficult as Pulumi will not be able to surface fine-grained errors and warnings. Additionally credentials are temporarily written to disk in order to provide them to the `docker-buildx` binary. :param pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['ExportArgs']]]] exports: Controls where images are persisted after building. Images are only stored in the local cache unless `exports` are explicitly configured. Exporting to multiple destinations requires a daemon running BuildKit 0.13 or later. Equivalent to Docker's `--output` flag. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] labels: Attach arbitrary key/value metadata to the image. Equivalent to Docker's `--label` flag. :param pulumi.Input[bool] load: When `true` the build will automatically include a `docker` export. Defaults to `false`. Equivalent to Docker's `--load` flag. :param pulumi.Input['NetworkMode'] network: Set the network mode for `RUN` instructions. Defaults to `default`. For custom networks, configure your builder with `--driver-opt network=...`. Equivalent to Docker's `--network` flag. :param pulumi.Input[bool] no_cache: Do not import cache manifests when building the image. Equivalent to Docker's `--no-cache` flag. :param pulumi.Input[Sequence[pulumi.Input['Platform']]] platforms: Set target platform(s) for the build. Defaults to the host's platform. Equivalent to Docker's `--platform` flag. :param pulumi.Input[bool] pull: Always pull referenced images. Equivalent to Docker's `--pull` flag. :param pulumi.Input[bool] push: When `true` the build will automatically include a `registry` export. Defaults to `false`. Equivalent to Docker's `--push` flag. :param pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['RegistryArgs']]]] registries: Registry credentials. Required if reading or exporting to private repositories. Credentials are kept in-memory and do not pollute pre-existing credentials on the host. Similar to `docker login`. :param pulumi.Input[Mapping[str, pulumi.Input[str]]] secrets: A mapping of secret names to their corresponding values. Unlike the Docker CLI, these can be passed by value and do not need to exist on-disk or in environment variables. Build arguments and environment variables are persistent in the final image, so you should use this for sensitive values. Similar to Docker's `--secret` flag. :param pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['SSHArgs']]]] ssh: SSH agent socket or keys to expose to the build. Equivalent to Docker's `--ssh` flag. :param pulumi.Input[Sequence[pulumi.Input[str]]] tags: Name and optionally a tag (format: `name:tag`). If exporting to a registry, the name should include the fully qualified registry address (e.g. `docker.io/pulumi/pulumi:latest`). Equivalent to Docker's `--tag` flag. :param pulumi.Input[str] target: Set the target build stage(s) to build. If not specified all targets will be built by default. Equivalent to Docker's `--target` flag. """ ... @overload def __init__(__self__, resource_name: str, args: ImageArgs, opts: Optional[pulumi.ResourceOptions] = None): """ A Docker image built using buildx -- Docker's interface to the improved BuildKit backend. ## Stability **This resource is pre-1.0 and in public preview.** We will strive to keep APIs and behavior as stable as possible, but we cannot guarantee stability until version 1.0. ## Migrating Pulumi Docker v3 and v4 Image resources This provider's `Image` resource provides a superset of functionality over the `Image` resources available in versions 3 and 4 of the Pulumi Docker provider. Existing `Image` resources can be converted to the docker-build `Image` resources with minor modifications. ### Behavioral differences There are several key behavioral differences to keep in mind when transitioning images to the new `Image` resource. #### Previews Version `3.x` of the Pulumi Docker provider always builds images during preview operations. This is helpful as a safeguard to prevent "broken" images from merging, but users found the behavior unnecessarily redundant when running previews and updates locally. Version `4.x` changed build-on-preview behavior to be opt-in. By default, `v4.x` `Image` resources do _not_ build during previews, but this behavior can be toggled with the `buildOnPreview` option. Several users reported outages due to the default behavior allowing bad images to accidentally sneak through CI. The default behavior of this provider's `Image` resource is similar to `3.x` and will build images during previews. This behavior can be changed by specifying `buildOnPreview`. #### Push behavior Versions `3.x` and `4.x` of the Pulumi Docker provider attempt to push images to remote registries by default. They expose a `skipPush: true` option to disable pushing. This provider's `Image` resource matches the Docker CLI's behavior and does not push images anywhere by default. To push images to a registry you can include `push: true` (equivalent to Docker's `--push` flag) or configure an `export` of type `registry` (equivalent to Docker's `--output type=registry`). Like Docker, if an image is configured without exports you will see a warning with instructions for how to enable pushing, but the build will still proceed normally. #### Secrets Version `3.x` of the Pulumi Docker provider supports secrets by way of the `extraOptions` field. Version `4.x` of the Pulumi Docker provider does not support secrets. The `Image` resource supports secrets but does not require those secrets to exist on-disk or in environment variables. Instead, they should be passed directly as values. (Please be sure to familiarize yourself with Pulumi's [native secret handling](https://www.pulumi.com/docs/concepts/secrets/).) Pulumi also provides [ESC](https://www.pulumi.com/product/esc/) to make it easier to share secrets across stacks and environments. #### Caching Version `3.x` of the Pulumi Docker provider exposes `cacheFrom: bool | { stages: [...] }`. It builds targets individually and pushes them to separate images for caching. Version `4.x` exposes a similar parameter `cacheFrom: { images: [...] }` which pushes and pulls inline caches. Both versions 3 and 4 require specific environment variables to be set and deviate from Docker's native caching behavior. This can result in inefficient builds due to unnecessary image pulls, repeated file transfers, etc. The `Image` resource delegates all caching behavior to Docker. `cacheFrom` and `cacheTo` options (equivalent to Docker's `--cache-to` and `--cache-from`) are exposed and provide additional cache targets, such as local disk, S3 storage, etc. #### Outputs Versions `3.x` and `4.x` of the provider exposed a `repoDigest` output which was a fully qualified tag with digest. In `4.x` this could also be a single sha256 hash if the image wasn't pushed. Unlike earlier providers the `Image` resource can push multiple tags. As a convenience, it exposes a `ref` output consisting of a tag with digest as long as the image was pushed. If multiple tags were pushed this uses one at random. If you need more control over tag references you can use the `digest` output, which is always a single sha256 hash as long as the image was exported somewhere. #### Tag deletion and refreshes Versions 3 and 4 of Pulumi Docker provider do not delete tags when the `Image` resource is deleted, nor do they confirm expected tags exist during `refresh` operations. The `buidx.Image` will query your registries during `refresh` to ensure the expected tags exist. If any are missing a subsequent `update` will push them. When a `Image` is deleted, it will _attempt_ to also delete any pushed tags. Deletion of remote tags is not guaranteed because not all registries support the manifest `DELETE` API (`docker.io` in particular). Manifests are _not_ deleted in the same way during updates -- to do so safely would require a full build to determine whether a Pulumi operation should be an update or update-replace. Use the [`retainOnDelete: true`](https://www.pulumi.com/docs/concepts/options/retainondelete/) option if you do not want tags deleted. ### Example migration Examples of "fully-featured" `v3` and `v4` `Image` resources are shown below, along with an example `Image` resource showing how they would look after migration. The `v3` resource leverages `buildx` via a `DOCKER_BUILDKIT` environment variable and CLI flags passed in with `extraOption`. After migration, the environment variable is no longer needed and CLI flags are now properties on the `Image`. In almost all cases, properties of `Image` are named after the Docker CLI flag they correspond to. The `v4` resource is less functional than its `v3` counterpart because it lacks the flexibility of `extraOptions`. It it is shown with parameters similar to the `v3` example for completeness. ## Example Usage ## Example Usage ### Push to AWS ECR with caching ```python import pulumi import pulumi_aws as aws import pulumi_docker_build as docker_build ecr_repository = aws.ecr.Repository("ecr-repository") auth_token = aws.ecr.get_authorization_token_output(registry_id=ecr_repository.registry_id) my_image = docker_build.Image("my-image", cache_from=[docker_build.CacheFromArgs( registry=docker_build.CacheFromRegistryArgs( ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:cache"), ), )], cache_to=[docker_build.CacheToArgs( registry=docker_build.CacheToRegistryArgs( image_manifest=True, oci_media_types=True, ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:cache"), ), )], context=docker_build.BuildContextArgs( location="./app", ), push=True, registries=[docker_build.RegistryArgs( address=ecr_repository.repository_url, password=auth_token.password, username=auth_token.user_name, )], tags=[ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest")]) pulumi.export("ref", my_image.ref) ``` ### Multi-platform image ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), platforms=[ docker_build.Platform.PLAN9_AMD64, docker_build.Platform.PLAN9_386, ], push=False) ``` ### Registry export ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), push=True, registries=[docker_build.RegistryArgs( address="docker.io", password=docker_hub_password, username="pulumibot", )], tags=["docker.io/pulumi/pulumi:3.107.0"]) pulumi.export("ref", my_image["ref"]) ``` ### Caching ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", cache_from=[docker_build.CacheFromArgs( local=docker_build.CacheFromLocalArgs( src="tmp/cache", ), )], cache_to=[docker_build.CacheToArgs( local=docker_build.CacheToLocalArgs( dest="tmp/cache", mode=docker_build.CacheMode.MAX, ), )], context=docker_build.BuildContextArgs( location="app", ), push=False) ``` ### Docker Build Cloud ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", builder=docker_build.BuilderConfigArgs( name="cloud-builder-name", ), context=docker_build.BuildContextArgs( location="app", ), exec_=True, push=False) ``` ### Build arguments ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", build_args={ "SET_ME_TO_TRUE": "true", }, context=docker_build.BuildContextArgs( location="app", ), push=False) ``` ### Build target ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), push=False, target="build-me") ``` ### Named contexts ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", named={ "golang:latest": docker_build.ContextArgs( location="docker-image://golang@sha256:b8e62cf593cdaff36efd90aa3a37de268e6781a2e68c6610940c48f7cdf36984", ), }, ), push=False) ``` ### Remote context ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="https://raw.githubusercontent.com/pulumi/pulumi-docker/api-types/provider/testdata/Dockerfile", ), push=False) ``` ### Inline Dockerfile ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), dockerfile=docker_build.DockerfileArgs( inline=\"\"\"FROM busybox COPY hello.c ./ \"\"\", ), push=False) ``` ### Remote context ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="https://github.com/docker-library/hello-world.git", ), dockerfile=docker_build.DockerfileArgs( location="app/Dockerfile", ), push=False) ``` ### Local export ```python import pulumi import pulumi_docker_build as docker_build image = docker_build.Image("image", context=docker_build.BuildContextArgs( location="app", ), exports=[docker_build.ExportArgs( docker=docker_build.ExportDockerArgs( tar=True, ), )], push=False) ``` :param str resource_name: The name of the resource. :param ImageArgs args: The arguments to use to populate this resource's properties. :param pulumi.ResourceOptions opts: Options for the resource. """ ... def __init__(__self__, resource_name: str, *args, **kwargs): resource_args, opts = _utilities.get_resource_args_opts(ImageArgs, pulumi.ResourceOptions, *args, **kwargs) if resource_args is not None: __self__._internal_init(resource_name, opts, **resource_args.__dict__) else: __self__._internal_init(resource_name, *args, **kwargs) def _internal_init(__self__, resource_name: str, opts: Optional[pulumi.ResourceOptions] = None, add_hosts: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, build_args: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, build_on_preview: Optional[pulumi.Input[bool]] = None, builder: Optional[pulumi.Input[pulumi.InputType['BuilderConfigArgs']]] = None, cache_from: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheFromArgs']]]]] = None, cache_to: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['CacheToArgs']]]]] = None, context: Optional[pulumi.Input[pulumi.InputType['BuildContextArgs']]] = None, dockerfile: Optional[pulumi.Input[pulumi.InputType['DockerfileArgs']]] = None, exec_: Optional[pulumi.Input[bool]] = None, exports: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['ExportArgs']]]]] = None, labels: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, load: Optional[pulumi.Input[bool]] = None, network: Optional[pulumi.Input['NetworkMode']] = None, no_cache: Optional[pulumi.Input[bool]] = None, platforms: Optional[pulumi.Input[Sequence[pulumi.Input['Platform']]]] = None, pull: Optional[pulumi.Input[bool]] = None, push: Optional[pulumi.Input[bool]] = None, registries: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['RegistryArgs']]]]] = None, secrets: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None, ssh: Optional[pulumi.Input[Sequence[pulumi.Input[pulumi.InputType['SSHArgs']]]]] = None, tags: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None, target: Optional[pulumi.Input[str]] = None, __props__=None): opts = pulumi.ResourceOptions.merge(_utilities.get_resource_opts_defaults(), opts) if not isinstance(opts, pulumi.ResourceOptions): raise TypeError('Expected resource options to be a ResourceOptions instance') if opts.id is None: if __props__ is not None: raise TypeError('__props__ is only valid when passed in combination with a valid opts.id to get an existing resource') __props__ = ImageArgs.__new__(ImageArgs) __props__.__dict__["add_hosts"] = add_hosts __props__.__dict__["build_args"] = build_args if build_on_preview is None: build_on_preview = True __props__.__dict__["build_on_preview"] = build_on_preview __props__.__dict__["builder"] = builder __props__.__dict__["cache_from"] = cache_from __props__.__dict__["cache_to"] = cache_to __props__.__dict__["context"] = context __props__.__dict__["dockerfile"] = dockerfile __props__.__dict__["exec_"] = exec_ __props__.__dict__["exports"] = exports __props__.__dict__["labels"] = labels __props__.__dict__["load"] = load if network is None: network = 'default' __props__.__dict__["network"] = network __props__.__dict__["no_cache"] = no_cache __props__.__dict__["platforms"] = platforms __props__.__dict__["pull"] = pull if push is None and not opts.urn: raise TypeError("Missing required property 'push'") __props__.__dict__["push"] = push __props__.__dict__["registries"] = registries __props__.__dict__["secrets"] = secrets __props__.__dict__["ssh"] = ssh __props__.__dict__["tags"] = tags __props__.__dict__["target"] = target __props__.__dict__["context_hash"] = None __props__.__dict__["digest"] = None __props__.__dict__["ref"] = None super(Image, __self__).__init__( 'docker-build:index:Image', resource_name, __props__, opts) @staticmethod def get(resource_name: str, id: pulumi.Input[str], opts: Optional[pulumi.ResourceOptions] = None) -> 'Image': """ Get an existing Image resource's state with the given name, id, and optional extra properties used to qualify the lookup. :param str resource_name: The unique name of the resulting resource. :param pulumi.Input[str] id: The unique provider ID of the resource to lookup. :param pulumi.ResourceOptions opts: Options for the resource. """ opts = pulumi.ResourceOptions.merge(opts, pulumi.ResourceOptions(id=id)) __props__ = ImageArgs.__new__(ImageArgs) __props__.__dict__["add_hosts"] = None __props__.__dict__["build_args"] = None __props__.__dict__["build_on_preview"] = None __props__.__dict__["builder"] = None __props__.__dict__["cache_from"] = None __props__.__dict__["cache_to"] = None __props__.__dict__["context"] = None __props__.__dict__["context_hash"] = None __props__.__dict__["digest"] = None __props__.__dict__["dockerfile"] = None __props__.__dict__["exec_"] = None __props__.__dict__["exports"] = None __props__.__dict__["labels"] = None __props__.__dict__["load"] = None __props__.__dict__["network"] = None __props__.__dict__["no_cache"] = None __props__.__dict__["platforms"] = None __props__.__dict__["pull"] = None __props__.__dict__["push"] = None __props__.__dict__["ref"] = None __props__.__dict__["registries"] = None __props__.__dict__["secrets"] = None __props__.__dict__["ssh"] = None __props__.__dict__["tags"] = None __props__.__dict__["target"] = None return Image(resource_name, opts=opts, __props__=__props__) @property @pulumi.getter(name="addHosts") def add_hosts(self) -> pulumi.Output[Optional[Sequence[str]]]: """ Custom `host:ip` mappings to use during the build. Equivalent to Docker's `--add-host` flag. """ return pulumi.get(self, "add_hosts") @property @pulumi.getter(name="buildArgs") def build_args(self) -> pulumi.Output[Optional[Mapping[str, str]]]: """ `ARG` names and values to set during the build. These variables are accessed like environment variables inside `RUN` instructions. Build arguments are persisted in the image, so you should use `secrets` if these arguments are sensitive. Equivalent to Docker's `--build-arg` flag. """ return pulumi.get(self, "build_args") @property @pulumi.getter(name="buildOnPreview") def build_on_preview(self) -> pulumi.Output[Optional[bool]]: """ Setting this to `false` will always skip image builds during previews, and setting it to `true` will always build images during previews. Images built during previews are never exported to registries, however cache manifests are still exported. On-disk Dockerfiles are always validated for syntactic correctness regardless of this setting. Defaults to `true` as a safeguard against broken images merging as part of CI pipelines. """ return pulumi.get(self, "build_on_preview") @property @pulumi.getter def builder(self) -> pulumi.Output[Optional['outputs.BuilderConfig']]: """ Builder configuration. """ return pulumi.get(self, "builder") @property @pulumi.getter(name="cacheFrom") def cache_from(self) -> pulumi.Output[Optional[Sequence['outputs.CacheFrom']]]: """ Cache export configuration. Equivalent to Docker's `--cache-from` flag. """ return pulumi.get(self, "cache_from") @property @pulumi.getter(name="cacheTo") def cache_to(self) -> pulumi.Output[Optional[Sequence['outputs.CacheTo']]]: """ Cache import configuration. Equivalent to Docker's `--cache-to` flag. """ return pulumi.get(self, "cache_to") @property @pulumi.getter def context(self) -> pulumi.Output[Optional['outputs.BuildContext']]: """ Build context settings. Defaults to the current directory. Equivalent to Docker's `PATH | URL | -` positional argument. """ return pulumi.get(self, "context") @property @pulumi.getter(name="contextHash") def context_hash(self) -> pulumi.Output[str]: """ A preliminary hash of the image's build context. Pulumi uses this to determine if an image _may_ need to be re-built. """ return pulumi.get(self, "context_hash") @property @pulumi.getter def digest(self) -> pulumi.Output[str]: """ A SHA256 digest of the image if it was exported to a registry or elsewhere. Empty if the image was not exported. Registry images can be referenced precisely as `@`. The `ref` output provides one such reference as a convenience. """ return pulumi.get(self, "digest") @property @pulumi.getter def dockerfile(self) -> pulumi.Output[Optional['outputs.Dockerfile']]: """ Dockerfile settings. Equivalent to Docker's `--file` flag. """ return pulumi.get(self, "dockerfile") @property @pulumi.getter(name="exec") def exec_(self) -> pulumi.Output[Optional[bool]]: """ Use `exec` mode to build this image. By default the provider embeds a v25 Docker client with v0.12 buildx support. This helps ensure consistent behavior across environments and is compatible with alternative build backends (e.g. `buildkitd`), but it may not be desirable if you require a specific version of buildx. For example you may want to run a custom `docker-buildx` binary with support for [Docker Build Cloud](https://docs.docker.com/build/cloud/setup/) (DBC). When this is set to `true` the provider will instead execute the `docker-buildx` binary directly to perform its operations. The user is responsible for ensuring this binary exists, with correct permissions and pre-configured builders, at a path Docker expects (e.g. `~/.docker/cli-plugins`). Debugging `exec` mode may be more difficult as Pulumi will not be able to surface fine-grained errors and warnings. Additionally credentials are temporarily written to disk in order to provide them to the `docker-buildx` binary. """ return pulumi.get(self, "exec_") @property @pulumi.getter def exports(self) -> pulumi.Output[Optional[Sequence['outputs.Export']]]: """ Controls where images are persisted after building. Images are only stored in the local cache unless `exports` are explicitly configured. Exporting to multiple destinations requires a daemon running BuildKit 0.13 or later. Equivalent to Docker's `--output` flag. """ return pulumi.get(self, "exports") @property @pulumi.getter def labels(self) -> pulumi.Output[Optional[Mapping[str, str]]]: """ Attach arbitrary key/value metadata to the image. Equivalent to Docker's `--label` flag. """ return pulumi.get(self, "labels") @property @pulumi.getter def load(self) -> pulumi.Output[Optional[bool]]: """ When `true` the build will automatically include a `docker` export. Defaults to `false`. Equivalent to Docker's `--load` flag. """ return pulumi.get(self, "load") @property @pulumi.getter def network(self) -> pulumi.Output[Optional['NetworkMode']]: """ Set the network mode for `RUN` instructions. Defaults to `default`. For custom networks, configure your builder with `--driver-opt network=...`. Equivalent to Docker's `--network` flag. """ return pulumi.get(self, "network") @property @pulumi.getter(name="noCache") def no_cache(self) -> pulumi.Output[Optional[bool]]: """ Do not import cache manifests when building the image. Equivalent to Docker's `--no-cache` flag. """ return pulumi.get(self, "no_cache") @property @pulumi.getter def platforms(self) -> pulumi.Output[Optional[Sequence['Platform']]]: """ Set target platform(s) for the build. Defaults to the host's platform. Equivalent to Docker's `--platform` flag. """ return pulumi.get(self, "platforms") @property @pulumi.getter def pull(self) -> pulumi.Output[Optional[bool]]: """ Always pull referenced images. Equivalent to Docker's `--pull` flag. """ return pulumi.get(self, "pull") @property @pulumi.getter def push(self) -> pulumi.Output[bool]: """ When `true` the build will automatically include a `registry` export. Defaults to `false`. Equivalent to Docker's `--push` flag. """ return pulumi.get(self, "push") @property @pulumi.getter def ref(self) -> pulumi.Output[str]: """ If the image was pushed to any registries then this will contain a single fully-qualified tag including the build's digest. If the image had tags but was not exported, this will take on a value of one of those tags. This will be empty if the image had no exports and no tags. This is only for convenience and may not be appropriate for situations where multiple tags or registries are involved. In those cases this output is not guaranteed to be stable. For more control over tags consumed by downstream resources you should use the `digest` output. """ return pulumi.get(self, "ref") @property @pulumi.getter def registries(self) -> pulumi.Output[Optional[Sequence['outputs.Registry']]]: """ Registry credentials. Required if reading or exporting to private repositories. Credentials are kept in-memory and do not pollute pre-existing credentials on the host. Similar to `docker login`. """ return pulumi.get(self, "registries") @property @pulumi.getter def secrets(self) -> pulumi.Output[Optional[Mapping[str, str]]]: """ A mapping of secret names to their corresponding values. Unlike the Docker CLI, these can be passed by value and do not need to exist on-disk or in environment variables. Build arguments and environment variables are persistent in the final image, so you should use this for sensitive values. Similar to Docker's `--secret` flag. """ return pulumi.get(self, "secrets") @property @pulumi.getter def ssh(self) -> pulumi.Output[Optional[Sequence['outputs.SSH']]]: """ SSH agent socket or keys to expose to the build. Equivalent to Docker's `--ssh` flag. """ return pulumi.get(self, "ssh") @property @pulumi.getter def tags(self) -> pulumi.Output[Optional[Sequence[str]]]: """ Name and optionally a tag (format: `name:tag`). If exporting to a registry, the name should include the fully qualified registry address (e.g. `docker.io/pulumi/pulumi:latest`). Equivalent to Docker's `--tag` flag. """ return pulumi.get(self, "tags") @property @pulumi.getter def target(self) -> pulumi.Output[Optional[str]]: """ Set the target build stage(s) to build. If not specified all targets will be built by default. Equivalent to Docker's `--target` flag. """ return pulumi.get(self, "target")