跳到主要内容

为 GitOps 做准备

GitOps 使用 Git 仓库作为 Ingress Controller 安装及其路由资源的事实来源。你无需运行安装命令并手动维护生成的对象，而是在 Git 中声明期望状态。GitOps Controller 会持续协调提交到仓库的变更、检测集群差异，并在发生漂移时恢复声明的状态。这种拉取式工作流使变更可审查、可跨环境重复执行，也能通过 Git 历史恢复。

Git 仓库可以包含 Controller Helm Chart 配置、CRD 所有权设置、凭证引用，以及 GatewayProxy、Gateway 和 HTTPRoute 等资源。Argo CD 和 Flux 等 GitOps 工具负责协调这些 Kubernetes 资源。Ingress Controller 监视路由资源，将其转换并同步为最终的网关配置。


GitOps 管理 Kubernetes 层；Ingress Controller 仍负责转换路由资源并同步网关配置。

在使用 Argo CD 或 Flux 安装 Ingress Controller 前，请准备仓库结构、资源与 CRD 所有权，以及 Controller 凭证。完成后，请继续阅读下一步中对应的操作流程。

前置条件​

开始前，请确保满足以下要求：

  • 集群运行 Kubernetes 1.31 或更高版本。本文使用的 Gateway API 1.6 Bundle 包含 admissionregistration.k8s.io/v1 的 ValidatingAdmissionPolicy，该 API 从 Kubernetes 1.30 起稳定可用。
  • GitOps Controller 可以读取一个 Git 仓库。
  • 有权创建 Ingress Controller 使用的命名空间、RBAC 资源、准入 Webhook 配置和 CRD。
  • 已有一种 Secret 管理方案，能够在目标集群中创建 Secret，而无需在 Git 中存储明文凭证或私钥。
  • 已部署 APISIX Gateway 和 Admin API Service，或有权访问 API7 Dashboard 并创建 Ingress Controller 类型的网关组。
  • Controller Pod 可以通过网络访问 APISIX Admin API 或 API7 控制面。

组织仓库​

将集群基础设施与应用路由资源分开。以下示例把每个集群的 Controller 和共享 Gateway 资源放在平台团队负责的基础设施目录中，而应用路由仍由对应应用团队管理：

clusters/
  production/
    infrastructure/
      ingress-controller/
      gateway-resources/
    applications/
      payments/

将 Argo CD Application，或 Flux HelmRepository 和 HelmRelease 清单存放在 infrastructure/ingress-controller/ 中。如果多个集群共享配置，请把可复用的 base 或 component 放在单独的顶层目录中，并让各集群引用。请根据平台的所有权模型调整目录名称和仓库边界。

普通 Chart values 可以保存在 Git 中。敏感值应通过已有 Secret、加密 Secret Controller 或外部 Secret 存储提供。固定 Chart 版本和远程清单版本；不要让集群级 CRD 引用持续变化的分支。

选择 Kubernetes 资源的存储方式​

本文档中的工作流使用官方 Helm Chart 安装 Ingress Controller。Argo CD 渲染该 Chart 并协调其输出；Flux Helm Controller 则通过 HelmRelease 完成安装和升级。

Gateway 和应用资源具有独立生命周期。请根据平台现有的 Kubernetes 应用管理方式选择其来源格式：

来源格式适用场景GitOps 集成方式
普通 Kubernetes YAML各环境拥有独立资源集，或只需少量定制。让 Argo CD Application 或 Flux Kustomization 指向清单目录。这也是各工具专用指南的默认路径。
Kustomize base 和 overlay多个环境共享大部分资源，只需少量明确差异。让 Argo CD 或 Flux 指向选定的 overlay。
应用 Helm Chart应用已用 Chart 打包 Deployment、Service 和路由资源，或需要大量由 values 驱动的配置。使用独立的 Argo CD Application 或 Flux HelmRelease 协调该 Chart，并与 Controller Release 分开。

这些格式最终都会生成 Ingress Controller 监视的 Kubernetes 资源。格式选择不会改变 Controller 转换和同步资源的方式。

规划资源所有权​

每个对象只能由一个协调器管理。不要让 Argo CD、Flux、其他 Helm Release 和手动执行的 kubectl apply 同时管理同一资源。

资源推荐所有者注意事项
Ingress Controller 命名空间平台 GitOps 配置外部管理的 Webhook 或凭证 Secret 必须先于引用它们的资源创建。
Gateway API CRD集群平台团队Chart 包含 Gateway API CRD。不要覆盖平台管理的 CRD 包。
APISIX CRD集群平台团队或 Controller Release升级期间应保持所有者一致。
Controller Deployment、Service、RBAC、ConfigMap 和 Webhook由所选 GitOps 工具管理的 Controller Release不要再用其他 Helm Release 或手动命令管理这些资源。
APISIX 或 API7 网关独立的基础设施 Release应尽可能让 Gateway 生命周期独立于 Controller。
GatewayProxy、GatewayClass 和 Gateway平台配置仓库在 CRD 与 Controller 就绪后再协调这些资源。如果 Chart 创建默认 GatewayProxy，应继续由 Chart 管理。
IngressClassAPISIX 环境由 Controller Release 管理；API7 环境由平台配置管理APISIX Chart 会渲染其配置的 IngressClass，不要在其他位置重复创建。
Route、Service 和策略应用团队仓库将应用交付与集群基础设施分开。
Admin Key 和 TLS 私钥目标集群的 Secret Controller只提交 Secret 引用或加密后的 Secret 资源。

