pulumi-docker-build/sdk/dotnet/Image.cs

// *** WARNING: this file was generated by pulumi. ***
// *** Do not edit by hand unless you're certain you know what you are doing! ***

using System;
using System.Collections.Generic;
using System.Collections.Immutable;
using System.Threading.Tasks;
using Pulumi.Serialization;

namespace Pulumi.DockerBuild
{
    /// <summary>
    /// 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
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using Aws = Pulumi.Aws;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var ecrRepository = new Aws.Ecr.Repository("ecr-repository");
    /// 
    ///     var authToken = Aws.Ecr.GetAuthorizationToken.Invoke(new()
    ///     {
    ///         RegistryId = ecrRepository.RegistryId,
    ///     });
    /// 
    ///     var myImage = new DockerBuild.Image("my-image", new()
    ///     {
    ///         CacheFrom = new[]
    ///         {
    ///             new DockerBuild.Inputs.CacheFromArgs
    ///             {
    ///                 Registry = new DockerBuild.Inputs.CacheFromRegistryArgs
    ///                 {
    ///                     Ref = ecrRepository.RepositoryUrl.Apply(repositoryUrl =&gt; $"{repositoryUrl}:cache"),
    ///                 },
    ///             },
    ///         },
    ///         CacheTo = new[]
    ///         {
    ///             new DockerBuild.Inputs.CacheToArgs
    ///             {
    ///                 Registry = new DockerBuild.Inputs.CacheToRegistryArgs
    ///                 {
    ///                     ImageManifest = true,
    ///                     OciMediaTypes = true,
    ///                     Ref = ecrRepository.RepositoryUrl.Apply(repositoryUrl =&gt; $"{repositoryUrl}:cache"),
    ///                 },
    ///             },
    ///         },
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "./app",
    ///         },
    ///         Push = true,
    ///         Registries = new[]
    ///         {
    ///             new DockerBuild.Inputs.RegistryArgs
    ///             {
    ///                 Address = ecrRepository.RepositoryUrl,
    ///                 Password = authToken.Apply(getAuthorizationTokenResult =&gt; getAuthorizationTokenResult.Password),
    ///                 Username = authToken.Apply(getAuthorizationTokenResult =&gt; getAuthorizationTokenResult.UserName),
    ///             },
    ///         },
    ///         Tags = new[]
    ///         {
    ///             ecrRepository.RepositoryUrl.Apply(repositoryUrl =&gt; $"{repositoryUrl}:latest"),
    ///         },
    ///     });
    /// 
    ///     return new Dictionary&lt;string, object?&gt;
    ///     {
    ///         ["ref"] = myImage.Ref,
    ///     };
    /// });
    /// 
    /// ```
    /// ### Multi-platform image
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Platforms = new[]
    ///         {
    ///             DockerBuild.Platform.Plan9_amd64,
    ///             DockerBuild.Platform.Plan9_386,
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Registry export
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Push = true,
    ///         Registries = new[]
    ///         {
    ///             new DockerBuild.Inputs.RegistryArgs
    ///             {
    ///                 Address = "docker.io",
    ///                 Password = dockerHubPassword,
    ///                 Username = "pulumibot",
    ///             },
    ///         },
    ///         Tags = new[]
    ///         {
    ///             "docker.io/pulumi/pulumi:3.107.0",
    ///         },
    ///     });
    /// 
    ///     return new Dictionary&lt;string, object?&gt;
    ///     {
    ///         ["ref"] = myImage.Ref,
    ///     };
    /// });
    /// 
    /// ```
    /// ### Caching
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         CacheFrom = new[]
    ///         {
    ///             new DockerBuild.Inputs.CacheFromArgs
    ///             {
    ///                 Local = new DockerBuild.Inputs.CacheFromLocalArgs
    ///                 {
    ///                     Src = "tmp/cache",
    ///                 },
    ///             },
    ///         },
    ///         CacheTo = new[]
    ///         {
    ///             new DockerBuild.Inputs.CacheToArgs
    ///             {
    ///                 Local = new DockerBuild.Inputs.CacheToLocalArgs
    ///                 {
    ///                     Dest = "tmp/cache",
    ///                     Mode = DockerBuild.CacheMode.Max,
    ///                 },
    ///             },
    ///         },
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Docker Build Cloud
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Builder = new DockerBuild.Inputs.BuilderConfigArgs
    ///         {
    ///             Name = "cloud-builder-name",
    ///         },
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Exec = true,
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Build arguments
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         BuildArgs = 
    ///         {
    ///             { "SET_ME_TO_TRUE", "true" },
    ///         },
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Build target
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Push = false,
    ///         Target = "build-me",
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Named contexts
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///             Named = 
    ///             {
    ///                 { "golang:latest", new DockerBuild.Inputs.ContextArgs
    ///                 {
    ///                     Location = "docker-image://golang@sha256:b8e62cf593cdaff36efd90aa3a37de268e6781a2e68c6610940c48f7cdf36984",
    ///                 } },
    ///             },
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Remote context
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "https://raw.githubusercontent.com/pulumi/pulumi-docker/api-types/provider/testdata/Dockerfile",
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Inline Dockerfile
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Dockerfile = new DockerBuild.Inputs.DockerfileArgs
    ///         {
    ///             Inline = @"FROM busybox
    /// COPY hello.c ./
    /// ",
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Remote context
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "https://github.com/docker-library/hello-world.git",
    ///         },
    ///         Dockerfile = new DockerBuild.Inputs.DockerfileArgs
    ///         {
    ///             Location = "app/Dockerfile",
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// ### Local export
    /// ```csharp
    /// using System.Collections.Generic;
    /// using System.Linq;
    /// using Pulumi;
    /// using DockerBuild = Pulumi.DockerBuild;
    /// 
    /// return await Deployment.RunAsync(() =&gt; 
    /// {
    ///     var image = new DockerBuild.Image("image", new()
    ///     {
    ///         Context = new DockerBuild.Inputs.BuildContextArgs
    ///         {
    ///             Location = "app",
    ///         },
    ///         Exports = new[]
    ///         {
    ///             new DockerBuild.Inputs.ExportArgs
    ///             {
    ///                 Docker = new DockerBuild.Inputs.ExportDockerArgs
    ///                 {
    ///                     Tar = true,
    ///                 },
    ///             },
    ///         },
    ///         Push = false,
    ///     });
    /// 
    /// });
    /// 
    /// ```
    /// </summary>
    [DockerBuildResourceType("docker-build:index:Image")]
    public partial class Image : global::Pulumi.CustomResource
    {
        /// <summary>
        /// Custom `host:ip` mappings to use during the build.
        /// 
        /// Equivalent to Docker's `--add-host` flag.
        /// </summary>
        [Output("addHosts")]
        public Output<ImmutableArray<string>> AddHosts { get; private set; } = null!;

