配置自定义证书

适用于管理员

本指南适用于需要配置 PAC 以信任 Git 提供方的自签名证书或自定义 CA 证书的 集群管理员。

注意：在本文档中，<pac-namespace> 或 tekton-pipelines 指 PAC 部署所在的 namespace。默认 namespace 为 tekton-pipelines，但你可以通过 TektonConfig CR 中的 targetNamespace 进行自定义。如果实际 namespace 不同，请将 <pac-namespace> 或 tekton-pipelines 替换为你的实际 namespace 名称。

本指南说明如何配置 PAC 以配合使用自签名证书或自定义 CA 证书的 Git 托管服务，例如 GitHub Enterprise 或自托管 GitLab。

前提条件

在配置自定义证书之前，请确保你具备以下条件：

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

概述

当你的 Git 托管服务使用自签名证书或由自定义 CA 签发的证书时，两个 controller 客户端可能都需要信任该 CA：

pipelines-as-code-controller，它会拉取 repository 内容，并在 webhook 投递后报告状态。
自动 webhook 注册控制器，它通过调用 Git 提供方 API 来注册或更新 GitLab/GitHub webhook。

这需要执行以下操作：

使用 CA 证书创建一个 ConfigMap
将证书挂载到 PAC controller Pod 中
在使用自动 webhook 注册时，将相同的证书挂载到自动 webhook 注册控制器中
配置 Git 和 HTTPS 客户端使用该证书

第 1 步：准备 CA 证书

从你的 Git 托管服务管理员处或组织的 certificate authority 获取 CA 证书文件。

常见的 CA 证书位置：

自托管 GitLab：通常可在 GitLab 安装中找到，或从你组织的 CA 获取
GitHub Enterprise：可从你的 GitHub Enterprise Server 管理员处获取

证书文件应为 PEM 格式：

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

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

在 PAC namespace 中创建一个包含 CA 证书的 ConfigMap（默认值：tekton-pipelines，如果实际 PAC namespace 不同，请替换为你的实际值）：

方法 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 中挂载证书

通过更新 TektonConfig CR，将证书挂载到 PAC controller Pod 中。

对于 `TektonConfig` CR

在 Kubernetes 集群上，PAC 选项位于 platforms.kubernetes 下。Operator 会拒绝在此处使用 platforms.openshift，并且会在 OpenShift 上拒绝使用 platforms.kubernetes：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        options:
          disabled: false
          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

不要将此块放到派生的 OpenShiftPipelinesAsCode CR 中。Operator 会在每次 reconcile 时将 options 从 TektonConfig 重新复制回去，因此挂载会再次消失。唯一的例外是 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 挂载到自动 webhook 注册控制器中，并设置 SSL_CERT_FILE。该控制器由 TektonConfig 管理，因此请更新 spec.pipeline.options.deployments，而不是直接 patch Deployment。若未设置 SSL_CERT_FILE，该控制器也会使用 GIT_SSL_CAINFO。

示例 TektonConfig patch：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      deployments:
        tektoncd-enhancement-controller:
          spec:
            template:
              spec:
                containers:
                - name: manager
                  volumeMounts:
                  - name: git-ca-cert
                    mountPath: /etc/ssl/certs/git-ca.crt
                    subPath: ca.crt
                    readOnly: true
                  env:
                  - name: SSL_CERT_FILE
                    value: /etc/ssl/certs/git-ca.crt
                volumes:
                - name: git-ca-cert
                  configMap:
                    name: git-ca-cert

CA 仅用于控制器到 Git 提供方 API 的连接，不会改变 webhook payload 验证。

如果你的 PAC webhook URL 本身使用自签名证书，那么 Git 提供方在调用 PAC 时也必须信任该证书。默认情况下，自动注册会启用提供方侧 TLS 验证。对于非生产环境，管理员可以通过 TektonConfig 设置 pac-webhook-registration.webhook-target-tls-verify: false；在生产环境中应保持启用。

第 4 步：应用配置

应用更新后的 TektonConfig：

kubectl apply -f your-tektonconfig-file.yaml

示例输出：

tektonconfig.operator.tekton.dev/config 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

示例输出 — git-ca-cert 卷是本指南新增的卷；tls 存在于每个 PAC controller Pod 中：

[
  {
    "name": "git-ca-cert",
    "configMap": {
      "defaultMode": 420,
      "name": "git-ca-cert"
    }
  },
  {
    "name": "tls",
    "secret": {
      "defaultMode": 420,
      "optional": true,
      "secretName": "pipelines-as-code-tls-secret"
    }
  }
]

如果只列出了 tls，则说明 Operator 还未应用该挂载，或者它从未到达 Deployment；这种情况通常是因为 options 块被写到了派生 CR 上，而不是写到 TektonConfig 上。

你应该能看到显示证书已挂载的卷配置。

检查 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 证书错误。

使用 repository 进行测试

从托管在你的 Git 服务上的 repository 触发一个测试 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 证书已过期。

解决方案：

从你的 certificate authority 获取新的 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 证书
对于自托管服务，请直接从该服务获取证书
对于企业服务，请联系你的管理员获取正确的证书

Pod 未重启

问题：更新 TektonConfig 后，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. 故障排除

先测试：在应用到生产环境之前，先使用测试 repository 测试证书配置
监控日志：定期检查 PAC controller 日志中的证书错误
备份：保留可用证书配置的备份副本

下一步

为 PAC 创建 Git Secret - 设置 Git 提供方凭据
管理 PAC 组件 - 了解如何管理 PAC 部署
配置 GitHub repository - GitHub 特定配置指南
配置 GitLab repository - GitLab 特定配置指南
常见问题 - 故障排除指南

#配置自定义证书

#目录

#前提条件

#概述

#第 1 步：准备 CA 证书

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

#方法 1：从文件创建

#方法 2：手动创建

#第 3 步：在 PAC Controller 中挂载证书

#对于 TektonConfig CR

#对于自动 webhook 注册

#第 4 步：应用配置

#第 5 步：验证证书配置

#检查证书是否已挂载

#检查 PAC Controller 日志

#使用 repository 进行测试

#故障排除

#检查证书是否未受信任

#检查证书是否已过期

#错误的证书

#Pod 未重启

#多个证书

#选项 1：在单个 ConfigMap 中合并证书

#选项 2：使用单独的 ConfigMap

#最佳实践

#1. 证书管理

#2. 安全性

#3. 故障排除

#下一步

配置自定义证书

目录

前提条件

概述

第 1 步：准备 CA 证书

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

方法 1：从文件创建

方法 2：手动创建

第 3 步：在 PAC Controller 中挂载证书

对于 `TektonConfig` CR

对于自动 webhook 注册

第 4 步：应用配置

第 5 步：验证证书配置

检查证书是否已挂载

检查 PAC Controller 日志

使用 repository 进行测试

故障排除

检查证书是否未受信任

检查证书是否已过期

错误的证书

Pod 未重启

多个证书

选项 1：在单个 ConfigMap 中合并证书

选项 2：使用单独的 ConfigMap

最佳实践

1. 证书管理

2. 安全性

3. 故障排除

下一步