Flux 通过 Kubernetes 事件来报告它做了什么,而 notification controller 会把这些事件变成告警,同时也接收 webhook。本指南设置两件事:当出现失败或成功时向聊天工具发送出站告警,以及让 Flux 在推送之后立即协调、而不是等待下一次轮询的入站 webhook。这里以 Slack 为例,但相同的对象同样适用于 Microsoft Teams、PagerDuty、Discord、通用 webhook 等,以及用于提交状态的 GitHub 和 GitLab 等 Git 提供商。

向 Slack 发送告警

涉及三种对象:一个包含 webhook 地址的 Secret、一个说明发送到哪里的 Provider,以及一个说明发送什么的 Alert。

创建 Secret(键必须是 address):

kubectl create secret generic slack-url \
  --namespace=flux-system \
  --from-literal=address=https://hooks.slack.com/services/XXX/YYY/ZZZ

apps/notifications/provider.yaml:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: slack
  namespace: flux-system
spec:
  type: slack
  channel: deployments
  secretRef:
    name: slack-url

apps/notifications/alert.yaml:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: on-call
  namespace: flux-system
spec:
  providerRef:
    name: slack
  eventSeverity: error
  eventSources:
    - kind: GitRepository
      name: "*"
    - kind: Kustomization
      name: "*"
    - kind: HelmRelease
      name: "*"
      namespace: podinfo

关键部分说明:

• providerRef 选择目的地。
• eventSeverity 是 info(一切,包括成功的应用)或 error。对于安静的值班频道使用 error,对于部署日志使用 info。
• eventSources 列出要监视的对象。名称为 "*" 会匹配该命名空间中该类型的所有对象,所以要监视其他命名空间,请使用 namespace:。

通知的 API 版本正在变化。v1beta2 已在 Flux 2.9 中被移除,所以如果你运行 Flux 2.9,请像上面那样使用 v1beta3,而 v1 API 计划在 Flux 2.10 中推出。用下面的命令检查你的集群支持什么:

kubectl get crd alerts.notification.toolkit.fluxcd.io \
  -o jsonpath='{.spec.versions[*].name}'; echo

提交这些文件,当某个 Kustomization 失败时,频道中会出现一条消息,包含对象、修订版本和错误。通过有意在 Git 中破坏一个清单路径来测试它。

将提交状态报告回 GitHub

第二个 Provider 可以把部署的结果作为提交状态发布,这样拉取请求或提交就会显示 Flux 是否已应用它:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: github-status
  namespace: flux-system
spec:
  type: github
  address: https://github.com/your-org/fleet-infra
  secretRef:
    name: github-token   # a Secret with a "token" key

将它与一个把 Kustomization 列为 source 的 Alert 配对使用。令牌需要有写入提交状态的权限。

接收 webhook 以实现即时同步

默认情况下,Flux 按 GitRepository 的间隔轮询 Git。Receiver 接受来自你的 Git 托管服务的 webhook,并立即触发协调,这样你可以延长轮询间隔,同时仍能获得近乎即时的部署。

创建一个共享的密钥令牌(键必须是 token):

TOKEN=$(head -c 12 /dev/urandom | shasum | cut -d ' ' -f1)
echo $TOKEN
kubectl create secret generic webhook-token \
  --namespace=flux-system --from-literal=token=$TOKEN

然后是 Receiver,使用稳定的 v1 API:

apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
  name: github-receiver
  namespace: flux-system
spec:
  type: github
  events:
    - ping
    - push
  secretRef:
    name: webhook-token
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: GitRepository
      name: flux-system

应用之后,向 Flux 询问它所生成的路径:

flux get receivers

路径形如 /hook/<hash>。notification controller 通过 flux-system 中名为 webhook-receiver 的 Service 暴露它,你需要通过 Ingress 或 LoadBalancer 将它发布到互联网。然后,在仓库设置中添加一个 webhook,使用该 URL、内容类型 application/json、你的令牌作为密钥,以及 push 事件。此后一次推送就会触发对 GitRepository 以及所有依赖它的内容的协调。Flux 2.9 还支持使用 OIDC 保护的通用 Receiver,它们不需要共享密钥,适用于能够出示 OIDC 令牌的平台。

故障排查

• 没有消息到达:检查 kubectl describe alert on-call -n flux-system 和用 flux logs --level=error 查看的控制器日志,并确认 Secret 的键名为 address。
• Webhook 没有触发:查看你的 Git 托管服务中的投递日志。404 通常意味着路径错误,401 或 403 则意味着令牌不匹配。
• 太吵:收紧 eventSeverity,并列出具体的 eventSources,而不是使用 "*"。