Add required_versions attribute to fleet_agent_policy for automatic agent upgrades (#1436)

* Initial plan

* Add required_versions attribute to fleet_agent_policy resource

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Fix linting issues and regenerate documentation

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Add validator to prevent duplicate versions in required_versions

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Simplify required_versions to use MapAttribute instead of custom Set type

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Update internal/fleet/agent_policy/acc_test.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add version check for required_versions (9.1.0+) and fix empty map handling

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Restructure tests and fixup the null versions case

* make lint

* Use math.Round() for explicit rounding semantics

Co-authored-by: tobio <444668+tobio@users.noreply.github.com>

* Changelog

* PR feedback

* PR feedback

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tobio <444668+tobio@users.noreply.github.com>
Co-authored-by: Toby Brain <toby.brain@elastic.co>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Toby Brain <tobio85@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -40,6 +40,7 @@ alias = [
 
 ### Changes
 
+- Add `required_versions` to `elasticstack_fleet_agent_policy` ([#1436](https://github.com/elastic/terraform-provider-elasticstack/pull/1436))
 - Migrate `elasticstack_elasticsearch_security_role` resource to Terraform Plugin Framework ([#1330](https://github.com/elastic/terraform-provider-elasticstack/pull/1330))
 - Fix an issue where the `elasticstack_fleet_output` resource would error due to inconsistent state after an ouptut was edited in the Kibana UI ([#1506](https://github.com/elastic/terraform-provider-elasticstack/pull/1506))
 - Allow `index` and `data_view_id` values to both be unknown during planning in `elasticstack_kibana_security_detection_rule` ([#1499](https://github.com/elastic/terraform-provider-elasticstack/pull/1499))

docs/resources/fleet_agent_policy.md

@@ -57,6 +57,7 @@ resource "elasticstack_fleet_agent_policy" "test_policy" {
 - `monitor_metrics` (Boolean) Enable collection of agent metrics.
 - `monitoring_output_id` (String) The identifier for monitoring output.
 - `policy_id` (String) Unique identifier of the agent policy.
+- `required_versions` (Map of Number) Map of agent versions to target percentages for automatic upgrade. The key is the target version and the value is the percentage of agents to upgrade to that version.
 - `skip_destroy` (Boolean) Set to true if you do not wish the agent policy to be deleted at destroy time, and instead just remove the agent policy from the Terraform state.
 - `space_ids` (Set of String) The Kibana space IDs that this agent policy should be available in. When not specified, defaults to ["default"]. Note: The order of space IDs does not matter as this is a set.
 - `supports_agentless` (Boolean) Set to true to enable agentless data collection.

internal/fleet/agent_policy/acc_test.go

@@ -524,3 +524,85 @@ func checkResourceAgentPolicySkipDestroy(s *terraform.State) error {
 	}
 	return nil
 }
+
+func TestAccResourceAgentPolicyWithRequiredVersions(t *testing.T) {
+	policyName := sdkacctest.RandStringFromCharSet(22, sdkacctest.CharSetAlphaNum)
+
+	resource.Test(t, resource.TestCase{
+		PreCheck:     func() { acctest.PreCheck(t) },
+		CheckDestroy: checkResourceAgentPolicyDestroy,
+		Steps: []resource.TestStep{
+			{
+				ProtoV6ProviderFactories: acctest.Providers,
+				SkipFunc:                 versionutils.CheckIfVersionIsUnsupported(agent_policy.MinVersionRequiredVersions),
+				ConfigDirectory:          acctest.NamedTestCaseDirectory("create"),
+				ConfigVariables: config.Variables{
+					"policy_name": config.StringVariable(fmt.Sprintf("Policy %s", policyName)),
+				},
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "name", fmt.Sprintf("Policy %s", policyName)),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "namespace", "default"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.%", "1"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.15.0", "100"),
+				),
+			},
+			{
+				ProtoV6ProviderFactories: acctest.Providers,
+				SkipFunc:                 versionutils.CheckIfVersionIsUnsupported(agent_policy.MinVersionRequiredVersions),
+				ConfigDirectory:          acctest.NamedTestCaseDirectory("update_percentage"),
+				ConfigVariables: config.Variables{
+					"policy_name": config.StringVariable(fmt.Sprintf("Policy %s", policyName)),
+				},
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "name", fmt.Sprintf("Policy %s", policyName)),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "namespace", "default"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.%", "1"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.15.0", "50"),
+				),
+			},
+			{
+				ProtoV6ProviderFactories: acctest.Providers,
+				SkipFunc:                 versionutils.CheckIfVersionIsUnsupported(agent_policy.MinVersionRequiredVersions),
+				ConfigDirectory:          acctest.NamedTestCaseDirectory("add_version"),
+				ConfigVariables: config.Variables{
+					"policy_name": config.StringVariable(fmt.Sprintf("Policy %s", policyName)),
+				},
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "name", fmt.Sprintf("Policy %s", policyName)),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "namespace", "default"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.%", "2"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.15.0", "50"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.16.0", "50"),
+				),
+			},
+			{
+				ProtoV6ProviderFactories: acctest.Providers,
+				SkipFunc:                 versionutils.CheckIfVersionIsUnsupported(agent_policy.MinVersionRequiredVersions),
+				ConfigDirectory:          acctest.NamedTestCaseDirectory("unset_versions"),
+				ConfigVariables: config.Variables{
+					"policy_name": config.StringVariable(fmt.Sprintf("Policy %s", policyName)),
+				},
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "name", fmt.Sprintf("Policy %s", policyName)),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "namespace", "default"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.%", "2"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.15.0", "50"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.8.16.0", "50"),
+				),
+			},
+			{
+				ProtoV6ProviderFactories: acctest.Providers,
+				SkipFunc:                 versionutils.CheckIfVersionIsUnsupported(agent_policy.MinVersionRequiredVersions),
+				ConfigDirectory:          acctest.NamedTestCaseDirectory("remove_versions"),
+				ConfigVariables: config.Variables{
+					"policy_name": config.StringVariable(fmt.Sprintf("Policy %s", policyName)),
+				},
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "name", fmt.Sprintf("Policy %s", policyName)),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "namespace", "default"),
+					resource.TestCheckResourceAttr("elasticstack_fleet_agent_policy.test_policy", "required_versions.%", "0"),
+				),
+			},
+		},
+	})
+}

