配置自定义证书
本指南适用于需要配置 PAC 以信任 Git provider 的自签名证书或自定义 CA 证书的集群管理员。
注意:在本文档中,<pac-namespace> 或 tekton-pipelines 指 PAC 部署到的命名空间。默认命名空间为 tekton-pipelines,但你可以通过 targetNamespace 在 TektonConfig CR 中自定义该命名空间。如果命名空间不同,请将 <pac-namespace> 或 tekton-pipelines 替换为实际的命名空间名称。
本指南介绍如何配置 PAC,使其能够与使用自签名证书或自定义 CA 证书的 Git 托管服务协同工作,例如 GitHub Enterprise 或自托管 GitLab。
目录
先决条件概述第 1 步:准备 CA 证书第 2 步:使用 CA 证书创建 ConfigMap方法 1:从文件创建方法 2:手动创建第 3 步:在 PAC controller 中挂载证书对于TektonConfig CR对于自动 webhook 注册配置自动 webhook 注册步骤 4:应用配置步骤 5:验证证书配置检查证书是否已挂载检查 Enhancement controller 配置检查 PAC Controller 日志使用存储库进行测试故障排除检查证书是否不受信任检查证书是否已过期证书错误Pod 未重启多个证书选项 1:在单个 ConfigMap 中合并证书选项 2:使用单独的 ConfigMap最佳实践1. 证书管理2. 安全性3. 故障排除后续步骤先决条件
在配置自定义证书之前,请确保具备以下条件:
- 已部署 PAC 组件
- 对集群具有管理员访问权限
- 可以访问 CA 证书文件
- 能够修改
TektonConfigCR
概述
当 Git 托管服务使用自签名证书或由自定义 CA 签名的证书时,请分别为每个出站连接配置信任链:
这需要执行以下操作:
- 创建包含 CA 证书的 ConfigMap
- 在 PAC controller pod 中挂载证书
- 使用自动 webhook 注册时,在
tektoncd-enhancement-controller中挂载相同的证书 - 配置 Git 和 HTTPS 客户端以使用该证书
第 1 步:准备 CA 证书
从 Git 托管服务管理员或组织的证书颁发机构获取 CA 证书文件。
CA 证书的常见位置:
- 自托管 GitLab:通常位于 GitLab 安装目录中,或由组织的 CA 提供
- GitHub Enterprise:可从 GitHub Enterprise Server 管理员处获取
证书文件应采用 PEM 格式:
第 2 步:使用 CA 证书创建 ConfigMap
在 PAC 命名空间中创建包含 CA 证书的 ConfigMap(默认为 tekton-pipelines;如果实际 PAC 命名空间不同,请替换为实际命名空间):
方法 1:从文件创建
示例输出:
方法 2:手动创建
创建 YAML 文件 git-ca-cert-configmap.yaml:
应用该文件:
示例输出:
注意:将 <your-ca-certificate-content> 替换为实际的证书内容。
第 3 步:在 PAC controller 中挂载证书
通过更新 TektonConfig CR,在 PAC controller pod 中挂载证书。
对于 TektonConfig CR
在 Kubernetes 集群上,PAC 选项位于 platforms.kubernetes 下。operator 会拒绝其中的 platforms.openshift,而在 OpenShift 上会拒绝 platforms.kubernetes:
不要将此代码块放在派生的 OpenShiftPipelinesAsCode CR 中。operator 会在每次 reconcile 时从 TektonConfig 中重新复制 options,因此挂载会再次消失。唯一的例外是 TektonConfig 完全不管理 PAC 的集群——spec.profile 为 basic 或 lite——此时应将相同的 options 代码块放在该 CR 的 spec.options 下。请参阅 Operator 如何管理 PAC。
重要事项:
- 证书会挂载到容器中的
/etc/ssl/certs/git-ca.crt - 环境变量
GIT_SSL_CAINFO和SSL_CERT_FILE会指示 Git 使用此证书 - 更新
TektonConfig后,Operator 会自动重启 PAC controller pod
对于自动 webhook 注册
如果对 GitLab 或 GitHub Webhook 模式使用自动 webhook 注册,请将相同的 CA bundle 挂载到 tektoncd-enhancement-controller,并设置 SSL_CERT_FILE。此 controller 由 TektonConfig 管理,因此请更新 spec.pipeline.options.deployments,而不是直接修补 Deployment。SSL_CERT_FILE 未设置时,此 controller 也会使用 GIT_SSL_CAINFO。
TektonConfig 修补示例:
本节挂载的 CA 仅用于 Enhancement controller 到 Git provider API 的连接。它不会改变 webhook payload 验证,也不会改变 Git provider 调用 PAC webhook 时执行的证书验证。
配置自动 webhook 注册
tektoncd-enhancement-controller 从受管理的 tektoncd-enhancement-config ConfigMap 中读取自动 webhook 注册设置。请通过 TektonConfig 配置该 ConfigMap;不要直接编辑受管理的 ConfigMap:
webhook-target-tls-verify 仅控制 GitLab 或 GitHub 在交付事件时是否验证 PAC webhook URL 证书。它不会在 tektoncd-enhancement-controller 或 pipelines-as-code-controller 调用 Git provider API 时禁用 TLS 验证。对于这些连接,请配置上述 CA 挂载和环境变量。有关完整的配置参考,请参阅通过 TektonConfig 配置 Enhancement 功能。
只要 Git provider 能够信任 PAC webhook 证书,就应在生产环境中保留 webhook-target-tls-verify: true。将其设置为 false 会降低 provider 到 PAC 连接的验证强度,不能替代安装正确的 CA 证书。
步骤 4:应用配置
应用更新后的 TektonConfig:
示例输出:
CR 更新后,Operator 会协调受管理的 ConfigMap 和部署。pac-webhook-registration.* 设置会热加载,无需执行滚动更新;更改 CA 卷或环境变量则需要重启相应的 controller 部署。请根据需要检查受影响的部署:
示例输出:
步骤 5:验证证书配置
检查证书是否已挂载
验证证书是否已挂载到 PAC controller pod 中:
示例输出 — git-ca-cert 卷是本指南添加的卷;每个 PAC controller pod 中都会存在 tls:
如果仅列出 tls,则表示 operator 尚未应用该挂载,或者该挂载从未到达 Deployment;当 options 块被写入派生 CR 而不是 TektonConfig 时,就会出现这种情况。
你应看到卷配置,其中显示证书已挂载。
检查 Enhancement controller 配置
验证受管理的 Enhancement ConfigMap 是否包含预期的注册设置,以及 controller pod 是否具有 CA 环境变量:
pac-webhook-registration.webhook-target-tls-verify 值应位于上面所示的 ConfigMap 数据中。CA 路径应位于 Enhancement controller 环境中,并且这两个设置都通过 TektonConfig 进行管理。
检查 PAC Controller 日志
检查 PAC controller 日志中是否存在任何与证书相关的错误:
如果配置正确,日志中不应出现 SSL/TLS 证书错误。
对于自动 webhook 注册,请单独检查 Enhancement controller 日志:
这些日志中的 x509: certificate signed by unknown authority 等错误表示 Enhancement controller 无法信任 Git provider API 证书。webhook-target-tls-verify: false 无法修复这些错误;请挂载正确的 CA bundle,并设置 SSL_CERT_FILE/GIT_SSL_CAINFO。
使用存储库进行测试
从托管在 Git 服务上的存储库触发测试流水线:
示例输出:
检查 PipelineRun 是否已成功创建:
示例输出:
故障排除
检查证书是否不受信任
问题:由于证书问题,PAC 仍无法连接到您的 Git 服务。
解决方案:
- 验证证书格式:确保该证书采用 PEM 格式,并包含正确的 BEGIN/END 标记
- 检查证书路径:确认该证书已挂载到正确的路径
- 验证环境变量:确保已正确设置
GIT_SSL_CAINFO和SSL_CERT_FILE - 检查 ConfigMap:确认 ConfigMap 存在且包含该证书:
示例输出:
检查证书是否已过期
问题:CA 证书已过期。
解决方案:
-
从证书颁发机构获取新的 CA 证书
-
更新 ConfigMap:
示例输出:
-
重启 PAC controller Pod:
证书错误
问题:为您的 Git 服务使用了错误的 CA 证书。
解决方案:
- 确认您使用的是适用于 Git 托管服务的正确 CA 证书
- 对于自托管服务,直接从该服务获取证书
- 对于企业服务,请联系您的管理员获取正确的证书
Pod 未重启
问题:更新 TektonConfig 后,PAC controller Pod 未重启。
解决方案:
-
检查 CR 状态:
示例输出:
-
检查 Operator 日志:
示例输出(示例日志条目):
- 手动重启 deployment:
多个证书
如果您需要信任多个 CA 证书(例如,多个 Git 托管服务的证书),可以:
选项 1:在单个 ConfigMap 中合并证书
将多个证书合并到单个文件中:
选项 2:使用单独的 ConfigMap
使用单独的 ConfigMap 并将其挂载到不同的位置,然后配置 Git 使用证书捆绑包:
通过将所有证书合并到单个文件中来创建证书捆绑包。
最佳实践
1. 证书管理
- 安全存储:将 CA 证书保存在安全的存储中
- 版本控制:在版本控制系统中跟踪证书变更(如果证书不敏感)
- 文档记录:记录所使用的证书及其来源
- 过期跟踪:监控证书的过期日期
2. 安全性
- 最小权限:仅授予访问必要证书的权限
- 轮换:定期轮换证书
- 验证:在部署前验证证书
3. 故障排除
- 先进行测试:在应用于生产环境之前,先使用测试仓库测试证书配置
- 监控日志:定期检查 PAC controller 日志中的证书错误
- 备份:保留有效证书配置的备份副本
后续步骤
- 为 PAC 创建 Git Secret - 设置 Git provider 凭据
- 管理 PAC Component - 了解如何管理 PAC 部署
- 配置 GitHub Repository - GitHub 专用配置指南
- 配置 GitLab Repository - GitLab 专用配置指南
- 通过 TektonConfig 配置 Enhancement 功能 - 自动 webhook 注册设置
- 常见问题 - 故障排除指南