配置自定义证书

面向管理员

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

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

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

前提条件

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

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

概述

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

  • pipelines-as-code-controller:用于获取仓库内容,并在 webhook 投递后报告状态。
  • 自动 webhook 注册 controller:通过调用 Git provider API 来注册或更新 GitLab/GitHub webhook。

这需要以下操作:

  1. 创建包含 CA 证书的 ConfigMap
  2. 在 PAC controller pod 中挂载证书
  3. 在使用自动 webhook 注册时,将同一证书挂载到自动 webhook 注册 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 中挂载证书

通过更新 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

对于自动 webhook 注册

如果你在 GitLab 或 GitHub Webhook 模式下使用自动 webhook 注册,请将相同的 CA bundle 挂载到自动 webhook 注册 controller 中,并设置 SSL_CERT_FILE。该 controller 由 TektonConfig 管理,因此应更新 spec.pipeline.options.deployments,而不是直接 patch Deployment。若未设置 SSL_CERT_FILE,该 controller 也会使用 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 仅用于 controller 与 Git provider API 之间的连接。它不会更改 webhook payload 验证。

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

第 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"
    }
  }
]

你应该能够看到卷配置,表明证书已挂载。

检查 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 服务上的仓库触发一个测试流水线:

# 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 未重启

问题:更新 CR 后,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 使用证书 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 日志中的证书错误
  • 备份:保留可正常工作的证书配置备份副本

后续步骤