通过 TektonConfig 配置增强功能

本指南介绍如何通过 TektonConfig 使用 spec.pipeline.options.configMaps 管理增强功能配置。

对于使用自签名或私有 CA 的 Git provider,请将 Enhancement 和 PAC controller 的 CA 信任配置与 provider 端 webhook 验证设置分开配置。有关完整的证书挂载示例,请参阅配置自定义证书。

命名空间说明:在本指南中,<tekton-pipelines> 用作 Tekton 命名空间的占位符。请将其替换为实际的命名空间名称。默认安装使用 tekton-pipelines 命名空间。

前提条件

  • 已安装 Tekton Operator。
  • TektonConfig 资源存在(通常命名为 config)。
  • 您可以在集群中编辑 TektonConfig。

步骤

1. 使用 spec.pipeline.options.configMaps 更新 TektonConfig

选项结构遵循调整子组件的可选配置项中所述的相同模式。

使用如下 TektonConfig patch:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: <tekton-pipelines>
  pipeline:
    options:
      configMaps:
        tektoncd-enhancement-config:
          data:
            config: |
              # Shared configuration for enhancement features.
              template-render:
                # Template to build the details URL.
                details-url-template: "{{- if .isPipelineRun -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/pipelineRuns/detail/{{ .pipelineRunName }}{{- else -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/taskRuns/detail/{{ .taskRunName }}{{- end -}}"
                # Empty value means using the container local time zone.
                time-zone: ""
              pac-webhook-registration:
                # Register GitLab/GitHub webhooks for PAC Repository resources.
                # The default is true. Setting this to false deletes webhooks
                # previously managed by tektoncd-enhancement.
                enabled: true
                # Keep enabled in production. This controls Git provider -> PAC
                # webhook delivery only; it does not disable controller -> Git
                # provider API TLS verification.
                webhook-target-tls-verify: true

2. 参数参考和默认值

参数含义默认值
template-render.details-url-template用于为邮件/模板渲染上下文渲染 detailsURL 的 Go 模板。{{- if .isPipelineRun -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/pipelineRuns/detail/{{ .pipelineRunName }}{{- else -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/taskRuns/detail/{{ .taskRunName }}{{- end -}}
template-render.time-zone用于模板渲染的全局时区设置。""(使用容器本地时区)
pac-webhook-registration.enabled为 PAC Repository 资源启用 GitLab/GitHub webhook 自动注册。设置为 false 时,controller 会删除之前管理的 provider webhook,并将 Repository 标记为 Disabled。true
pac-webhook-registration.webhook-target-tls-verifyGitLab 或 GitHub 在传递事件时是否验证 PAC webhook URL 证书。此设置仅影响 provider -> PAC webhook 连接;不影响从 tektoncd-enhancement-controller 或 pipelines-as-code-controller 到 Git provider API 的 TLS 验证。true

PAC webhook 注册从 pipelines-as-code-info.data.controller-url 读取公开 webhook URL。请通过 PAC 组件选项配置该值;参阅获取 PAC Webhook URL。

要使用 webhook 自动注册,请将每个 PAC Repository spec.git_provider.type 设置为 github 或 gitlab。不支持的类型所对应的 Repository 将被跳过,原因会记录为 Repository Event 和状态注释。

如果 Git provider 无法验证自签名 PAC webhook 证书,请仅在非生产环境中设置 webhook-target-tls-verify: false。此设置无法解决 Enhancement controller 中的 x509 或 certificate signed by unknown authority 错误;请挂载 Git provider CA,并按照配置自定义证书中的说明设置 SSL_CERT_FILE/GIT_SSL_CAINFO。

WARNING

将 pac-webhook-registration.enabled 设置为 false 不仅会暂停后续注册,还会删除之前由 enhancement controller 创建或更新的 Git provider webhook。将其改回 true,以便 controller 再次协调符合条件的 PAC Repository 资源,并重新创建或更新其 webhook。

对于处于活动状态的 Repository 资源,必须先完成清理,controller 才会移除所管理的 webhook 注释和 finalizer。如果凭证缺失或 provider API 暂时无法访问,请修复凭证或 provider 访问问题,controller 会重试。删除 Repository 则有所不同:provider 清理采用尽力而为策略,因此在记录清理警告后即可移除 Kubernetes finalizer。

3. 验证 ConfigMap 更新

更新 TektonConfig 后,检查所管理的 ConfigMap 是否已完成协调:

kubectl get configmap tektoncd-enhancement-config -n <tekton-pipelines> -o yaml

Tekton Operator 会应用来自 TektonConfig 的配置。请勿直接更新所管理的 Deployment 或 ConfigMap,因为这些更改可能会在下一次协调时被覆盖。

4. 重启 controller 以应用启动时加载的设置

pac-webhook-registration.* 设置会在 ConfigMap 更新后热加载。template-render.* 设置会在 enhancement controller 启动时加载,因此在更改 template-render.details-url-template 或 template-render.time-zone 后,请重启 tektoncd-enhancement-controller:

kubectl rollout restart deployment tektoncd-enhancement-controller -n <tekton-pipelines>
kubectl rollout status deployment tektoncd-enhancement-controller -n <tekton-pipelines>

常见问题

我更新了 TektonConfig,但生效的配置没有变化。应该检查什么?

请按以下顺序检查:

  1. TektonConfig 是否已成功更新。
  2. 命名空间 <tekton-pipelines> 中的 tektoncd-enhancement-config 是否包含预期的 data.config。
  3. Tekton Operator 是否已协调最新的 TektonConfig。
  4. 如果更改了任何 template-render.* 设置,请确认 ConfigMap 更新后已重启 tektoncd-enhancement-controller。

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

kubectl logs -n <tekton-pipelines> \
  -l app=tektoncd-enhancement-controller \
  --tail=100

x509 或 certificate signed by unknown authority 错误表示 controller 到 Git provider 的 API 连接存在问题。在 GitLab 或 GitHub 中 webhook 传送测试失败,则表示 provider 到 PAC 的连接存在问题,应结合 pac-webhook-registration.webhook-target-tls-verify 和 PAC webhook 证书进行调查。