@pulumi/docker 4.6.0-alpha.4 → 4.6.0-beta.1

package/buildx/image.d.ts

@@ -1,8 +1,208 @@
 import * as pulumi from "@pulumi/pulumi";
 import * as inputs from "../types/input";
 import * as outputs from "../types/output";
+import * as enums from "../types/enums";
 /**
- * A Docker image built using Buildkit
+ * A Docker image built using buildx -- Docker's interface to the improved
+ * BuildKit backend.
+ *
+ * **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.
+ *
+ * Only use this resource if you understand and accept the risks.
+ *
+ * ## Example Usage
+ * ### Multi-platform image
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ *     platforms: [
+ *         docker.buildx.image.Platform.Plan9_amd64,
+ *         docker.buildx.image.Platform.Plan9_386,
+ *     ],
+ * });
+ * ```
+ * ### Registry export
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ *     exports: [{
+ *         registry: {
+ *             ociMediaTypes: true,
+ *         },
+ *     }],
+ *     registries: [{
+ *         address: "docker.io",
+ *         password: dockerHubPassword,
+ *         username: "pulumibot",
+ *     }],
+ * });
+ * ```
+ * ### Caching
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     cacheFrom: [{
+ *         local: {
+ *             src: "tmp/cache",
+ *         },
+ *     }],
+ *     cacheTo: [{
+ *         local: {
+ *             dest: "tmp/cache",
+ *             mode: docker.buildx.image.CacheMode.Max,
+ *         },
+ *     }],
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ * });
+ * ```
+ * ### Build arguments
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     buildArgs: {
+ *         SET_ME_TO_TRUE: "true",
+ *     },
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ * });
+ * ```
+ * ### Build targets
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ *     targets: [
+ *         "build-me",
+ *         "also-build-me",
+ *     ],
+ * });
+ * ```
+ * ### Named contexts
+ *
+ * ```typescript
+ * 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",
+ *             },
+ *         },
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ * });
+ * ```
+ * ### Remote context
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {context: {
+ *     location: "https://raw.githubusercontent.com/pulumi/pulumi-docker/api-types/provider/testdata/Dockerfile",
+ * }});
+ * ```
+ * ### Inline Dockerfile
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         inline: `FROM busybox
+ * COPY hello.c ./
+ * `,
+ *     },
+ * });
+ * ```
+ * ### Remote context
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "https://github.com/docker-library/hello-world.git",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ * });
+ * ```
+ * ### Local export
+ *
+ * ```typescript
+ * import * as pulumi from "@pulumi/pulumi";
+ * import * as docker from "@pulumi/docker";
+ *
+ * const image = new docker.buildx.Image("image", {
+ *     context: {
+ *         location: "app",
+ *     },
+ *     dockerfile: {
+ *         location: "app/Dockerfile",
+ *     },
+ *     exports: [{
+ *         docker: {
+ *             tar: true,
+ *         },
+ *     }],
+ * });
+ * ```
  */
 export declare class Image extends pulumi.CustomResource {
     /**
@@ -20,75 +220,105 @@ export declare class Image extends pulumi.CustomResource {
      */
     static isInstance(obj: any): obj is Image;
     /**
+     * `ARG` names and values to set during the build.
      *
-     * An optional map of named build-time argument variables to set during
-     * the Docker build. This flag allows you to pass build-time variables that
-     * can be accessed like environment variables inside the RUN
-     * instruction.
+     * 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.
      */
     readonly buildArgs: pulumi.Output<{
         [key: string]: string;
     } | undefined>;
     /**
-     *
-     * When true, attempt to build the image during previews. Outputs are not
-     * pushed to registries, however caches are still populated.
+     * When `true`, attempt to build the image during previews. The image will
+     * not be pushed to registries, however caches will still populated.
      */
     readonly buildOnPreview: pulumi.Output<boolean | undefined>;
     /**
-     *
-     * Build with a specific builder instance
+     * Builder configuration.
      */
-    readonly builder: pulumi.Output<string | undefined>;
+    readonly builder: pulumi.Output<outputs.buildx.BuilderConfig | undefined>;
     /**
-     *
-     * External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")
+     * External cache configuration.
      */
-    readonly cacheFrom: pulumi.Output<string[] | undefined>;
+    readonly cacheFrom: pulumi.Output<outputs.buildx.CacheFromEntry[] | undefined>;
     /**
-     *
-     * Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")
+     * Cache export configuration.
+     */
+    readonly cacheTo: pulumi.Output<outputs.buildx.CacheToEntry[] | undefined>;
+    /**
+     * Build context settings.
      */
-    readonly cacheTo: pulumi.Output<string[] | undefined>;
+    readonly context: pulumi.Output<outputs.buildx.BuildContext | undefined>;
     /**
+     * A preliminary hash of the image's build context.
      *
-     * Path to use for build context. If omitted, an empty context is used.
+     * Pulumi uses this to determine if an image _may_ need to be re-built.
      */
-    readonly context: pulumi.Output<string | undefined>;
     readonly contextHash: pulumi.Output<string | undefined>;
     /**
-     *
-     * Name and optionally a tag (format: "name:tag"). If outputting to a
-     * registry, the name should include the fully qualified registry address.
+     * A mapping of platform type to refs which were pushed to registries.
      */
-    readonly exports: pulumi.Output<string[] | undefined>;
+    readonly digests: pulumi.Output<{
+        [key: string]: string[];
+    } | undefined>;
     /**
-     *
-     * Name of the Dockerfile to use (defaults to "${context}/Dockerfile").
+     * Dockerfile settings.
      */
-    readonly file: pulumi.Output<string | undefined>;
-    readonly manifests: pulumi.Output<outputs.buildx.Manifest[]>;
+    readonly dockerfile: pulumi.Output<outputs.buildx.Dockerfile | undefined>;
     /**
+     * Controls where images are persisted after building.
      *
-     * Set target platforms for the build. Defaults to the host's platform
+     * Images are only stored in the local cache unless `exports` are
+     * explicitly configured.
      */
-    readonly platforms: pulumi.Output<string[] | undefined>;
+    readonly exports: pulumi.Output<outputs.buildx.ExportEntry[] | undefined>;
     /**
-     *
-     * Always attempt to pull all referenced images
+     * Attach arbitrary key/value metadata to the image.
+     */
+    readonly labels: pulumi.Output<{
+        [key: string]: string;
+    } | undefined>;
+    /**
+     * Set target platform(s) for the build. Defaults to the host's platform
+     */
+    readonly platforms: pulumi.Output<enums.buildx.Platform[] | undefined>;
+    /**
+     * Always pull referenced images.
      */
     readonly pull: pulumi.Output<boolean | undefined>;
     /**
-     *
-     * Logins for registry outputs
+     * Registry credentials. Required if reading or exporting to private
+     * repositories.
      */
     readonly registries: pulumi.Output<outputs.buildx.RegistryAuth[] | undefined>;
     /**
+     * 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.
+     */
+    readonly secrets: pulumi.Output<{
+        [key: string]: string;
+    } | 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`).
+     */
+    readonly tags: pulumi.Output<string[] | undefined>;
+    /**
+     * Set the target build stage(s) to build.
      *
-     * Name and optionally a tag (format: "name:tag"). If outputting to a
-     * registry, the name should include the fully qualified registry address.
+     * If not specified all targets will be built by default.
      */
-    readonly tags: pulumi.Output<string[]>;
+    readonly targets: pulumi.Output<string[] | undefined>;
     /**
      * Create a Image resource with the given unique name, arguments, and options.
      *
@@ -96,78 +326,98 @@ export declare class Image extends pulumi.CustomResource {
      * @param args The arguments to use to populate this resource's properties.
      * @param opts A bag of options that control this resource's behavior.
      */
-    constructor(name: string, args: ImageArgs, opts?: pulumi.CustomResourceOptions);
+    constructor(name: string, args?: ImageArgs, opts?: pulumi.CustomResourceOptions);
 }
 /**
  * The set of arguments for constructing a Image resource.
  */
 export interface ImageArgs {
     /**
+     * `ARG` names and values to set during the build.
      *
-     * An optional map of named build-time argument variables to set during
-     * the Docker build. This flag allows you to pass build-time variables that
-     * can be accessed like environment variables inside the RUN
-     * instruction.
+     * 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.
      */
     buildArgs?: pulumi.Input<{
         [key: string]: pulumi.Input<string>;
     }>;
     /**
-     *
-     * When true, attempt to build the image during previews. Outputs are not
-     * pushed to registries, however caches are still populated.
+     * When `true`, attempt to build the image during previews. The image will
+     * not be pushed to registries, however caches will still populated.
      */
     buildOnPreview?: pulumi.Input<boolean>;
     /**
-     *
-     * Build with a specific builder instance
+     * Builder configuration.
      */
-    builder?: pulumi.Input<string>;
+    builder?: pulumi.Input<inputs.buildx.BuilderConfig>;
     /**
-     *
-     * External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")
+     * External cache configuration.
      */
-    cacheFrom?: pulumi.Input<pulumi.Input<string>[]>;
+    cacheFrom?: pulumi.Input<pulumi.Input<inputs.buildx.CacheFromEntry>[]>;
     /**
-     *
-     * Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")
+     * Cache export configuration.
      */
-    cacheTo?: pulumi.Input<pulumi.Input<string>[]>;
+    cacheTo?: pulumi.Input<pulumi.Input<inputs.buildx.CacheToEntry>[]>;
     /**
-     *
-     * Path to use for build context. If omitted, an empty context is used.
+     * Build context settings.
      */
-    context?: pulumi.Input<string>;
+    context?: pulumi.Input<inputs.buildx.BuildContext>;
     /**
-     *
-     * Name and optionally a tag (format: "name:tag"). If outputting to a
-     * registry, the name should include the fully qualified registry address.
+     * Dockerfile settings.
      */
-    exports?: pulumi.Input<pulumi.Input<string>[]>;
+    dockerfile?: pulumi.Input<inputs.buildx.Dockerfile>;
     /**
+     * Controls where images are persisted after building.
      *
-     * Name of the Dockerfile to use (defaults to "${context}/Dockerfile").
+     * Images are only stored in the local cache unless `exports` are
+     * explicitly configured.
      */
-    file?: pulumi.Input<string>;
+    exports?: pulumi.Input<pulumi.Input<inputs.buildx.ExportEntry>[]>;
     /**
-     *
-     * Set target platforms for the build. Defaults to the host's platform
+     * Attach arbitrary key/value metadata to the image.
      */
-    platforms?: pulumi.Input<pulumi.Input<string>[]>;
+    labels?: pulumi.Input<{
+        [key: string]: pulumi.Input<string>;
+    }>;
     /**
-     *
-     * Always attempt to pull all referenced images
+     * Set target platform(s) for the build. Defaults to the host's platform
+     */
+    platforms?: pulumi.Input<pulumi.Input<enums.buildx.Platform>[]>;
+    /**
+     * Always pull referenced images.
      */
     pull?: pulumi.Input<boolean>;
     /**
-     *
-     * Logins for registry outputs
+     * Registry credentials. Required if reading or exporting to private
+     * repositories.
      */
     registries?: pulumi.Input<pulumi.Input<inputs.buildx.RegistryAuth>[]>;
     /**
+     * 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.
+     */
+    secrets?: pulumi.Input<{
+        [key: string]: pulumi.Input<string>;
+    }>;
+    /**
+     * 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`).
+     */
+    tags?: pulumi.Input<pulumi.Input<string>[]>;
+    /**
+     * Set the target build stage(s) to build.
      *
-     * Name and optionally a tag (format: "name:tag"). If outputting to a
-     * registry, the name should include the fully qualified registry address.
+     * If not specified all targets will be built by default.
      */
-    tags: pulumi.Input<pulumi.Input<string>[]>;
+    targets?: pulumi.Input<pulumi.Input<string>[]>;
 }