[Proposal] Use Major Version for Policy Identity Between Gateway Controller and Policy Engine

[renuka-fernando]

Summary

Change the internal version contract between Gateway Controller and Policy Engine from full semantic versions (v0.1.2) to major-only versions (v0). The policy engine registry would key policies by name:vN instead of name:vN.M.P, and the Gateway Controller would send major-only versions over xDS. This eliminates version mismatch failures during Kubernetes rolling updates and aligns the internal protocol with the already major-only user-facing API YAML contract.

Motivation

The API Platform gateway has three main runtime components that interact around policy versions:

• Gateway Controller loads policy definitions from YAML files (e.g., api-key-auth.yaml with version: v0.1.2) and sends policy chains to the Policy Engine via xDS.
• Policy Engine executes policies compiled into its binary at build time. Each policy is registered with a name and full semver version (e.g., api-key-auth:v0.1.2).
• Gateway Builder compiles both components from the same source tree. It mounts policy definition YAMLs into the Gateway Controller and compiles policy Go modules into the Policy Engine binary.

Current Version Flow

1. API YAML (user-facing) defines policies with major-only versions: version: v0
2. Gateway Controller resolves v0 to v0.1.2 (full semver) using ResolvePolicyVersion() from loaded policy definitions
3. Gateway Controller sends v0.1.2 to Policy Engine via xDS in PolicyInstance.Version
4. Policy Engine registry stores policies keyed by full semver: api-key-auth:v0.1.2
5. Policy Engine looks up api-key-auth:v0.1.2 -- must match exactly

The Problem

Only one implementation per major version can exist. The policy engine binary contains exactly one compiled implementation of each policy. There is no scenario where v0.1.0 and v0.1.2 of api-key-auth coexist in the same binary. The full semver in the registry key carries precision that does not correspond to any real distinction.

Kubernetes rolling updates cause version mismatch failures. In a Kubernetes deployment, the Gateway Controller pod and Gateway Runtime pod may briefly run different builds during a rollout restart. A new Gateway Controller (loading policy definitions at v0.1.3) may connect to an old Policy Engine (compiled with v0.1.2). The exact-match lookup on api-key-auth:v0.1.3 fails against the registry entry api-key-auth:v0.1.2, even though the policies are functionally compatible within the same major version.

The internal protocol is more precise than the user-facing contract. Users already specify version: v0 in their API YAML. The Gateway Controller resolves this to full semver solely for the internal xDS message, introducing fragile coupling that the user never asked for.

Rollout Restart Failure Scenario

sequenceDiagram
    participant User as User/CI
    participant K8s as Kubernetes
    participant GC_old as Gateway Controller<br/>(Old Build v0.1.2)
    participant GC_new as Gateway Controller<br/>(New Build v0.1.3)
    participant PE_old as Policy Engine<br/>(Old Build v0.1.2)
    participant PE_new as Policy Engine<br/>(New Build v0.1.3)

    Note over K8s: Initial State: Both components running v0.1.2

    User->>K8s: Deploy new gateway image (v0.1.3)
    K8s->>GC_new: Start new Gateway Controller pod
    Note over GC_new: Loads policy defs v0.1.3
    K8s--xGC_old: Terminate old Gateway Controller

    Note over PE_old: Policy Engine still running old build (v0.1.2)

    User->>GC_new: Deploy API with policy version: v0
    GC_new->>GC_new: Resolve v0 → v0.1.3 (full semver)

    rect rgb(255, 200, 200)
        Note over GC_new,PE_old: VERSION MISMATCH WINDOW
        GC_new->>PE_old: xDS: PolicyInstance{version: "v0.1.3"}
        PE_old->>PE_old: Lookup "api-key-auth:v0.1.3"
        PE_old-->>GC_new: ERROR: policy not found<br/>(registry has "api-key-auth:v0.1.2")
    end

    Note over K8s: Eventually PE pod also restarts...
    K8s->>PE_new: Start new Policy Engine pod
    K8s--xPE_old: Terminate old Policy Engine
    GC_new->>PE_new: xDS: PolicyInstance{version: "v0.1.3"}
    PE_new->>PE_new: Lookup "api-key-auth:v0.1.3" ✓
    PE_new-->>GC_new: OK

Loading

Solution with Major-Only Versions