        /// <summary>
        /// `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.
        /// </summary>
        [Output("buildArgs")]
        public Output<ImmutableDictionary<string, string>?> BuildArgs { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("buildOnPreview")]
        public Output<bool?> BuildOnPreview { get; private set; } = null!;

        /// <summary>
        /// Builder configuration.
        /// </summary>
        [Output("builder")]
        public Output<Outputs.BuilderConfig?> Builder { get; private set; } = null!;

        /// <summary>
        /// Cache export configuration.
        /// 
        /// Equivalent to Docker's `--cache-from` flag.
        /// </summary>
        [Output("cacheFrom")]
        public Output<ImmutableArray<Outputs.CacheFrom>> CacheFrom { get; private set; } = null!;

        /// <summary>
        /// Cache import configuration.
        /// 
        /// Equivalent to Docker's `--cache-to` flag.
        /// </summary>
        [Output("cacheTo")]
        public Output<ImmutableArray<Outputs.CacheTo>> CacheTo { get; private set; } = null!;

        /// <summary>
        /// Build context settings. Defaults to the current directory.
        /// 
        /// Equivalent to Docker's `PATH | URL | -` positional argument.
        /// </summary>
        [Output("context")]
        public Output<Outputs.BuildContext?> Context { get; private set; } = null!;

