atlassian/pipelines-agent-metric-sidecar

Bitbucket Pipelines 指标收集 Sidecar 镜像文档

1. 镜像概述和主要用途

该镜像为 Kubernetes Sidecar 容器，用于在 Kubernetes Pod 中收集其他容器的运行指标，并将指标数据上传至 Bitbucket Pipelines 后端系统。主要用途是为 Bitbucket Pipelines 相关工作负载提供容器级指标采集能力，支持监控、性能分析及后端数据集成。

2. 核心功能和特性

• 跨容器指标采集：收集 Pod 内其他容器的运行指标（如 CPU/内存使用率、网络 I/O、容器状态等）。
• 后端数据上传：将采集的指标实时或定时同步至 Bitbucket Pipelines 后端。
• Sidecar 部署模式：与主容器共享 Pod 网络和资源命名空间，无需额外网络配置。
• 轻量级设计：低资源占用，对主容器运行性能影响极小。

3. 使用场景和适用范围

3.1 使用场景

• 在 Kubernetes 集群中运行 Bitbucket Pipelines 构建、部署等工作负载时，需监控容器运行状态。
• 需将容器指标集成至 Bitbucket Pipelines 日志、报告或计费系统。
• 对 Bitbucket Pipelines 工作负载进行性能瓶颈分析和优化。

3.2 适用范围

• Kubernetes 集群环境（支持 Kubernetes 1.16+ 版本）。
• 与 Bitbucket Pipelines 集成的工作负载 Pod。
• 需要采集容器级指标并上传至 Bitbucket Pipelines 后端的场景。

4. 使用方法和配置说明

4.1 部署方式

该镜像需作为 Sidecar 容器添加至目标 Pod 的 spec.containers 中，与主容器共同运行。

4.2 配置参数（环境变量）

4.3 卷挂载要求

根据指标来源，可能需挂载以下卷（按需配置）：

• /var/run/docker.sock：访问 Docker 容器运行时（若使用 Docker 作为容器运行时）。
• /sys/fs/cgroup：访问 cgroup 指标（如 CPU/内存使用）。
• 主容器 metrics endpoint 挂载卷（若主容器暴露指标接口）。

4.4 Kubernetes Pod 配置示例

以下为在 Pod 中集成该 Sidecar 的配置示例：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: bitbucket-pipelines-worker
  namespace: bitbucket
spec:
  containers:
    # 主容器（Bitbucket Pipelines 工作负载）
    - name: pipelines-worker
      image: atlassian/bitbucket-pipelines-worker:latest
      # 主容器其他配置（如资源限制、命令等）...

    # Sidecar 容器（指标收集）
    - name: metrics-collector
      image: [镜像名称]:[标签]  # 替换为实际镜像名称和标签
      env:
        - name: BITBUCKET_PIPELINES_BACKEND_URL
          value: "https://pipelines.bitbucket.org/api/v1/metrics"  # 示例后端 URL
        - name: BITBUCKET_API_TOKEN
          valueFrom:
            secretKeyRef:
              name: bitbucket-secrets  # 存储 API 令牌的 Secret
              key: api-token
        - name: METRIC_COLLECTION_INTERVAL
          value: "15"  # 每 15 秒采集一次指标
        - name: LOG_LEVEL
          value: "INFO"
      volumeMounts:
        - name: docker-sock
          mountPath: /var/run/docker.sock
        - name: cgroup
          mountPath: /sys/fs/cgroup
          readOnly: true  # 只读挂载 cgroup 目录
  volumes:
    - name: docker-sock
      hostPath:
        path: /var/run/docker.sock  # 访问 Docker 运行时（按需调整）
    - name: cgroup
      hostPath:
        path: /sys/fs/cgroup  # 访问 cgroup 指标

5. 注意事项

• 确保 Sidecar 与主容器在同一 Pod 内，共享网络和存储命名空间。
• BITBUCKET_API_TOKEN 需具备向 Bitbucket Pipelines 后端上传指标的权限。
• 根据集群容器运行时（如 Docker、containerd）调整卷挂载配置（例如 containerd 无需挂载 /var/run/docker.sock）。
• 指标采集间隔建议不低于 10 秒，避免增加集群和后端系统负载。