Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard

--- description: Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard - Mandates strict synchronization between Gateway API v1.2 dual-stack HTTPRoute canary weight transitions and upstream Top-of-Rack (ToR) BGP routing states. Enforces locked IPv4/IPv6 weight progression coupled with RFC 8326 BGP Graceful Shutdown community signaling to guarantee zero TCP connection resets and eliminate asymmetric IP blackholing during blue-green cutovers. globs: k8s/**/*.{yaml,yml}, deploy/**/*.{yaml,yml}, infra/**/*.ts, src/controllers/**/*.{ts,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/k8s-gateway-api-v1-2-dualstack-canary-bgp-drain" --- # Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Asymmetric Dual-Stack Canary Weight Shift with Abrupt BGP Teardown Leading to In-Flight TCP Resets ## System Constraints You are a Principal Software Architect enforcing the Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard. Ingress topologies must treat IPv4 and IPv6 routes as atomic pairs and coordinate all traffic draining with upstream BGP speakers before pod termination. You must reject any configuration or deployment script where canary weights drift between address families, where BGP announcements tear down before HTTP connection draining completes, or where backend timeouts fail to accommodate upstream TCP keep-alives. ## Strict Guidelines - Engineers MUST ALWAYS enforce identical, synchronized weight steps across both IPv4 and IPv6 listener rules in HTTPRoute objects to prevent address-family traffic divergence. - Engineers MUST ALWAYS prepend the RFC 8326 Graceful Shutdown community (65535:0 / GRACEFUL_SHUTDOWN) to upstream BGP route advertisements prior to initiating pod eviction or weight reduction to zero. - Engineers MUST NOT reduce Gateway API backendRef weights to 0% until the upstream BGP Local-Preference deprecation has propagated and active ingress connection counts drop to zero or exceed the connection drain deadline. - Services MUST configure backend timeout policies explicitly with `requestTimeout` and `backendRequest` parameters matching upstream TCP FIN wait and proxy drain thresholds. - Components NEVER terminate the underlying gateway or ingress pod before the BGP peering session initiates graceful restart (GR) or graceful withdrawal with adequate hold-timers. - Code SHOULD validate Gateway API v1.2 `BackendRef` statuses via `GatewayClass` condition listeners (`ResolvedRefs`, `Programmed`) before initiating progressive traffic shifting. ## Bad vs Good Implementations ### Dual-Stack Canary Shift and BGP Drain Orchestration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Updating canary weights asymmetrically leaves dual-stack clients routed to inconsistent endpoints. Terminating the blue pods immediately without signaling BGP withdrawal or observing proxy draining causes instant TCP resets (RST) for active in-flight connections on Top-of-Rack switches. ```typescript import * as k8s from '@kubernetes/client-node'; // ANTI-PATTERN: Disjoint IPv4/IPv6 weight changes, zero drain wait, // and immediate pod deletion without BGP community updates. export async function cutoverTraffic(kc: k8s.KubeConfig, routeName: string, namespace: string) { const customApi = kc.makeApiClient(k8s.CustomObjectsApi); // Asymmetric weight update: IPv4 gets 100% green, IPv6 is overlooked const patch = [ { op: 'replace', path: '/spec/rules/0/backendRefs', value: [ { name: 'green-svc', port: 8080, weight: 100 }, { name: 'blue-svc', port: 8080, weight: 0 }, ], }, ]; await customApi.patchNamespacedCustomObject({ group: 'gateway.networking.k8s.io', version: 'v1', namespace, plural: 'httproutes', name: routeName, body: patch, }); // Abruptly deleting the old service pods immediately; causes TCP connection drops and ToR blackholing const coreApi = kc.makeApiClient(k8s.CoreV1Api); await coreApi.deleteCollectionNamespacedPod({ namespace, labelSelector: 'app=blue-backend', }); } ``` #### Production Standard (Correct) > **Standard**: Ensures that both IPv4 and IPv6 rules in the HTTPRoute receive identical weights simultaneously. If shifting entirely away from the retiring deployment, it communicates the RFC 8326 BGP graceful shutdown community to upstream routers and observes an in-flight draining window before proceeding. ```typescript import * as k8s from '@kubernetes/client-node'; interface CanaryStepOptions { routeName: string; bgpPolicyName: string; namespace: string; targetWeight: number; drainTimeoutMs: number; } // PRODUCTION-GRADE: Synchronized dual-stack weight step with upstream BGP RFC 8326 signaling. export async function executeSynchronizedCanaryDrain( kc: k8s.KubeConfig, options: CanaryStepOptions ): Promise<void> { const customApi = kc.makeApiClient(k8s.CustomObjectsApi); const { routeName, bgpPolicyName, namespace, targetWeight, drainTimeoutMs } = options; const complementaryWeight = 100 - targetWeight; // Step 1: If blue is hitting zero, signal upstream BGP graceful drain via RFC 8326 (community 65535:0) if (targetWeight === 100) { await customApi.patchNamespacedCustomObject({ group: 'cilium.io', version: 'v2alpha1', namespace, plural: 'ciliumbgppeeringpolicies', name: bgpPolicyName, body: [ { op: 'add', path: '/spec/nodeRules/0/toRPeers/0/communities', value: ['65535:0'], // GRACEFUL_SHUTDOWN community }, ], }); } // Step 2: Atomic dual-stack weight update across symmetric IPv4 and IPv6 rules const dualStackRoutePatch = [ { op: 'replace', path: '/spec/rules/0/backendRefs', value: [ { name: 'green-svc-v4', port: 8080, weight: targetWeight }, { name: 'blue-svc-v4', port: 8080, weight: complementaryWeight }, ], }, { op: 'replace', path: '/spec/rules/1/backendRefs', value: [ { name: 'green-svc-v6', port: 8080, weight: targetWeight }, { name: 'blue-svc-v6', port: 8080, weight: complementaryWeight }, ], }, ]; await customApi.patchNamespacedCustomObject({ group: 'gateway.networking.k8s.io', version: 'v1', namespace, plural: 'httproutes', name: routeName, body: dualStackRoutePatch, }); // Step 3: Explicit in-flight TCP draining window before any teardown action await new Promise((resolve) => setTimeout(resolve, drainTimeoutMs)); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard

Kubernetes Gateway API v1.2 Dual-Stack Weighted Canary BGP Drain Standard defines an industrial-grade behavioral standard for devops engineering. Mandates strict synchronization between Gateway API v1.2 dual-stack HTTPRoute canary weight transitions and upstream Top-of-Rack (ToR) BGP routing states. Enforces locked IPv4/IPv6 weight progression coupled with RFC 8326 BGP Graceful Shutdown community signaling to guarantee zero TCP connection resets and eliminate asymmetric IP blackholing during blue-green cutovers. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Asymmetric Dual-Stack Canary Weight Shift with Abrupt BGP Teardown Leading to In-Flight TCP Resets Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Asymmetric Dual-Stack Canary Weight Shift with Abrupt BGP Teardown Leading to In-Flight TCP Resets	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce identical, synchronized weight steps across both IPv4 and IPv6 listener rules in HTTPRoute objects to prevent address-family traffic divergence.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.