Add support for release field in agentless deployment mode (#1130)

* Add support for  field in agentless deployment mode

* Add PR link to changelog

* Remove 'rc' from agentless release enum

* Extract validateAgentlessReleaseDeployment, add tests

* Formatting

* Update code/go/internal/validator/semantic/validate_deployment_modes.go

Co-authored-by: Tere <romero.teresa@protonmail.com>

* Formatting

* Change agentless deployment mode 'release' default to 'beta'

* Undo formatting changes

* Clarify var name

* Address PR feedback

* Update description of deployment mode release field

* Move changelog entry from next patch to next minor

---------

Co-authored-by: Tere <romero.teresa@protonmail.com>

Author: MichelLosier

code/go/internal/validator/semantic/validate_deployment_modes.go

@@ -14,6 +14,35 @@ import (
 	"github.com/elastic/package-spec/v3/code/go/pkg/specerrors"
 )
 
+type deploymentModesManifest struct {
+	PolicyTemplates []deploymentModesPolicyTemplate `yaml:"policy_templates"`
+}
+
+type deploymentModesPolicyTemplate struct {
+	Name            string                 `yaml:"name"`
+	DeploymentModes deploymentModesSpec    `yaml:"deployment_modes"`
+	Inputs          []deploymentModesInput `yaml:"inputs"`
+}
+
+type deploymentModesSpec struct {
+	Default   deploymentModesDefault   `yaml:"default"`
+	Agentless deploymentModesAgentless `yaml:"agentless"`
+}
+
+type deploymentModesDefault struct {
+	Enabled *bool `yaml:"enabled"` // pointer to detect if field was set; when unset (nil) semantical meaning is default deployment is enabled
+}
+
+type deploymentModesAgentless struct {
+	Enabled bool   `yaml:"enabled"`
+	Release string `yaml:"release"`
+}
+
+type deploymentModesInput struct {
+	Type            string    `yaml:"type"`
+	DeploymentModes *[]string `yaml:"deployment_modes"` // pointer to detect if field was set
+}
+
 // ValidateDeploymentModes ensures that for each deployment mode enabled in a policy template,
 // there is at least one input that supports that deployment mode.
 func ValidateDeploymentModes(fsys fspath.FS) specerrors.ValidationErrors {
@@ -23,30 +52,18 @@ func ValidateDeploymentModes(fsys fspath.FS) specerrors.ValidationErrors {
 		return specerrors.ValidationErrors{specerrors.NewStructuredErrorf("file \"%s\" is invalid: failed to read manifest: %w", fsys.Path(manifestPath), err)}
 	}
 
-	var manifest struct {
-		PolicyTemplates []struct {
-			Name            string `yaml:"name"`
-			DeploymentModes struct {
-				Default struct {
-					Enabled *bool `yaml:"enabled"` // Use pointer to detect if field was set, default is true
-				} `yaml:"default"`
-				Agentless struct {
-					Enabled bool `yaml:"enabled"`
-				} `yaml:"agentless"`
-			} `yaml:"deployment_modes"`
-			Inputs []struct {
-				Type            string    `yaml:"type"`
-				DeploymentModes *[]string `yaml:"deployment_modes"` // Use pointer to detect if field was set
-			} `yaml:"inputs"`
-		} `yaml:"policy_templates"`
-	}
-
+	var manifest deploymentModesManifest
 	err = yaml.Unmarshal(d, &manifest)
 	if err != nil {
 		return specerrors.ValidationErrors{specerrors.NewStructuredErrorf("file \"%s\" is invalid: failed to parse manifest: %w", fsys.Path(manifestPath), err)}
 	}
 
 	var errs specerrors.ValidationErrors
+
+	if err := validateAgentlessReleaseDeployment(manifest); err != nil {
+		errs = append(errs, specerrors.NewStructuredError(fmt.Errorf("file \"%s\" is invalid: %w", fsys.Path(manifestPath), err), specerrors.UnassignedCode))
+	}
+
 	for _, template := range manifest.PolicyTemplates {
 		// Collect enabled deployment modes for this policy template
 		enabledModes := []string{}
@@ -110,3 +127,20 @@ func ValidateDeploymentModes(fsys fspath.FS) specerrors.ValidationErrors {
 
 	return errs
 }
+
+// validateAgentlessReleaseDeployment checks that agentless.release is not set in a
+// single-policy-template package where agentless is the only deployment mode. In that
+// case the package version is the authoritative source of maturity and an explicit
+// override would conflict.
+func validateAgentlessReleaseDeployment(manifest deploymentModesManifest) error {
+	if len(manifest.PolicyTemplates) != 1 {
+		return nil
+	}
+	tmpl := manifest.PolicyTemplates[0]
+	// Default.Enabled == nil means default mode is implicitly enabled, so agentless is not the only mode.
+	defaultDeploymentDisabled := tmpl.DeploymentModes.Default.Enabled != nil && !*tmpl.DeploymentModes.Default.Enabled
+	if defaultDeploymentDisabled && tmpl.DeploymentModes.Agentless.Release != "" {
+		return fmt.Errorf("policy template \"%s\" sets agentless.release but agentless is the only deployment mode; use the package version to indicate maturity instead", tmpl.Name)
+	}
+	return nil
+}

code/go/internal/validator/semantic/validate_deployment_modes_test.go

@@ -214,3 +214,104 @@ policy_templates:
 		})
 	}
 }
