Extend max_surge and max_unavailable descriptions (#533)

* extend max_surge and max_unavailable descriptions

* Update stackit/internal/services/ske/cluster/resource.go

Co-authored-by: João Palet <joao.palet@outlook.com>

* update docs

---------

Co-authored-by: Gökçe Gök Klingel <goekce.goek_klingel@stackit.cloud>
Co-authored-by: João Palet <joao.palet@outlook.com>

Author: GokceGK

docs/resources/ske_cluster.md

@@ -81,8 +81,8 @@ Optional:
 
 - `cri` (String) Specifies the container runtime. Defaults to `containerd`
 - `labels` (Map of String) Labels to add to each node.
-- `max_surge` (Number) Maximum number of additional VMs that are created during an update.
-- `max_unavailable` (Number) Maximum number of VMs that that can be unavailable during an update.
+- `max_surge` (Number) Maximum number of additional VMs that are created during an update. If set (larger than 0), then it must be at least the amount of zones configured for the nodepool. The `max_surge` and `max_unavailable` fields cannot both be unset at the same time.
+- `max_unavailable` (Number) Maximum number of additional VMs that are created during an update. If set (larger than 0), then it must be at least the amount of zones configured for the nodepool. The `max_surge` and `max_unavailable` fields cannot both be unset at the same time.
 - `os_name` (String) The name of the OS image. Defaults to `flatcar`.
 - `os_version` (String, Deprecated) This field is deprecated, use `os_version_min` to configure the version and `os_version_used` to get the currently used version instead.
 - `os_version_min` (String) The minimum OS image version. This field will be used to set the minimum OS image version on creation/update of the cluster. If unset, the latest supported OS image version will be used. SKE automatically updates the cluster Kubernetes version if you have set `maintenance.enable_kubernetes_version_updates` to true or if there is a mandatory update, as described in [Updates for Kubernetes versions and Operating System versions in SKE](https://docs.stackit.cloud/stackit/en/version-updates-in-ske-10125631.html). To get the current OS image version being used for the node pool, use the read-only `os_version_used` field.

stackit/internal/services/ske/cluster/resource.go

@@ -301,6 +301,9 @@ func (r *clusterResource) Schema(_ context.Context, _ resource.SchemaRequest, re
 		"main": "SKE Cluster Resource schema. Must have a `region` specified in the provider configuration.",
 		"node_pools_plan_note": "When updating `node_pools` of a `stackit_ske_cluster`, the Terraform plan might appear incorrect as it matches the node pools by index rather than by name. " +
 			"However, the SKE API correctly identifies node pools by name and applies the intended changes. Please review your changes carefully to ensure the correct configuration will be applied.",
+		"max_surge":           "Maximum number of additional VMs that are created during an update.",
+		"max_unavailable":     "Maximum number of VMs that that can be unavailable during an update.",
+		"nodepool_validators": "If set (larger than 0), then it must be at least the amount of zones configured for the nodepool. The `max_surge` and `max_unavailable` fields cannot both be unset at the same time.",
 	}
 
 	resp.Schema = schema.Schema{
@@ -397,15 +400,15 @@ func (r *clusterResource) Schema(_ context.Context, _ resource.SchemaRequest, re
 							Required:    true,
 						},
 						"max_surge": schema.Int64Attribute{
-							Description: "Maximum number of additional VMs that are created during an update.",
+							Description: fmt.Sprintf("%s %s", descriptions["max_surge"], descriptions["nodepool_validators"]),
 							Optional:    true,
 							Computed:    true,
 							PlanModifiers: []planmodifier.Int64{
 								int64planmodifier.UseStateForUnknown(),
 							},
 						},
 						"max_unavailable": schema.Int64Attribute{
-							Description: "Maximum number of VMs that that can be unavailable during an update.",
+							Description: fmt.Sprintf("%s %s", descriptions["max_surge"], descriptions["nodepool_validators"]),
 							Optional:    true,
 							Computed:    true,
 							PlanModifiers: []planmodifier.Int64{