#Configure Custom Certificates

本指南介绍如何配置 PAC 以支持使用自签名证书或自定义 CA 证书的 Git 托管服务。此配置适用于所有 Git 提供商（GitHub Enterprise、GitLab 自托管、Bitbucket Server 等）。

#前提条件

在配置自定义证书之前，请确保您已具备：

• 已部署 PAC 组件
• 集群管理员权限
• 可访问 CA 证书文件
• 能够修改 OpenShiftPipelinesAsCode CR 或 TektonConfig CR

#概述

当您的 Git 托管服务使用自签名证书或由自定义 CA 签发的证书时，PAC 的控制器 Pod 需要信任这些证书，才能成功连接到 Git 服务。此过程包括：

1. 创建包含 CA 证书的 ConfigMap
2. 在 PAC 控制器 Pod 中挂载该证书
3. 配置 Git 使用该证书

#第 1 步：准备 CA 证书

从您的 Git 托管服务管理员或组织的证书颁发机构获取 CA 证书文件。

CA 证书常见位置：

• 自托管 GitLab：通常可在 GitLab 安装目录或组织的 CA 中获得
• GitHub Enterprise：可向 GitHub Enterprise 服务器管理员获取
• Bitbucket Server：可向 Bitbucket Server 管理员获取

证书文件应为 PEM 格式：

-----BEGIN CERTIFICATE-----
<certificate-content>
-----END CERTIFICATE-----

#第 2 步：创建包含 CA 证书的 ConfigMap

在 PAC 命名空间（默认：tekton-pipelines，如果不同请替换为实际命名空间）中创建包含 CA 证书的 ConfigMap：

#方法 1：从文件创建

kubectl create configmap git-ca-cert \
  --from-file=ca.crt=/path/to/ca.crt \
  -n <pac-namespace>  # 默认：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>  # 默认：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 控制器中挂载证书

通过更新 OpenShiftPipelinesAsCode CR 或 TektonConfig CR，将证书挂载到 PAC 控制器 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  # 默认命名空间，可自定义
  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 控制器 Pod

#第 4 步：应用配置

应用更新后的 CR：

kubectl apply -f your-cr-file.yaml

示例输出：

openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code configured

等待 PAC 控制器 Pod 重启：

kubectl rollout status deployment/pipelines-as-code-controller -n <pac-namespace>  # 将 <pac-namespace> 替换为实际命名空间（默认：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 控制器 Pod：

# 设置 PAC 命名空间（默认：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"
    }
  }
]

您应能看到包含证书挂载的卷配置。

#查看 PAC 控制器日志

检查 PAC 控制器日志中是否有证书相关错误：

# 设置 PAC 命名空间（默认：tekton-pipelines）
PAC_NAMESPACE="tekton-pipelines"

kubectl logs -n ${PAC_NAMESPACE} \
  -l app=pipelines-as-code-controller \
  --tail=100

如果配置正确，日志中不应出现 SSL/TLS 证书错误。

#使用仓库测试

从托管在您的 Git 服务上的仓库触发测试流水线：

# 提交空提交以触发流水线
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 服务，提示证书问题。

解决方案：

1. 验证证书格式：确保证书为 PEM 格式，包含正确的 BEGIN/END 标记

2. 检查证书路径：确认证书挂载路径正确

3. 验证环境变量：确保 GIT_SSL_CAINFO 和 SSL_CERT_FILE 设置正确

4. 检查 ConfigMap：确认 ConfigMap 存在且包含证书内容：

   kubectl get configmap git-ca-cert -n <pac-namespace> -o yaml  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

示例输出：

apiVersion: v1
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDXTCCAkWgAwIBAgIJAK...
    -----END CERTIFICATE-----
kind: ConfigMap
metadata:
  name: git-ca-cert
  namespace: tekton-pipelines

#检查证书是否过期

问题：CA 证书已过期。

解决方案：

1. 从证书颁发机构获取新的 CA 证书

2. 更新 ConfigMap：

   # 将 <pac-namespace> 替换为实际命名空间（默认：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

3. 重启 PAC 控制器 Pod：

   kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace>  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

#证书错误

问题：使用了错误的 CA 证书。

解决方案：

1. 确认使用的是正确的 Git 托管服务的 CA 证书
2. 对于自托管服务，从服务端直接获取证书
3. 对于企业服务，联系管理员获取正确证书

#Pod 未重启

问题：更新 CR 后 PAC 控制器 Pod 未重启。

解决方案：

1. 检查 CR 状态：

   kubectl get openshiftpipelinesascodes

   示例输出：

   NAME                  VERSION   READY   REASON
   pipelines-as-code    0.x.x     True    Ready

2. 查看 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"}

3. 手动重启部署：

   kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace>  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

#多个证书

如果需要信任多个 CA 证书（例如多个 Git 托管服务），您可以：

#方案 1：将多个证书合并到单个 ConfigMap

将多个证书合并到一个文件中：

apiVersion: v1
kind: ConfigMap
metadata:
  name: git-ca-cert
  namespace: <pac-namespace>  # 默认：tekton-pipelines
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <certificate-1-content>
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    <certificate-2-content>
    -----END CERTIFICATE-----

#方案 2：使用多个 ConfigMap

使用多个 ConfigMap，分别挂载到不同位置，然后配置 Git 使用证书捆绑包：

env:
- name: GIT_SSL_CAINFO
  value: /etc/ssl/certs/ca-bundle.crt
- name: SSL_CERT_FILE
  value: /etc/ssl/certs/ca-bundle.crt

通过将所有证书合并成一个文件创建证书捆绑包。

#最佳实践

#1. 证书管理

• 安全存储：将 CA 证书保存在安全位置
• 版本控制：跟踪证书变更（如果不敏感）
• 文档记录：记录所用证书及其来源
• 过期监控：监控证书过期时间

#2. 安全性

• 最小权限：仅授予必要的证书访问权限
• 定期轮换：定期更换证书
• 验证：部署前验证证书有效性

#3. 故障排查

• 先测试：先在测试仓库验证证书配置
• 监控日志：定期检查 PAC 控制器日志中的证书错误
• 备份：保留工作证书配置的备份

#后续步骤

• Configure Authentication for Private Repositories - 配置私有仓库认证
• Manage PAC Component - 了解 PAC 组件管理
• Configure GitLab Repository - GitLab 特定配置指南
• Common Issues - 故障排查指南