Kubernetes Higress 安装与测试文档

本文档介绍如何在 Kubernetes 集群中使用 Helm 以 HostNetwork + DaemonSet 模式部署 Higress，并通过一个简单的 Nginx 应用验证路由是否生效。文档整体结构参考现有 Nginx Ingress Controller 安装文档，但安装方式切换为 Higress 官方 Helm Chart，适用于裸机和自建 Kubernetes 集群场景。

零、安装 Helm（如已安装可跳过）

在部署 Higress 之前，需要确保主控节点上已经安装了 Helm 工具。

# 下载安装脚本
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3

# 赋予执行权限
chmod 700 get_helm.sh

# 执行安装
./get_helm.sh

# 验证安装是否成功
helm version

一、准备 Helm 仓库

1. 添加官方仓库并更新

# 添加 Higress 官方 Helm 仓库
helm repo add higress.io https://higress.io/helm-charts

# 更新本地仓库缓存
helm repo update

# 查看可用 chart 版本
helm search repo higress.io/higress -l

2. 说明

Higress 官方 Helm Chart 默认即可直接安装，不需要像 ingress-nginx 那样单独下载 Chart 包再解压处理。
另外，Higress 官方镜像使用独立镜像仓库，通常不受 Docker Hub 访问限制影响。

二、部署模式说明

Higress 安装完成后，数据面组件是 higress-gateway，控制面组件是 higress-controller。

本文档统一采用 HostNetwork + DaemonSet 模式部署，适用于不支持 LoadBalancer 的裸机集群，让 Higress 直接监听节点上的 80/443 端口。

如果你当前是三台物理机自建 Kubernetes 集群，这种方式通常比 LoadBalancer 模式更直接，也更符合实际使用场景。

三、安装 Higress

HostNetwork + DaemonSet 安装

建议使用以下方式部署：

cat > higress-values.yaml <<'EOF'
global:
  ingressClass: higress

higress-core:
  gateway:
    kind: DaemonSet
    hostNetwork: true
EOF

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

卸载命令

如果之前安装失败，可以先执行卸载：

helm uninstall higress -n higress-system

四、检查 Higress 运行状态

1. 查看 Pod 状态

kubectl get pods -n higress-system

正常情况下，应该至少看到以下组件处于 Running 状态：

  • higress-controller
  • higress-gateway

2. 查看 Service

kubectl get svc -n higress-system

说明：即使采用 HostNetwork + DaemonSet 模式，集群中仍然会创建 higress-gateway 对应的 Service，用于集群内部发现；对外访问仍以节点 IP 的 80/443 端口为主。

3. 查看 IngressClass

kubectl get ingressclass

正常情况下会看到 higress 这个 IngressClass。

4. 查看 Higress 监听方式

由于本文档采用的是 HostNetwork + DaemonSet 模式，因此可以直接使用运行 Higress Gateway 的节点 IP，通过 80/443 端口访问。

例如：

kubectl get pods -n higress-system -o wide

五、部署测试应用

部署一个简单的 Nginx 网页服务，并为其创建 Service 和 Ingress 路由规则。

1. 创建部署文件 my-nginx.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx:latest
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    run: my-nginx
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: higress
  rules:
  - host: test.higress.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 8080

2. 应用配置

kubectl apply -f my-nginx.yaml

3. 查看资源状态

kubectl get pod,svc,ingress

六、验证访问

1. 检查 Ingress 是否被 Higress 接管

kubectl describe ingress example-ingress

重点确认以下内容：

  • Ingress Class 为 higress
  • 规则中的 Host 为 test.higress.com
  • 后端 Service 为 nginx-service:8080

2. 通过节点 IP 测试访问

可以直接把域名解析到任意一台运行 higress-gateway 的节点 IP，然后发起请求：

curl -H "Host: test.higress.com" http://<运行Higress的Node_IP>

或者先在本机 /etc/hosts 中添加：

<运行Higress的Node_IP> test.higress.com

然后直接访问：

curl http://test.higress.com

如果返回了标准的 Nginx 欢迎页面（Welcome to nginx!），则说明 Higress 已经成功接管 Ingress 并完成转发。

七、常用排查命令

1. 查看 Higress 相关资源

kubectl get all -n higress-system

2. 查看网关日志

kubectl logs -n higress-system "$(kubectl get pods -n higress-system | awk '/higress-gateway/ {print $1; exit}')" --tail=100

3. 查看控制器日志

kubectl logs -n higress-system "$(kubectl get pods -n higress-system | awk '/higress-controller/ {print $1; exit}')" --tail=100

4. 查看测试应用日志

kubectl logs -l run=my-nginx --tail=100

5. 重新安装或升级

helm upgrade higress higress.io/higress \
  -n higress-system \
  --reuse-values