sequenceDiagram
    participant User as User/CI
    participant K8s as Kubernetes
    participant GC_new as Gateway Controller<br/>(New Build v0.1.3)
    participant PE_old as Policy Engine<br/>(Old Build v0.1.2)
    participant PE_new as Policy Engine<br/>(New Build v0.1.3)

    Note over K8s: Rolling update in progress

    User->>GC_new: Deploy API with policy version: v0

    rect rgb(200, 255, 200)
        Note over GC_new,PE_old: MAJOR VERSION - ALWAYS COMPATIBLE
        GC_new->>PE_old: xDS: PolicyInstance{version: "v0"}
        PE_old->>PE_old: Lookup "api-key-auth:v0" ✓<br/>(registered v0.1.2 as major v0)
        PE_old-->>GC_new: OK
    end

    Note over K8s: PE pod restarts later...
    K8s->>PE_new: Start new Policy Engine pod
    K8s--xPE_old: Terminate old Policy Engine

    rect rgb(200, 255, 200)
        Note over GC_new,PE_new: STILL COMPATIBLE
        GC_new->>PE_new: xDS: PolicyInstance{version: "v0"}
        PE_new->>PE_new: Lookup "api-key-auth:v0" ✓<br/>(registered v0.1.3 as major v0)
        PE_new-->>GC_new: OK
    end

Loading

Proposal

Principle

Use major version only (v0, v1, v2) as the policy identity contract between Gateway Controller and Policy Engine. This matches:

• The user-facing API YAML contract (already major-only)
• The reality that only one implementation per major version exists in the runtime
• The need for loose coupling during Kubernetes rolling updates

Changes Required

Policy Engine Side

1. Registry Register() method -- Extract the major version from def.Version (full semver) before creating the composite key.

Current behavior:

// registry.go
func (r *PolicyRegistry) Register(def *policy.PolicyDefinition, factory policy.PolicyFactory) error {
    key := compositeKey(def.Name, def.Version) // "api-key-auth:v0.1.2"
    // ...
    r.Policies[key] = &PolicyEntry{Definition: def, Factory: factory}
}

Proposed behavior:

func (r *PolicyRegistry) Register(def *policy.PolicyDefinition, factory policy.PolicyFactory) error {
    major := majorVersion(def.Version) // "v0.1.2" → "v0"
    key := compositeKey(def.Name, major) // "api-key-auth:v0"
    // ...
    r.Policies[key] = &PolicyEntry{Definition: def, Factory: factory}
    // def.Version still contains "v0.1.2" for debugging/admin endpoints
}

The majorVersion() helper extracts the major component:

// majorVersion extracts the major version from a semver string.
// "v0.1.2" → "v0", "v1.0.0" → "v1"
func majorVersion(version string) string {
    if idx := strings.Index(version, "."); idx != -1 {
        return version[:idx]
    }
    return version // already major-only
}

2. CreateInstance() and PolicyExists() -- No changes needed. They receive major-only versions from xDS and look up directly against the major-keyed registry.

Gateway Controller Side

1. DerivePolicyFromAPIConfig in builder.go -- Still call ResolvePolicyVersion() for validation (confirming a policy definition exists for the requested major version), but pass the original major-only version from the API YAML to ConvertAPIPolicyToModel instead of the resolved full semver.

Current behavior:

resolvedVersion, err := config.ResolvePolicyVersion(policyDefinitions, p.Name, p.Version)
// resolvedVersion = "v0.1.2"
apiPolicies[p.Name] = ConvertAPIPolicyToModel(p, policyv1alpha.LevelAPI, resolvedVersion)
// xDS sends version: "v0.1.2"

Proposed behavior:

_, err := config.ResolvePolicyVersion(policyDefinitions, p.Name, p.Version)
// Still validates that the policy definition exists, but we discard the resolved version
apiPolicies[p.Name] = ConvertAPIPolicyToModel(p, policyv1alpha.LevelAPI, p.Version)
// xDS sends version: "v0" (the original major-only from API YAML)

2. System policy constants -- Change version constants from full semver to major-only:

// constants.go — before
ANALYTICS_SYSTEM_POLICY_VERSION = "v0.1.0"

// constants.go — after
ANALYTICS_SYSTEM_POLICY_VERSION = "v0"

Key Design Decisions

• PolicyEntry.Definition retains full semver. The original def.Version field (e.g., "v0.1.2") is preserved in the stored PolicyDefinition struct. Only the map key changes. Admin endpoints like DumpPolicies() continue to report the precise build-time version for debugging.

