add important note to datasource

Author: h3adex

docs/data-sources/image.md

@@ -3,12 +3,47 @@
 page_title: "stackit_image Data Source - stackit"
 subcategory: ""
 description: |-
-  Image datasource schema. Must have a region specified in the provider configuration.
+  Provides access to operating system images for use with resources such as servers. The provider configuration must specify a region.
+  ~> Important: When using the name, name_regex, or filter attributes to select images dynamically, be aware that image IDs may change frequently. Each OS patch or update results in a new unique image ID. If this data source is used to populate fields like boot_volume.source_id in a server resource, it may cause Terraform to detect changes and recreate the associated resource.
+  To avoid unintended updates or resource replacements:
+  Prefer using a static image_id to pin a specific image version.If you accept automatic image updates but wish to suppress resource changes, use a lifecycle block to ignore relevant changes. For example:
+  
+  resource "stackit_server" "example" {
+    boot_volume = {
+      size        = 64
+      source_type = "image"
+      source_id   = data.stackit_image.latest.id
+    }
+  
+    lifecycle {
+      ignore_changes = [boot_volume[0].source_id]
+    }
+  }
 ---
 
 # stackit_image (Data Source)
 
-Image datasource schema. Must have a `region` specified in the provider configuration.
+Provides access to operating system images for use with resources such as servers. The provider configuration must specify a region.
+
+~> Important: When using the `name`, `name_regex`, or `filter` attributes to select images dynamically, be aware that image IDs may change frequently. Each OS patch or update results in a new unique image ID. If this data source is used to populate fields like `boot_volume.source_id` in a server resource, it may cause Terraform to detect changes and recreate the associated resource.
+
+To avoid unintended updates or resource replacements:
+ - Prefer using a static `image_id` to pin a specific image version.
+ - If you accept automatic image updates but wish to suppress resource changes, use a `lifecycle` block to ignore relevant changes. For example:
+
+```hcl
+resource "stackit_server" "example" {
+  boot_volume = {
+    size        = 64
+    source_type = "image"
+    source_id   = data.stackit_image.latest.id
+  }
+
+  lifecycle {
+    ignore_changes = [boot_volume[0].source_id]
+  }
+}
+```
 
 ## Example Usage
 

stackit/internal/services/iaas/image/datasource.go

@@ -107,7 +107,27 @@ func (d *imageDataSource) ConfigValidators(_ context.Context) []datasource.Confi
 
 // Schema defines the schema for the datasource.
 func (d *imageDataSource) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
-	description := "Image datasource schema. Must have a `region` specified in the provider configuration."
+	description := fmt.Sprintf(
+		"%s\n\n~> %s",
+		"Provides access to operating system images for use with resources such as servers. The provider configuration must specify a region.",
+		"Important: When using the `name`, `name_regex`, or `filter` attributes to select images dynamically, be aware that image IDs may change frequently. Each OS patch or update results in a new unique image ID. If this data source is used to populate fields like `boot_volume.source_id` in a server resource, it may cause Terraform to detect changes and recreate the associated resource.\n\n"+
+			"To avoid unintended updates or resource replacements:\n"+
+			" - Prefer using a static `image_id` to pin a specific image version.\n"+
+			" - If you accept automatic image updates but wish to suppress resource changes, use a `lifecycle` block to ignore relevant changes. For example:\n\n"+
+			"```hcl\n"+
+			"resource \"stackit_server\" \"example\" {\n"+
+			"  boot_volume = {\n"+
+			"    size        = 64\n"+
+			"    source_type = \"image\"\n"+
+			"    source_id   = data.stackit_image.latest.id\n"+
+			"  }\n"+
+			"\n"+
+			"  lifecycle {\n"+
+			"    ignore_changes = [boot_volume[0].source_id]\n"+
+			"  }\n"+
+			"}\n"+
+			"```",
+	)
 	resp.Schema = schema.Schema{
 		MarkdownDescription: description,
 		Description:         description,