Helm Chart

APISIX 和 API7 Ingress Controller 都可以通过 Helm Chart 部署。二者使用不同的 Chart，并具有不同的配置项和部署方式。

已发布版本

产品	兼容的专用控制器 Chart	说明
APISIX Ingress Controller	1.4.0	默认使用 `apache/apisix-ingress-controller:2.2.0` 和 `ghcr.io/api7/adc:0.27.1` 边车（sidecar）。包含当前 APISIX CRD，并可选渲染 Gateway API 1.6 bundle，其中包括 `safe-upgrades` 准入策略及其 Binding。
API7 Ingress Controller	0.1.28	默认使用 `api7/api7-ingress-controller:2.2.1` 和 `ghcr.io/api7/adc:0.30.2` 边车。包含 Gateway API 1.6 和 APISIX CRD、ConfigMap 和 `L4RoutePolicy` RBAC，以及 v1 TCPRoute 和 UDPRoute Webhook 路径。

Controller 二进制在 config.yaml 省略 listener_port_match_mode 时默认为 off。APISIX Chart 会在渲染文件中写入 auto。入门指南中的 umbrella Chart 安装和下方独立 Chart 示例会设置 off，以免把 80、443 等 Gateway 监听器端口作为 server_port 匹配条件注入，而 APISIX 容器端口实际为 9080、9443。安装后请检查挂载的 config.yaml。参见配置文件。

APISIX Helm Chart

APISIX Helm Chart 提供基于 Helm 的 APISIX 组件安装和管理方式，可用于 Kubernetes 环境。

APISIX Ingress Controller 可以通过两种方式部署到 Kubernetes：

嵌入 apisix/apisix Chart 中，通过设置 ingress-controller.enabled=true，将控制器作为 APISIX Helm release 的一部分启用。
使用 apisix/apisix-ingress-controller Chart，将控制器作为单独的 Helm release 部署。

快速开始教程中的安装命令会先确认当前 APISIX umbrella Chart 包含 Ingress Controller Chart 1.3.0 或更高的兼容版本，再将 Controller 与 APISIX 部署到同一个 Helm release 中。Ingress Controller Pod 会与 APISIX 网关 Pod 一起运行，但 helm ls 中只会显示一个 Helm release（apisix）。

你也可以将 APISIX Ingress Controller 独立于 APISIX 部署为单独的 Helm release。以下示例展示如何将 APISIX Ingress Controller 作为独立 Helm release 安装：

# 替换为你的配置细节
helm install apisix-ingress-controller \
  --create-namespace \
  -n aic \
  --set gatewayProxy.createDefault=true \
  --set gatewayProxy.provider.controlPlane.auth.adminKey.value=edd1c9f034335f136f87ad84b625c8f1 \
  --set apisix.adminService.namespace=aic \
  --set apisix.adminService.name=apisix-admin \
  --set apisix.adminService.port=9180 \
  --set config.listenerPortMatchMode=off \
  --version 1.4.0 \
  apisix/apisix-ingress-controller

高亮值会覆盖 Chart 自带的 auto 模式，避免把 Service 对外的 Gateway 监听器端口转换为物理 server_port 匹配条件。

当 Gateway API 对象不存在或已由同一个 Helm release 拥有时，独立 Chart 默认会渲染 Gateway API bundle。如果集群平台拥有 Gateway API，请设置 crds.gatewayAPI.enabled=false。Chart 的 APISIX CRD 仍位于 crds/ 目录，遵循 Helm 独立的 CRD 生命周期；--skip-crds 不会禁用渲染出来的 Gateway API bundle。

入门教程使用的 APISIX umbrella Chart 当前嵌入 Controller Chart 1.3.0。它将两组 CRD 都置于 Helm 的 CRD 生命周期中，不支持 crds.gatewayAPI.enabled。

API7 Helm Chart

API7 Helm Chart 提供基于 Helm 的 API7 组件安装和管理方式，可用于 Kubernetes 环境。

API7 Ingress Controller 拥有专用 Helm Chart，只用于部署 Ingress Controller 组件，并连接到已有 API7 控制面。与 APISIX Helm Chart 不同，API7 网关 Helm Chart 不提供在同一个 Helm release 中同时部署 Ingress Controller 的选项。

