Skip to content

fix(connectivity): BackendTrafficPolicy renders spec.targetRefs[].namespace, which Envoy Gateway >= 1.1 does not declare — the connectivity upgrade fails with 'field not declared in schema' when ingress.backendTrafficPolicy is on #377

Description

@teemow

Problem

The connectivity chart's BackendTrafficPolicy objects (ingress.backendTrafficPolicy.enabled: true: templates/ingress/muster-backendtrafficpolicy.yaml, templates/agentgateway/backendtrafficpolicy.yaml, templates/kagent/controller-backendtrafficpolicy.yaml, templates/kagent/ui-backendtrafficpolicy.yaml) render spec.targetRefs[].namespace. Envoy Gateway's BackendTrafficPolicy has taken local policy target references since v1.1 (LocalPolicyTargetReferenceWithSectionName: group, kind, name, sectionName — no namespace), so on an installation with a current Envoy Gateway the release cannot be applied:

Helm upgrade failed for release agent-platform/agent-platform-connectivity with chart agent-platform-connectivity@4.7.0+c439a9c72d9c:
failed to create resource: server-side apply failed for object agent-platform/agentgateway gateway.envoyproxy.io/v1alpha1, Kind=BackendTrafficPolicy:
failed to create typed patch object (agent-platform/agentgateway; gateway.envoyproxy.io/v1alpha1, Kind=BackendTrafficPolicy): .spec.targetRefs[0].namespace: field not declared in schema

Seen 2026-09-11 on the first installation of the 4.x line (Envoy Gateway v1.9.1, CRD targetRefs.items.properties = group, kind, name, sectionName). helm-controller applies server-side with strict field validation, so an unknown field is a hard failure of the whole connectivity upgrade — and with it the Substrate and kagent releases that depend on it. The 4.0 line made the policy matter: a GRPCRoute has no timeouts, so kagent-controller-public relies on this policy to keep Envoy from cutting A2A streaming turns (UPGRADE.md "Envoy front Gateway"); an installation that has to switch the knob off loses that.

Proposed solution

Drop namespace from spec.targetRefs[] in all four templates — a BackendTrafficPolicy can only target routes of its own namespace, which is where the chart renders both the policy and the route. If an installation's Envoy Gateway predates v1.1 (the fleet's envoy-gateway-app version decides), keep compatibility behind a knob rather than the field: the v1.1+ shape by default.

Acceptance criteria

  • helm template with ingress.backendTrafficPolicy.enabled: true renders no namespace under spec.targetRefs[] of any BackendTrafficPolicy; a verify target asserts it.
  • The rendered policies validate against the Envoy Gateway v1.9 CRD (e.g. kubectl apply --dry-run=server in the ATS kind smoke, which has the Gateway API CRDs — or a kubeconform step with the EG schema).
  • CHANGELOG entry; UPGRADE.md notes that installations which switched the knob off can turn it back on.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions