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

higress-helm

Skill4 starsChanged 5 months agoMITView on GitHub

Deploy, configure, or upgrade Higress AI Gateway on Kubernetes via Helm chart. Covers Gateways, plugins, Ingress/CRD routing, observability, and production patterns.

  • Reads credentials

The file

Files
SKILL.md

Higress — Helm Chart

Repo: https://higress.io/helm-charts
Charts: higress, higress-core, higress-console
Latest: 2.2.2
Images: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/ (hub)

Quick Install

helm repo add higress.io https://higress.io/helm-charts
helm repo update

helm install higress higress.io/higress \
  -n higress-system --create-namespace

Minimal Gateway-Only

helm install higress higress.io/higress -n higress-system \
  --create-namespace \
  --set global.o11y.enabled=false \
  --set controller.replicas=1 \
  --set gateway.replicas=2

Charts Overview

higress (umbrella)

Deploys everything: higress-core + higress-console + optional o11y stack.

Sub-componentChartEnabled by default
Gateway + Controller + Pilothigress-core✅
Web UI Consolehigress-console✅
Redis (AI caching, rate limiting)included❌ (global.enableRedis)
Grafana + Prometheus + Lokiincluded❌ (global.o11y.enabled)
Plugin Serverincluded❌ (global.enablePluginServer)

higress-core

Core engine only: controller, gateway, pilot, optional Redis.

higress-console

Web UI dashboard only (requires higress-core for backend).

Global Configuration

ParameterDefaultDescription
global.hubhigress-registry.cn-hangzhou.cr.aliyuncs.comImage registry
global.imagePullPolicy""Image pull policy
global.imagePullSecrets[]Image pull secrets
global.ingressClasshigressIngressClass to watch
global.watchNamespace""Restrict to single namespace
global.enableH3falseEnable HTTP/3 (QUIC)
global.enableIPv6falseEnable IPv6
global.enableProxyProtocolfalseProxy protocol
global.enableRedisfalseDeploy Redis for AI caching
global.enablePluginServerfalseDeploy Wasm plugin server
global.enableIstioAPItrueWatch Istio CRDs
global.enableGatewayAPItrueWatch Gateway API CRDs
global.enableInferenceExtensionfalseGateway API Inference Extension
global.enableStatustrueUpdate Ingress status field
global.localfalseLocal/kind cluster mode
global.o11y.enabledfalseDeploy observability stack
global.logging.leveldefault:infoLog level
global.defaultResources{cpu: 10m}Default resource requests
global.priorityClassName""Priority class
global.multiCluster.enabledtrueMulti-cluster support
global.multiCluster.clusterName""Cluster name

Gateway

ParameterDefaultDescription
gateway.namehigress-gatewayGateway deployment name
gateway.replicas2Pod count
gateway.kindDeploymentDeployment or DaemonSet
gateway.imagegatewayImage name (hub/gateway)
gateway.tag"" (chart appVersion)Image tag
gateway.httpPort80HTTP port
gateway.httpsPort443HTTPS port
gateway.hostNetworkfalseHost networking
gateway.service.typeLoadBalancerService type (None disables)
gateway.service.loadBalancerIP""Static LB IP
gateway.service.loadBalancerClass""LB class
gateway.service.loadBalancerSourceRanges[]LB source ranges
gateway.service.externalTrafficPolicy""External traffic policy
gateway.autoscaling.enabledfalseHPA
gateway.autoscaling.minReplicas1HPA min
gateway.autoscaling.maxReplicas5HPA max
gateway.resources{cpu: 2, mem: 2Gi}Container resources
gateway.metrics.enabledfalsePodMonitor/VMPodScrape
gateway.metrics.providermonitoring.coreos.comCRD provider
gateway.metrics.podMonitorSelector{release: kube-prome}PodMonitor selector
gateway.rollingMaxSurge100%Rolling update max surge
gateway.rollingMaxUnavailable25%Rolling update max unavailable
gateway.nodeSelector{}Node selector
gateway.tolerations[]Tolerations
gateway.affinity{}Affinity
gateway.topologySpreadConstraints[]Topology spread
gateway.automaticHttps.enabledtrueLet's Encrypt auto HTTPS
gateway.automaticHttps.email""Let's Encrypt email

Controller

ParameterDefaultDescription
controller.namehigress-controllerController deployment name
controller.replicas1Pod count
controller.imagehigressImage name (hub/higress)
controller.tag""Image tag
controller.service.typeClusterIPService type
controller.resources{cpu: 500m/1, mem: 2Gi}Resource requests/limits
controller.autoscaling.enabledfalseHPA
controller.autoscaling.minReplicas1HPA min
controller.autoscaling.maxReplicas5HPA max
controller.automaticHttps.enabledtrueAuto HTTPS
controller.automaticHttps.email""Let's Encrypt email
controller.nodeSelector{}Node selector
controller.tolerations[]Tolerations
controller.affinity{}Affinity

Pilot (Istiod)

ParameterDefaultDescription
pilot.imagepilotImage name (hub/pilot)
pilot.tag""Image tag
pilot.traceSampling1.0Trace sampling rate
pilot.resources{cpu: 500m, mem: 2Gi}Resources
pilot.env.PILOT_ENABLE_METADATA_EXCHANGEfalseDisable metadata exchange
pilot.keepaliveMaxServerConnectionAge30mxDS max connection age

