woodpeckerci/plugin-kaniko

Woodpecker CI Kaniko插件

镜像概述

Woodpecker CI Kaniko插件是一个集成Google Kaniko工具的Woodpecker CI插件，专为在CI/CD流水线中构建Docker镜像而设计。该插件无需依赖Docker守护进程（daemon），通过直接访问容器镜像层来构建镜像，适用于无Docker守护进程的受限环境（如Kubernetes集群、安全隔离环境），可无缝集成到Woodpecker CI的自动化流程中，实现镜像构建、推送的全自动化。

核心功能与特性

核心功能

• 无Docker守护进程依赖：基于Kaniko实现，无需暴露Docker守护进程，避免权限安全风险
• 多平台镜像构建：支持同时构建多种CPU架构的镜像（如amd64、arm64）
• 镜像推送集成：支持将构建后的镜像推送到主流容器仓库（Docker Hub、GitHub Container Registry、私有仓库等）
• 构建缓存支持：支持构建缓存（层缓存、构建上下文缓存），加速重复构建过程
• Woodpecker CI原生集成：无缝接收Woodpecker CI的环境变量和参数，支持动态配置构建参数
• 安全构建：在非特权环境中运行，减少安全***面，符合最小权限原则

关键特性

• 支持自定义Dockerfile路径及构建上下文
• 提供镜像标签（tag）动态配置（如基于Git commit hash、分支名）
• 支持私有仓库认证（用户名/密码、令牌、SSH密钥）
• 支持构建参数（--build-arg）传递
• 兼容OCI标准镜像格式

使用场景

CI/CD流水线集成

作为Woodpecker CI流水线的关键步骤，在代码提交、合并或定时触发时自动构建Docker镜像，实现"代码提交→测试→构建镜像→推送仓库"的全流程自动化。

受限环境构建

在无Docker守护进程的环境（如Kubernetes Pod、容器化CI节点）中构建镜像，解决传统Docker-in-Docker（DinD）方案的权限和性能问题。

安全构建场景

适用于对安全要求较高的环境，通过避免暴露Docker守护进程权限（无需--privileged模式），降低容器逃逸和权限滥用风险。

多平台镜像分发

需为不同硬件架构（如x86_64、ARM）构建镜像时，通过多平台构建功能一次性生成多架构镜像并推送至仓库。

使用方法与配置说明

基本用法

在Woodpecker CI的流水线配置文件（.woodpecker.yml）中，通过steps定义使用该插件，示例如下：

yaml
steps:
  build-image:
    image: docker.xuanyuan.run/woodpeckerci/plugin-kaniko
    settings:
      repo: my-docker-repo/my-image
      tag: latest
      dockerfile: ./Dockerfile
      context: .
      registry: https://index.docker.io/v1/
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password

配置参数

高级配置示例

1. 多平台构建

yaml
steps:
  build-multiarch:
    image: docker.xuanyuan.run/woodpeckerci/plugin-kaniko
    settings:
      repo: my-repo/my-app
      tag: multiarch
      platforms: linux/amd64,linux/arm64
      dockerfile: Dockerfile.multiarch
      registry: https://index.docker.io/v1/
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password

2. 启用构建缓存加速

yaml
steps:
  build-with-cache:
    image: docker.xuanyuan.run/woodpeckerci/plugin-kaniko
    settings:
      repo: my-repo/my-app
      tag: ${CI_COMMIT_BRANCH}
      cache: true
      cache_repo: my-repo/build-cache  # 独立缓存仓库，避免污染目标镜像
      dockerfile: Dockerfile
      context: .

3. 传递构建参数

yaml
steps:
  build-with-args:
    image: docker.xuanyuan.run/woodpeckerci/plugin-kaniko
    settings:
      repo: my-repo/my-app
      tag: ${CI_COMMIT_SHA:0:8}
      build_args: "APP_VERSION=${CI_COMMIT_TAG},BUILD_DATE=$(date +%Y-%m-%d)"
      dockerfile: Dockerfile

注意事项

• 私有仓库认证：用户名/密码需通过Woodpecker CI的from_secret从密钥管理中获取，避免明文暴露。
• 多标签支持：tag参数支持动态值（如Git提交哈希、分支名），需结合Woodpecker CI的环境变量（如CI_COMMIT_SHA、CI_COMMIT_BRANCH）。
• 缓存优化：启用缓存可大幅减少重复构建时间，但需注意缓存仓库的清理策略，避免存储空间占用过大。
• 权限要求：插件运行无需--privileged权限，但需确保构建上下文（代码仓库）可被插件访问。