        /// <summary>
        /// A preliminary hash of the image's build context.
        /// 
        /// Pulumi uses this to determine if an image _may_ need to be re-built.
        /// </summary>
        [Output("contextHash")]
        public Output<string> ContextHash { get; private set; } = null!;

        /// <summary>
        /// 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 `&lt;tag&gt;@&lt;digest&gt;`. The
        /// `ref` output provides one such reference as a convenience.
        /// </summary>
        [Output("digest")]
        public Output<string> Digest { get; private set; } = null!;

        /// <summary>
        /// Dockerfile settings.
        /// 
        /// Equivalent to Docker's `--file` flag.
        /// </summary>
        [Output("dockerfile")]
        public Output<Outputs.Dockerfile?> Dockerfile { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("exec")]
        public Output<bool?> Exec { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("exports")]
        public Output<ImmutableArray<Outputs.Export>> Exports { get; private set; } = null!;

        /// <summary>
        /// Attach arbitrary key/value metadata to the image.
        /// 
        /// Equivalent to Docker's `--label` flag.
        /// </summary>
        [Output("labels")]
        public Output<ImmutableDictionary<string, string>?> Labels { get; private set; } = null!;

        /// <summary>
        /// When `true` the build will automatically include a `docker` export.
        /// 
        /// Defaults to `false`.
        /// 
        /// Equivalent to Docker's `--load` flag.
        /// </summary>
        [Output("load")]
        public Output<bool?> Load { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("network")]
        public Output<Pulumi.DockerBuild.NetworkMode?> Network { get; private set; } = null!;

        /// <summary>
        /// Do not import cache manifests when building the image.
        /// 
        /// Equivalent to Docker's `--no-cache` flag.
        /// </summary>
        [Output("noCache")]
        public Output<bool?> NoCache { get; private set; } = null!;

        /// <summary>
        /// Set target platform(s) for the build. Defaults to the host's platform.
        /// 
        /// Equivalent to Docker's `--platform` flag.
        /// </summary>
        [Output("platforms")]
        public Output<ImmutableArray<Pulumi.DockerBuild.Platform>> Platforms { get; private set; } = null!;

        /// <summary>
        /// Always pull referenced images.
        /// 
        /// Equivalent to Docker's `--pull` flag.
        /// </summary>
        [Output("pull")]
        public Output<bool?> Pull { get; private set; } = null!;

        /// <summary>
        /// When `true` the build will automatically include a `registry` export.
        /// 
        /// Defaults to `false`.
        /// 
        /// Equivalent to Docker's `--push` flag.
        /// </summary>
        [Output("push")]
        public Output<bool> Push { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("ref")]
        public Output<string> Ref { get; private set; } = null!;

        /// <summary>
        /// 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`.
        /// </summary>
        [Output("registries")]
        public Output<ImmutableArray<Outputs.Registry>> Registries { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("secrets")]
        public Output<ImmutableDictionary<string, string>?> Secrets { get; private set; } = null!;

        /// <summary>
        /// SSH agent socket or keys to expose to the build.
        /// 
        /// Equivalent to Docker's `--ssh` flag.
        /// </summary>
        [Output("ssh")]
        public Output<ImmutableArray<Outputs.SSH>> Ssh { get; private set; } = null!;

        /// <summary>
        /// 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.
        /// </summary>
        [Output("tags")]
        public Output<ImmutableArray<string>> Tags { get; private set; } = null!;

        /// <summary>
        /// Set the target build stage(s) to build.
        /// 
        /// If not specified all targets will be built by default.
        /// 
        /// Equivalent to Docker's `--target` flag.
        /// </summary>
        [Output("target")]
        public Output<string?> Target { get; private set; } = null!;


        /// <summary>
        /// Create a Image resource with the given unique name, arguments, and options.
        /// </summary>
        ///
        /// <param name="name">The unique name of the resource</param>
        /// <param name="args">The arguments used to populate this resource's properties</param>
        /// <param name="options">A bag of options that control this resource's behavior</param>
        public Image(string name, ImageArgs args, CustomResourceOptions? options = null)
            : base("docker-build:index:Image", name, args ?? new ImageArgs(), MakeResourceOptions(options, ""))
        {
        }