八、补充说明

1. 关于 Ingress 兼容性

Higress 支持作为 Kubernetes Ingress 网关使用，并兼容大量常见的 Nginx Ingress 使用方式。因此，对于已经在使用 Ingress 资源的业务，通常只需要把：

  • ingressClassName 改为 higress

即可完成基础迁移验证。

2. 关于 Gateway API

Higress 除了支持传统 Ingress，也支持 Gateway API。
如果后续你希望从 Ingress 逐步演进到更强的网关模型，可以在安装完成后再启用 Gateway API 支持。

3. 关于 TLS 与证书

如果你已经在集群中部署了 cert-manager，后续可以直接为 Higress 配置 HTTPS 证书，与 Nginx Ingress 的证书使用方式类似。

九、配置与访问管理界面（Higress Console）

Higress 提供了一个官方的可视化管理界面（Higress Console），如果希望通过域名（例如 console.higress.com）直接访问该界面，可以通过以下步骤进行配置：

1. 开启控制台组件

为了在不更改或覆盖之前已有配置的前提下开启控制台，建议在升级时直接使用 --set 指定控制台副本数，并加上 --reuse-values 参数复用历史配置：

helm upgrade higress higress.io/higress \
  -n higress-system \
  --set higress-console.replicaCount=1 \
  --reuse-values

2. 创建 Ingress 路由规则

