配置自定义证书

面向管理员

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

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

本指南介绍如何配置 PAC,使其能够与使用自签名证书或自定义 CA 证书的 Git 托管服务协同工作,例如 GitHub Enterprise 或自托管 GitLab。

先决条件

在配置自定义证书之前,请确保具备以下条件:

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

概述

当 Git 托管服务使用自签名证书或由自定义 CA 签名的证书时,请分别为每个出站连接配置信任链:

连接功能配置
pipelines-as-code-controller -> Git provider API在 webhook 交付后获取仓库内容并报告状态。挂载 CA,并在 PAC controller 中设置 GIT_SSL_CAINFO 和 SSL_CERT_FILE。
tektoncd-enhancement-controller -> Git provider API为 PAC Repository 资源注册或更新 GitLab/GitHub webhook。挂载相同的 CA,并在 Enhancement controller 中设置 SSL_CERT_FILE(以及可选的 GIT_SSL_CAINFO)。
Git provider -> PAC webhook将 webhook 事件交付到 PAC 端点。provider 会验证 PAC 端点证书。自动注册默认启用此验证;请参阅 webhook-target-tls-verify。

这需要执行以下操作:

  1. 创建包含 CA 证书的 ConfigMap
  2. 在 PAC controller pod 中挂载证书
  3. 使用自动 webhook 注册时,在 tektoncd-enhancement-controller 中挂载相同的证书
  4. 配置 Git 和 HTTPS 客户端以使用该证书

第 1 步:准备 CA 证书

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

CA 证书的常见位置:

  • 自托管 GitLab:通常位于 GitLab 安装目录中,或由组织的 CA 提供
  • GitHub Enterprise:可从 GitHub Enterprise 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 中挂载证书

通过更新 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 时从 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 修补示例:

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
                  - name: GIT_SSL_CAINFO
                    value: /etc/ssl/certs/git-ca.crt
                volumes:
                - name: git-ca-cert
                  configMap:
                    name: git-ca-cert

本节挂载的 CA 仅用于 Enhancement controller 到 Git provider API 的连接。它不会改变 webhook payload 验证,也不会改变 Git provider 调用 PAC webhook 时执行的证书验证。

配置自动 webhook 注册

tektoncd-enhancement-controller 从受管理的 tektoncd-enhancement-config ConfigMap 中读取自动 webhook 注册设置。请通过 TektonConfig 配置该 ConfigMap;不要直接编辑受管理的 ConfigMap:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        tektoncd-enhancement-config:
          data:
            config: |
              pac-webhook-registration:
                enabled: true
                # Set false only when the PAC webhook certificate is not trusted
                # by the Git provider (for example, in a non-production cluster).
                webhook-target-tls-verify: false

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:

kubectl apply -f your-tektonconfig-file.yaml

示例输出:

tektonconfig.operator.tekton.dev/config configured

CR 更新后,Operator 会协调受管理的 ConfigMap 和部署。pac-webhook-registration.* 设置会热加载,无需执行滚动更新;更改 CA 卷或环境变量则需要重启相应的 controller 部署。请根据需要检查受影响的部署:

kubectl rollout status deployment/pipelines-as-code-controller -n <pac-namespace>  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
kubectl rollout status deployment/tektoncd-enhancement-controller -n <pac-namespace>

示例输出:

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 卷是本指南添加的卷;每个 PAC controller pod 中都会存在 tls:

[
  {
    "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 时,就会出现这种情况。

你应看到卷配置,其中显示证书已挂载。

检查 Enhancement controller 配置

验证受管理的 Enhancement ConfigMap 是否包含预期的注册设置,以及 controller pod 是否具有 CA 环境变量:

kubectl get configmap tektoncd-enhancement-config -n <pac-namespace> -o yaml
kubectl get deployment tektoncd-enhancement-controller -n <pac-namespace> \
  -o jsonpath='{.spec.template.spec.containers[?(@.name=="manager")].env}'

pac-webhook-registration.webhook-target-tls-verify 值应位于上面所示的 ConfigMap 数据中。CA 路径应位于 Enhancement controller 环境中,并且这两个设置都通过 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 证书错误。

对于自动 webhook 注册,请单独检查 Enhancement controller 日志:

kubectl logs -n <pac-namespace> \
  -l app=tektoncd-enhancement-controller \
  --tail=100 | grep -Ei 'x509|certificate|tls|webhook|ProviderAPIError'

这些日志中的 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 服务上的存储库触发测试流水线:

# 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 服务。

解决方案:

  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  # 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 证书已过期。

解决方案:

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

  2. 更新 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
  3. 重启 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 证书。

解决方案:

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

Pod 未重启

问题:更新 TektonConfig 后,PAC controller 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"}
  1. 手动重启 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 使用证书捆绑包:

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 controller 日志中的证书错误
  • 备份:保留有效证书配置的备份副本

后续步骤