feat: deprecate autoscaler policies that were replaced by node templates (#504)

* feat: deprecate autoscaler policies that were replaced by node templates

* Add deprecation information and remove deprecated fields usage from examples.

* Generate docs, tf lint.

* Refine the deprecation messages.

* Add readme outlining the details of deprecated fields.

---------

Co-authored-by: Witold Konior <witold@cast.ai>

Author: primoz-hrovat

README.md

@@ -120,14 +120,14 @@ Migrating from 3.x.x to 4.x.x
 Version 4.x.x changed:
 * `castai_eks_clusterid` type from data source to resource
 
-Having old configuration: 
+Having old configuration:
 
 ```terraform
 data "castai_eks_clusterid" "cluster_id" {
   account_id   = data.aws_caller_identity.current.account_id
   region       = var.cluster_region
   cluster_name = var.cluster_name
-} 
+}
 ```
 and usage `data.castai_eks_clusterid.cluster_id.id`
 
@@ -144,7 +144,7 @@ and usage `castai_eks_clusterid.cluster_id.id`
 
 * removal of `castai_cluster_token` resource in favour of `cluster_token` in `castai_eks_cluster`
 
-Having old configuration: 
+Having old configuration:
 ```terraform
 resource "castai_cluster_token" "this" {
   cluster_id = castai_eks_cluster.this.id
@@ -154,7 +154,7 @@ resource "castai_eks_cluster" "this" {
   region     = var.cluster_region
   name       = var.cluster_name
 }
-    
+
 ```
 and usage `castai_cluster_token.this.cluster_token`
 
@@ -375,7 +375,7 @@ Old configuration:
 ```hcl
 resource "castai_autoscaler" "castai_autoscaler_policies" {
   cluster_id               = data.castai_eks_clusterid.cluster_id.id // or other reference
-  
+
   autoscaler_policies_json = <<-EOT
      {
         "enabled": true,
@@ -441,7 +441,7 @@ resource "castai_autoscaler" "castai_autoscaler_policies" {
 
     cluster_limits {
       enabled = true
-      
+
       cpu {
         max_cores = 20
         min_cores = 1
@@ -458,6 +458,33 @@ https://github.com/castai/terraform-castai-eks-cluster/blob/main/README.md#migra
 If you have used `castai-gke-cluster` or other modules follow:
 https://github.com/castai/terraform-castai-gke-cluster/blob/main/README.md#migrating-from-4xx-to-5xx
 
+Deprecations in `castai_autoscaler` (Introduced in v7.9.3)
+-------------------------------------------------------------------------------------------------
+
+Starting with version `v7.9.3`, several fields within the `castai_autoscaler` resource (specifically under the `autoscaler_settings` block) have been deprecated.
+
+These fields are planned for removal in a future major version. Users are encouraged to update their configurations to use the new recommended approaches to ensure compatibility and leverage the latest features. Most of these functionalities have been consolidated into the `castai_node_template` resource (default template) for a more unified approach to node configuration.
+
+**Summary of Deprecated Fields and New Locations:**
+
+1.  **Headroom Configuration:**
+    *   **Deprecated:** `autoscaler_settings.headroom`, `autoscaler_settings.headroom_spot`. These configurations are deprecated. For managing cluster headroom, please refer to the CAST AI Autoscaler FAQ for recommended strategies, such as using low-priority placeholder deployments.
+        *   FAQ Link: [https://docs.cast.ai/docs/autoscaler-1#can-you-please-share-some-guidance-on-cluster-headroom-i-would-like-to-add-some-buffer-room-so-that-pods-have-a-place-to-run-when-nodes-go-down](https://docs.cast.ai/docs/autoscaler-1#can-you-please-share-some-guidance-on-cluster-headroom-i-would-like-to-add-some-buffer-room-so-that-pods-have-a-place-to-run-when-nodes-go-down)
+
+2.  **Node Constraints for Unschedulable Pods:**
+    *   **Deprecated:** `autoscaler_settings.unschedulable_pods.node_constraints` (including its fields like `min_cpu_cores`, `max_cpu_cores`, `min_ram_mib`, `max_ram_mib`). Use the `constraints` block (with fields like `min_cpu`, `max_cpu`, `min_memory`, `max_memory`) within the default `castai_node_template` resource.
+    *   **Deprecated:** `autoscaler_settings.unschedulable_pods.node_constraints.custom_instances_enabled`. Use the top-level `custom_instances_enabled` field in the default `castai_node_template` resource.
+
+3.  **Spot Instance Configuration:**
+    *   **Deprecated:** The entire `autoscaler_settings.spot_instances` block.
+        *   `spot_instances.enabled`: **New Location:** Use `constraints.spot` in the default `castai_node_template`.
+        *   `spot_instances.max_reclaim_rate`: **Note:** This field is deprecated and has no direct replacement in the node template. Setting it will have no effect.
+        *   `spot_instances.spot_backups`: **New Location:** Use `constraints.use_spot_fallbacks` and `constraints.fallback_restore_rate_seconds` in the default `castai_node_template`.
+    *   **Deprecated:** `autoscaler_settings.spot_diversity_enabled`. Use `constraints.enable_spot_diversity` in the default `castai_node_template`.
+    *   **Deprecated:** `autoscaler_settings.spot_diversity_price_increase_limit`. Use `constraints.spot_diversity_price_increase_limit_percent` in the default `castai_node_template`.
+
+4.  **Spot Interruption Predictions:**
+    *   **Deprecated:** `autoscaler_settings.spot_interruption_predictions` block. Use the top-level `spot_interruption_predictions_enabled` and `spot_interruption_predictions_type` fields in the default `castai_node_template` resource.
 
 Developing the provider
 ---------------------------

castai/resource_autoscaler.go

@@ -141,6 +141,7 @@ func resourceAutoscaler() *schema.Resource {
 										Optional:    true,
 										MaxItems:    1,
 										Description: "additional headroom based on cluster's total available capacity for on-demand nodes.",
+										Deprecated:  "`headroom` is deprecated. Please refer to the FAQ for guidance on cluster headroom: https://docs.cast.ai/docs/autoscaler-1#can-you-please-share-some-guidance-on-cluster-headroom-i-would-like-to-add-some-buffer-room-so-that-pods-have-a-place-to-run-when-nodes-go-down",
 										Elem: &schema.Resource{
 											Schema: map[string]*schema.Schema{
 												FieldCPUPercentage: {
@@ -171,6 +172,7 @@ func resourceAutoscaler() *schema.Resource {
 										Optional:    true,
 										MaxItems:    1,
 										Description: "additional headroom based on cluster's total available capacity for spot nodes.",
+										Deprecated:  "`headroom_spot` is deprecated. Please refer to the FAQ for guidance on cluster headroom: https://docs.cast.ai/docs/autoscaler-1#can-you-please-share-some-guidance-on-cluster-headroom-i-would-like-to-add-some-buffer-room-so-that-pods-have-a-place-to-run-when-nodes-go-down",
 										Elem: &schema.Resource{
 											Schema: map[string]*schema.Schema{
 												FieldCPUPercentage: {
@@ -201,6 +203,7 @@ func resourceAutoscaler() *schema.Resource {
 										Optional:    true,
 										MaxItems:    1,
 										Description: "defines the node constraints that will be applied when autoscaling with Unschedulable Pods policy.",
+										Deprecated:  "`node_constraints` under `unschedulable_pods` is deprecated. Use the `constraints` field in the default `castai_node_template` resource instead. The default node template has `is_default = true`.",
 										Elem: &schema.Resource{
 											Schema: map[string]*schema.Schema{
 												FieldMinCPUCores: {
@@ -256,7 +259,7 @@ func resourceAutoscaler() *schema.Resource {
 										Type:        schema.TypeBool,
 										Optional:    true,
 										Default:     false,
-										Deprecated:  "customInstancesEnabled is deprecated. Use custom_instances_enabled field the node template resource.",
+										Deprecated:  "`custom_instances_enabled` under `unschedulable_pods.node_constraints` is deprecated. Use the `custom_instances_enabled` field in the default `castai_node_template` resource instead. The default node template has `is_default = true`.",
 										Description: "enable/disable custom instances policy.",
 									},
 								},
@@ -307,24 +310,28 @@ func resourceAutoscaler() *schema.Resource {
 							Optional:    true,
 							MaxItems:    1,
 							Description: "policy defining whether autoscaler can use spot instances for provisioning additional workloads.",
+							Deprecated:  "`spot_instances` is deprecated. Configure spot instance settings using the `constraints` field in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 							Elem: &schema.Resource{
 								Schema: map[string]*schema.Schema{
 									FieldEnabled: {
 										Type:        schema.TypeBool,
 										Optional:    true,
 										Default:     false,
+										Deprecated:  "`enabled` under `spot_instances` is deprecated. To enable spot instances, set `constraints.spot = true` in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 										Description: "enable/disable spot instances policy.",
 									},
 									FieldMaxReclaimRate: {
 										Type:        schema.TypeInt,
 										Optional:    true,
 										Default:     0,
+										Deprecated:  "`max_reclaim_rate` under `spot_instances` is deprecated. This field has no direct equivalent in the `castai_node_template` resource, and setting it will have no effect.",
 										Description: "max allowed reclaim rate when choosing spot instance type. E.g. if the value is 10%, instance types having 10% or higher reclaim rate will not be considered. Set to zero to use all instance types regardless of reclaim rate.",
 									},
 									FieldSpotBackups: {
 										Type:        schema.TypeList,
 										Optional:    true,
 										MaxItems:    1,
+										Deprecated:  "`spot_backups` under `spot_instances` is deprecated. Configure spot backup behavior using `constraints.use_spot_fallbacks` and `constraints.fallback_restore_rate_seconds` in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 										Description: "policy defining whether autoscaler can use spot backups instead of spot instances when spot instances are not available.",
 										Elem: &schema.Resource{
 											Schema: map[string]*schema.Schema{
@@ -348,12 +355,14 @@ func resourceAutoscaler() *schema.Resource {
 										Type:        schema.TypeBool,
 										Optional:    true,
 										Default:     false,
+										Deprecated:  "`spot_diversity_enabled` is deprecated. Use the `enable_spot_diversity` field within `castai_node_template.constraints` in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 										Description: "enable/disable spot diversity policy. When enabled, autoscaler will try to balance between diverse and cost optimal instance types.",
 									},
 									FieldSpotDiversityPriceIncreaseLimit: {
 										Type:             schema.TypeInt,
 										Optional:         true,
 										Default:          20,
+										Deprecated:       "`spot_diversity_price_increase_limit` is deprecated. Use `spot_diversity_price_increase_limit_percent` within `castai_node_template.constraints` in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 										Description:      "allowed node configuration price increase when diversifying instance types. E.g. if the value is 10%, then the overall price of diversified instance types can be 10% higher than the price of the optimal configuration.",
 										ValidateDiagFunc: validation.ToDiagFunc(validation.IntAtLeast(1)),
 									},
@@ -362,6 +371,7 @@ func resourceAutoscaler() *schema.Resource {
 										Optional:    true,
 										MaxItems:    1,
 										Description: "configure the handling of SPOT interruption predictions.",
+										Deprecated:  "`spot_interruption_predictions` is deprecated. Use the `spot_interruption_predictions_enabled` and `spot_interruption_predictions_type` fields in the default `castai_node_template` resource. The default node template has `is_default = true`.",
 										Elem: &schema.Resource{
 											Schema: map[string]*schema.Schema{
 												FieldEnabled: {

docs/resources/autoscaler.md

@@ -114,18 +114,6 @@ module "castai-aks-cluster" {
 
     unschedulable_pods = {
       enabled = true
-
-      headroom = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
-
-      headroom_spot = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
     }
 
     node_downscaler = {

examples/aks/aks_cluster_arm_template/castai.tf

@@ -130,18 +130,6 @@ module "castai-aks-cluster" {
 
     unschedulable_pods = {
       enabled = true
-
-      headroom = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
-
-      headroom_spot = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
     }
 
     node_downscaler = {

examples/aks/aks_cluster_autoscaler_policies/castai.tf

@@ -182,18 +182,6 @@ module "castai-eks-cluster" {
 
     unschedulable_pods = {
       enabled = true
-
-      headroom = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
-
-      headroom_spot = {
-        enabled           = true
-        cpu_percentage    = 10
-        memory_percentage = 10
-      }
     }
 
     node_downscaler = {

examples/eks/eks_cluster_autoscaler_policies/castai.tf

@@ -39,17 +39,18 @@ resource "castai_node_template" "default_by_castai" {
   constraints {
     on_demand = true
   }
+
+  custom_instances_enabled = false
 }
 
 resource "castai_node_template" "example_spot_template" {
   cluster_id = castai_gke_cluster.this.id
 
-  name                     = "example_spot_template"
-  is_default               = false
-  is_enabled               = true
-  configuration_id         = castai_node_configuration.default.id
-  should_taint             = true
-  custom_instances_enabled = false # custom_instances_enabled should be set to same value(true or false) at Node templates & unschedulable_pods policy for backward compatability
+  name             = "example_spot_template"
+  is_default       = false
+  is_enabled       = true
+  configuration_id = castai_node_configuration.default.id
+  should_taint     = true
 
   custom_labels = {
     type = "spot"