fluxcd/flux-recv

Flux CD Webhook接收器镜像文档

镜像概述

本镜像为Flux CD（一个开源GitOps工具链）提供Webhook接收功能，用于监听Git仓库事件（如代码推送、合并请求），并自动触发Flux的Kubernetes资源同步过程。通过接收并验证外部事件，实现GitOps工作流中"代码变更即部署"的自动化闭环，是GitOps实践中的关键组件。

核心功能与特性

• 多平台事件接收：支持主流版本控制系统的Webhook事件（GitHub、GitLab、Bitbucket、Gitea等）
• 事件验证：通过密钥令牌（Secret Token）验证Webhook请求合法性，防止未授权触发
• 同步触发：接收事件后自动调用Flux API，触发Git仓库与Kubernetes集群的资源同步
• 灵活配置：支持自定义同步策略（如仅同步特定命名空间、设置同步超时时间）
• 日志与监控：输出详细事件处理日志，支持Prometheus指标暴露，便于监控与问题排查

适用场景

• GitOps自动化部署：代码提交至Git仓库后，自动触发Kubernetes资源更新
• 多环境管理：通过分支或目录区分环境（如dev、staging、prod），实现环境隔离与自动部署
• 基础设施即代码（IaC）：监控Git仓库中的基础设施配置文件（如Terraform、Kustomize）变更，自动同步至集群
• CI/CD流水线集成：作为CI流程的终点，在代码构建测试完成后触发部署环节
• 混合云/多云部署：跨集群统一接收Git事件，实现多集群资源同步

使用方法

基本部署（Docker Run）

bash
docker run -d \
  --name flux-webhook-receiver \
  -p 8080:8080 \
  -e FLUX_CONTROLLER_URL=http://flux-controller:8080 \  # Flux Sync Controller的API地址
  -e WEBHOOK_SECRET_TOKEN=your-secure-token \          # 用于验证Webhook的密钥（需与Git平台配置一致）
  -e PROVIDER=github \                                 # 版本控制系统类型（github/gitlab/bitbucket/gitea等）
  -e SYNC_NAMESPACE=default \                          # 可选，指定同步的Kubernetes命名空间（默认全部）
  fluxcd/webhook-receiver:latest

Kubernetes部署示例

yaml
# flux-webhook-receiver.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: flux-webhook-receiver
  namespace: flux-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: flux-webhook-receiver
  template:
    metadata:
      labels:
        app: flux-webhook-receiver
    spec:
      containers:
      - name: receiver
        image: fluxcd/webhook-receiver:latest
        ports:
        - containerPort: 8080
        env:
        - name: FLUX_CONTROLLER_URL
          value: "http://source-controller.flux-system.svc.cluster.local:80"  # Flux Source Controller内部地址
        - name: WEBHOOK_SECRET_TOKEN
          valueFrom:
            secretKeyRef:
              name: flux-webhook-token
              key: token  # 从Secret中获取密钥（推荐生产环境使用）
        - name: PROVIDER
          value: "github"
        - name: SYNC_TIMEOUT
          value: "30s"  # 同步超时时间
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10

环境变量配置

版本控制系统配置示例

GitHub Webhook配置

1. 进入Git仓库 → Settings → Webhooks → Add webhook
2. Payload URL: http://<receiver-ip>:8080/hook（公网可访问地址）
3. Content type: application/json
4. Secret: 填写与WEBHOOK_SECRET_TOKEN一致的密钥
5. Events: 勾选Just the push event（或根据需求选择事件）
6. 点击"Add webhook"完成配置

GitLab Webhook配置

1. 进入Git仓库 → Settings → Webhooks
2. URL: http://<receiver-ip>:8080/hook
3. Secret token: 填写与WEBHOOK_SECRET_TOKEN一致的密钥
4. Trigger: 勾选Push events
5. 点击"Add webhook"完成配置

安全注意事项

• 生产环境中必须通过WEBHOOK_SECRET_TOKEN验证事件合法性，防止***触发
• 建议使用HTTPS暴露Webhook端点（可配合Ingress控制器配置TLS）
• WEBHOOK_SECRET_TOKEN应通过Kubernetes Secret或环境变量安全注入，避免硬编码
• 限制SYNC_NAMESPACE范围，遵循最小权限原则