atlassian/pipelines-kubectl

Bitbucket Pipelines Kubectl 镜像文档

1. 镜像概述和主要用途

概述

Bitbucket Pipelines Kubectl 镜像是一个轻量级 Docker 镜像，基于 Alpine Linux 3.16 构建，内置 Kubernetes 命令行工具 kubectl。该镜像由 Atlassian Bitbucket Pipelines 团队维护，旨在为 Bitbucket CI/CD 流程提供标准化的 kubectl 运行环境，简化在自动化流水线中与 Kubernetes 集群的交互操作。

主要用途

• 在 Bitbucket Pipelines 自动化流程中执行 kubectl 命令（如部署应用、查看集群资源、配置 Kubernetes 资源等）。
• 作为本地或 CI/CD 环境中快速获取指定版本 kubectl 的便捷工具，无需手动安装和配置。

2. 核心功能与特性

核心功能

• 提供完整的 kubectl 命令行工具，支持与 Kubernetes 集群的所有标准交互操作。
• 内置基础依赖（ca-certificates、bash），确保 HTTPS 通信安全性和基本 shell 环境支持。

特性

• 轻量级基础：基于 Alpine Linux 3.16，镜像体积小，资源占用低，适合 CI/CD 环境快速拉取和启动。
• 版本可控：支持通过构建参数指定 kubectl 版本，确保与目标 Kubernetes 集群版本兼容。
• CI/CD 优化：默认 ENTRYPOINT 设为 kubectl，容器启动即可直接执行命令，简化流水线配置。

3. 使用场景和适用范围

典型使用场景

• Bitbucket CI/CD 流水线：在 Bitbucket 仓库的自动化部署阶段，通过 kubectl 部署应用到 Kubernetes 集群、更新配置或执行集群检查。
• 本地开发/测试：快速启动包含指定版本 kubectl 的容器，无需在本地系统安装 kubectl。
• 轻量级 Kubernetes 管理：在资源受限环境（如边缘设备、小型 CI 节点）中执行 kubectl 命令。

适用范围

• 需与 Kubernetes 集群交互的 Bitbucket Pipelines 工作流。
• 需要统一 kubectl 版本的自动化脚本或工具链。
• 追求轻量级、标准化 kubectl 运行环境的场景。

4. 使用方法和配置说明

4.1 镜像获取

构建镜像（推荐）

若需自定义 kubectl 版本，可基于提供的 Dockerfile 构建镜像：

bash
# 克隆包含 Dockerfile 的仓库后执行构建，指定 kubectl 版本（如 1.28.0）
docker build --build-arg VERSION=1.28.0 -t bitbucket-pipelines-kubectl:1.28.0 .

拉取预构建镜像（如已托管）

若镜像已上传至容器仓库（如 Docker Hub、Atlassian 私有仓库），可直接拉取：

bash
docker pull <仓库地址>/bitbucket-pipelines-kubectl:<版本号>  # 示例：docker pull my-registry/kubectl:1.28.0

4.2 运行容器执行 kubectl 命令

由于镜像默认 ENTRYPOINT 为 kubectl，容器启动时的命令参数将直接作为 kubectl 的子命令和参数。

基础命令示例

• 查看 kubectl 版本：

  bash
  docker run --rm bitbucket-pipelines-kubectl:1.28.0 version --client
  

• 查看 Kubernetes 集群 pods（需挂载本地 kubeconfig 以访问集群）：

  bash
  # 将本地 ~/.kube/config 挂载到容器内 /root/.kube/config（容器默认工作目录为 /root）
  docker run --rm -v ~/.kube/config:/root/.kube/config bitbucket-pipelines-kubectl:1.28.0 get pods
  

4.3 在 Bitbucket Pipelines 中使用

在 bitbucket-pipelines.yml 中配置步骤，使用该镜像执行 kubectl 命令。示例如下：

yaml
pipelines:
  default:
    - step:
        name: Deploy to Kubernetes Cluster
        image: bitbucket-pipelines-kubectl:1.28.0  # 使用构建或拉取的镜像
        script:
          - kubectl config use-context my-k8s-cluster  # 切换到目标集群上下文（需提前配置集群访问凭证）
          - kubectl apply -f k8s/deployment.yaml       # 应用部署配置
          - kubectl rollout status deployment/my-app   # 检查部署状态
          - kubectl get pods -l app=my-app             # 验证 pod 启动

4.4 配置参数说明

构建参数（ARG）

环境变量（ENV）

5. 部署方案示例

5.1 Docker Run 完整示例（本地访问集群）

bash
# 挂载本地 kubeconfig，执行 kubectl 命令查看集群节点
docker run --rm \
  -v ~/.kube/config:/root/.kube/config \  # 挂载集群访问配置
  bitbucket-pipelines-kubectl:1.28.0 \    # 使用指定版本镜像
  get nodes --output wide                 # kubectl 命令及参数

5.2 Bitbucket Pipelines 部署示例（带集群认证）

在 bitbucket-pipelines.yml 中配置 Kubernetes 集群访问凭证（通过 Bitbucket 环境变量注入），并执行部署：

yaml
pipelines:
  branches:
    main:  # 仅在 main 分支触发
      - step:
          name: Deploy to Production Cluster
          image: bitbucket-pipelines-kubectl:1.28.0
          script:
            # 将 Bitbucket 环境变量中的集群凭证写入 kubeconfig
            - echo "$KUBE_CONFIG" > /root/.kube/config
            # 部署应用并验证
            - kubectl apply -f k8s/prod/deployment.yaml
            - kubectl set image deployment/my-app my-app=my-registry/my-app:${BITBUCKET_COMMIT}  # 使用当前提交哈希作为镜像标签
            - kubectl rollout status deployment/my-app
          environment:
            # 在 Bitbucket 仓库设置中配置 KUBE_CONFIG 环境变量（存储 base64 编码的 kubeconfig 内容）
            KUBE_CONFIG: $KUBE_CONFIG