跳到主要内容

使用 Flux 管理

Flux 是由多个专用 Kubernetes Controller 组成的 GitOps 工具集。Source Controller 获取带版本的配置和部署产物，其他 Controller 则把这些来源协调到集群中。在本工作流中，Flux Helm Controller 把 APISIX 或 API7 Ingress Controller 作为 Git 中定义的声明式 Helm Release 管理。

Flux Helm Controller 执行 Helm 安装与升级，并保存渲染后的 Release 清单。它还可以修复失败操作和配置漂移。由于 Flux 不会在每次比较时重新渲染 Chart，当前 Webhook 证书生成行为预计不会造成持续漂移。请保持启用 Webhook，并在生产使用该工作流前验证一次无变更协调。

本指南介绍如何创建 HelmRepository 与 HelmRelease、配置 CRD 生命周期策略和修复机制，以及协调 Gateway 和应用资源；还包括验证、升级、回滚和故障排查。

前置条件​

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

  • 已完成为 GitOps 做准备中所述的仓库、资源所有权、CRD 和凭证准备。
  • 已安装 Flux，并配置已认证的 flux CLI。
  • Flux 可以访问平台仓库，并有权管理目标命名空间和所需集群级资源。

示例使用 aic 作为目标命名空间。如果使用其他命名空间，请替换所有清单和命令中的 aic。

示例 values 侧重 GitOps 所有权与协调，副本数、资源请求和 Pod 调度仍使用 Chart 默认值。用于生产前，请按工作负载配置容量、运行多个 Controller 副本，并将其分布到不同故障域。请参阅 AIC 高可用，并在目标集群中测试故障转移。固定的两个 Controller Chart 均可在 podDisruptionBudget.enabled=true，且自动伸缩的最小副本数至少为 2，或关闭自动伸缩且 deployment.replicas 大于 1 时，渲染 PodDisruptionBudget。

创建 Helm Source 与 Release​

为所选 Controller 创建 HelmRepository 与 HelmRelease。示例采用 Controller 管理 CRD 的模型。

配置 HelmRelease 时，请应用为 GitOps 做准备中确定的 CRD 所有权策略：

  • 如果由 HelmRelease 管理两组资源，请把 install.crds 设置为 Create，并把 upgrade.crds 设置为 CreateReplace。对于 APISIX Chart 1.4.0，还应保持 crds.gatewayAPI.enabled=true。升级 Release 前应分别审查两组资源。
  • 如果由平台管理 Gateway API，而独立 APISIX HelmRelease 管理 APISIX CRD，请设置 crds.gatewayAPI.enabled=false，并保留 Create 和 CreateReplace 策略。
  • 如果由平台管理两组资源，请通过独立且固定版本的 Flux Kustomization 协调它们。对于 APISIX Chart 1.4.0，请设置 crds.gatewayAPI.enabled=false；对于两种产品，请把 HelmRelease 的两项 CRD 策略都设为 Skip。等待 CRD 报告 Established 状态后，再协调 HelmRelease。如果 Flux 也通过 Kustomization 应用 HelmRelease，请让该 Kustomization 依赖 CRD Kustomization。

清单使用 Flux v2 HelmRelease API 和漂移检测。应用前请确认当前 Flux 安装支持这些字段。

在共享或多租户集群中，把 HelmRelease 的 spec.serviceAccountName 设置为平台管理且仅拥有必要权限的 ServiceAccount。该 ServiceAccount 必须能够管理分配给 Release 的命名空间级与集群级资源；如果 HelmRelease 管理 CRD，还必须有权管理 CRD。否则 Flux 会使用授予 Helm Controller 的权限执行 Helm 操作。

目标命名空间（示例中为 aic）必须已经存在 APISIX Admin API Service 和 apisix-admin-key Secret。

apisix-ingress-controller-release.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: aic
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: apisix
  namespace: aic
