Envoy Gateway Proxy-Wasm Linear Memory Budgeting and Runtime Recycling Guardrail

--- description: Envoy Gateway Proxy-Wasm Linear Memory Budgeting and Runtime Recycling Guardrail - Enforces strict WebAssembly (Wasm) linear memory limits, max page allocations, and instance lifecycle recycling across Envoy Gateway extension filters. Unbounded Wasm linear memory growth triggers OS-level OOM kills of shared Envoy worker threads, inducing cascading ingress failures across co-located tenants. globs: **/envoy-gateway/**/*.yaml, **/envoyextensionpolicy*.yaml, **/envoyfilter*.yaml, **/k8s/**/*.yaml, **/helm/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/envoy-gateway-proxy-wasm-linear-memory-budgeting-guardrail" --- # Envoy Gateway Proxy-Wasm Linear Memory Budgeting and Runtime Recycling Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Wasm Linear Memory and Indefinite VM Lifecycles Causing Worker Thread Crashes ## System Constraints You are a Principal Engineer enforcing Envoy Gateway Proxy-Wasm Linear Memory Budgeting Guardrails. WebAssembly guest modules compile to linear 64KiB memory pages that dynamically grow via memory.grow instructions. In Envoy's multi-threaded event-driven architecture, an unconstrained Proxy-Wasm filter that experiences memory leaks or unbounded payload buffering will trigger host OOM aborts, terminating the Envoy worker thread and dropping all active TCP streams. You must mandate deterministic memory boundaries, fail-open/fail-closed error isolation, and strict VM lifecycle limits in all EnvoyExtensionPolicy and EnvoyFilter definitions. ## Strict Guidelines - Engineers MUST ALWAYS declare explicit linear memory upper bounds using runtime engine constraints or proxy-wasm memory page ceilings (maximum 512 pages / 32 MiB per VM instance). - Engineers MUST NOT deploy Wasm filters with shared VM contexts (shared runtime) without per-request allocation watermarks and strict buffer limits. - Engineers MUST configure `fail_open: true` on observability/telemetry Wasm filters so guest runtime traps or memory exhaustion do not sever client ingress traffic. - Engineers MUST configure `fail_open: false` with deterministic error responses (HTTP 500/503) exclusively on security-critical Wasm filters (e.g., auth, token verification, body inspection). - Services MUST enable Envoy Wasm VM recycling or request-count limits when using heap-allocating languages (such as Rust or Go/TinyGo) to prevent progressive fragmentation. - Components NEVER buffer unbounded request or response bodies inside Wasm linear memory; maximum streaming chunk sizes MUST be budgeted before buffering headers or payload. ## Bad vs Good Implementations ### EnvoyExtensionPolicy Wasm Memory Cap and Failure Mode Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Wasm filter definition omits memory limits and failure domain isolation. If the guest module executes dynamic allocations without bounds (e.g., buffering a multi-megabyte payload), the linear memory expansion will exceed the process memory ceiling and trigger an immediate Envoy worker crash, dropping all co-located tenant streams. ```yaml # INSECURE: Default unbounded Wasm VM with no memory budgeting or fail-safe isolation apiVersion: gateway.envoyproxy.io/v1alpha1 kind: EnvoyExtensionPolicy metadata: name: noisy-tenant-wasm-filter namespace: ingress-gateway spec: targetRef: group: gateway.networking.k8s.io kind: HTTPRoute name: api-ingress-route wasm: - name: request-transformer code: type: HTTP http: url: https://internal-registry.corp/filters/transformer-v1.wasm # Anti-pattern: Missing fail_open configuration # Anti-pattern: Missing vm_config bounds and max memory limits # Result: Memory leak in guest Wasm crashes Envoy worker thread via host SIGABRT ``` #### Production Standard (Correct) > **Standard**: The configuration specifies failOpen: true to isolate non-critical filter faults from terminating production traffic, pins the artifact via sha256, and budgets linear memory by passing strict page allocations (512 pages = 32 MiB) alongside a bounded buffer and lifecycle request recycling target. ```yaml # SECURE: Hard memory-budgeted Wasm VM with explicit fail-open isolation and recycling apiVersion: gateway.envoyproxy.io/v1alpha1 kind: EnvoyExtensionPolicy metadata: name: bounded-tenant-wasm-filter namespace: ingress-gateway spec: targetRef: group: gateway.networking.k8s.io kind: HTTPRoute name: api-ingress-route wasm: - name: request-transformer failOpen: true code: type: HTTP http: url: https://internal-registry.corp/filters/transformer-v1.wasm sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 config: "@type": type.googleapis.com/google.protobuf.StringValue value: |- { "max_buffer_bytes": 1048576, "max_memory_pages": 512, "recycle_after_requests": 100000 } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Envoy Gateway Proxy-Wasm Linear Memory Budgeting and Runtime Recycling Guardrail

Envoy Gateway Proxy-Wasm Linear Memory Budgeting and Runtime Recycling Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces strict WebAssembly (Wasm) linear memory limits, max page allocations, and instance lifecycle recycling across Envoy Gateway extension filters. Unbounded Wasm linear memory growth triggers OS-level OOM kills of shared Envoy worker threads, inducing cascading ingress failures across co-located tenants. 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: Unbounded Wasm Linear Memory and Indefinite VM Lifecycles Causing Worker Thread Crashes 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	Unbounded Wasm Linear Memory and Indefinite VM Lifecycles Causing Worker Thread Crashes	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 declare explicit linear memory upper bounds using runtime engine constraints or proxy-wasm memory page ceilings (maximum 512 pages / 32 MiB per VM instance).

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.