        private Image(string name, Input<string> id, CustomResourceOptions? options = null)
            : base("docker-build:index:Image", name, null, MakeResourceOptions(options, id))
        {
        }

        private static CustomResourceOptions MakeResourceOptions(CustomResourceOptions? options, Input<string>? id)
        {
            var defaultOptions = new CustomResourceOptions
            {
                Version = Utilities.Version,
            };
            var merged = CustomResourceOptions.Merge(defaultOptions, options);
            // Override the ID if one was specified for consistency with other language SDKs.
            merged.Id = id ?? merged.Id;
            return merged;
        }
        /// <summary>
        /// Get an existing Image resource's state with the given name, ID, and optional extra
        /// properties used to qualify the lookup.
        /// </summary>
        ///
        /// <param name="name">The unique name of the resulting resource.</param>
        /// <param name="id">The unique provider ID of the resource to lookup.</param>
        /// <param name="options">A bag of options that control this resource's behavior</param>
        public static Image Get(string name, Input<string> id, CustomResourceOptions? options = null)
        {
            return new Image(name, id, options);
        }
    }

    public sealed class ImageArgs : global::Pulumi.ResourceArgs
    {
        [Input("addHosts")]
        private InputList<string>? _addHosts;

        /// <summary>
        /// Custom `host:ip` mappings to use during the build.
        /// 
        /// Equivalent to Docker's `--add-host` flag.
        /// </summary>
        public InputList<string> AddHosts
        {
            get => _addHosts ?? (_addHosts = new InputList<string>());
            set => _addHosts = value;
        }

        [Input("buildArgs")]
        private InputMap<string>? _buildArgs;

        /// <summary>
        /// `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.
        /// </summary>
        public InputMap<string> BuildArgs
        {
            get => _buildArgs ?? (_buildArgs = new InputMap<string>());
            set => _buildArgs = value;
        }

        /// <summary>
        /// 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.
        /// </summary>
        [Input("buildOnPreview")]
        public Input<bool>? BuildOnPreview { get; set; }

        /// <summary>
        /// Builder configuration.
        /// </summary>
        [Input("builder")]
        public Input<Inputs.BuilderConfigArgs>? Builder { get; set; }

        [Input("cacheFrom")]
        private InputList<Inputs.CacheFromArgs>? _cacheFrom;

        /// <summary>
        /// Cache export configuration.
        /// 
        /// Equivalent to Docker's `--cache-from` flag.
        /// </summary>
        public InputList<Inputs.CacheFromArgs> CacheFrom
        {
            get => _cacheFrom ?? (_cacheFrom = new InputList<Inputs.CacheFromArgs>());
            set => _cacheFrom = value;
        }

        [Input("cacheTo")]
        private InputList<Inputs.CacheToArgs>? _cacheTo;

        /// <summary>
        /// Cache import configuration.
        /// 
        /// Equivalent to Docker's `--cache-to` flag.
        /// </summary>
        public InputList<Inputs.CacheToArgs> CacheTo
        {
            get => _cacheTo ?? (_cacheTo = new InputList<Inputs.CacheToArgs>());
            set => _cacheTo = value;
        }

        /// <summary>
        /// Build context settings. Defaults to the current directory.
        /// 
        /// Equivalent to Docker's `PATH | URL | -` positional argument.
        /// </summary>
        [Input("context")]
        public Input<Inputs.BuildContextArgs>? Context { get; set; }

        /// <summary>
        /// Dockerfile settings.
        /// 
        /// Equivalent to Docker's `--file` flag.
        /// </summary>
        [Input("dockerfile")]
        public Input<Inputs.DockerfileArgs>? Dockerfile { get; set; }

        /// <summary>
        /// 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.
        /// </summary>
        [Input("exec")]
        public Input<bool>? Exec { get; set; }

        [Input("exports")]
        private InputList<Inputs.ExportArgs>? _exports;

