initializbuildpacks/image-labels

Init Image Labels Buildpack

镜像概述和主要用途

Init Image Labels Buildpack 是一个用于容器镜像构建流程的构建包，主要功能是通过环境变量配置，为生成的OCI镜像自动添加标准OCI标签及用户自定义的任意标签。该构建包简化了镜像标签管理流程，无需手动修改构建配置文件即可灵活设置镜像元数据。

核心功能和特性

• 环境变量驱动配置：所有标签通过环境变量定义，无需修改构建脚本或配置文件，简化配置流程
• 标准OCI标签支持：内置支持org.opencontainers.image系列标准标签（如版本、作者、描述等），符合OCI镜像规范
• 自定义标签灵活性：允许添加任意用户定义的标签键值对，满足特定业务需求
• 构建流程集成：可无缝集成到CI/CD构建流程或构建工具（如Cloud Native Buildpacks、Buildpacks等）中

使用场景和适用范围

• 镜像元数据标准化：需要为组织内所有镜像统一添加标准OCI元数据标签的场景，确保镜像元数据一致性
• CI/CD自动化构建：在持续集成流程中，根据构建环境变量（如Git提交哈希、构建编号、分支名称）动态生成标签
• 多环境部署：为开发、测试、生产等不同环境的镜像添加区分性标签（如environment=production），便于镜像版本管理
• 简化标签管理：减少手动维护标签配置的工作量，降低因手动操作导致的配置错误风险

使用方法和配置说明

集成方式

该构建包需集成到支持Buildpacks规范的构建流程中，例如使用Cloud Native Buildpacks的pack CLI或平台（如Kpack、Tekton等）。在构建时指定该构建包即可启用标签设置功能。

环境变量配置

标准OCI标签

通过以OCI_LABEL_为前缀的环境变量设置标准OCI标签，格式为OCI_LABEL_<标签键>=<标签值>。支持的标准OCI标签键包括但不限于：

• org.opencontainers.image.version：镜像版本号（如1.0.0）
• org.opencontainers.image.authors：镜像作者信息（如Dev Team <dev@example.com>）
• org.opencontainers.image.description：镜像描述信息
• org.opencontainers.image.source：源代码仓库地址（如https://github.com/example/app）
• org.opencontainers.image.revision：源代码Git提交哈希（如a1b2c3d4e5f6）
• org.opencontainers.image.licenses：镜像许可证信息（如MIT）
• org.opencontainers.image.title：镜像标题
• org.opencontainers.image.url：镜像相关项目URL

示例：

bash
# 设置标准OCI标签
export OCI_LABEL_org.opencontainers.image.version="1.0.0"
export OCI_LABEL_org.opencontainers.image.authors="Dev Team <dev@example.com>"
export OCI_LABEL_org.opencontainers.image.source="https://github.com/example/my-app"
export OCI_LABEL_org.opencontainers.image.revision="a1b2c3d4e5f6"

自定义标签

通过以CUSTOM_LABEL_为前缀的环境变量设置自定义标签，格式为CUSTOM_LABEL_<标签键>=<标签值>。构建包会自动去除CUSTOM_LABEL_前缀，将剩余部分作为标签键。

示例：

bash
# 设置自定义标签
export CUSTOM_LABEL_environment="production"
export CUSTOM_LABEL_team="backend"
export CUSTOM_LABEL_build_number="1234"

上述配置会为镜像添加以下自定义标签：

• environment=production
• team=backend
• build_number=1234

构建示例

以下是使用pack CLI构建镜像并应用该构建包的示例：

bash
pack build my-app:latest \
  --builder paketobuildpacks/builder:base \
  --buildpack <init-image-labels-buildpack-url> \
  --env OCI_LABEL_org.opencontainers.image.version="1.0.0" \
  --env OCI_LABEL_org.opencontainers.image.authors="Dev Team <dev@example.com>" \
  --env CUSTOM_LABEL_environment="production" \
  --env CUSTOM_LABEL_build_number="1234"

构建完成后，可通过docker inspect my-app:latest命令查看镜像标签，确认标准OCI标签和自定义标签已正确添加。

注意事项

• 环境变量值中若包含特殊字符（如空格、引号），需按Shell语法进行转义
• 标签键应符合OCI规范，避免使用特殊字符（推荐使用字母、数字、点、连字符和下划线）
• 若未设置某标签环境变量，则该标签不会被添加到镜像中