Redis (Optional)

ParameterDefaultDescription
redis.redis.nameredis-stack-serverRedis deployment
redis.redis.imageredis-stack-serverImage name
redis.redis.tag7.4.0-v3Image tag
redis.redis.replicas1Replicas
redis.redis.password""Password (empty = none)
redis.redis.service.port6379Service port
redis.redis.persistence.enabledfalseEnable PVC
redis.redis.persistence.size1GiPVC size

Plugin Server (Optional)

ParameterDefaultDescription
pluginServer.namehigress-plugin-serverPlugin server name
pluginServer.replicas2Pod count
pluginServer.imageplugin-serverImage name
pluginServer.tag""Image tag
pluginServer.service.port80Service port
pluginServer.resources{cpu: 200m/500m, mem: 128Mi/256Mi}Resources

Console (UI)

ParameterDefaultDescription
image.repositoryhigress/consoleConsole image
image.tag""Image tag
replicaCount1Replicas
service.port8080Service port
ingress.enabledfalseExpose via Ingress
ingress.domainconsole.higress.ioConsole domain
ingress.tlsSecretName""TLS secret
admin.usernameadminAdmin user
admin.password""Admin password
chat.enabledfalseAI chat in console
chat.endpoint""Chat API endpoint

O11y (Observability)

ParameterDefaultDescription
global.o11y.enabledfalseEnable all o11y
global.o11y.grafana.replicas1Grafana replicas
global.o11y.grafana.storage1GiGrafana PVC
global.o11y.prometheus.replicas1Prometheus replicas
global.o11y.prometheus.storage1GiPrometheus PVC
global.o11y.loki.replicas1Loki replicas
global.o11y.loki.storage1GiLoki PVC

Production Values Example

global:
  ingressClass: higress
  enableGatewayAPI: true
  enableIstioAPI: true
  enableRedis: true
  enablePluginServer: true
  o11y:
    enabled: true
  priorityClassName: system-cluster-critical

gateway:
  replicas: 3
  kind: Deployment
  service:
    type: LoadBalancer
    externalTrafficPolicy: Local
  resources:
    requests:
      cpu: 2
      memory: 2Gi
    limits:
      cpu: 4
      memory: 4Gi
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 80
  metrics:
    enabled: true
    provider: monitoring.coreos.com
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - higress-gateway
          topologyKey: kubernetes.io/hostname

controller:
  replicas: 2
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2
      memory: 4Gi
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5

redis:
  redis:
    persistence:
      enabled: true
      size: 10Gi
      storageClass: ssd

IngressClass Configuration

global:
  ingressClass: higress  # default

  # Special: watch nginx Ingress resources (migration mode)
  # ingressClass: nginx
  # - watches both "nginx" class AND no-class Ingress resources
  # - enables smooth migration from ingress-nginx

  # Special: watch all Ingress resources
  # ingressClass: ""

Gateway API Integration

helm install higress higress.io/higress -n higress-system \
  --set global.enableGatewayAPI=true

Requires Gateway API CRDs installed:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

AI Gateway + Redis

helm install higress higress.io/higress -n higress-system \
  --set global.enableRedis=true \
  --set global.enablePluginServer=true

Upgrading

helm repo update
helm upgrade higress higress.io/higress -n higress-system \
  --values values.yaml \
  --version 2.2.2

Uninstalling

helm uninstall higress -n higress-system
kubectl delete namespace higress-system

Note: CRDs persist after uninstall. Remove manually:

kubectl delete crd wasmplugins.extensions.higress.io
kubectl delete crd http2rpcs.networking.higress.io
kubectl delete crd mcpbridges.networking.higress.io

Common Mistakes

  • Hub region — Default hub is in China (cn-hangzhou). Use us-west-1.cr.aliyuncs.com for NA, ap-southeast-7.cr.aliyuncs.com for SEA. Set global.hub before install.
  • Gateway API CRDs missing — Setting global.enableGatewayAPI=true without installing Gateway API CRDs causes controller errors.
  • IngressClass == nginx — Setting ingressClass: nginx makes Higress watch nginx-class Ingresses. Remove or change to higress after migration.
  • Redis for AI features — AI caching, token rate limiting, and quota require global.enableRedis=true. Without Redis, these plugins fail.
  • Plugin Server for OCI plugins — If using url: oci://... in WasmPlugin, ensure global.enablePluginServer=true or have direct OCI registry access.
  • Standalone console ingress — higress-console needs ingress.enabled=true and a domain for external access. Default is ClusterIP only.
  • Gateway metrics — gateway.metrics.enabled=true creates PodMonitor. Requires prometheus-operator or VictoriaMetrics operator CRDs.
  • Controller readiness — Controller uses /ready on port 8888. Ensure network policies allow this.
  • HostNetwork gateway — gateway.hostNetwork=true binds host ports 80/443. Requires host port availability and potential security implications.
  • autoscaling/v2 API — global.autoscalingv2API (default: true) uses autoscaling/v2. If your cluster is older, set to false.
  • alpn h2 — global.disableAlpnH2: false (default) enables HTTP/2 ALPN. Set true if clients don't support HTTP/2.

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.