Getting Started with Higress: A Cloud‑Native AI‑Powered API Gateway

Overview

Higress is an open‑source, cloud‑native API gateway built on Istio and Envoy. It adds AI‑oriented capabilities such as OpenAI‑compatible protocol support, prompt rewriting and semantic traffic understanding.

Architecture

Higress consists of three core components:

higress-console – a visual management UI (Node.js front‑end, Java SpringBoot back‑end) built with ICE.

higress-controller – watches the Kubernetes API server, converts Ingress and Higress CRDs into Istio API objects and generates xDS configuration for Envoy.

higress-gateway – embeds Envoy to forward data‑plane traffic.

All configuration is stored as Custom Resource Definitions (CRDs) in the Kubernetes etcd store; no external database is required.

Installation

Higress can be installed on any standard Kubernetes cluster with Helm. A minimal installation uses two commands:

helm repo add higress.io https://higress.cn/helm-charts
helm install higress -n higress-system higress.io/higress --create-namespace --render-subchart-notes

For local testing (e.g., Kind clusters) add the flag --set global.local=true to enable local‑mode settings.

Component Details

higress‑controller

The controller runs two containers:

higress‑core – watches the Kubernetes API, translates Ingress and Higress CRDs into Istio API objects.

pilot – a fork of Istio’s istiod pilot module that converts Istio API objects into xDS resources and pushes them to the Envoy data plane.

Build the controller binary from source with:

make build

higress‑gateway

The gateway component embeds an Envoy proxy. It receives the xDS configuration generated by the controller and performs actual request forwarding. Direct modification of the Envoy binary is rarely needed.

higress‑console

The console provides a UI for managing CRDs, visualizing traffic policies and monitoring metrics. The back‑end is a SpringBoot service; the front‑end is a Node.js application built with ICE.

Plugin Development

Higress supports extensible Wasm plugins written in Go, Rust or JavaScript. Plugins are stored under the repository https://github.com/alibaba/higress/tree/main/plugins. Core AI plugins such as ai‑proxy and ai‑token‑ratelimit demonstrate traffic governance for large‑language‑model services. To develop a new plugin, compile it to a Wasm module and reference it in a Higress CRD.

Contribution Guide

Typical contribution workflow:

Fork the target repository (e.g., https://github.com/higress-group/higress-console).

Add the upstream remote and synchronize with the main branch:

git remote add upstream https://github.com/alibaba/higress.git
git fetch upstream
git rebase upstream/main
git checkout -b my_feature_branch

Implement changes, commit, and push the branch.

Open a Pull Request against the upstream repository and follow the review process.

Issues can be used to report bugs, request features, or discuss design decisions. Claim an issue by commenting first to avoid duplicate effort.

Key Repository URLs

Console source: https://github.com/higress-group/higress-console Controller and gateway source: https://github.com/alibaba/higress Helm charts:

https://github.com/alibaba/higress/tree/main/helm

References

Official documentation and quick‑start guides are hosted at https://higress.cn/docs/latest/. The project’s GitHub organization is https://github.com/alibaba/higress.