+
+func boolPtr(b bool) *bool { return &b }
+
+func TestValidateAgentlessReleaseDeployment(t *testing.T) {
+	cases := []struct {
+		title       string
+		manifest    deploymentModesManifest
+		expectedErr string
+	}{
+		{
+			title: "valid - default enabled explicitly, release set",
+			manifest: deploymentModesManifest{
+				PolicyTemplates: []deploymentModesPolicyTemplate{
+					{
+						Name: "test",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: boolPtr(true)},
+							Agentless: deploymentModesAgentless{Enabled: true, Release: "ga"},
+						},
+					},
+				},
+			},
+		},
+		{
+			title: "valid - default enabled implicitly (nil), release set",
+			manifest: deploymentModesManifest{
+				PolicyTemplates: []deploymentModesPolicyTemplate{
+					{
+						Name: "test",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: nil},
+							Agentless: deploymentModesAgentless{Enabled: true, Release: "ga"},
+						},
+					},
+				},
+			},
+		},
+		{
+			title: "valid - agentless-only single template, no release set",
+			manifest: deploymentModesManifest{
+				PolicyTemplates: []deploymentModesPolicyTemplate{
+					{
+						Name: "test",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: boolPtr(false)},
+							Agentless: deploymentModesAgentless{Enabled: true},
+						},
+					},
+				},
+			},
+		},
+		{
+			title: "valid - multiple templates, one agentless-only with release set",
+			manifest: deploymentModesManifest{
+				PolicyTemplates: []deploymentModesPolicyTemplate{
+					{
+						Name: "test1",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: boolPtr(true)},
+							Agentless: deploymentModesAgentless{Enabled: true},
+						},
+					},
+					{
+						Name: "test2",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: boolPtr(false)},
+							Agentless: deploymentModesAgentless{Enabled: true, Release: "ga"},
+						},
+					},
+				},
+			},
+		},
+		{
+			title: "invalid - agentless-only single template with release set",
+			manifest: deploymentModesManifest{
+				PolicyTemplates: []deploymentModesPolicyTemplate{
+					{
+						Name: "test",
+						DeploymentModes: deploymentModesSpec{
+							Default:   deploymentModesDefault{Enabled: boolPtr(false)},
+							Agentless: deploymentModesAgentless{Enabled: true, Release: "ga"},
+						},
+					},
+				},
+			},
+			expectedErr: `policy template "test" sets agentless.release but agentless is the only deployment mode; use the package version to indicate maturity instead`,
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.title, func(t *testing.T) {
+			err := validateAgentlessReleaseDeployment(c.manifest)
+			if c.expectedErr == "" {
+				assert.NoError(t, err)
+			} else {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), c.expectedErr)
+			}
+		})
+	}
+}

code/go/pkg/validator/validator_test.go

@@ -379,6 +379,12 @@ func TestValidateFile(t *testing.T) {
 				`var "access_key_id" in non-required var_group "credential_type" should not have required: true (var_group is optional)`,
 			},
 		},
+		"bad_agentless_release": {
+			"manifest.yml",
+			[]string{
+				`policy template "test" sets agentless.release but agentless is the only deployment mode; use the package version to indicate maturity instead`,
+			},
+		},
 		"bad_input_deployment_modes": {
 			"manifest.yml",
 			[]string{

spec/changelog.yml

@@ -8,6 +8,9 @@
     - description: Add support for semantic_text field definition.
       type: enhancement
       link: https://github.com/elastic/package-spec/pull/807
+    - description: Add optional `release` field to agentless deployment mode to explicitly declare its release stage.
+      type: enhancement
+      link: https://github.com/elastic/package-spec/pull/1130
 - version: 3.6.2
   changes:
     - description: Add support for ML modules in content packages.

spec/integration/manifest.spec.yml

@@ -295,6 +295,19 @@ spec:
               type: string
               examples:
                 - "cloud-security-posture-management"
+            release:
+              description: >
+                The maturity level of the agentless deployment mode for this policy template.
+                If not defined, Kibana will provide a default value based on agentless platform maturity.
+                Packages where agentless is the only deployment mode, should defer to the package's top-level `version`.
+                Only evaluated in Kibana 9.5.0 or later.
+              type: string
+              enum:
+                - beta
+                - ga
+              examples:
+                - beta
+                - ga
             resources:
               description: >
                 The computing resources specifications for the Agentless deployment.

test/packages/bad_agentless_release/changelog.yml

@@ -0,0 +1,5 @@
+- version: 0.0.1
+  changes:
+    - description: Initial version
+      type: enhancement
+      link: https://github.com/elastic/package-spec/pull/1130

test/packages/bad_agentless_release/docs/README.md

@@ -0,0 +1,3 @@
+# Test Package
+
+This is a test package for agentless release validation.

test/packages/bad_agentless_release/manifest.yml

@@ -0,0 +1,30 @@
+format_version: 3.6.1
+name: bad_agentless_release
+title: Bad Agentless Release
+description: Test package where agentless.release is set but agentless is the only deployment mode
+version: 0.0.1
+type: integration
+policy_templates:
+  - name: test
+    title: Test
+    description: Test policy template
+    deployment_modes:
+      default:
+        enabled: false
+      agentless:
+        enabled: true
+        release: ga
+        organization: elastic
+        division: observability
+        team: test
+    inputs:
+      - type: httpjson
+        title: Test HTTP JSON
+        description: Test HTTP JSON input
+        deployment_modes: ['agentless']
+conditions:
+  kibana:
+    version: '^9.5.0'
+owner:
+  github: elastic/ecosystem
+  type: elastic

test/packages/good_v3/manifest.yml

@@ -8,7 +8,7 @@ source:
   license: "Apache-2.0"
 conditions:
   kibana:
-    version: '^8.10.0'
+    version: '^9.5.0'
   elastic:
     subscription: 'basic'
     capabilities:
@@ -39,6 +39,7 @@ policy_templates:
       agentless:
         enabled: true
         is_default: true
+        release: ga
         organization: elastic
         division: observability
         team: obs-infraobs-integrations