agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/higress-operator/SKILL.md

higress-operator

Skill4 starsChanged 5 months agoMITView on GitHub

Create and manage Higress CRDs — WasmPlugin, Http2Rpc, McpBridge, AI Gateway, 41 Wasm plugins, 16 AI provider integrations, and Gateway configuration.

  • Reads credentials

The file

Files
SKILL.md

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)

CRDAPI VersionKindShort NamesPurpose
WasmPluginextensions.higress.io/v1alpha1WasmPlugin—Wasm plugin lifecycle & config
Http2Rpcnetworking.higress.io/v1Http2Rpc—HTTP-to-RPC (Dubbo/gRPC) mapping
McpBridgenetworking.higress.io/v1McpBridge—Multi-registry service discovery
EnvoyFilternetworking.istio.io/v1alpha3EnvoyFilter—Envoy filter chain patching (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

FieldTypeDefaultDescription
urlstring—Wasm module URL (oci://..., http://...)
sha256string—SHA256 checksum
pluginNamestring—Plugin name
pluginConfigobject—Plugin config (pass-through to plugin)
defaultConfigobject{}Default config for unmatched routes
defaultConfigDisableboolfalseDisable plugin by default
failStrategyenumFAIL_CLOSEFAIL_CLOSE or FAIL_OPEN
phaseenum—UNSPECIFIED_PHASE, AUTHN, AUTHZ, STATS
priorityint—Ordering within same phase
imagePullPolicyenum—UNSPECIFIED_POLICY, IfNotPresent, Always
imagePullSecretstring—OCI pull secret name
verificationKeystring—Plugin signature verification key
vmConfig.env[]EnvVar—Wasm VM environment variables
matchRules[][]MatchRule—Per-route config overrides

MatchRule fields:

FieldTypeDescription
domain[][]stringMatch by domain name
ingress[][]stringMatch by Ingress resource name
service[][]stringMatch by K8s service name
routeTypeenumHTTP or GRPC
configobjectPlugin config for this rule
configDisableboolDisable plugin for this rule

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

FieldTypeRequiredDescription
dubbo.servicestringoneOfDubbo service interface
dubbo.versionstring✅Dubbo service version
dubbo.groupstring❌Dubbo service group
dubbo.methods[].serviceMethodstring✅Dubbo method name
dubbo.methods[].httpPathstring✅HTTP path to map
dubbo.methods[].httpMethods[][]string✅Allowed HTTP methods
dubbo.methods[].headersAttachstring❌Headers to propagate
dubbo.methods[].params[].paramSourcestring✅URL_PATH, URL_QUERY, REQUEST_HEADER
dubbo.methods[].params[].paramKeystring✅Parameter key name
dubbo.methods[].params[].paramTypestring✅Java type (e.g. java.lang.Long)
dubbo.methods[].paramFromEntireBody.paramTypestring❌Use entire body as param
grpc.proto_descriptor_strstringoneOfInline protobuf descriptor
grpc.proto_descriptor_file_pathstring❌Path to proto descriptor file
grpc.services[][]string✅gRPC service names

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

FieldTypeDescription
registries[][]RegistryService registry configurations

Registry fields:

FieldTypeDescription
typestringnacos2, nacos3, nacos, zookeeper, consul, eureka, static, dns
namestringRegistry name
domainstringRegistry host
portintRegistry port
protocolstringHTTP or HTTPS
snistringSNI for TLS
nacosNamespaceIdstringNacos namespace ID
nacosGroups[]stringNacos groups
nacosAccessKeystringNacos auth key
nacosSecretKeystringNacos auth secret
nacosAddressServerstringNacos address server
nacosRefreshIntervalintRefresh interval (ms)
zkServicesPath[]stringZooKeeper service paths
consulDatacenterstringConsul datacenter
consulNamespacestringConsul namespace
consulServiceTagstringConsul service tag
consulRefreshIntervalintRefresh interval (ms)
authSecretNamestringSecret name for registry auth
enableMCPServerboolEnable MCP server for Nacos 3.x
allowMcpServers[]stringAllowed MCP server addresses
mcpServerBaseUrlstringMCP server base URL
mcpServerExportDomains[]stringDomains to export via MCP
enableScopeMcpServersboolScope MCP servers
vport.defaultintDefault virtual port
vport.services[]objectPer-service vport overrides
metadatamapExtra metadata
proxyNamestringProxy name

Proxy fields:

FieldTypeDescription
typestringhttp_connect
namestringProxy name
serverAddressstringProxy server address
serverPortintProxy server port
listenerPortintLocal listener port
connectTimeoutintConnection timeout (ms)

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)

CategoryPluginsCount
AIai-proxy, ai-cache, ai-token-ratelimit, ai-quota, ai-security-guard, ai-statistics, ai-rag, ai-search, ai-agent, ai-transformer, ai-prompt-template, ai-prompt-decorator, ai-intent, ai-history, ai-json-resp, ai-data-masking, ai-load-balancer, ai-image-reader, model-mapper, model-router, mcp-router, mcp-server, chatgpt-proxy23
Authbasic-auth, key-auth, hmac-auth, hmac-auth-apisix, jwt-auth, simple-jwt-auth, oauth/oidc, ext-auth, opa9
Securitywaf, bot-detect, cors, ip-restriction, request-block, replay-protection6
Trafficcluster-key-rate-limit, key-rate-limit, request-validation, traffic-tag, traffic-editor, response-cache6
Transformationtransformer, custom-response, cache-control, de-graphql, frontend-gray, nginx-rewrite-compatible6

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

Providertype valueAuth Method
OpenAIopenaiapiTokens[]
Azure OpenAIazureapiTokens[]
Anthropic ClaudeclaudeapiTokens[]
Google GeminigeminiapiTokens[]
AWS Bedrockaws-bedrockIAM (env)
DeepSeekdeepseekapiTokens[]
MoonshotmoonshotapiTokens[]
Qwen (Tongyi)qwenapiTokens[]
Alibaba BailianbailianapiTokens[]
DoubaodoubaoapiTokens[]
Spark (Xunfei)sparkapiTokens[]
Cloudflare Workers AIcloudflareapiTokens[]
Together AItogetherapiTokens[]
OpenRouteropenrouterapiTokens[]
MistralmistralapiTokens[]
NVIDIA Tritonnvidia-triton—

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.