Add note about stability and tweak index docs

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,

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,
 	)

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
     /// 

sdk/dotnet/Index.cs

@@ -10,13 +10,25 @@ using Pulumi.Serialization;
 namespace Pulumi.DockerBuild
 {
     /// <summary>
-    /// 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

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
 //

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

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
 //

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

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
  * 

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

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
  *

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

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
 

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