Add conditions.agent.version into integration and input manifest spec with validation (#999)

Adds a new property into the integration and input spec to add the minimum agent version a package is compatible with.

The new field is required after 3.6

Author: teresaromero

code/go/internal/validator/semantic/validate_agent_version.go

@@ -0,0 +1,59 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package semantic
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/Masterminds/semver/v3"
+
+	"github.com/elastic/package-spec/v3/code/go/internal/fspath"
+	"github.com/elastic/package-spec/v3/code/go/internal/pkgpath"
+	"github.com/elastic/package-spec/v3/code/go/pkg/specerrors"
+)
+
+var (
+	errInvalidAgentVersionCondition = fmt.Errorf("invalid agent.version condition")
+	errAgentVersionIncorrectType    = fmt.Errorf("manifest agent version is not a string")
+)
+
+// ValidateMinimumAgentVersion checks that the package manifest includes the agent.version condition.
+func ValidateMinimumAgentVersion(fsys fspath.FS) specerrors.ValidationErrors {
+	manifest, err := readManifest(fsys)
+	if err != nil {
+		return specerrors.ValidationErrors{specerrors.NewStructuredError(err, specerrors.UnassignedCode)}
+	}
+
+	agentVersionCondition, err := getAgentVersionCondition(*manifest)
+	if err != nil {
+		return specerrors.ValidationErrors{specerrors.NewStructuredError(err, specerrors.UnassignedCode)}
+	}
+
+	if agentVersionCondition != "" {
+		if _, err := semver.NewConstraint(agentVersionCondition); err != nil {
+			return specerrors.ValidationErrors{specerrors.NewStructuredError(errors.Join(err, errInvalidAgentVersionCondition), specerrors.UnassignedCode)}
+		}
+	}
+
+	return nil
+}
+
+func getAgentVersionCondition(manifest pkgpath.File) (string, error) {
+	val, err := manifest.Values("$.conditions[\"agent.version\"]")
+	if err != nil {
+		val, err = manifest.Values("$.conditions.agent.version")
+		if err != nil {
+			return "", nil
+		}
+	}
+
+	sVal, ok := val.(string)
+	if !ok {
+		return "", errAgentVersionIncorrectType
+	}
+
+	return sVal, nil
+}

code/go/internal/validator/semantic/validate_agent_version_test.go

@@ -0,0 +1,87 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package semantic
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/elastic/package-spec/v3/code/go/internal/fspath"
+)
+
+func TestValidateMinimumAgentVersion(t *testing.T) {
+	cases := []struct {
+		title        string
+		manifestYAML string
+		expectedErr  error
+	}{
+		{
+			title: "valid - agent.version condition is present",
+			manifestYAML: `
+name: test-package
+version: 1.0.0
+conditions:
+  agent:
+    version: "^8.0.0"
+`,
+			expectedErr: nil,
+		},
+		{
+			title: "invalid - agent.version condition is missing",
+			manifestYAML: `
+name: test-package
+version: 1.0.0
+conditions:
+  some.other.condition: "value"
+`,
+			expectedErr: nil,
+		},
+		{
+			title: "invalid - agent.version condition is not a string",
+			manifestYAML: `
+name: test-package
+version: 1.0.0
+conditions:
+  agent.version:
+    min: "^8.0.0"
+`,
+			expectedErr: errAgentVersionIncorrectType,
+		},
+		{
+			title: "invalid - agent.version condition is not a constraint",
+			manifestYAML: `
+name: test-package
+version: 1.0.0
+conditions:
+  agent.version: test
+`,
+			expectedErr: errInvalidAgentVersionCondition,
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.title, func(t *testing.T) {
+			tempDir := t.TempDir()
+
+			manifestPath := filepath.Join(tempDir, "manifest.yml")
+			err := os.WriteFile(manifestPath, []byte(c.manifestYAML), 0644)
+			require.NoError(t, err)
+
+			fsys := fspath.DirFS(tempDir)
+			errs := ValidateMinimumAgentVersion(fsys)
+
+			if c.expectedErr != nil {
+				require.Len(t, errs, 1)
+				require.ErrorIs(t, errs[0], c.expectedErr)
+			} else {
+				require.Empty(t, errs)
+			}
+		})
+	}
+
+}