创建一个名为 console-ingress.yaml 的文件，将域名 console.higress.com 路由到控制台服务：
`

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: higress-console-ingress
  namespace: higress-system
spec:
  ingressClassName: higress
  rules:
  - host: higress.aioil.top
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: higress-console
            port:
              number: 8080

应用该配置：

kubectl apply -f console-ingress.yaml

3. 验证访问

在本机的 /etc/hosts 中添加解析记录，将域名指向运行 Higress Gateway 的节点 IP：

<运行Higress的Node_IP> higress.aioil.top

然后在浏览器中访问 http://higress.aioil.top 即可打开 Higress 管理界面。

十、开启与配置监控（Prometheus + Grafana）

方案 A：使用 Higress 内置监控套件

Higress 官方 Helm Chart 内置了完整的 Prometheus + Grafana 监控套件。如果你希望直接使用这套内置的监控页面，可以通过 Helm 升级来一键开启。

使用 --set global.o11y.enabled=true 参数开启，并复用之前的配置：

helm upgrade higress higress.io/higress \
  -n higress-system \
  --set global.o11y.enabled=true \
  --reuse-values

(注意：如果你的 Kubernetes 集群不支持 ReadWriteMany 的存储类，还需要额外增加 --set global.pvc.rwxSupported=false 参数)

更新完成后，刷新 Higress Console，点击“监控面板”，界面会自动加载内置大盘。

方案 B：对接已有的 kube-prometheus-stack（独立部署监控）

如果你的集群中已经安装了 kube-prometheus-stack，可以直接将 Higress 暴露的监控指标采集到现有的 Prometheus 中，并在 Higress 控制台填入现有的 Grafana 链接。

1. 开启指标暴露并创建 PodMonitor

Higress 的 Helm chart 默认支持创建 PodMonitor。通过复用配置并启用 metrics 选项，将其接入现有的 Prometheus 体系：

helm upgrade higress higress.io/higress \
  -n higress-system \
  --set higress-core.gateway.metrics.enabled=true \
  --set higress-core.gateway.metrics.podMonitorSelector.release="prometheus-stack" \
  --reuse-values

(注意：podMonitorSelector.release 的值需要匹配你集群中 Prometheus 的 podMonitorSelector 标签。)

验证配置是否生效：

升级完成后，你可以通过以下命令确认 PodMonitor 资源是否已经成功创建并打上了正确的标签：

kubectl get podmonitor higress-gateway-metrics -n higress-system --show-labels

如果能看到名为 higress-gateway-metrics 的资源，且 LABELS 列中包含 release=prometheus-stack，说明配置已成功生效，稍等片刻 Prometheus 就会自动发现并抓取它。

如何查看 podMonitorSelector.release 应该填什么？

你可以通过以下命令查看现有的 Prometheus 是如何筛选 PodMonitor 的：

# 假设你的 prometheus 安装在 monitoring 命名空间
kubectl get prometheus -n monitoring -o yaml | grep -A 5 "podMonitorSelector"

如果输出结果类似：

  podMonitorSelector:
    matchLabels:
      release: prometheus-stack

那么上面的 podMonitorSelector.release 就应该填 "prometheus-stack"。如果你当时使用 Helm 安装时的命名不同（比如叫 prom），这里的值就需要相应修改。

提示： 如果命令输出 podMonitorSelector: {}，代表你的 Prometheus 被配置为无条件抓取所有的 PodMonitor。这种情况下，你不需要指定上述的 --set higress-core.gateway.metrics.podMonitorSelector.release=... 参数，直接开启 enabled 即可。

2. 配置 Grafana 允许内嵌显示（关键）

由于 Higress 控制台是通过 iframe 网页内嵌的方式来展示 Grafana 面板的，而 Grafana 默认禁止被其他网站内嵌，因此你必须修改现有的 Grafana 配置。
(注：对于前面提到的 Prometheus relabel_config 提示，由于我们使用了 ServiceMonitor 机制，Prometheus Operator 会自动处理抓取规则，因此无需手动配置 relabel_config)

由于你是通过 kube-prometheus-stack 部署的 Grafana，请通过更新该 Helm release 的 values 来修改配置。新建或修改你的 prometheus-values.yaml 文件，补充以下内容：

grafana:
  grafana.ini:
    security:
      allow_embedding: true
      cookie_samesite: none
      cookie_secure: true

然后执行升级命令。

注意： 升级前，请务必确认你的 kube-prometheus-stack 的真实 Helm release 名称。你可以通过 helm ls -n monitoring 命令查看。假设你的 release 名字叫 prometheus-stack：

helm upgrade prometheus-stack prometheus-community/kube-prometheus-stack -n monitoring -f prometheus-values.yaml --reuse-values

如何验证 Grafana 配置是否生效？

升级完成后，Grafana Pod 会进行重启。你可以通过查看 Grafana 容器内的实际配置文件，或者通过查看环境变量来确认配置是否注入成功：

# 获取 grafana pod 的名称
GRAFANA_POD=$(kubectl get pods -n monitoring -l app.kubernetes.io/name=grafana -o jsonpath="{.items[0].metadata.name}")

# 方式一：查看容器内生成的 grafana.ini 配置文件
kubectl exec -it $GRAFANA_POD -n monitoring -- grep -A 5 "\[security\]" /etc/grafana/grafana.ini

# 方式二：查看 Grafana 进程加载的环境变量
kubectl exec -it $GRAFANA_POD -n monitoring -- env | grep GF_SECURITY

如果输出中包含了 allow_embedding = true（或对应的环境变量 GF_SECURITY_ALLOW_EMBEDDING=true），则说明配置已成功生效。

3. 获取 Prometheus 数据源 UID 并导入大盘

由于 Grafana 在展示大盘时需要知道去哪里查数据，Higress 控制台会提示你填写 “Prometheus 数据源 UID” 以生成匹配你环境的大盘 JSON。请按以下步骤操作：

  1. 获取数据源 UID：

    • 登录你集群中独立的 Grafana 界面。
    • 在左侧导航栏找到 Connections (连接) -> Data sources (数据源)。
    • 点击列表中的 Prometheus 数据源进入编辑页面。
    • 观察此时浏览器的地址栏 URL，格式通常为 http://<grafana-ip>/connections/datasources/edit/<UID>。
    • 浏览器地址栏中最后的这一段就是该数据源的 UID。对于 kube-prometheus-stack 用户，该 UID 通常就是单词 prometheus。

  2. 生成并导入 JSON 配置：

    • 回到 Higress 控制台，将刚才找到的 UID 填入“Prometheus 数据源 UID”输入框中。
    • 选择适合你的配置模板（见下方说明），点击下载或复制配置。
    • 再次回到 Grafana，在左侧导航栏点击 Dashboards (大盘) -> 右上角点击 New (新建) -> Import (导入)。
    • 将复制的 JSON 内容粘贴进 “Import via panel json” 文本框中（或上传下载的 JSON 文件），点击 Load，然后保存。

    配置模板说明：

    • 通用网关监控模板：适用于传统的微服务路由、API 转发场景，包含 QPS、延迟、HTTP 状态码分布、请求大小等标准网关流量指标。如果你主要是做普通的请求转发，请选择这个模板。
    • AI 网关监控模板：专为 Higress 的 AI 代理插件（如对接大模型 API）设计的监控面板。除了包含基础指标外，还会额外展示 AI 相关的业务指标，比如大模型的 Token 消耗量、Token 生成速率、AI 请求的专属延迟等。如果你使用 Higress 代理了 LLM 大模型流量，请选择这个模板。

  3. 获取大盘 URL：

    • 导入成功后，Grafana 会打开这个全新的 Higress 监控面板。
    • 复制浏览器地址栏中的完整 URL，这就是后续要在 Higress 里内嵌的地址。

4. 在 Higress 控制台中完成关联

  1. 回到 Higress Console 的 “监控面板”。
  2. 在界面上方最主要的“监控面板 URL”输入框中，填入刚才复制的完整 Grafana 大盘 URL（注意：必须确保你在访问 Higress 控制台的浏览器里，也能直接访问到这个 Grafana URL）。
  3. 点击保存，控制台会自动刷新，并将外部的 Grafana 页面完美内嵌显示在右侧。后续如需修改，点击左上角的“重新配置”即可。

5. 修复官方大盘无数据问题（必做）

在部分 Kubernetes 环境下，由于底层监控组件（如 cAdvisor）上报指标时的标签差异，导入官方大盘后可能会遇到左上角变量下拉框为空，以及 CPU/Memory 图表显示 No Data 的情况。请按照以下步骤手动修复大盘配置：

步骤一：修复左上角变量下拉框为空

  1. 在 Grafana 大盘页面右上角，点击 Edit（编辑模式图标）。
  2. 点击顶部的 齿轮图标（Dashboard settings），然后在左侧菜单选择 Variables。
  3. 修改 namespace 变量：
    • 点击进入 namespace，将其 Type（类型）从 Query 修改为 Custom。
    • 在 Values separated by comma 中输入：higress-system。
    • 点击底部的 Apply。
  4. 修改 gateway 变量（可选）：
    • 由于接下来我们将直接修改图表的查询语句，这个变量的值不再重要。你可以将其保留为默认的 Custom 并随意填入一个值，或者直接将其删除。

步骤二：修复图表显示 N/A 或 No Data（终极解决方案）
如果你确认底层指标存在，但图表仍然显示 N/A 或 No Data，这是因为官方大盘默认使用的 higress="$gateway" 标签在标准的 Helm 部署中可能不存在。

由于大盘中包含大量图表，手动逐一修改非常繁琐，强烈建议使用 JSON Model 进行批量替换：

  1. 进入大盘源码：在 Grafana 大盘页面右上角点击 Edit，然后点击顶部的 齿轮图标（Dashboard settings），在左侧菜单点击底部的 JSON Model。
  2. 复制配置：将右侧巨大的 JSON 文本全部复制，粘贴到一个本地文本编辑器中。
  3. 全局查找并替换：
    • 查找内容：higress=\"$gateway\"
    • 替换为：namespace=\"higress-system\"
      (这样既删除了不存在的标签限制，又确保了只统计 higress 命名空间下的流量，避免与其他 Envoy 网关冲突。)
  4. 粘贴并保存：将替换后的完整 JSON 复制回 Grafana 的 JSON Model 输入框中，覆盖原有内容，然后点击左下角的 Save Changes。

对于 CPU 和 Memory 图表：
如果在上述替换后，CPU 和内存图表仍显示 No Data，请在刚才的 JSON 中或者图表编辑页，将 container="higress-gateway" 替换为与你实际抓取到的指标相符的容器标签（如果不确定，可以直接删除 container 标签过滤）。

全部修改完成后，在终端中执行 curl http://test.higress.com 制造一些流量，所有图表即可完美展示！

# kubernetes # 容器 # 云原生
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

3分钟掌握Codex技能安装：一键部署你的AI助手工具库

想要为你的Codex AI助手安装新技能？不用再手动复制文件了！skill-installer为你提供了一套完整的解决方案，让你能够从GitHub仓库快速获取和安装各种实用的Codex技能。无论你是AI开发新手还是经验丰富的开发者，这个工具都能让你在几分钟内扩展Codex的功能边界。## 为什么选择skill-installer？ 🤔在AI辅助编程的时代，Codex技能已经成为提升开发效

avatar AI编程社区

DB-GPT分布式AI数据引擎：企业级智能分析平台架构解析

DB-GPT作为新一代AI数据助手，通过分布式架构和智能代理引擎重构了传统数据分析范式。该平台将大型语言模型的自然语言理解能力与企业级数据处理需求深度融合，构建了面向生产环境的可扩展AI数据平台。其核心价值在于将复杂的SQL生成、数据分析和可视化任务转化为简单的自然语言交互，同时确保系统安全性、可追溯性和企业级可靠性。## 技术定位与生态分析在当前数据智能生态中，DB-GPT填补了传统BI

avatar AI编程社区

如何用Awesome Claude Skills将AI助手打造成你的全能创作伙伴和职业顾问

你是否曾想过，如果有一个AI伙伴能帮你完成从专业文章撰写到完美简历定制的所有工作，工作效率会提升多少倍？Awesome Claude Skills正是这样一个神奇的AI技能宝库，它汇集了1000+个精心筛选的Claude技能，覆盖内容创作、职业发展、文档处理等各个方面，让你在AI的帮助下轻松应对各种工作挑战。## 痛点分析：传统工作流程的三大瓶颈在内容创作和职业发展中，我们常常面临这样的困

avatar AI编程社区