        /// <summary>
        /// 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.
        /// </summary>
        public InputList<Inputs.ExportArgs> Exports
        {
            get => _exports ?? (_exports = new InputList<Inputs.ExportArgs>());
            set => _exports = value;
        }

        [Input("labels")]
        private InputMap<string>? _labels;

        /// <summary>
        /// Attach arbitrary key/value metadata to the image.
        /// 
        /// Equivalent to Docker's `--label` flag.
        /// </summary>
        public InputMap<string> Labels
        {
            get => _labels ?? (_labels = new InputMap<string>());
            set => _labels = value;
        }

        /// <summary>
        /// When `true` the build will automatically include a `docker` export.
        /// 
        /// Defaults to `false`.
        /// 
        /// Equivalent to Docker's `--load` flag.
        /// </summary>
        [Input("load")]
        public Input<bool>? Load { get; set; }

        /// <summary>
        /// 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.
        /// </summary>
        [Input("network")]
        public Input<Pulumi.DockerBuild.NetworkMode>? Network { get; set; }

        /// <summary>
        /// Do not import cache manifests when building the image.
        /// 
        /// Equivalent to Docker's `--no-cache` flag.
        /// </summary>
        [Input("noCache")]
        public Input<bool>? NoCache { get; set; }

        [Input("platforms")]
        private InputList<Pulumi.DockerBuild.Platform>? _platforms;

        /// <summary>
        /// Set target platform(s) for the build. Defaults to the host's platform.
        /// 
        /// Equivalent to Docker's `--platform` flag.
        /// </summary>
        public InputList<Pulumi.DockerBuild.Platform> Platforms
        {
            get => _platforms ?? (_platforms = new InputList<Pulumi.DockerBuild.Platform>());
            set => _platforms = value;
        }

        /// <summary>
        /// Always pull referenced images.
        /// 
        /// Equivalent to Docker's `--pull` flag.
        /// </summary>
        [Input("pull")]
        public Input<bool>? Pull { get; set; }

        /// <summary>
        /// When `true` the build will automatically include a `registry` export.
        /// 
        /// Defaults to `false`.
        /// 
        /// Equivalent to Docker's `--push` flag.
        /// </summary>
        [Input("push", required: true)]
        public Input<bool> Push { get; set; } = null!;

        [Input("registries")]
        private InputList<Inputs.RegistryArgs>? _registries;

        /// <summary>
        /// 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`.
        /// </summary>
        public InputList<Inputs.RegistryArgs> Registries
        {
            get => _registries ?? (_registries = new InputList<Inputs.RegistryArgs>());
            set => _registries = value;
        }

        [Input("secrets")]
        private InputMap<string>? _secrets;

        /// <summary>
        /// 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.
        /// </summary>
        public InputMap<string> Secrets
        {
            get => _secrets ?? (_secrets = new InputMap<string>());
            set => _secrets = value;
        }

        [Input("ssh")]
        private InputList<Inputs.SSHArgs>? _ssh;

        /// <summary>
        /// SSH agent socket or keys to expose to the build.
        /// 
        /// Equivalent to Docker's `--ssh` flag.
        /// </summary>
        public InputList<Inputs.SSHArgs> Ssh
        {
            get => _ssh ?? (_ssh = new InputList<Inputs.SSHArgs>());
            set => _ssh = value;
        }

        [Input("tags")]
        private InputList<string>? _tags;

        /// <summary>
        /// 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.
        /// </summary>
        public InputList<string> Tags
        {
            get => _tags ?? (_tags = new InputList<string>());
            set => _tags = value;
        }

        /// <summary>
        /// Set the target build stage(s) to build.
        /// 
        /// If not specified all targets will be built by default.
        /// 
        /// Equivalent to Docker's `--target` flag.
        /// </summary>
        [Input("target")]
        public Input<string>? Target { get; set; }

        public ImageArgs()
        {
            BuildOnPreview = true;
            Network = Pulumi.DockerBuild.NetworkMode.@Default;
        }
        public static new ImageArgs Empty => new ImageArgs();
    }
}