配置自定义证书
供管理员使用
本指南适用于需要配置 PAC 以信任 Git 提供程序的自签名证书或自定义 CA 证书的集群管理员。
注意：在本文档中，<pac-namespace> 或 tekton-pipelines 指 PAC 部署所在的命名空间。默认命名空间是 tekton-pipelines，但你可以通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义。如果不同，请将 <pac-namespace> 或 tekton-pipelines 替换为你的实际命名空间名称。
本指南说明如何配置 PAC 以配合使用自签名证书或由自定义 CA 签名的证书的 Git 托管服务。此配置适用于所有 Git 提供程序（GitHub Enterprise、GitLab self-hosted、Bitbucket Server 等）。
前提条件
在配置自定义证书之前，请确保你已具备：
- 已部署 PAC 组件
- 对集群的管理员访问权限
- CA 证书文件的访问权限
- 能够修改
OpenShiftPipelinesAsCode CR 或 TektonConfig CR
概览
当你的 Git 托管服务使用自签名证书或由自定义 CA 签名的证书时，PAC 的 controller pod 需要信任这些证书，才能成功连接到 Git 服务。这需要：
- 创建一个包含 CA 证书的 ConfigMap
- 将证书挂载到 PAC controller pod 中
- 配置 Git 使用该证书
第 1 步：准备 CA 证书
从你的 Git 托管服务管理员或组织的证书颁发机构获取 CA 证书文件。
CA 证书的常见位置：
- self-hosted GitLab：通常可在 GitLab 安装中获取，或从你组织的 CA 获取
- GitHub Enterprise：可从你的 GitHub Enterprise Server 管理员处获取
- Bitbucket Server：可从你的 Bitbucket Server 管理员处获取
证书文件应为 PEM 格式：
-----BEGIN CERTIFICATE-----
<certificate-content>
-----END CERTIFICATE-----
第 2 步：创建包含 CA 证书的 ConfigMap
在 PAC 命名空间中创建一个包含 CA 证书的 ConfigMap（默认：tekton-pipelines，如果不同请替换为你的实际 PAC 命名空间）：
方法 1：从文件创建
kubectl create configmap git-ca-cert \
--from-file=ca.crt=/path/to/ca.crt \
-n <pac-namespace> # Default: tekton-pipelines
示例输出：
configmap/git-ca-cert created
方法 2：手动创建
创建一个 YAML 文件 git-ca-cert-configmap.yaml：
apiVersion: v1
kind: ConfigMap
metadata:
name: git-ca-cert
namespace: <pac-namespace> # Default: tekton-pipelines
data:
ca.crt: |
-----BEGIN CERTIFICATE-----
<your-ca-certificate-content>
-----END CERTIFICATE-----
应用它：
kubectl apply -f git-ca-cert-configmap.yaml
示例输出：
configmap/git-ca-cert created
注意：将 <your-ca-certificate-content> 替换为实际的证书内容。
第 3 步：在 PAC Controller 中挂载证书
通过更新 OpenShiftPipelinesAsCode CR 或 TektonConfig CR，将证书挂载到 PAC controller pod 中。
对于 OpenShiftPipelinesAsCode CR
如果你正在使用 OpenShiftPipelinesAsCode CR：
apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
name: pipelines-as-code
spec:
settings:
application-name: Pipelines as Code CI
hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
targetNamespace: tekton-pipelines # Default namespace, you can customize this
options:
deployments:
pipelines-as-code-controller:
spec:
template:
spec:
containers:
- name: pac-controller
volumeMounts:
- name: git-ca-cert
mountPath: /etc/ssl/certs/git-ca.crt
subPath: ca.crt
readOnly: true
env:
- name: GIT_SSL_CAINFO
value: /etc/ssl/certs/git-ca.crt
- name: SSL_CERT_FILE
value: /etc/ssl/certs/git-ca.crt
volumes:
- name: git-ca-cert
configMap:
name: git-ca-cert
对于 TektonConfig CR
如果你正在使用 TektonConfig CR（适用于 OpenShift 部署）：
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
platforms:
openshift:
pipelinesAsCode:
enable: true
options:
deployments:
pipelines-as-code-controller:
spec:
template:
spec:
containers:
- name: pac-controller
volumeMounts:
- name: git-ca-cert
mountPath: /etc/ssl/certs/git-ca.crt
subPath: ca.crt
readOnly: true
env:
- name: GIT_SSL_CAINFO
value: /etc/ssl/certs/git-ca.crt
- name: SSL_CERT_FILE
value: /etc/ssl/certs/git-ca.crt
volumes:
- name: git-ca-cert
configMap:
name: git-ca-cert
重要：
- 证书会挂载到容器中的
/etc/ssl/certs/git-ca.crt
- 环境变量
GIT_SSL_CAINFO 和 SSL_CERT_FILE 会告诉 Git 使用此证书
- 更新 CR 后，Operator 会自动重启 PAC controller pod
第 4 步：应用配置
应用更新后的 CR：
kubectl apply -f your-cr-file.yaml
示例输出：
openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code configured
等待 PAC controller pod 重启：
kubectl rollout status deployment/pipelines-as-code-controller -n <pac-namespace> # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
示例输出：
Waiting for deployment "pipelines-as-code-controller" rollout to finish: 0 of 1 updated replicas are available...
deployment "pipelines-as-code-controller" successfully rolled out
第 5 步：验证证书配置
检查证书是否已挂载
验证证书是否已挂载到 PAC controller pod 中：
# Set your PAC namespace (default: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"
kubectl get pod -n ${PAC_NAMESPACE} \
-l app=pipelines-as-code-controller \
-o jsonpath='{.items[0].spec.volumes}' | jq
示例输出：
[
{
"name": "tls",
"secret": {
"defaultMode": 420,
"optional": true,
"secretName": "pipelines-as-code-tls-secret"
}
}
]
你应该能看到显示证书已挂载的 volume 配置。
检查 PAC Controller 日志
检查 PAC controller 日志中是否存在任何与证书相关的错误：
# Set your PAC namespace (default: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"
kubectl logs -n ${PAC_NAMESPACE} \
-l app=pipelines-as-code-controller \
--tail=100
如果配置正确，你不应在日志中看到 SSL/TLS 证书错误。
使用仓库进行测试
从托管在你的 Git 服务上的仓库触发一个测试 pipeline：
# Push a commit to trigger the pipeline
git commit --allow-empty -m "Test certificate configuration"
git push origin main
示例输出：
[main abc1234] Test certificate configuration
Enumerating objects: 3, done.
Writing objects: 100% (2/2), 240 bytes | 240.00 KiB/s, done.
To https://gitlab.example.com/user/repo
def5678..abc1234 main -> main
检查是否成功创建了 PipelineRun：
kubectl get pipelineruns -n <your-namespace>
示例输出：
NAME STARTED DURATION STATUS
test-pipeline-xxxxx 1 minute ago 25s Succeeded
故障排除
检查证书是否不受信任
问题：由于证书问题，PAC 仍然无法连接到你的 Git 服务。
解决方案：
- 验证证书格式：确保证书为 PEM 格式，并包含正确的 BEGIN/END 标记
- 检查证书路径：确认证书挂载到了正确的路径
- 验证环境变量：确保
GIT_SSL_CAINFO 和 SSL_CERT_FILE 设置正确
- 检查 ConfigMap：验证 ConfigMap 是否存在并包含证书：
kubectl get configmap git-ca-cert -n <pac-namespace> -o yaml # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
示例输出：
apiVersion: v1
data:
ca.crt: |
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAK...
-----END CERTIFICATE-----
kind: ConfigMap
metadata:
name: git-ca-cert
namespace: tekton-pipelines
检查证书是否已过期
问题：CA 证书已过期。
解决方案：
-
从证书颁发机构获取新的 CA 证书
-
更新 ConfigMap：
# Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
kubectl create configmap git-ca-cert \
--from-file=ca.crt=/path/to/new-ca.crt \
-n <pac-namespace> \
--dry-run=client -o yaml | kubectl apply -f -
示例输出：
configmap/git-ca-cert configured
-
重启 PAC controller pod：
kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace> # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
证书错误
问题：为你的 Git 服务使用了错误的 CA 证书。
解决方案：
- 验证你使用的是该 Git 托管服务的正确 CA 证书
- 对于 self-hosted 服务，直接从该服务获取证书
- 对于企业服务，请联系你的管理员获取正确的证书
Pod 未重启
问题：更新 CR 后，PAC controller pod 没有重启。
解决方案：
-
检查 CR 状态：
kubectl get openshiftpipelinesascodes
示例输出：
NAME VERSION READY REASON
pipelines-as-code 0.x.x True Ready
-
检查 Operator 日志：
kubectl logs -n tekton-operator -l app=tekton-operator --tail=100
示例输出（示例日志条目）：
{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"operator","msg":"Processing OpenShiftPipelinesAsCode CR"}
- 手动重启 deployment：
kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace> # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
多个证书
如果你需要信任多个 CA 证书（例如多个 Git 托管服务），可以：
选项 1：在单个 ConfigMap 中合并证书
将多个证书合并到单个文件中：
apiVersion: v1
kind: ConfigMap
metadata:
name: git-ca-cert
namespace: <pac-namespace> # Default: tekton-pipelines
data:
ca.crt: |
-----BEGIN CERTIFICATE-----
<certificate-1-content>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<certificate-2-content>
-----END CERTIFICATE-----
选项 2：使用独立的 ConfigMap
使用独立的 ConfigMap 并将它们挂载到不同位置，然后配置 Git 使用证书 bundle：
env:
- name: GIT_SSL_CAINFO
value: /etc/ssl/certs/ca-bundle.crt
- name: SSL_CERT_FILE
value: /etc/ssl/certs/ca-bundle.crt
通过将所有证书合并为一个文件来创建证书 bundle。
最佳实践
1. 证书管理
- 安全存储：将 CA 证书保存在安全存储中
- 版本控制：跟踪证书变更并纳入版本控制（如果不涉及敏感信息）
- 文档记录：记录使用了哪些证书及其来源
- 过期跟踪：监控证书到期时间
2. 安全性
- 最小权限：仅授予必要证书的访问权限
- 轮换：定期轮换证书
- 验证：在部署前验证证书
3. 故障排除
- 先测试：在应用到生产环境之前，先使用测试仓库测试证书配置
- 监控日志：定期检查 PAC controller 日志中的证书错误
- 备份：保留可用证书配置的备份副本
下一步