code/go/internal/validator/spec.go

@@ -218,6 +218,7 @@ func (s Spec) rules(pkgType string, rootSpec spectypes.ItemSpec) validationRules
 		{fn: semantic.ValidateDeploymentModes, types: []string{"integration"}},
 		{fn: semantic.ValidateDurationVariables, since: semver.MustParse("3.5.0")},
 		{fn: semantic.ValidateInputPackagesPolicyTemplates, types: []string{"input"}},
+		{fn: semantic.ValidateMinimumAgentVersion},
 	}
 
 	var validationRules validationRules

code/go/pkg/validator/validator_test.go

@@ -317,6 +317,12 @@ func TestValidateFile(t *testing.T) {
 				"policy template \"sql_query\" references template_path \"\": template_path is required for input type packages",
 			},
 		},
+		"bad_agent_version_v3": {
+			"manifest.yml",
+			[]string{
+				"field conditions.agent: version is required",
+			},
+		},
 	}
 
 	for pkgName, test := range tests {

spec/changelog.yml

@@ -12,6 +12,9 @@
     - description: Add support for semantic_text field definition.
       type: enhancement
       link: https://github.com/elastic/package-spec/pull/807
+    - description: Require defining agent version constraints in input and integration packages.
+      type: breaking-change
+      link: https://github.com/elastic/package-spec/pull/999
 - version: 3.5.1-next
   changes:
     - description: Input packages don't require to define fields.
@@ -23,6 +26,9 @@
     - description: Input packages require to define template_path in manifest.
       type: enhancement
       link: https://github.com/elastic/package-spec/pull/1000
+    - description: Allow to define agent version constrains in input and integration packages.
+      type: enhancement
+      link: https://github.com/elastic/package-spec/pull/999
 - version: 3.5.0
   changes:
     - description: Add `duration` variable data type with `min_duration` and `max_duration` validation properties.

spec/content/manifest.spec.yml

@@ -66,7 +66,14 @@ spec:
     categories:
       $ref: "../integration/manifest.spec.yml#/definitions/categories"
     conditions:
-      $ref: "../integration/manifest.spec.yml#/definitions/conditions"
+      description: Conditions under which this package can be installed.
+      type: object
+      additionalProperties: false
+      properties:
+        elastic:
+          $ref: "../integration/manifest.spec.yml#/definitions/conditions/properties/elastic"
+        kibana:
+          $ref: "../integration/manifest.spec.yml#/definitions/conditions/properties/kibana"
     discovery:
       $ref: "#/definitions/discovery"
     icons:

spec/input/manifest.spec.yml

@@ -120,9 +120,14 @@ spec:
   - version
   - type
   - owner
+  - conditions
 
 # JSON patches for newer versions should be placed on top
 versions:
+  - before: 3.6.0
+    patch:
+      - op: remove
+        path: "/required/7" # removes requirement for conditions
   # Reserve otelcol input name before 3.5.0.
   - before: 3.5.0
     patch:

spec/integration/manifest.spec.yml

@@ -217,6 +217,20 @@ spec:
               description: Kibana versions compatible with this package.
               examples:
                 - ">=7.9.0"
+        agent:
+          description: Elastic Agent conditions
+          type: object
+          additionalProperties: false
+          properties:
+            version:
+              type: string
+              description: Elastic Agent versions compatible with this package.
+              examples:
+                - "^9.5.0"
+          required:
+            - version
+      required:
+        - agent
     description:
       description: >
         A longer description of the package. It should describe, at least all the kinds of
@@ -670,6 +684,7 @@ spec:
     - version
     - type
     - owner
+    - conditions
   allOf:
     - if:
         properties:
@@ -692,6 +707,14 @@ spec:
 
 # JSON patches for newer versions should be placed on top
 versions:
+  - before: 3.6.0
+    patch:
+      - op: remove
+        path: "/required/7" # removes requirement for conditions
+      - op: remove
+        path: "/definitions/conditions/required/0" # removes requirement for agent
+      - op: remove
+        path: "/definitions/conditions/properties/agent/required/0" # removes requirement for version
   - before: 3.3.2
     patch:
       - op: remove