跳到主要内容

使用 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 高可用，并在目标集群中测试故障转移。当前固定版本 Chart 的 podDisruptionBudget.enabled 选项无法成功渲染；除非确认后续 Chart Release 已修复，否则不要启用。

创建 Helm Source 与 Release​

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

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

  • 如果由 HelmRelease 管理 Chart 自带 CRD，请把 install.crds 设置为 Create，并把 upgrade.crds 设置为 CreateReplace。卸载 Release 时 Helm 会把 CRD 留在集群中，但升级可能替换它们。升级 Release 前应单独审查 CRD 变更。
  • 如果由平台管理 CRD，请通过独立且固定版本的 Flux Kustomization 协调所需 Gateway API 与 APISIX CRD。等待它们报告 Established 状态，并把 HelmRelease 的两项 CRD 策略都设为 Skip。如果 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.2.2"
      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:
    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

示例会把失败操作重试三次。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，但当前版本的 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

当前版本的 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 的唯一协调器。

升级 Controller：

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

回滚前，请确认已安装 CRD 与旧版 Controller 兼容。在回滚变更中把 upgrade.crds 设置为 Skip，防止 Flux 使用 Chart 中的旧版 CRD 替换已安装 Schema。如果 CRD 由独立且固定版本的平台 Kustomization 管理，请保持 install.crds 与 upgrade.crds 均为 Skip。然后在 Git 中恢复 Chart 版本和 Controller values。

如果 upgrade.crds 仍为 CreateReplace，恢复 Chart 版本可能会用旧版 Schema 替换已安装 CRD。按上述方式设置为 Skip 可以防止 Flux 在回滚时处理 Chart 中的 CRD。不要对 Flux 管理的 Release 运行 helm rollback 或 helm upgrade。

故障排查​

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

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