internal/fleet/agent_policy/models.go

@@ -3,6 +3,7 @@ package agent_policy
 import (
 	"context"
 	"fmt"
+	"math"
 	"slices"
 	"time"
 
@@ -22,6 +23,7 @@ type features struct {
 	SupportsInactivityTimeout   bool
 	SupportsUnenrollmentTimeout bool
 	SupportsSpaceIds            bool
+	SupportsRequiredVersions    bool
 }
 
 type globalDataTagsItemModel struct {
@@ -48,6 +50,7 @@ type agentPolicyModel struct {
 	UnenrollmentTimeout customtypes.Duration `tfsdk:"unenrollment_timeout"`
 	GlobalDataTags      types.Map            `tfsdk:"global_data_tags"` //> globalDataTagsModel
 	SpaceIds            types.Set            `tfsdk:"space_ids"`
+	RequiredVersions    types.Map            `tfsdk:"required_versions"`
 }
 
 func (model *agentPolicyModel) populateFromAPI(ctx context.Context, data *kbapi.AgentPolicy) diag.Diagnostics {
@@ -134,6 +137,25 @@ func (model *agentPolicyModel) populateFromAPI(ctx context.Context, data *kbapi.
 		model.SpaceIds = types.SetNull(types.StringType)
 	}
 
+	// Handle required_versions
+	if data.RequiredVersions != nil {
+		versionMap := make(map[string]attr.Value)
+
+		for _, rv := range *data.RequiredVersions {
+			// Round the float32 percentage to nearest integer since we use Int32 in the schema
+			percentage := int32(math.Round(float64(rv.Percentage)))
+			versionMap[rv.Version] = types.Int32Value(percentage)
+		}
+
+		reqVersions, d := types.MapValue(types.Int32Type, versionMap)
+		if d.HasError() {
+			return d
+		}
+		model.RequiredVersions = reqVersions
+	} else {
+		model.RequiredVersions = types.MapNull(types.Int32Type)
+	}
+
 	return nil
 }
 
@@ -186,6 +208,72 @@ func (model *agentPolicyModel) convertGlobalDataTags(ctx context.Context, feat f
 	return &itemsList, diags
 }
 
+// convertRequiredVersions converts the required versions from terraform model to API model
+func (model *agentPolicyModel) convertRequiredVersions(feat features) (*[]struct {
+	Percentage float32 `json:"percentage"`
+	Version    string  `json:"version"`
+}, diag.Diagnostics) {
+	var diags diag.Diagnostics
+
+	if model.RequiredVersions.IsNull() || model.RequiredVersions.IsUnknown() {
+		return nil, diags
+	}
+
+	// Check if required_versions is supported
+	if !feat.SupportsRequiredVersions {
+		return nil, diag.Diagnostics{
+			diag.NewAttributeErrorDiagnostic(
+				path.Root("required_versions"),
+				"Unsupported Elasticsearch version",
+				fmt.Sprintf("Required versions (automatic agent upgrades) are only supported in Elastic Stack %s and above", MinVersionRequiredVersions),
+			),
+		}
+	}
+
+	elements := model.RequiredVersions.Elements()
+
+	// If the map is empty (required_versions = {}), return an empty array to clear upgrades
+	if len(elements) == 0 {
+		emptyArray := make([]struct {
+			Percentage float32 `json:"percentage"`
+			Version    string  `json:"version"`
+		}, 0)
+		return &emptyArray, diags
+	}
+
+	result := make([]struct {
+		Percentage float32 `json:"percentage"`
+		Version    string  `json:"version"`
+	}, 0, len(elements))
+
+	for version, percentageVal := range elements {
+		percentageInt32, ok := percentageVal.(types.Int32)
+		if !ok {
+			diags.AddError("required_versions conversion error", fmt.Sprintf("Expected Int32 value, got %T", percentageVal))
+			continue
+		}
+
+		if percentageInt32.IsNull() || percentageInt32.IsUnknown() {
+			diags.AddError("required_versions validation error", "percentage cannot be null or unknown")
+			continue
+		}
+
+		result = append(result, struct {
+			Percentage float32 `json:"percentage"`
+			Version    string  `json:"version"`
+		}{
+			Percentage: float32(percentageInt32.ValueInt32()),
+			Version:    version,
+		})
+	}
+
+	if diags.HasError() {
+		return nil, diags
+	}
+
+	return &result, diags
+}
+
 func (model *agentPolicyModel) toAPICreateModel(ctx context.Context, feat features) (kbapi.PostFleetAgentPoliciesJSONRequestBody, diag.Diagnostics) {
 	monitoring := make([]kbapi.PostFleetAgentPoliciesJSONBodyMonitoringEnabled, 0, 2)
 
@@ -282,6 +370,13 @@ func (model *agentPolicyModel) toAPICreateModel(ctx context.Context, feat featur
 		body.SpaceIds = &spaceIds
 	}
 
+	// Handle required_versions
+	requiredVersions, d := model.convertRequiredVersions(feat)
+	if d.HasError() {
+		return kbapi.PostFleetAgentPoliciesJSONRequestBody{}, d
+	}
+	body.RequiredVersions = requiredVersions
+
 	return body, nil
 }
 
@@ -379,5 +474,12 @@ func (model *agentPolicyModel) toAPIUpdateModel(ctx context.Context, feat featur
 		body.SpaceIds = &spaceIds
 	}
 
+	// Handle required_versions
+	requiredVersions, d := model.convertRequiredVersions(feat)
+	if d.HasError() {
+		return kbapi.PutFleetAgentPoliciesAgentpolicyidJSONRequestBody{}, d
+	}
+	body.RequiredVersions = requiredVersions
+
 	return body, nil
 }

internal/fleet/agent_policy/resource.go

@@ -24,6 +24,7 @@ var (
 	MinVersionInactivityTimeout   = version.Must(version.NewVersion("8.7.0"))
 	MinVersionUnenrollmentTimeout = version.Must(version.NewVersion("8.15.0"))
 	MinVersionSpaceIds            = version.Must(version.NewVersion("9.1.0"))
+	MinVersionRequiredVersions    = version.Must(version.NewVersion("9.1.0"))
 )
 
 // NewResource is a helper function to simplify the provider implementation.
@@ -75,11 +76,17 @@ func (r *agentPolicyResource) buildFeatures(ctx context.Context) (features, diag
 		return features{}, diagutil.FrameworkDiagsFromSDK(diags)
 	}
 
+	supportsRequiredVersions, diags := r.client.EnforceMinVersion(ctx, MinVersionRequiredVersions)
+	if diags.HasError() {
+		return features{}, diagutil.FrameworkDiagsFromSDK(diags)
+	}
+
 	return features{
 		SupportsGlobalDataTags:      supportsGDT,
 		SupportsSupportsAgentless:   supportsSupportsAgentless,
 		SupportsInactivityTimeout:   supportsInactivityTimeout,
 		SupportsUnenrollmentTimeout: supportsUnenrollmentTimeout,
 		SupportsSpaceIds:            supportsSpaceIds,
+		SupportsRequiredVersions:    supportsRequiredVersions,
 	}, nil
 }

