[Fleet] Write policy_base_id field at agent enrollment

[juliaElastic]

Summary

Adds a denormalized policy_base_id field written at agent enrollment to enable cheap term/terms queries in place of expensive prefix/wildcard queries.

Background

Fleet supports version-specific agent policies where policy_id gets a #major.minor suffix (e.g. my-policy#9.2). Querying agents by policy currently requires:

{ "bool": { "should": [{ "term": { "policy_id": "my-policy" } }, { "prefix": { "policy_id": "my-policy#" } }] } }

The policy_base_id field stores the canonical base ID (suffix stripped), enabling a single term: { policy_base_id: "my-policy" } query instead.

Changes

• internal/pkg/dl/constants.go: Add FieldPolicyBaseID = "policy_base_id" constant
• internal/pkg/model/schema.go: Add PolicyBaseID string json:"policy_base_id,omitempty" field to the Agent model
• internal/pkg/api/handleEnroll.go: Set PolicyBaseID: policyBaseID(policyID) in the agent struct at enrollment; add policyBaseID helper that strips the #version suffix

Notes

• Checkin (bulk.go) writes agent_policy_id via partial update — no change needed there; policy_base_id tracks policy_id, not agent_policy_id
• Kibana backfills existing documents via update_by_query during Fleet setup (companion PR: [Fleet] Add policy_base_id field to eliminate prefix/wildcard agent policy queries (B2) kibana#279716)
• Companion ES mapping PR: [Fleet] Add policy_base_id field to fleet-agents and fleet-policies index templates elasticsearch#154521

Part of elastic/ingest-dev#8624 (Workstream B2).

[mergify]

This pull request does not have a backport label. Could you fix it @juliaElastic? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-./d./d is the label to automatically backport to the 8./d branch. /d is the digit
• backport-active-all is the label that automatically backports to all active branches.
• backport-active-8 is the label that automatically backports to all active minor branches for the 8 major.
• backport-active-9 is the label that automatically backports to all active minor branches for the 9 major.

[mergify]

This pull request is now in conflicts. Could you fix it @juliaElastic? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b feat/policy-base-id upstream/feat/policy-base-id
git merge upstream/main
git push upstream feat/policy-base-id

[github-actions]

TL;DR

The check-ci Buildkite job fails because go-licenser modifies four generated Go files during the header check, leaving the worktree dirty. This is a generated-file/license-header drift issue; no compile or test failure is shown.

Remediation

• Regenerate the affected files on the PR branch (or run the repository generation target) so the generated outputs include the required Elastic license headers, and commit the resulting changes. The affected files are internal/pkg/api/openapi.gen.go, internal/pkg/model/schema.go, pkg/api/client.gen.go, and pkg/api/types.gen.go.
• Re-run .buildkite/scripts/check_ci.sh or mage check:ci and confirm the header check leaves no working-tree changes.

Investigation details

Root Cause

.buildkite/scripts/check_ci.sh runs mage check:ci; the repository header target invokes go-licenser with the Elasticv2 license. On this build, that check added the standard four-line copyright header to the four generated files above. Because the generated files were not already synchronized with the header tool, the subsequent git update-index --refresh pre-exit check failed.

Evidence

• Build: https://buildkite.com/elastic/fleet-server/builds/15575
• Job/step: Run check-ci
• Key log excerpt: internal/pkg/api/openapi.gen.go: needs update, internal/pkg/model/schema.go: needs update, pkg/api/client.gen.go: needs update, pkg/api/client.gen.go: needs update, followed by Error: git update-index failure.

Verification

The supplied Buildkite log was inspected locally. The PR checkout was not available in the workspace, so no PR-specific rerun was performed.

---

What is this? | From workflow: PR Buildkite Detective

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[Copilot]

Pull request overview

This PR introduces a denormalized policy_base_id field on agent documents to enable efficient term/terms queries for “base policy ID” lookups when policy_id may include a #major.minor version suffix.

Changes:

• Adds policy_base_id to the Agent schema/model and corresponding DL constant.
• Populates PolicyBaseID during agent creation in the enrollment handler via a policyBaseID() helper.
• Adds a unit test for the policyBaseID() helper and a changelog fragment.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
model/schema.json	Adds policy_base_id to the agent schema definition.
internal/pkg/model/schema.go	Regenerates model output to include Agent.PolicyBaseID.
internal/pkg/dl/constants.go	Adds FieldPolicyBaseID constant for ES field naming.
internal/pkg/api/handleEnroll.go	Writes PolicyBaseID on agent creation and adds policyBaseID() helper.
internal/pkg/api/handleEnroll_test.go	Adds unit coverage for policyBaseID() helper behavior.
changelog/fragments/1784718180-write-policy-base-id-on-enrollment.yaml	Records the feature in the changelog.

Files not reviewed (1)

• internal/pkg/model/schema.go: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ycombinator]

internal/pkg/api/handleEnroll_test.go — TestEnrollWithAgentIDExistingActive (lines 382–410)

TestEnrollWithAgentIDExistingActive exercises the re-enrollment UpdateFields path — the exact path where the original omission was caught by Copilot review. The mock accepts any args on Update, so a missing FieldPolicyBaseID would pass silently. Suggested change: use a versioned policy ID and assert the field is written.

// before (lines 382–410)
	source := fmt.Sprintf(`{"active":true,"agent":{"id":"1234","version":"8.9.0"},"type":"PERMANENT","policy_id":"1234","replace_token":"%s"}`, replaceHash)
	// ... bulker mock setup ...
	resp, _ := et._enroll(ctx, rb, zlog, req, "1234", []string{}, "8.9.0")
	// only resp.Action and resp.Item.Id are asserted
}

// after
	policyID := "my-policy#9.2"
	source := fmt.Sprintf(`{"active":true,"agent":{"id":"1234","version":"8.9.0"},"type":"PERMANENT","policy_id":"%s","replace_token":"%s"}`, policyID, replaceHash)
	// ... bulker mock setup unchanged ...
	resp, _ := et._enroll(ctx, rb, zlog, req, policyID, []string{}, "8.9.0")

	if resp.Action != "created" {
		t.Fatal("enroll failed")
	}
	if resp.Item.Id != agentID {
		t.Fatalf("agent ID should have been %s (not %s)", agentID, resp.Item.Id)
	}

	var updateBody []byte
	for _, c := range bulker.Calls {
		if c.Method == "Update" {
			updateBody = c.Arguments.Get(3).([]byte)
			break
		}
	}
	var updateDoc struct {
		Doc map[string]any `json:"doc"`
	}
	assert.NoError(t, json.Unmarshal(updateBody, &updateDoc))
	assert.Equal(t, "my-policy", updateDoc.Doc[dl.FieldPolicyBaseID])
}

[ycombinator]

While this PR handles the enrollment path, my concern was around the policy reassignment path. But it looks like the companion Kibana PR takes care of setting both policy_id and the new base_policy_id fields on the Agent doc during policy reassignment as well. 👍

[juliaElastic]

@ycombinator thanks for the review, updated the test

If you ready to approve, can you help with the merge too? I don't have access.