选择 CRD 所有权​

本指南使用的 Controller Chart 包含 APISIX Ingress Controller CRD 和 Gateway API 1.6.0 standard bundle。不同安装方式的所有权控制不同：

安装方式Gateway API bundleAPISIX CRD
独立 APISIX Ingress Controller Chart 1.4.0crds.gatewayAPI.enabled=true 时作为 Helm 模板渲染。连接集群的 Helm 会跳过由其他所有者管理的对象。从 crds/apisixic-crds.yaml 安装。
带 Controller 1.3.0 依赖项的 APISIX umbrella Chart从依赖项的 crds/ 目录安装。从依赖项的 crds/ 目录安装。
API7 Ingress Controller Chart 0.1.28从 Chart 的 crds/ 目录安装。从 Chart 的 crds/ 目录安装。

Gateway API bundle 还包含 safe-upgrades.gateway.networking.k8s.io ValidatingAdmissionPolicy 及其 Binding。应让它们与 Gateway API CRD 由同一所有者管理。通过 Chart 的 crds/ 目录安装的资源在 Helm 卸载 Release 后仍会保留。独立 APISIX Chart 还为其渲染的 Gateway API 资源添加了卸载时保留的注解。

Argo CD 等不连接集群就渲染 Chart 的工具无法检查实时所有权。crds.gatewayAPI.enabled=true 时，它们会渲染完整的 Gateway API bundle。只要该 bundle 由其他来源管理，就应将此值设为 false。

Gateway API 建议由集群管理员管理 Gateway API CRD，尤其是其他 Controller 或 Kubernetes 平台已经提供这些 CRD 时。详情请参阅 Gateway API CRD 管理。

由 Controller Release 管理 CRD​

只有在平台或其他 Release 均未管理这两组 CRD 时，才应使用此模型。Controller Release 会创建两组 CRD。使用独立 APISIX Chart 时，请保留 crds.gatewayAPI.enabled=true。请按照各工具专用流程配置 APISIX CRD 的升级及所有集群级资源的删除行为，并在每次升级 Controller 时分别审查两组资源。

使用独立 APISIX Chart 分开管理所有权​

当平台管理 Gateway API、而独立的 APISIX Controller release 管理其 APISIX CRD 时，请使用此模型。设置 crds.gatewayAPI.enabled=false，保留工具专用的 APISIX CRD 安装或升级策略，并在协调 Controller release 之前先协调平台的 Gateway API bundle。

由平台管理 CRD​

当平台应管理两组 CRD 时，请使用此模型。这包括多个 Controller 共享 Gateway API，或 Controller release 不应管理集群级资源的情况。

  1. 从一个独立且固定版本的集群基础设施来源协调所需的 Gateway API 和 APISIX CRD。
  2. 等待所有 CRD 报告 Established 状态。
  3. 对于独立 APISIX Chart，设置 crds.gatewayAPI.enabled=false，并配置 GitOps 工具跳过 Chart 的 crds/ 目录。对于 API7 或 APISIX umbrella Chart，则配置工具跳过捆绑的静态 CRD。
  4. 确保 Controller Release 不会删除或替换平台管理的 CRD。

该模型允许平台独立升级 CRD，并防止 Controller 回滚时替换其 Schema。请确认已安装的 CRD 版本与已部署的 Ingress Controller release 兼容。Argo CD 和 Flux 流程会说明如何用对应工具实现所选所有权模型。

现有的独立 APISIX Chart 1.3.x 安装在升级前需要检查所有权。针对直接 Helm、Flux 和 Argo CD 的流程，请参阅迁移 APISIX Chart 1.3.x Gateway API 所有权。

准备 Gateway 连接​

GatewayProxy 定义 Ingress Controller 如何连接到 APISIX Admin API 或 API7 控制面并进行身份验证。当它引用 Kubernetes Secret 时，Controller 会从 GatewayProxy 所在命名空间读取该 Secret。请配置 Secret 管理方案，确保先于 GatewayProxy 创建 Secret，从而使首次协调成功。

通过 Secret 管理方案创建名为 apisix-admin-key 的 Secret，其中包含 admin-key Key。在 Chart values 中引用它：

values.yaml
config:
  provider:
    type: apisix-standalone
gatewayProxy:
  createDefault: true
  provider:
    type: ControlPlane
    controlPlane:
      service:
        name: apisix-admin
        port: 9180
      auth:
        type: AdminKey
        adminKey:
          valueFrom:
            secretKeyRef:
              name: apisix-admin-key
              key: admin-key

此示例遵循设置 APISIX Ingress Controller中的 API 驱动 APISIX 独立模式部署方式。Chart values 将 Controller 配置为独立模式，并创建一个指向 Controller 命名空间内 APISIX Admin API Service 的默认 GatewayProxy。

如果 APISIX 由其他系统管理，请确保其 Admin API 接受来自 Controller Pod 的连接。在 APISIX config.yaml 中配置 deployment.admin.allow_admin；若使用 Helm 安装 APISIX，则使用 apisix.admin.allow.ipList 渲染该设置。应把访问范围限制为所需 Pod 或集群 CIDR。

下一步​

完成这些准备工作后，请继续阅读管理 Ingress Controller 的对应 GitOps 工具指南：