internal/fleet/agent_policy/schema.go

@@ -5,6 +5,8 @@ import (
 
 	"github.com/elastic/terraform-provider-elasticstack/internal/utils/customtypes"
 	"github.com/hashicorp/terraform-plugin-framework-validators/float32validator"
+	"github.com/hashicorp/terraform-plugin-framework-validators/int32validator"
+	"github.com/hashicorp/terraform-plugin-framework-validators/mapvalidator"
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/attr"
 	"github.com/hashicorp/terraform-plugin-framework/path"
@@ -13,6 +15,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/booldefault"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/boolplanmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/mapdefault"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/mapplanmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
@@ -145,6 +148,20 @@ func getSchema() schema.Schema {
 				Optional:    true,
 				Computed:    true,
 			},
+			"required_versions": schema.MapAttribute{
+				Description: "Map of agent versions to target percentages for automatic upgrade. The key is the target version and the value is the percentage of agents to upgrade to that version.",
+				ElementType: types.Int32Type,
+				Optional:    true,
+				Computed:    true,
+				PlanModifiers: []planmodifier.Map{
+					mapplanmodifier.UseStateForUnknown(),
+				},
+				Validators: []validator.Map{
+					mapvalidator.ValueInt32sAre(
+						int32validator.Between(0, 100),
+					),
+				},
+			},
 		}}
 }
 func getGlobalDataTagsAttrTypes() attr.Type {

internal/fleet/agent_policy/testdata/TestAccResourceAgentPolicyWithRequiredVersions/add_version/main.tf

@@ -0,0 +1,22 @@
+variable "policy_name" {
+  type        = string
+  description = "Name for the agent policy"
+}
+
+provider "elasticstack" {
+  elasticsearch {}
+  kibana {}
+}
+
+resource "elasticstack_fleet_agent_policy" "test_policy" {
+  name            = var.policy_name
+  namespace       = "default"
+  description     = "Test Agent Policy with Multiple Required Versions"
+  monitor_logs    = true
+  monitor_metrics = false
+  skip_destroy    = false
+  required_versions = {
+    "8.15.0" = 50
+    "8.16.0" = 50
+  }
+}

internal/fleet/agent_policy/testdata/TestAccResourceAgentPolicyWithRequiredVersions/create/main.tf

@@ -0,0 +1,21 @@
+variable "policy_name" {
+  type        = string
+  description = "Name for the agent policy"
+}
+
+provider "elasticstack" {
+  elasticsearch {}
+  kibana {}
+}
+
+resource "elasticstack_fleet_agent_policy" "test_policy" {
+  name            = var.policy_name
+  namespace       = "default"
+  description     = "Test Agent Policy with Required Versions"
+  monitor_logs    = true
+  monitor_metrics = false
+  skip_destroy    = false
+  required_versions = {
+    "8.15.0" = 100
+  }
+}

internal/fleet/agent_policy/testdata/TestAccResourceAgentPolicyWithRequiredVersions/remove_versions/main.tf

@@ -0,0 +1,19 @@
+variable "policy_name" {
+  type        = string
+  description = "Name for the agent policy"
+}
+
+provider "elasticstack" {
+  elasticsearch {}
+  kibana {}
+}
+
+resource "elasticstack_fleet_agent_policy" "test_policy" {
+  name              = var.policy_name
+  namespace         = "default"
+  description       = "Test Agent Policy without Required Versions"
+  monitor_logs      = true
+  monitor_metrics   = false
+  skip_destroy      = false
+  required_versions = {}
+}

internal/fleet/agent_policy/testdata/TestAccResourceAgentPolicyWithRequiredVersions/unset_versions/main.tf

@@ -0,0 +1,18 @@
+variable "policy_name" {
+  type        = string
+  description = "Name for the agent policy"
+}
+
+provider "elasticstack" {
+  elasticsearch {}
+  kibana {}
+}
+
+resource "elasticstack_fleet_agent_policy" "test_policy" {
+  name            = var.policy_name
+  namespace       = "default"
+  description     = "Test Agent Policy without Required Versions"
+  monitor_logs    = true
+  monitor_metrics = false
+  skip_destroy    = false
+}