spec:
  interval: 1h
  url: https://apache.github.io/apisix-helm-chart
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: apisix-ingress-controller
  namespace: aic
spec:
  interval: 30m
  releaseName: apisix-ingress-controller
  chart:
    spec:
      chart: apisix-ingress-controller
      version: "1.4.0"
      sourceRef:
        kind: HelmRepository
        name: apisix
        namespace: aic
      interval: 12h
  install:
    crds: Create
    remediation:
      retries: 3
  upgrade:
    crds: CreateReplace
    remediation:
      retries: 3
  driftDetection:
    mode: enabled
  values:
    crds:
      gatewayAPI:
        enabled: true
    config:
      listenerPortMatchMode: "off"
      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 Chart 自带的 auto 模式，避免把 Service 对外的 Gateway 监听器端口转换为物理 server_port 匹配条件。

示例会把失败操作重试三次。Flux 会在重试失败的安装前先卸载，并在重试失败的升级前先回滚。请根据恢复策略调整重试次数并设置有限值，使持续存在的配置或权限错误必须由操作人员审查。

协调 Helm Release​

把清单提交到 Flux 协调的路径，请求协调并检查 Release：

flux reconcile source helm <repository-name> -n aic
flux reconcile helmrelease <release-name> -n aic --with-source
flux get helmreleases -n aic

HelmRelease 应报告 Ready=True。在不更改 Git 的情况下再次执行协调，并确认版本和 Webhook Secret 保持不变。

协调 Gateway 与应用资源​

HelmRelease 管理 Controller Release。请使用独立 Flux Kustomization 资源管理共享 Gateway 资源和应用路由，使其所有权与生命周期互相独立。尽管资源名为 Kustomization，每个被引用目录都可以只包含普通 Kubernetes YAML，而无需 kustomization.yaml 文件。

把产品专用 GatewayProxy、GatewayClass、共享 Gateway、应用命名空间和授权标签存放在之前准备且由平台管理的 infrastructure/gateway-resources/ 目录。对于 APISIX，如果 Controller Chart 会创建默认 GatewayProxy，请不要在该目录中重复保存。对于 API7，请使用 API7 Dashboard 生成的非敏感资源，并保留其名称和引用。

为平台仓库创建 GitRepository，并为共享资源创建 Kustomization：

gateway-resources.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: platform-config
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/platform-config.git
  ref:
    branch: main
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: platform-gateway-resources
  namespace: flux-system
spec:
  interval: 10m
  path: ./clusters/production/infrastructure/gateway-resources
  prune: true
  wait: true
  timeout: 3m
  sourceRef:
    kind: GitRepository
    name: platform-config

把每个应用的 Deployment、Service、HTTPRoute 和策略与该应用存放在一起。可以直接使用配置示例中的清单，无需创建 Overlay。为应用目录添加另一个 Kustomization，并让它依赖共享资源：

httpbin-resources.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: httpbin-production
  namespace: flux-system
spec:
  interval: 10m
  path: ./clusters/production/applications/httpbin
  prune: true
  wait: true
  timeout: 3m
  targetNamespace: <application-namespace>
  sourceRef:
    kind: GitRepository
    name: platform-config
  dependsOn:
  - name: platform-gateway-resources

如果任一目录包含普通清单，Flux 会生成构建配置。请把这些资源提交到 Flux Bootstrap 路径。应用 Kustomization 运行前，应用命名空间必须已由平台 Kustomization 或其他所有者创建。在共享或多租户集群中，请把每个 Kustomization 的 spec.serviceAccountName 设置为权限范围适当的 ServiceAccount。

该依赖会等待平台 Kustomization 报告 Ready=True，但两个 Controller 的 GatewayProxy 都没有状态。请通过 Gateway 与 HTTPRoute 状态和端到端请求验证实际 Gateway 连接。

验证​

把 Release 推广到其他环境前，请验证 Controller Deployment、CRD、Gateway 连接和端到端路由。

