@pulumi/docker 4.6.0-beta.1 → 4.6.0-beta.2

package/buildx/image.d.ts

@@ -6,14 +6,274 @@ import * as enums from "../types/enums";
  * A Docker image built using buildx -- Docker's interface to the improved
  * BuildKit backend.
  *
+ * ## Stability
+ *
  * **This resource is experimental and subject to change.**
  *
  * API types are unstable. Subsequent releases _may_ require manual edits
  * to your state file(s) in order to adopt API changes.
  *
+ * `retainOnDelete: true` is recommended with this resource until it is
+ * stable. This enables future API changes to be adopted more easily by renaming
+ * resources.
+ *
  * Only use this resource if you understand and accept the risks.
  *
+ * ## Migrating v3 and v4 Image resources
+ *
+ * The `buildx.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 `build.Image` resources with minor modifications.
+ *
+ * ### Behavioral differences
+ *
+ * There are several key behavioral differences to keep in mind when transitioning images to the new `buildx.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.
+ * Some users felt this made previews in CI less helpful because they no longer detected bad images by default.
+ *
+ * The default behavior of the `buildx.Image` resource has been changed to strike a better balance between CI use cases and manual updates.
+ * By default, Pulumi will now only build `buildx.Image` resources during previews when it detects a CI environment like GitHub Actions.
+ * Previews run in non-CI environments will not build images.
+ * This behavior is still configurable with `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.
+ *
+ * The `buildx.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 `buildx.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 `buildx.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
+ *
+ * TODO:
+ *
+ * #### 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 `buildx.Image` is deleted, it will _attempt_ to also delete any pushed tags.
+ * Deletion of remote tags is not guaranteed, because not all registries currently support this operation (`docker.io` in particular).
+ *
+ * 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 `buildx.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 `buildx.Image`.
+ * In almost all cases, properties of `buildx.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
+ * ### v3/v4 migration
+ *
+ * ```typescript
+ *
+ * // v3 Image
+ * const v3 = new docker.Image("v3-image", {
+ *   imageName: "myregistry.com/user/repo:latest",
+ *   localImageName: "local-tag",
+ *   skipPush: false,
+ *   build: {
+ *     dockerfile: "./Dockerfile",
+ *     context: "../app",
+ *     target: "mytarget",
+ *     args: {
+ *       MY_BUILD_ARG: "foo",
+ *     },
+ *     env: {
+ *       DOCKER_BUILDKIT: "1",
+ *     },
+ *     extraOptions: [
+ *       "--cache-from",
+ *       "type=registry,myregistry.com/user/repo:cache",
+ *       "--cache-to",
+ *       "type=registry,myregistry.com/user/repo:cache",
+ *       "--add-host",
+ *       "metadata.google.internal:169.254.169.254",
+ *       "--secret",
+ *       "id=mysecret,src=/local/secret",
+ *       "--ssh",
+ *       "default=/home/runner/.ssh/id_ed25519",
+ *       "--network",
+ *       "host",
+ *       "--platform",
+ *       "linux/amd64",
+ *     ],
+ *   },
+ *   registry: {
+ *     server: "myregistry.com",
+ *     username: "username",
+ *     password: pulumi.secret("password"),
+ *   },
+ * });
+ *
+ * // v3 Image after migrating to buildx.Image
+ * const v3Migrated = new docker.buildx.Image("v3-to-buildx", {
+ *     tags: ["myregistry.com/user/repo:latest", "local-tag"],
+ *     push: true,
+ *     dockerfile: {
+ *         location: "./Dockerfile",
+ *     },
+ *     context: {
+ *         location: "../app",
+ *     },
+ *     targets: ["mytarget"],
+ *     buildArgs: {
+ *         MY_BUILD_ARG: "foo",
+ *     },
+ *     cacheFrom: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
+ *     cacheTo: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
+ *     secrets: {
+ *         mysecret: "value",
+ *     },
+ *     addHosts: ["metadata.google.internal:169.254.169.254"],
+ *     ssh: {
+ *         default: ["/home/runner/.ssh/id_ed25519"],
+ *     },
+ *     network: "host",
+ *     platforms: ["linux/amd64"],
+ *     registries: [{
+ *         address: "myregistry.com",
+ *         username: "username",
+ *         password: pulumi.secret("password"),
+ *     }],
+ * });
+ *
+ *
+ * // v4 Image
+ * const v4 = new docker.Image("v4-image", {
+ *     imageName: "myregistry.com/user/repo:latest",
+ *     skipPush: false,
+ *     build: {
+ *         dockerfile: "./Dockerfile",
+ *         context: "../app",
+ *         target: "mytarget",
+ *         args: {
+ *             MY_BUILD_ARG: "foo",
+ *         },
+ *         cacheFrom: {
+ *             images: ["myregistry.com/user/repo:cache"],
+ *         },
+ *         addHosts: ["metadata.google.internal:169.254.169.254"],
+ *         network: "host",
+ *         platform: "linux/amd64",
+ *     },
+ *     buildOnPreview: true,
+ *     registry: {
+ *         server: "myregistry.com",
+ *         username: "username",
+ *         password: pulumi.secret("password"),
+ *     },
+ * });
+ *
+ * // v4 Image after migrating to buildx.Image
+ * const v4Migrated = new docker.buildx.Image("v4-to-buildx", {
+ *     tags: ["myregistry.com/user/repo:latest"],
+ *     push: true,
+ *     dockerfile: {
+ *         location: "./Dockerfile",
+ *     },
+ *     context: {
+ *         location: "../app",
+ *     },
+ *     targets: ["mytarget"],
+ *     buildArgs: {
+ *         MY_BUILD_ARG: "foo",
+ *     },
+ *     cacheFrom: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
+ *     cacheTo: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
+ *     addHosts: ["metadata.google.internal:169.254.169.254"],
+ *     network: "host",
+ *     platforms: ["linux/amd64"],
+ *     registries: [{
+ *         address: "myregistry.com",
+ *         username: "username",
+ *         password: pulumi.secret("password"),
+ *     }],
+ * });
+ *
+ * ```
+ *
+ * ## Example Usage
+ * ### Push to AWS ECR with caching
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as aws from "@pulumi/aws";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const ecrRepository = new aws.ecr.Repository("ecr-repository", {});
+ * const authToken = aws.ecr.getAuthorizationTokenOutput({
+ *     registryId: ecrRepository.registryId,
+ * });
+ * const myImage = new docker.buildx.Image("my-image", {
+ *     cacheFrom: [{
+ *         registry: {
+ *             ref: pulumi.interpolate`${ecrRepository.repositoryUrl}:cache`,
+ *         },
+ *     }],
+ *     cacheTo: [{
+ *         registry: {
+ *             imageManifest: true,
+ *             ociMediaTypes: true,
+ *             ref: pulumi.interpolate`${ecrRepository.repositoryUrl}:cache`,
+ *         },
+ *     }],
+ *     context: {
+ *         location: "./app",
+ *     },
+ *     dockerfile: {
+ *         location: "./Dockerfile",
+ *     },
+ *     push: true,
+ *     registries: [{
+ *         address: ecrRepository.repositoryUrl,
+ *         password: authToken.apply(authToken => authToken.password),
+ *         username: authToken.apply(authToken => authToken.userName),
+ *     }],
+ *     tags: [pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`],
+ * });
+ * ```
  * ### Multi-platform image
  *
  * ```typescript
@@ -24,9 +284,6 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
  *     platforms: [
  *         docker.buildx.image.Platform.Plan9_amd64,
  *         docker.buildx.image.Platform.Plan9_386,
@@ -43,19 +300,13 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
- *     exports: [{
- *         registry: {
- *             ociMediaTypes: true,
- *         },
- *     }],
+ *     push: true,
  *     registries: [{
  *         address: "docker.io",
  *         password: dockerHubPassword,
  *         username: "pulumibot",
  *     }],
+ *     tags: ["docker.io/pulumi/pulumi:3.107.0"],
  * });
  * ```
  * ### Caching
@@ -79,9 +330,6 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
  * });
  * ```
  * ### Build arguments
@@ -97,9 +345,6 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
  * });
  * ```
  * ### Build targets
@@ -112,9 +357,6 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
  *     targets: [
  *         "build-me",
  *         "also-build-me",
@@ -127,19 +369,14 @@ import * as enums from "../types/enums";
  * import * as pulumi from "@pulumi/pulumi";
  * import * as docker from "@pulumi/docker";
  *
- * const image = new docker.buildx.Image("image", {
- *     context: {
- *         location: "app",
- *         named: {
- *             "golang:latest": {
- *                 location: "docker-image://golang@sha256:b8e62cf593cdaff36efd90aa3a37de268e6781a2e68c6610940c48f7cdf36984",
- *             },
+ * const image = new docker.buildx.Image("image", {context: {
+ *     location: "app",
+ *     named: {
+ *         "golang:latest": {
+ *             location: "docker-image://golang@sha256:b8e62cf593cdaff36efd90aa3a37de268e6781a2e68c6610940c48f7cdf36984",
  *         },
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
- * });
+ * }});
  * ```
  * ### Remote context
  *
@@ -193,9 +430,6 @@ import * as enums from "../types/enums";
  *     context: {
  *         location: "app",
  *     },
- *     dockerfile: {
- *         location: "app/Dockerfile",
- *     },
  *     exports: [{
  *         docker: {
  *             tar: true,
@@ -219,6 +453,12 @@ export declare class Image extends pulumi.CustomResource {
      * when multiple copies of the Pulumi SDK have been loaded into the same process.
      */
     static isInstance(obj: any): obj is Image;
+    /**
+     * Custom `host:ip` mappings to use during the build.
+     *
+     * Equivalent to Docker's `--add-host` flag.
+     */
+    readonly addHosts: pulumi.Output<string[] | undefined>;
     /**
      * `ARG` names and values to set during the build.
      *
@@ -227,13 +467,27 @@ export declare class Image extends pulumi.CustomResource {
      *
      * Build arguments are persisted in the image, so you should use `secrets`
      * if these arguments are sensitive.
+     *
+     * Equivalent to Docker's `--build-arg` flag.
      */
     readonly buildArgs: pulumi.Output<{
         [key: string]: string;
     } | undefined>;
     /**
-     * When `true`, attempt to build the image during previews. The image will
-     * not be pushed to registries, however caches will still populated.
+     * By default, preview behavior depends on the execution environment. If
+     * Pulumi detects the operation is running on a CI system (GitHub Actions,
+     * Travis CI, Azure Pipelines, etc.) then it will build images during
+     * previews as a safeguard. Otherwise, if not running on CI, previews will
+     * not build images.
+     *
+     * Setting this to `false` forces previews to never perform builds, and
+     * setting it to `true` will always build the image 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.
      */
     readonly buildOnPreview: pulumi.Output<boolean | undefined>;
     /**
@@ -241,15 +495,21 @@ export declare class Image extends pulumi.CustomResource {
      */
     readonly builder: pulumi.Output<outputs.buildx.BuilderConfig | undefined>;
     /**
-     * External cache configuration.
+     * Cache export configuration.
+     *
+     * Equivalent to Docker's `--cache-from` flag.
      */
     readonly cacheFrom: pulumi.Output<outputs.buildx.CacheFromEntry[] | undefined>;
     /**
-     * Cache export configuration.
+     * Cache import configuration.
+     *
+     * Equivalent to Docker's `--cache-to` flag.
      */
     readonly cacheTo: pulumi.Output<outputs.buildx.CacheToEntry[] | undefined>;
     /**
      * Build context settings.
+     *
+     * Equivalent to Docker's `PATH | URL | -` positional argument.
      */
     readonly context: pulumi.Output<outputs.buildx.BuildContext | undefined>;
     /**
@@ -257,15 +517,21 @@ export declare class Image extends pulumi.CustomResource {
      *
      * Pulumi uses this to determine if an image _may_ need to be re-built.
      */
-    readonly contextHash: pulumi.Output<string | undefined>;
+    readonly contextHash: pulumi.Output<string>;
     /**
-     * A mapping of platform type to refs which were pushed to registries.
+     * A mapping of target names to the SHA256 digest of their pushed manifest.
+     *
+     * If no target was specified 'default' is used as the target name.
+     *
+     * Pushed manifests can be referenced as `<tag>@<digest>`.
      */
     readonly digests: pulumi.Output<{
-        [key: string]: string[];
-    } | undefined>;
+        [key: string]: string;
+    }>;
     /**
      * Dockerfile settings.
+     *
+     * Equivalent to Docker's `--file` flag.
      */
     readonly dockerfile: pulumi.Output<outputs.buildx.Dockerfile | undefined>;
     /**
@@ -273,25 +539,80 @@ export declare class Image extends pulumi.CustomResource {
      *
      * Images are only stored in the local cache unless `exports` are
      * explicitly configured.
+     *
+     * Equivalent to Docker's `--output` flag.
      */
     readonly exports: pulumi.Output<outputs.buildx.ExportEntry[] | undefined>;
     /**
      * Attach arbitrary key/value metadata to the image.
+     *
+     * Equivalent to Docker's `--label` flag.
      */
     readonly labels: pulumi.Output<{
         [key: string]: string;
     } | undefined>;
     /**
-     * Set target platform(s) for the build. Defaults to the host's platform
+     * When `true` the build will automatically include a `docker` export.
+     *
+     * Defaults to `false`.
+     *
+     * Equivalent to Docker's `--load` flag.
+     */
+    readonly load: pulumi.Output<boolean | undefined>;
+    /**
+     * 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.
+     */
+    readonly network: pulumi.Output<enums.buildx.NetworkMode | undefined>;
+    /**
+     * Do not import cache manifests when building the image.
+     *
+     * Equivalent to Docker's `--no-cache` flag.
+     */
+    readonly noCache: pulumi.Output<boolean | undefined>;
+    /**
+     * Set target platform(s) for the build. Defaults to the host's platform.
+     *
+     * Equivalent to Docker's `--platform` flag.
      */
     readonly platforms: pulumi.Output<enums.buildx.Platform[] | undefined>;
     /**
      * Always pull referenced images.
+     *
+     * Equivalent to Docker's `--pull` flag.
      */
     readonly pull: pulumi.Output<boolean | undefined>;
+    /**
+     * When `true` the build will automatically include a `registry` export.
+     *
+     * Defaults to `false`.
+     *
+     * Equivalent to Docker's `--push` flag.
+     */
+    readonly push: pulumi.Output<boolean | undefined>;
+    /**
+     * If the image was pushed to any registries then this will contain a
+     * single fully-qualified tag including the build's digest.
+     *
+     * 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 `Digests` output.
+     */
+    readonly ref: pulumi.Output<string>;
     /**
      * 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`.
      */
     readonly registries: pulumi.Output<outputs.buildx.RegistryAuth[] | undefined>;
     /**
@@ -302,21 +623,33 @@ export declare class Image extends pulumi.CustomResource {
      *
      * 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.
      */
     readonly secrets: pulumi.Output<{
         [key: string]: string;
     } | undefined>;
+    /**
+     * SSH agent socket or keys to expose to the build.
+     *
+     * Equivalent to Docker's `--ssh` flag.
+     */
+    readonly ssh: pulumi.Output<outputs.buildx.SSH[] | undefined>;
     /**
      * 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.
      */
     readonly tags: pulumi.Output<string[] | undefined>;
     /**
      * Set the target build stage(s) to build.
      *
      * If not specified all targets will be built by default.
+     *
+     * Equivalent to Docker's `--target` flag.
      */
     readonly targets: pulumi.Output<string[] | undefined>;
     /**
@@ -332,6 +665,12 @@ export declare class Image extends pulumi.CustomResource {
  * The set of arguments for constructing a Image resource.
  */
 export interface ImageArgs {
+    /**
+     * Custom `host:ip` mappings to use during the build.
+     *
+     * Equivalent to Docker's `--add-host` flag.
+     */
+    addHosts?: pulumi.Input<pulumi.Input<string>[]>;
     /**
      * `ARG` names and values to set during the build.
      *
@@ -340,13 +679,27 @@ export interface ImageArgs {
      *
      * Build arguments are persisted in the image, so you should use `secrets`
      * if these arguments are sensitive.
+     *
+     * Equivalent to Docker's `--build-arg` flag.
      */
     buildArgs?: pulumi.Input<{
         [key: string]: pulumi.Input<string>;
     }>;
     /**
-     * When `true`, attempt to build the image during previews. The image will
-     * not be pushed to registries, however caches will still populated.
+     * By default, preview behavior depends on the execution environment. If
+     * Pulumi detects the operation is running on a CI system (GitHub Actions,
+     * Travis CI, Azure Pipelines, etc.) then it will build images during
+     * previews as a safeguard. Otherwise, if not running on CI, previews will
+     * not build images.
+     *
+     * Setting this to `false` forces previews to never perform builds, and
+     * setting it to `true` will always build the image 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.
      */
     buildOnPreview?: pulumi.Input<boolean>;
     /**
@@ -354,19 +707,27 @@ export interface ImageArgs {
      */
     builder?: pulumi.Input<inputs.buildx.BuilderConfig>;
     /**
-     * External cache configuration.
+     * Cache export configuration.
+     *
+     * Equivalent to Docker's `--cache-from` flag.
      */
     cacheFrom?: pulumi.Input<pulumi.Input<inputs.buildx.CacheFromEntry>[]>;
     /**
-     * Cache export configuration.
+     * Cache import configuration.
+     *
+     * Equivalent to Docker's `--cache-to` flag.
      */
     cacheTo?: pulumi.Input<pulumi.Input<inputs.buildx.CacheToEntry>[]>;
     /**
      * Build context settings.
+     *
+     * Equivalent to Docker's `PATH | URL | -` positional argument.
      */
     context?: pulumi.Input<inputs.buildx.BuildContext>;
     /**
      * Dockerfile settings.
+     *
+     * Equivalent to Docker's `--file` flag.
      */
     dockerfile?: pulumi.Input<inputs.buildx.Dockerfile>;
     /**
@@ -374,25 +735,68 @@ export interface ImageArgs {
      *
      * Images are only stored in the local cache unless `exports` are
      * explicitly configured.
+     *
+     * Equivalent to Docker's `--output` flag.
      */
     exports?: pulumi.Input<pulumi.Input<inputs.buildx.ExportEntry>[]>;
     /**
      * Attach arbitrary key/value metadata to the image.
+     *
+     * Equivalent to Docker's `--label` flag.
      */
     labels?: pulumi.Input<{
         [key: string]: pulumi.Input<string>;
     }>;
     /**
-     * Set target platform(s) for the build. Defaults to the host's platform
+     * When `true` the build will automatically include a `docker` export.
+     *
+     * Defaults to `false`.
+     *
+     * Equivalent to Docker's `--load` flag.
+     */
+    load?: pulumi.Input<boolean>;
+    /**
+     * 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.
+     */
+    network?: pulumi.Input<enums.buildx.NetworkMode>;
+    /**
+     * Do not import cache manifests when building the image.
+     *
+     * Equivalent to Docker's `--no-cache` flag.
+     */
+    noCache?: pulumi.Input<boolean>;
+    /**
+     * Set target platform(s) for the build. Defaults to the host's platform.
+     *
+     * Equivalent to Docker's `--platform` flag.
      */
     platforms?: pulumi.Input<pulumi.Input<enums.buildx.Platform>[]>;
     /**
      * Always pull referenced images.
+     *
+     * Equivalent to Docker's `--pull` flag.
      */
     pull?: pulumi.Input<boolean>;
+    /**
+     * When `true` the build will automatically include a `registry` export.
+     *
+     * Defaults to `false`.
+     *
+     * Equivalent to Docker's `--push` flag.
+     */
+    push?: pulumi.Input<boolean>;
     /**
      * 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`.
      */
     registries?: pulumi.Input<pulumi.Input<inputs.buildx.RegistryAuth>[]>;
     /**
@@ -403,21 +807,33 @@ export interface ImageArgs {
      *
      * 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.
      */
     secrets?: pulumi.Input<{
         [key: string]: pulumi.Input<string>;
     }>;
+    /**
+     * SSH agent socket or keys to expose to the build.
+     *
+     * Equivalent to Docker's `--ssh` flag.
+     */
+    ssh?: pulumi.Input<pulumi.Input<inputs.buildx.SSH>[]>;
     /**
      * 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.
      */
     tags?: pulumi.Input<pulumi.Input<string>[]>;
     /**
      * Set the target build stage(s) to build.
      *
      * If not specified all targets will be built by default.
+     *
+     * Equivalent to Docker's `--target` flag.
      */
     targets?: pulumi.Input<pulumi.Input<string>[]>;
 }