• Validation still happens. ResolvePolicyVersion() is still called to confirm that a policy definition exists for the requested major version. The resolved full version is simply discarded rather than being passed through to xDS.

• Duplicate detection at major level. Attempting to register both v1.0.0 and v1.1.0 of the same policy will fail as a duplicate (both map to api-key-auth:v1). This is correct since only one implementation per major version can be compiled into the binary.

Backward Compatibility

Both Gateway Controller and Policy Engine must be updated together. In practice this is safe because:

1. In the gateway-runtime container (the common deployment model), Router and Policy Engine are co-located in a single container. They are always the same build.
2. In Kubernetes with separate pods, the rolling update window is exactly the problem this change fixes. After this change, the mismatch window becomes safe because both old and new builds register and look up by major version.
3. The Gateway Builder builds both components from the same source tree. A single build produces both the Gateway Controller image (with policy definition YAMLs) and the Policy Engine binary.

There is no supported scenario where a pre-change Gateway Controller communicates with a post-change Policy Engine or vice versa across different release trains.

Alternatives Considered

Alternative 1: Fuzzy Matching in the Policy Engine Registry

Make the registry lookup tolerate minor/patch differences. If api-key-auth:v0.1.3 is not found, fall back to any api-key-auth:v0.x.x.

Rejected because:

• Adds complexity to a hot path (every policy lookup during request processing)
• The registry would need a secondary index by major version
• Masks configuration errors rather than preventing them
• The fundamental issue is that full semver carries no meaningful information in this context

Alternative 2: Version Negotiation via xDS

Add a handshake where the Policy Engine reports its compiled policy versions, and the Gateway Controller adapts its xDS messages accordingly.

Rejected because:

• Significant protocol complexity for a problem that only exists during brief rolling updates
• Adds round-trip latency to startup
• Over-engineered for the actual constraint (one implementation per major version)

Alternative 3: Keep Full Semver but Ignore Patch/Minor in Lookup

The registry key remains api-key-auth:v0.1.2, but the CreateInstance() method strips to major version before lookup.

Rejected because:

• Inconsistent: the key would not match what callers provide
• Debugging confusion: the key format would differ between registration and lookup
• Cleaner to align the key at registration time

Impact Analysis

Benefits

• Eliminates rolling update failures in Kubernetes deployments where Gateway Controller and Policy Engine pods restart at different times
• Simplifies the version contract -- the internal protocol now matches the user-facing API YAML semantics
• Removes unnecessary coupling between the exact build-time patch version and the runtime lookup path

Risks

• Coordinated deployment required -- Both Gateway Controller and Policy Engine must be updated in the same release. This is the existing deployment model and does not introduce new risk.
• Multiple major versions of the same policy would need distinct major numbers. This is already the case by design (major version bumps indicate breaking changes).

Document Version: 1.0
Last Updated: 2026-02-12
Status: Proposed

[Thushani-Jayasekera]

This proposal effectively addresses the rolling update compatibility issue by using major-only versions. I'd like to suggest an additional enhancement that could make the system even more resilient:

Instead of strict version matching, we could implement a fallback mechanism:

1. Gateway-side Resolution: The Gateway Controller continues to resolve the full policy version (e.g.,
   v0.1.3) from the major version specified in the API YAML (e.g., v0)
2. Exact Match Request: Gateway requests the specific resolved version from the Policy Engine
3. Policy Engine Lookup:
   - First, attempt to locate the exact version requested by the Gateway ( v0.1.3)
   - If not found, fall back to the latest available patch version within the same major version (v0.1.5)
   - Return ok with resolved version (v0.1.5)
4. Version Drift Detection:
   - Gateway compares the requested version against the applied version (v0.1.3)
   - If they differ, emit a WARN-level log indicating version mismatch (v0.1.5)
   - Log message should include: policy name, requested version, applied version

Benefits:

• Graceful Degradation: System remains operational during version mismatches instead of failing
• Operational Visibility: Gateway admins get clear signals when there are mismatches between the versions in policy engine and gateway controller, and need updates
• Backward Compatibility: Works within the major-only versioning scheme proposed

This would make the system more robust during gradual rollouts and provide early warning signals for
version inconsistencies without requiring perfect synchronization between components.

[renuka-fernando]

Thanks, @Thushani-Jayasekera, for the suggestion.

I also had the same thinking, and feel like this is also a good approach again. I will reconsider this.