确认 Deployment 可用且 CRD 已建立：

kubectl rollout status deployment \
  -l app.kubernetes.io/instance=<release-name> \
  -n aic \
  --timeout=300s
kubectl get pods,services -n aic
kubectl get crd gatewayproxies.apisix.apache.org
kubectl wait --for=condition=Established \
  crd/gatewayproxies.apisix.apache.org \
  --timeout=60s

Controller Pod 应报告 Controller 与 ADC 两个容器都已就绪。检查渲染出的 Controller 配置和预期 GatewayProxy：

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

两个 Controller 的 GatewayProxy 都不公开接受状态。启用准入 Webhook 后，无效对象可能在创建时被拒绝。请通过 Controller 日志，以及相关 Gateway 与 HTTPRoute 资源上的 Accepted、Programmed 和 ResolvedRefs 状态验证运行时连接。

使用 Git 管理的 Gateway 与 Class 完成代理请求到服务。成功请求可以验证从 Kubernetes 路由资源经 Controller 到 Gateway 的完整路径。

最后再次协调，并确认没有资源变化：

flux reconcile helmrelease <release-name> -n aic --with-source
flux get helmreleases -n aic

升级与回滚​

通过 Git 管理升级和回滚，确保 Flux 始终是 Helm Release 的唯一协调器。

将 APISIX Ingress Controller Chart 1.3.x 升级到 1.4.0 之前，请先按迁移 APISIX Chart 1.3.x Gateway API 所有权操作。

升级 Controller：

  1. 审查 Ingress Controller 发布说明。另行审查所选 Chart 的 Release Notes，包括 CRD 变更。
  2. 在 Git 中更改固定的 Chart 版本和所需 values。
  3. 协调前检查渲染出的差异。
  4. 协调一个环境，并重复 Deployment、路由和无变更验证。
  5. 把相同 Git 变更推广到下一个环境。

回滚前，请确认已安装 CRD 与旧版 Controller 兼容。在回滚变更中把 upgrade.crds 设置为 Skip，防止旧 Chart 替换静态 CRD。对于 APISIX Chart 1.4.0，还应设置 crds.gatewayAPI.enabled=false，以免回滚变更渲染 Gateway API bundle。如果两组资源都由平台 Kustomization 管理，请保持 install.crds 与 upgrade.crds 均为 Skip。然后在 Git 中恢复 Chart 版本和 Controller values。

CRD 策略只控制 Chart crds/ 目录中的资源，不能抑制 APISIX Chart 1.4.0 作为模板渲染的 Gateway API 资源。请检查渲染出的回滚差异，确认它不会修改任一 bundle。自动失败升级修复可能重新应用已存储的 release 清单，之后的 Git 变更无法改写该清单。避免在 CRD 所有权变更期间自动回滚，并使用已审查的 Git revision 恢复。不要对 Flux 管理的 Release 运行 helm rollback 或 helm upgrade。

故障排查​

使用以下检查诊断常见 Release 与协调故障：

现象检查解决方案
HelmRelease 报告 CRD 所有权或升级失败检查 install.crds、upgrade.crds、APISIX Chart 1.4.0 的 crds.gatewayAPI.enabled，以及管理相同 CRD 的其他 Controller。为每组资源分别选定唯一所有者，并在其他 release 中禁用该 bundle。
GatewayProxy 创建被拒绝，或 Controller 日志报告连接错误确认其 Secret、端点或 Service、网络访问和 CRD 在协调前已经存在。修正 Secret 引用、连接或依赖顺序，然后重新协调。
手动删除或编辑后 Controller 资源重新出现检查是否启用 Flux 漂移检测。在 Git 中完成预期变更，不要编辑实际对象。
Release 修复机制持续重试检查 Helm Controller 事件与 Release 历史。修正 Chart values 或依赖，然后重新协调来源与 Release。