Higress Operator

Higress — Operator CRDs & Configuration

Repository: github.com/alibaba/higress
Latest: v2.2.2 (May 21, 2026)
CNCF: Sandbox (March 2026)
License: Apache 2.0
Stars: 8.5k

Architecture

Ingress/Gateway API/CRDs → higress-controller (Go) → Istio Pilot → xDS (LDS/RDS/CDS/EDS) → higress-gateway (Envoy + Wasm)

• Control plane: higress-controller (Go) watches K8s resources, converts to Istio config, pushes via xDS
• Data plane: higress-gateway (Envoy-based) handles all traffic, runs Wasm plugins, zero-downtime config reload
• Three ingress interfaces: Standard K8s Ingress, Gateway API, Istio API (all simultaneous)

CRDs (3 custom + 1 bundled)

WasmPlugin — extensions.higress.io/v1alpha1

Extends Envoy with Wasm-based plugins for auth, AI proxy, rate limiting, transformation, etc.

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: ai-proxy
  namespace: higress-system
spec:
  # Plugin source
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/ai-proxy:1.0.0
  sha256: abc123...
  pluginName: ai-proxy
  imagePullPolicy: IfNotPresent
  imagePullSecret: my-registry-cred

  # Plugin configuration (global)
  pluginConfig:
    provider:
      type: openai
      apiTokens:
        - "sk-..."
      modelMapping:
        "gpt-4": "gpt-4o"
      timeout: 120000

  # Default config (applied when no matchRules match)
  defaultConfig: {}
  defaultConfigDisable: false

  # Failure behavior
  failStrategy: FAIL_CLOSE  # FAIL_CLOSE | FAIL_OPEN

  # Position in filter chain
  phase: AUTHN  # UNSPECIFIED_PHASE | AUTHN | AUTHZ | STATS
  priority: 100

  # Wasm VM config
  vmConfig:
    env:
      - name: LOG_LEVEL
        value: debug

  # Per-route overrides
  matchRules:
    - domain:
        - "api.example.com"
      config:
        provider:
          type: openai
          apiTokens:
            - "sk-another-token"
      configDisable: false
    - ingress:
        - "my-ingress"
      routeType: HTTP
      configDisable: true
    - service:
        - "llm-service.default.svc"
      config:
        provider:
          type: anthropic

Spec Fields

MatchRule fields:

Http2Rpc — networking.higress.io/v1

Maps HTTP endpoints to Dubbo or gRPC services.

apiVersion: networking.higress.io/v1
kind: Http2Rpc
metadata:
  name: dubbo-user-service
spec:
  # Dubbo destination (oneOf: dubbo XOR grpc)
  dubbo:
    service: com.example.UserService
    version: 1.0.0
    group: prod
    methods:
      - serviceMethod: getUserById
        httpPath: /api/users/:id
        httpMethods:
          - GET
        headersAttach: x-request-id
        params:
          - paramSource: URL_PATH
            paramKey: id
            paramType: java.lang.Long
      - serviceMethod: createUser
        httpPath: /api/users
        httpMethods:
          - POST
        paramFromEntireBody:
          paramType: com.example.User

  # OR gRPC destination (alternative to dubbo):
  # grpc:
  #   proto_descriptor_str: "...base64..."
  #   proto_descriptor_file_path: /etc/proto/user.pb
  #   services:
  #     - com.example.UserService

Spec Fields

McpBridge — networking.higress.io/v1

Multi-registry service discovery for integrating external service registries.

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: default
  namespace: higress-system