安装时，API7 控制台会引导你在 Kubernetes 上部署 Ingress Controller 和 API7 网关，并在过程中生成所需部署脚本和命令。

API7 部署版本

Dashboard 生成的版本

API7 Dashboard 与 API7 Ingress Controller 独立发布，因此生成的命令可能选择与本文档不同的 Controller release。安装或升级前，请同时将命令中的 --version 和 deployment.image.tag 与已发布版本进行比较。显式设置 Controller 镜像标签会覆盖 Chart 默认值。

如需检查现有部署，请列出其命名空间中安装的 Chart：

helm list -n <namespace>

CHART 列标识已安装的 Chart 版本。由于 APP VERSION 不会反映镜像覆盖，还应检查 Controller Deployment 中配置的镜像：

kubectl get deployment <ingress-controller-deployment> -n <namespace> \
  -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{": "}{.image}{"\n"}{end}'

请根据已安装的 Controller release 判断功能是否可用。如需更新 release，请按照升级 Ingress Controller同时更新 Chart 和 Controller 镜像。除非已经审查过自定义覆盖，否则应保留目标 Chart 默认的 ADC 镜像。

Helm Chart values

Helm Chart values 用于定义 Chart 配置。它们可以来自 Chart 默认的 values.yaml 文件，也可以在安装或升级时被覆盖，用于自定义部署。

查看默认 values

如需查看 Helm Chart 提供的默认 values，运行：

helm show values <repo>/<chart-name> --version <chart-version>

# 例如：
# helm show values apisix/apisix
# helm show values apisix/apisix-ingress-controller
# helm show values api7/api7-ingress-controller

该命令会显示 Chart 打包时包含的 values.yaml，不会读取已安装 Helm release 的 values。如需检查当前 Helm release 实际关联的 values，请使用 helm get values。

有关特定版本 Chart 的详细信息，请查看 values 参考表（提供可读字段说明）和 values.yaml（提供原始默认值和嵌套结构）：

查看已安装的 values

如需查看已安装 Helm release 关联的 Chart values（包括默认值和覆盖值），运行：

helm get values <release-name> -n <namespace> --all

该命令显示 Chart 输入值，但不显示 Chart 模板渲染后的 config.yaml。

查看渲染后的控制器配置

如需检查已安装 release 渲染出的所有 Kubernetes 资源，运行：

helm get manifest <release-name> -n <namespace>

在渲染的清单中，找到 data 包含 config.yaml 的 ConfigMap，并记录其 metadata.name。运行以下命令可从实时 ConfigMap 输出 config.yaml：

kubectl get configmap <configmap-name> -n <namespace> \
  -o jsonpath='{.data.config\.yaml}{"\n"}'

Helm 清单显示该 release 渲染的内容；实时 ConfigMap 显示集群中当前存储的配置，包括在 Helm 之外所作的更改。

更新 values

如需更新 Helm release，可以编辑其有效 values 并应用变更。

首先，将 Helm release 的完整 values 导出到文件中，包括 Chart 默认值和所有覆盖值：

helm get values <release-name> -n <namespace> --all -o yaml > my-values.yaml

然后，打开导出的 values 文件并更新参数值。

最后，将更新后的 values 应用到同一 Chart 版本的 Helm release。请将 <installed-chart-version> 替换为 helm list -n <namespace> 输出中 CHART 列的版本，不要使用 APP VERSION：

helm upgrade <release-name> <chart-name> -n <namespace> \
  --version <installed-chart-version> \
  -f my-values.yaml

上面的 --all 导出包含当前 Chart 的默认值，因此只能在固定同一 Chart 版本时复用。如果要升级 Chart，请改为导出不带 --all 的用户覆盖值，按照升级 Ingress Controller迁移已重命名或移除的字段，再将迁移后的覆盖值应用到明确指定的新 Chart 版本。

如果由 Argo CD 管理渲染出的 Chart 资源，或由 Flux 管理 Helm Release，请在 Git 中更新固定的 Chart 版本或 values，不要运行 helm upgrade。有关 CRD 所有权、Secret 处理、协调和回滚指南，请参阅为 GitOps 做准备。

已发布版本​

APISIX Helm Chart​

API7 Helm Chart​

API7 部署版本​

Helm Chart values​

查看默认 values​

查看已安装的 values​

查看渲染后的控制器配置​

更新 values​