diff --git a/provider/internal/image.go b/provider/internal/image.go index b444654..b4194f3 100644 --- a/provider/internal/image.go +++ b/provider/internal/image.go @@ -72,16 +72,10 @@ func (i *Image) Annotate(a infer.Annotator) { ## Stability - **This resource is experimental and subject to change.** + **This resource is pre-1.0 and in public preview.** - 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. + We will strive to keep APIs and behavior as stable as possible, but we + cannot guarantee stability until version 1.0. `)+ "\n\n"+_migration+ "\n\n"+_imageExamples, diff --git a/provider/internal/index.go b/provider/internal/index.go index ab063a0..d424210 100644 --- a/provider/internal/index.go +++ b/provider/internal/index.go @@ -64,13 +64,25 @@ type IndexState struct { // Annotate sets docstrings and defaults on Index. func (i *Index) Annotate(a infer.Annotator) { a.Describe(&i, dedent(` - An index (or manifest list) referencing one or more existing images. + A wrapper around "docker buildx imagetools create" to create an index + (or manifest list) referencing one or more existing images. - Useful for crafting a multi-platform image from several - platform-specific images. + In most cases you do not need an "Index" to build a multi-platform + image -- specifying multiple platforms on the "Image" will handle this + for you automatically. - This creates an OCI image index or a Docker manifest list depending on - the media types of the source images. + However, as of April 2024, building multi-platform images _with + caching_ will only export a cache for one platform at a time (see [this + discussion](https://github.com/docker/buildx/discussions/1382) for more + details). + + Therefore this resource can be helpful if you are building + multi-platform images with caching: each platform can be built and + cached separately, and an "Index" can join them all together. An + example of this is shown below. + + This resource creates an OCI image index or a Docker manifest list + depending on the media types of the source images. `)+ "\n\n"+_indexExamples, ) diff --git a/sdk/dotnet/Image.cs b/sdk/dotnet/Image.cs index f597010..1f825c9 100644 --- a/sdk/dotnet/Image.cs +++ b/sdk/dotnet/Image.cs @@ -15,16 +15,10 @@ namespace Pulumi.DockerBuild /// /// ## Stability /// - /// **This resource is experimental and subject to change.** + /// **This resource is pre-1.0 and in public preview.** /// - /// 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. + /// We will strive to keep APIs and behavior as stable as possible, but we + /// cannot guarantee stability until version 1.0. /// /// ## Migrating v3 and v4 Image resources /// diff --git a/sdk/dotnet/Index.cs b/sdk/dotnet/Index.cs index 585b4ee..9d113b0 100644 --- a/sdk/dotnet/Index.cs +++ b/sdk/dotnet/Index.cs @@ -10,13 +10,25 @@ using Pulumi.Serialization; namespace Pulumi.DockerBuild { /// - /// An index (or manifest list) referencing one or more existing images. + /// A wrapper around `docker buildx imagetools create` to create an index + /// (or manifest list) referencing one or more existing images. /// - /// Useful for crafting a multi-platform image from several - /// platform-specific images. + /// In most cases you do not need an `Index` to build a multi-platform + /// image -- specifying multiple platforms on the `Image` will handle this + /// for you automatically. /// - /// This creates an OCI image index or a Docker manifest list depending on - /// the media types of the source images. + /// However, as of April 2024, building multi-platform images _with + /// caching_ will only export a cache for one platform at a time (see [this + /// discussion](https://github.com/docker/buildx/discussions/1382) for more + /// details). + /// + /// Therefore this resource can be helpful if you are building + /// multi-platform images with caching: each platform can be built and + /// cached separately, and an `Index` can join them all together. An + /// example of this is shown below. + /// + /// This resource creates an OCI image index or a Docker manifest list + /// depending on the media types of the source images. /// /// ## Example Usage /// ### Multi-platform registry caching diff --git a/sdk/go/dockerbuild/image.go b/sdk/go/dockerbuild/image.go index 049bf40..d725e9a 100644 --- a/sdk/go/dockerbuild/image.go +++ b/sdk/go/dockerbuild/image.go @@ -17,16 +17,10 @@ import ( // // ## Stability // -// **This resource is experimental and subject to change.** +// **This resource is pre-1.0 and in public preview.** // -// 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. +// We will strive to keep APIs and behavior as stable as possible, but we +// cannot guarantee stability until version 1.0. // // ## Migrating v3 and v4 Image resources // diff --git a/sdk/go/dockerbuild/index.go b/sdk/go/dockerbuild/index.go index 547b3be..2429e89 100644 --- a/sdk/go/dockerbuild/index.go +++ b/sdk/go/dockerbuild/index.go @@ -13,13 +13,25 @@ import ( "github.com/pulumi/pulumi/sdk/v3/go/pulumix" ) -// An index (or manifest list) referencing one or more existing images. +// A wrapper around `docker buildx imagetools create` to create an index +// (or manifest list) referencing one or more existing images. // -// Useful for crafting a multi-platform image from several -// platform-specific images. +// In most cases you do not need an `Index` to build a multi-platform +// image -- specifying multiple platforms on the `Image` will handle this +// for you automatically. // -// This creates an OCI image index or a Docker manifest list depending on -// the media types of the source images. +// However, as of April 2024, building multi-platform images _with +// caching_ will only export a cache for one platform at a time (see [this +// discussion](https://github.com/docker/buildx/discussions/1382) for more +// details). +// +// Therefore this resource can be helpful if you are building +// multi-platform images with caching: each platform can be built and +// cached separately, and an `Index` can join them all together. An +// example of this is shown below. +// +// This resource creates an OCI image index or a Docker manifest list +// depending on the media types of the source images. // // ## Example Usage // ### Multi-platform registry caching diff --git a/sdk/go/dockerbuild/x/image.go b/sdk/go/dockerbuild/x/image.go index 0fe21ce..dd7d708 100644 --- a/sdk/go/dockerbuild/x/image.go +++ b/sdk/go/dockerbuild/x/image.go @@ -17,16 +17,10 @@ import ( // // ## Stability // -// **This resource is experimental and subject to change.** +// **This resource is pre-1.0 and in public preview.** // -// 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. +// We will strive to keep APIs and behavior as stable as possible, but we +// cannot guarantee stability until version 1.0. // // ## Migrating v3 and v4 Image resources // diff --git a/sdk/go/dockerbuild/x/index.go b/sdk/go/dockerbuild/x/index.go index b153b0b..1deb0f3 100644 --- a/sdk/go/dockerbuild/x/index.go +++ b/sdk/go/dockerbuild/x/index.go @@ -13,13 +13,25 @@ import ( "github.com/pulumi/pulumi/sdk/v3/go/pulumix" ) -// An index (or manifest list) referencing one or more existing images. +// A wrapper around `docker buildx imagetools create` to create an index +// (or manifest list) referencing one or more existing images. // -// Useful for crafting a multi-platform image from several -// platform-specific images. +// In most cases you do not need an `Index` to build a multi-platform +// image -- specifying multiple platforms on the `Image` will handle this +// for you automatically. // -// This creates an OCI image index or a Docker manifest list depending on -// the media types of the source images. +// However, as of April 2024, building multi-platform images _with +// caching_ will only export a cache for one platform at a time (see [this +// discussion](https://github.com/docker/buildx/discussions/1382) for more +// details). +// +// Therefore this resource can be helpful if you are building +// multi-platform images with caching: each platform can be built and +// cached separately, and an `Index` can join them all together. An +// example of this is shown below. +// +// This resource creates an OCI image index or a Docker manifest list +// depending on the media types of the source images. // // ## Example Usage // ### Multi-platform registry caching diff --git a/sdk/java/src/main/java/com/pulumi/dockerbuild/Image.java b/sdk/java/src/main/java/com/pulumi/dockerbuild/Image.java index 4c2a04a..8a2b4c0 100644 --- a/sdk/java/src/main/java/com/pulumi/dockerbuild/Image.java +++ b/sdk/java/src/main/java/com/pulumi/dockerbuild/Image.java @@ -31,16 +31,10 @@ import javax.annotation.Nullable; * * ## Stability * - * **This resource is experimental and subject to change.** + * **This resource is pre-1.0 and in public preview.** * - * 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. + * We will strive to keep APIs and behavior as stable as possible, but we + * cannot guarantee stability until version 1.0. * * ## Migrating v3 and v4 Image resources * diff --git a/sdk/java/src/main/java/com/pulumi/dockerbuild/Index.java b/sdk/java/src/main/java/com/pulumi/dockerbuild/Index.java index c752591..6f013c0 100644 --- a/sdk/java/src/main/java/com/pulumi/dockerbuild/Index.java +++ b/sdk/java/src/main/java/com/pulumi/dockerbuild/Index.java @@ -17,13 +17,25 @@ import java.util.Optional; import javax.annotation.Nullable; /** - * An index (or manifest list) referencing one or more existing images. + * A wrapper around `docker buildx imagetools create` to create an index + * (or manifest list) referencing one or more existing images. * - * Useful for crafting a multi-platform image from several - * platform-specific images. + * In most cases you do not need an `Index` to build a multi-platform + * image -- specifying multiple platforms on the `Image` will handle this + * for you automatically. * - * This creates an OCI image index or a Docker manifest list depending on - * the media types of the source images. + * However, as of April 2024, building multi-platform images _with + * caching_ will only export a cache for one platform at a time (see [this + * discussion](https://github.com/docker/buildx/discussions/1382) for more + * details). + * + * Therefore this resource can be helpful if you are building + * multi-platform images with caching: each platform can be built and + * cached separately, and an `Index` can join them all together. An + * example of this is shown below. + * + * This resource creates an OCI image index or a Docker manifest list + * depending on the media types of the source images. * * ## Example Usage * ### Multi-platform registry caching diff --git a/sdk/nodejs/image.ts b/sdk/nodejs/image.ts index 1046c31..ec2e089 100644 --- a/sdk/nodejs/image.ts +++ b/sdk/nodejs/image.ts @@ -13,16 +13,10 @@ import * as utilities from "./utilities"; * * ## Stability * - * **This resource is experimental and subject to change.** + * **This resource is pre-1.0 and in public preview.** * - * 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. + * We will strive to keep APIs and behavior as stable as possible, but we + * cannot guarantee stability until version 1.0. * * ## Migrating v3 and v4 Image resources * diff --git a/sdk/nodejs/index_.ts b/sdk/nodejs/index_.ts index 1ebbba7..e2986c6 100644 --- a/sdk/nodejs/index_.ts +++ b/sdk/nodejs/index_.ts @@ -8,13 +8,25 @@ import * as enums from "./types/enums"; import * as utilities from "./utilities"; /** - * An index (or manifest list) referencing one or more existing images. + * A wrapper around `docker buildx imagetools create` to create an index + * (or manifest list) referencing one or more existing images. * - * Useful for crafting a multi-platform image from several - * platform-specific images. + * In most cases you do not need an `Index` to build a multi-platform + * image -- specifying multiple platforms on the `Image` will handle this + * for you automatically. * - * This creates an OCI image index or a Docker manifest list depending on - * the media types of the source images. + * However, as of April 2024, building multi-platform images _with + * caching_ will only export a cache for one platform at a time (see [this + * discussion](https://github.com/docker/buildx/discussions/1382) for more + * details). + * + * Therefore this resource can be helpful if you are building + * multi-platform images with caching: each platform can be built and + * cached separately, and an `Index` can join them all together. An + * example of this is shown below. + * + * This resource creates an OCI image index or a Docker manifest list + * depending on the media types of the source images. * * ## Example Usage * ### Multi-platform registry caching diff --git a/sdk/python/pulumi_docker_build/image.py b/sdk/python/pulumi_docker_build/image.py index 31f621f..63f835b 100644 --- a/sdk/python/pulumi_docker_build/image.py +++ b/sdk/python/pulumi_docker_build/image.py @@ -616,16 +616,10 @@ class Image(pulumi.CustomResource): ## Stability - **This resource is experimental and subject to change.** + **This resource is pre-1.0 and in public preview.** - 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. + We will strive to keep APIs and behavior as stable as possible, but we + cannot guarantee stability until version 1.0. ## Migrating v3 and v4 Image resources @@ -1053,16 +1047,10 @@ class Image(pulumi.CustomResource): ## Stability - **This resource is experimental and subject to change.** + **This resource is pre-1.0 and in public preview.** - 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. + We will strive to keep APIs and behavior as stable as possible, but we + cannot guarantee stability until version 1.0. ## Migrating v3 and v4 Image resources diff --git a/sdk/python/pulumi_docker_build/index.py b/sdk/python/pulumi_docker_build/index.py index cbbbbff..62ffaf2 100644 --- a/sdk/python/pulumi_docker_build/index.py +++ b/sdk/python/pulumi_docker_build/index.py @@ -104,13 +104,25 @@ class Index(pulumi.CustomResource): tag: Optional[pulumi.Input[str]] = None, __props__=None): """ - An index (or manifest list) referencing one or more existing images. + A wrapper around `docker buildx imagetools create` to create an index + (or manifest list) referencing one or more existing images. - Useful for crafting a multi-platform image from several - platform-specific images. + In most cases you do not need an `Index` to build a multi-platform + image -- specifying multiple platforms on the `Image` will handle this + for you automatically. - This creates an OCI image index or a Docker manifest list depending on - the media types of the source images. + However, as of April 2024, building multi-platform images _with + caching_ will only export a cache for one platform at a time (see [this + discussion](https://github.com/docker/buildx/discussions/1382) for more + details). + + Therefore this resource can be helpful if you are building + multi-platform images with caching: each platform can be built and + cached separately, and an `Index` can join them all together. An + example of this is shown below. + + This resource creates an OCI image index or a Docker manifest list + depending on the media types of the source images. ## Example Usage ### Multi-platform registry caching @@ -179,13 +191,25 @@ class Index(pulumi.CustomResource): args: IndexArgs, opts: Optional[pulumi.ResourceOptions] = None): """ - An index (or manifest list) referencing one or more existing images. + A wrapper around `docker buildx imagetools create` to create an index + (or manifest list) referencing one or more existing images. - Useful for crafting a multi-platform image from several - platform-specific images. + In most cases you do not need an `Index` to build a multi-platform + image -- specifying multiple platforms on the `Image` will handle this + for you automatically. - This creates an OCI image index or a Docker manifest list depending on - the media types of the source images. + However, as of April 2024, building multi-platform images _with + caching_ will only export a cache for one platform at a time (see [this + discussion](https://github.com/docker/buildx/discussions/1382) for more + details). + + Therefore this resource can be helpful if you are building + multi-platform images with caching: each platform can be built and + cached separately, and an `Index` can join them all together. An + example of this is shown below. + + This resource creates an OCI image index or a Docker manifest list + depending on the media types of the source images. ## Example Usage ### Multi-platform registry caching