grafana/shipwright

Shipwright 构建镜像文档

概述

Shipwright 构建镜像是一个专为容器镜像构建设计的工具镜像，旨在简化和标准化容器化应用的构建流程。它支持多种构建策略，允许开发者根据项目需求选择最适合的构建方式，并与 Kubernetes 生态系统深度集成，提供自动化、可扩展的镜像构建解决方案。

核心功能和特性

• 多构建策略支持：兼容 Dockerfile、Cloud Native Buildpacks、Kaniko、Buildah 等多种构建工具和规范，满足不同场景的构建需求。
• Kubernetes 原生集成：作为 Kubernetes 自定义资源（CRD）部署，可利用 Kubernetes 资源进行构建任务调度、资源管理和监控，与集群环境无缝衔接。
• 构建缓存优化：内置构建缓存机制，自动缓存中间构建结果，加速重复构建过程，减少网络传输和资源消耗。
• 高度可扩展性：支持自定义构建步骤、插件和钩子，允许扩展构建能力以适配特定业务场景或合规要求。
• 多平台镜像构建：支持同时构建多架构（如 amd64、arm64）容器镜像，适配不同硬件平台的部署需求。

使用场景和适用范围

• 云原生应用开发：适用于基于 Kubernetes 的微服务架构，简化分布式应用的容器化构建流程，统一构建标准。
• CI/CD 流水线集成：可嵌入 Jenkins、GitLab CI、GitHub Actions 等 CI/CD 系统，实现代码提交到镜像构建的自动化流程。
• 混合构建策略管理：当项目中不同服务需要使用不同构建方式（如部分服务用 Dockerfile，部分用 Buildpacks）时，提供统一的构建入口和管理能力。
• 企业级容器化转型：满足企业对构建流程标准化、可审计、可追溯的需求，支持多团队协作和权限控制。

使用方法和配置说明

环境准备

• Kubernetes 集群（推荐 1.21+ 版本）
• kubectl 命令行工具（与集群版本匹配）
• Shipwright 控制器（参考 官方安装文档 完成部署）

构建策略配置

通过 BuildStrategy 自定义资源定义构建策略，以下是常用策略示例：

Dockerfile 构建策略

yaml
apiVersion: shipwright.io/v1beta1
kind: BuildStrategy
metadata:
  name: dockerfile-strategy
  namespace: default
spec:
  buildSteps:
    - name: build-image
      image: docker.xuanyuan.run/docker:20.10
      command: ["docker", "build", "-f", "$(DOCKERFILE)", "-t", "$(OUTPUT_IMAGE)", "$(CONTEXT)"]
      volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock
  volumes:
    - name: docker-socket
      hostPath:
        path: /var/run/docker.sock
        type: Socket
  parameters:
    - name: DOCKERFILE
      default: ./Dockerfile
    - name: CONTEXT
      default: .

Buildpacks 构建策略

yaml
apiVersion: shipwright.io/v1beta1
kind: BuildStrategy
metadata:
  name: buildpacks-strategy
  namespace: default
spec:
  buildSteps:
    - name: buildpacks-build
      image: docker.xuanyuan.run/paketobuildpacks/builder:base
      command: ["pack", "build", "$(OUTPUT_IMAGE)", "--builder", "paketobuildpacks/builder:base"]

构建任务定义

通过 Build 资源定义具体构建任务，关联源代码和输出镜像：

yaml
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: example-app-build
  namespace: default
spec:
  source:
    type: Git
    git:
      url: https://github.com/example/example-app.git  # 源代码仓库地址
      revision: main  # 分支或提交哈希
  strategy:
    name: dockerfile-strategy  # 关联上述定义的构建策略
    kind: BuildStrategy
  output:
    image: registry.example.com/example-app:v1.0.0  # 输出镜像地址
    credentials:
      name: registry-creds  # 镜像仓库认证密钥（需提前创建 Secret）
  parameters:
    - name: DOCKERFILE
      value: ./deploy/Dockerfile  # 自定义 Dockerfile 路径（覆盖策略默认值）

触发构建任务

通过 BuildRun 资源触发构建流程：

yaml
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: example-app-buildrun
  namespace: default
spec:
  build:
    name: example-app-build  # 关联上述定义的 Build 资源

应用配置并触发构建：

bash
# 创建构建策略
kubectl apply -f dockerfile-strategy.yaml

# 创建构建任务
kubectl apply -f example-app-build.yaml

# 触发构建
kubectl apply -f example-app-buildrun.yaml

查看构建状态与日志

bash
# 查看构建任务状态
kubectl get buildrun example-app-buildrun -o wide

# 查看构建日志
kubectl logs -l shipwright.io/buildrun=example-app-buildrun -c step-build-image

配置参数说明

环境变量

构建策略参数

不同策略支持自定义参数，可在 Build 资源的 parameters 字段中覆盖默认值，例如：

• Dockerfile 策略：DOCKERFILE（文件路径）、CONTEXT（构建上下文路径）
• Buildpacks 策略：BUILDER_IMAGE（构建器镜像）、ENV_VARS（环境变量）

注意事项

• 构建节点需确保网络通畅，能够访问源代码仓库和镜像仓库。
• 对于私有仓库，需提前创建包含认证信息的 Secret，并在 Build 资源中通过 output.credentials 关联。
• 大规模构建场景建议配置构建缓存（如使用 PersistentVolume 存储缓存数据）以提升性能。