spec:
  registries:
    # Nacos 2.x (gRPC)
    - type: nacos2
      name: my-nacos
      domain: nacos.example.com
      port: 8848
      protocol: HTTP
      nacosNamespaceId: public
      nacosGroups:
        - DEFAULT_GROUP
      nacosRefreshInterval: 5000

    # Nacos 3.x (MCP auto-discovery)
    - type: nacos3
      name: nacos-mcp
      domain: nacos3.example.com
      port: 8848
      enableMCPServer: true

    # ZooKeeper
    - type: zookeeper
      name: my-zk
      domain: zk.example.com
      port: 2181
      zkServicesPath:
        - /dubbo

    # Consul
    - type: consul
      name: my-consul
      domain: consul.example.com
      port: 8500
      consulDatacenter: dc1
      consulServiceTag: prod

    # Static/DNS
    - type: static
      name: static-backends
      domain: backend.example.com
      port: 8080

  proxies:
    - type: http_connect
      name: corporate-proxy
      serverAddress: proxy.example.com
      serverPort: 3128
      listenerPort: 80
      connectTimeout: 5000

Spec Fields

Registry fields:

Proxy fields:

EnvoyFilter — networking.istio.io/v1alpha3

Bundled Istio CRD for low-level Envoy filter chain patching.

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: custom-filter
  namespace: higress-system
spec:
  configPatches:
    - applyTo: HTTP_FILTER
      match:
        context: GATEWAY
        listener:
          filterChain:
            filter:
              name: envoy.filters.network.http_connection_manager
              subFilter:
                name: envoy.filters.http.router
      patch:
        operation: INSERT_BEFORE
        value:
          name: envoy.filters.http.lua
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
            inline_code: |
              function envoy_on_request(request_handle)
                -- custom logic
              end

Wasm Plugin System

Plugin Categories (41 built-in)

Plugin Languages

• Go (69 plugins) — primary, via TinyGo + wasm-go SDK
• Rust (5), C++, AssemblyScript

Plugin Loading

• OCI images: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/<name>:<version>
• HTTP distribution: via plugin-server
• SDK: github.com/higress-group/wasm-go

WasmPlugin AI Proxy Example

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: ai-proxy-openai
spec:
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/ai-proxy:1.0.0
  pluginConfig:
    provider:
      type: openai
      apiTokens:
        - "sk-..."
      modelMapping:
        "gpt-4": "gpt-4o"
      timeout: 120000
      protocol: openai  # or "original" for native provider protocol

AI Gateway Provider Options

Common WasmPlugin Patterns

Rate Limiting:

spec:
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/key-rate-limit:1.0.0
  pluginConfig:
    limit: 100
    window_size: 60
    key_source: X-Forwarded-For

JWT Auth:

spec:
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/jwt-auth:1.0.0
  pluginConfig:
    consumers:
      - name: myapp
        credential: myapp-secret
        iss: https://auth.example.com

CORS:

spec:
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/cors:1.0.0
  pluginConfig:
    allow_origins: "https://app.example.com"
    allow_methods: "GET,POST,PUT,DELETE"
    allow_headers: "Content-Type,Authorization"
    expose_headers: "X-Custom-Header"
    max_age: 3600

Common Mistakes

• No short names defined — WasmPlugin/Http2Rpc/McpBridge have no kubectl short names. Use full plural: kubectl get wasmplugins, kubectl get http2rpcs, kubectl get mcpbridges.
• WasmPlugin url without OCI — Only oci:// and http:// schemes supported. Don't use docker://.
• Image pull secret — Private OCI registries need imagePullSecret referencing a secret in the same namespace.
• Phase ordering — Plugins run in order: AUTHN → AUTHZ → STATS. Within same phase, lower priority runs first.
• matchRules overlap — If multiple rules match, first match wins. Order domain → ingress → service by priority.
• Dubbo version required — dubbo.version is required even if not used by the target service.
• McpBridge registry name — Each registry in registries[] must have a unique name.
• Nacos namespace — Use nacosNamespaceId (not nacosNamespace which is legacy) for Nacos multi-tenant.
• EnvoyFilter complexity — EnvoyFilter patches are powerful but break on Envoy version upgrades. Prefer WasmPlugin when possible.
• Gateway API mutual exclusion — When both Ingress and Gateway API define the same route, Gateway API takes precedence.
• Fail strategy — FAIL_CLOSE blocks traffic on plugin error. FAIL_OPEN passes through. Use FAIL_CLOSE for auth, FAIL_OPEN for observability.