initializbuildpacks/ca-certificates

CA Certificates 构建包

概述和主要用途

CA Certificates是一个符合Cloud Native Buildpacks规范的构建包，旨在简化将自定义CA证书添加到应用程序容器系统信任存储的过程。它支持在构建阶段和运行阶段自动配置CA证书，确保应用程序能够信任自定义证书颁发机构（CA）颁发的证书，适用于需要自定义证书信任的云原生应用场景。

核心功能和特性

• 双阶段证书配置：同时支持在构建时和运行时添加CA证书，满足应用构建过程和运行时对证书信任的不同需求
• 跨系统适配：自动识别并适配主流操作系统（如Alpine、Debian、Ubuntu等）的信任存储路径
• 无缝集成：与Cloud Native Buildpacks生态系统深度整合，支持Buildpacks v3及以上规范
• PEM格式支持：原生支持PEM格式证书文件，自动解析并添加到系统信任位置
• 零配置默认值：提供合理的默认配置，无需额外设置即可快速使用

使用场景和适用范围

• 企业内网环境：应用程序需要与使用企业内部CA颁发证书的服务通信时
• 私有云部署：在私有云或混合云环境中，服务使用自定义CA证书进行TLS加密时
• 开发测试环境：开发或测试阶段使用自签名证书或私有CA证书时
• 合规性要求：满足特定行业合规标准，需要严格控制证书信任链的场景
• 代理环境：应用程序通过需要证书验证的代理服务器访问外部资源时

使用方法和配置说明

基本使用流程

1. 在应用程序项目根目录创建证书目录（默认路径：ca-certificates）
2. 将PEM格式的CA证书文件放入该目录（文件扩展名必须为.pem）
3. 使用支持Cloud Native Buildpacks的构建工具（如pack、Tekton等）构建应用镜像

配置参数

构建示例

使用pack命令构建

bash
# 创建证书目录并添加证书
mkdir -p ca-certificates
cp /path/to/your/custom-ca.pem ca-certificates/

# 使用默认builder构建应用
pack build my-app \
  --builder paketobuildpacks/builder:base \
  --path ./my-app-source

自定义证书路径

bash
# 使用自定义证书目录
pack build my-app \
  --builder paketobuildpacks/builder:base \
  --path ./my-app-source \
  --env BP_CA_CERTS_PATH=/app/config/certs

与docker-compose集成

yaml
version: '3.8'
services:
  app-builder:
    image: paketobuildpacks/builder:base
    volumes:
      - ./my-app-source:/app
      - ./custom-certs:/app/custom-certs
    command: >
      pack build my-app:latest 
      --path /app 
      --env BP_CA_CERTS_PATH=/app/custom-certs

注意事项

• 证书文件必须具有正确的文件权限（构建用户需要读取权限）
• 证书文件必须是有效的PEM格式，包含完整的证书链（如有多层CA）
• 构建包会覆盖系统默认信任存储中的同名证书，建议使用唯一的证书文件名
• 对于多阶段构建，构建时添加的证书仅影响构建阶段，运行时证书需单独配置

验证证书配置

构建完成后，可通过以下方式验证证书是否已正确添加：

bash
# 运行构建好的镜像
docker run --rm my-app:latest sh -c "cat /etc/ssl/certs/ca-certificates.crt | grep 'Your CA Common Name'"

若命令输出包含您的CA证书_common name_，则表示证书已成功添加到系统信任存储。