高级 Repository 配置
本指南面向需要高级 Repository CR 配置的普通用户,例如并发限制、源分支设置和自定义参数展开。
本指南介绍 Repository Custom Resource 的高级配置选项,包括:
- 用于自动配置继承的全局 Repository CR(技术预览)
- 并发限制
- 源分支配置
- 自定义参数展开
目录
先决条件创建全局 Repository CR示例:全局 Repository CR示例:使用全局设置停止使用全局 Repository CR设置并发限制配置并发限制使用场景示例验证并发限制更改 Pipeline 定义的源分支配置 PipelineRun 定义源设置的作用配置比较自定义参数扩展定义自定义参数在流水线中使用自定义参数参数优先级示例:特定环境的配置组合使用高级功能最佳实践1. 并发限制2. 源分支配置3. 自定义参数故障排除并发限制不起作用参数未展开后续步骤先决条件
- PAC 组件已部署并正在运行
- 已创建 Repository CR(参见 指南)
- 对于引用 Secret
my-repo-auth的 Repository 示例:在 Repository 的命名空间project-pipelines中创建包含密钥provider.token和webhook.secret的 Secret(在示例:特定环境的配置 中,标识符为production和staging),具体说明参见为 PAC 创建 Git Secret,第 3 步;由于使用默认密钥,这些示例省略了key。全局 Repository 示例使用其自身的 Secret,而my-app-repo示例继承全局 Repository 的 Secret - Repository 示例使用 GitLab.com(
https://gitlab.com)。对于自托管 GitLab,请将spec.url设置为项目 URL,并将git_provider.url设置为 GitLab 基础 URL;如果没有git_provider.url,PAC 可以使用 Repository 的令牌将运行的最终状态报告给https://gitlab.com - 集群管理员权限或命名空间级别的权限
创建全局 Repository CR
全局 Repository CR 功能属于技术预览功能,允许 Repository CR 从一个全局 Repository CR 继承共享配置。
或者,您也可以在 PAC 安装所在的命名空间中创建一个全局 Repository CR(通常为 tekton-pipelines,或者通过 TektonConfig CR 中配置的 targetNamespace 指定)。如果您在此命名空间中创建名为 pipelines-as-code 的 Repository CR,其他 Repository CR 将在满足下面行为部分所列条件的情况下,继承其中未设置的字段。
要点:
- 名称:必须完全是
pipelines-as-code - 命名空间:必须位于 PAC 安装命名空间中(例如
tekton-pipelines) - 继承:Repository 仅继承自身未设置的字段;仅当 Repository 自身包含
git_provider或settings块时,才会继承git_provider字段和某些settings字段,而不会继承incoming(请参见下面的行为部分) - 技术预览:此功能属于技术预览功能
示例:全局 Repository CR
在 PAC 命名空间中创建全局 Repository CR,即 TektonConfig.spec.targetNamespace 中的命名空间;下面的示例假定该命名空间为默认的 tekton-pipelines。如果您的集群使用其他命名空间,请替换它:PAC 只会从自身的命名空间读取全局 Repository。在任何其他命名空间中,PAC admission webhook 都会拒绝下面的示例,因为该示例没有 spec.url:admission webhook "validation.pipelinesascode.tekton.dev" denied the request: URL must be set。创建全局 Repository 及其 Secret 需要对 PAC 命名空间中的 Repositories 和 Secrets 具有写入权限,通常需要集群管理员权限。
在与全局 Repository 相同的命名空间中创建 Secret gitlab-webhook-config。未设置 git_provider.url 的 Repository 会继承此 url(请参见下面的行为部分);对于自托管 GitLab,请将其设置为 GitLab 基础 URL。
将 CR 保存为 global-repository.yaml 并应用:
行为:
git_provider:仅当 Repository 自身包含git_provider块,且其type为空或与全局 Repository 的值相同时,Repository 才会继承全局 Repository 的git_provider字段(url、user、type、secret、webhook_secret)中未设置的字段。不包含git_provider块,或具有不同type的 Repository 不会继承这些字段中的任何一个settings:仅当 Repository 自身包含settings块,并且未设置这些字段时,才会继承全局 Repository 的以下settings字段:pipelinerun_provenance、policy、github_app_token_scope_repos、forgejo、ai和gitops_command_prefix。settings.gitlab和settings.github等保存comment_strategy的 Provider 设置不会被继承;请在每个 Repository 中设置这些设置concurrency_limit和params:如果 Repository 未设置该字段,则使用全局值incoming:不会继承。只有当请求中指定的 Repository 具有自身的incoming规则时,PAC 才会处理传入 webhook 请求。否则,PAC 会丢弃该请求:调用方会收到 HTTP200,响应正文为空,不会创建PipelineRun,并且 PAC controller 日志会显示error processing incoming webhook: you need to have incoming webhooks rules in your repo spec, repo: <name>。请在每个接收传入 webhook 的 Repository 中定义incomingsecret和webhook_secret:以相同方式设置。可以在 Repository 中同时设置这两项,并引用 Repository 自身命名空间中的 Secret;也可以在继承git_provider字段的 Repository 中同时不设置这两项(请参见第一项),以便同时继承它们;之后 PAC 会从全局 Repository 所在的命名空间读取令牌和 webhook Secret- Repository CR 自身设置的字段会保留自身的值;全局值不会覆盖该值
- 您仍需要在每个 Repository CR 中指定
spec.url及其他特定于 Repository 的设置
示例:使用全局设置
使用上面的全局 CR,您可以创建仅包含最少配置的独立 Repository CR:
停止使用全局 Repository CR
PAC 会在每个 webhook 请求到达时重新读取全局 Repository CR,因此删除它会在下一事件发生时生效:从那时起,每个 Repository 只包含自身设置的字段。要停止使用全局 Repository CR,请先更新继承它的 Repository,然后将其删除:
-
对于每个从全局 Repository CR 继承配置的 Repository,设置它所继承的字段。在上面行为部分所列的条件下,这些字段包括
git_provider字段(url、user、type、secret、webhook_secret)、concurrency_limit、params,以及列出的、Repository 未设置的settings字段;kubectl get repository <name> -n <namespace> -o yaml显示其自身设置的字段。对于令牌和 webhook Secret,请按照创建 Git Secret 中的说明,在 Repository 自身的命名空间中创建 Secret,并在secret和webhook_secret中同时引用该 Secret:在 Repository 中同时设置这两项后,PAC 会从 Repository 的命名空间读取二者(请参见上面的行为部分)。对于webhook.secret,存储 Git provider webhook 当前发送的值;只要 Repository 的事件仍能正常通过,该值就等于 PAC 当前为该 Repository 读取的 webhook Secret(对于同时继承secret和webhook_secret的 Repository,例如my-app-repo示例,即 PAC 命名空间中 Secretgitlab-webhook-config的密钥webhook.secret)。从 PAC 命名空间读取 Secret 需要对该命名空间中的 Secrets 具有读取权限,通常需要集群管理员权限。如果新 Secret 保存的值不同,则从 Repository 引用该 Secret 起,PAC 会丢弃该 Repository 的 Git provider 事件,直到 webhook 发送新值;在 GitLab 上,controller 日志随后会显示could not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secret。 -
删除全局 Repository CR;如果没有其他对象使用其 Secret,也将该 Secret 删除。这需要对 PAC 命名空间中的 Repositories 和 Secrets 具有删除权限,通常需要集群管理员权限。本节中的命令使用
tekton-pipelines,即TektonConfigspec.targetNamespace的默认值;如果您的安装使用其他命名空间,请在命令中替换它:
如果先删除全局 Repository CR,那么在下一次事件发生时,继承了 secret 或 webhook_secret 的 Repository 将没有令牌或 webhook Secret,PAC 会丢弃其事件:不会创建 PipelineRun。对于继承了 secret 的 Repository,controller 日志会记录一行以 cannot get secret from repository: failed to find secret in git_provider section in repository spec: <namespace>/<name> 结尾的内容;对于仅继承 webhook_secret 的 Repository,日志会记录 故障排除(配置 GitLab Repository)中的某个 webhook Secret 错误。
要查看 PAC 是否读取全局 Repository CR,请检查 PAC controller 日志;这需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常需要集群管理员权限。全局 Repository CR 存在时,PAC 会为每个 webhook 请求记录 detected global repository settings named pipelines-as-code in namespace <pac-namespace>;删除后,新请求将不再记录此行。该行不会显示事件所属的 Repository。使用 -l 时,kubectl logs 只会打印最后 10 行,除非设置了 --tail,因此该命令会读取最近 10 分钟内的每一行;如果事件发生时间更早,请增大 --since:
设置并发限制
并发限制有助于在大量事件同时触发流水线时防止资源耗尽。您可以设置一个 Repository 可同时运行的最大 PipelineRun 数量。
配置并发限制
编辑 Repository CR,添加 concurrency_limit 字段:
重要事项:
- 最小值为
1 - 如果 Repository 和全局 Repository 都未设置该值,则并发 PipelineRun 没有数量限制。Repository 无法移除从全局 Repository 继承的限制:
0会被拒绝(spec.concurrency_limit in body should be greater than or equal to 1);它只能设置自己的值 - 达到限制后,新事件将排队,直到某个 PipelineRun 完成
使用场景示例
高流量 Repository:限制并发运行数量,防止集群过载:
资源密集型流水线:进行限制,以确保每次运行都有足够的资源:
无限制(默认值,即全局 Repository 未设置 concurrency_limit 时):允许无限数量的并发运行:
验证并发限制
检查 Repository CR:
示例输出(已省略部分内容):
监控正在运行的 PipelineRun:
示例输出:
更改 Pipeline 定义的源分支
默认情况下,Pipelines-as-Code 会从触发事件的分支获取 PipelineRun 定义(例如 push 或 pull request 所在的分支)。
您可以通过 Repository 自定义资源中的 spec.settings.pipelinerun_provenance 字段更改此行为。此设置控制从哪个分支获取 PipelineRun 定义。
配置 PipelineRun 定义源
pipelinerun_provenance 支持的值:
source:默认行为。PipelineRun 定义从触发事件所在的分支获取。default_branch:PipelineRun 定义从名称与 Git provider 上配置的 Repository 默认分支相同的分支获取(例如main、master或trunk)。
设置的作用
使用 default_branch 时,无论 pull request 或 merge request 来自哪个分支,PAC 都会从名称与 Repository 默认分支相同的分支读取 .tekton/ 定义(例如 main)。pipelinerun_provenance 只选择 PAC 读取定义的分支。它不是访问控制设置:不会限制谁可以向默认分支推送,也不要求进行审查。
- 审查由 Git provider 负责:保护默认分支,并在 Git provider 上要求 merge request 或 pull request 获得批准,以便每项流水线更改在进入默认分支前都经过审查。
要检查设置是否生效,请打开一个测试 merge request 或 pull request,更改 .tekton/ 文件中的某个值(例如某个步骤打印的文本),然后读取 PAC 为其创建的 PipelineRun(kubectl get pipelinerun <name> -n <namespace> -o yaml)。使用 default_branch 时,PipelineRun 仍具有默认分支中的值;使用 source 时,它具有更改后的值。只有当 Repository 自身具有 settings 块时,它才会从全局 Repository 继承 pipelinerun_provenance(请参见创建全局 Repository CR下的行为)。能够读取 PAC 命名空间中 Pod 日志的读者还可以在 PAC controller 日志中找到 Using PipelineRun definition from default_branch: <branch>。
配置比较
注意:使用 default_branch 时,还应保护默认分支,并在 Git provider 上要求进行审查。
自定义参数扩展
您可以在 Repository CR 中定义自定义参数,这些参数将扩展到为该 Repository 创建的所有 PipelineRun 中。这对于为所有流水线设置通用值非常有用。
定义自定义参数
将参数添加到 Repository CR 的 spec.params 字段:
在流水线中使用自定义参数
重要:Repository CR 参数使用 PAC 变量语法 {{ param }},而不是 Tekton 的 $(params.param) 语法。
-
PAC 变量(
{{ variable }}):PAC 会在创建 PipelineRun 之前替换这些变量。其中包括:- 来自
spec.params的 Repository CR 参数(例如{{ environment }}、{{ cluster-name }}) - PAC 内置变量(例如
{{ revision }}、{{ repo_url }}、{{ source_branch }})
- 来自
-
Tekton 参数(
$(params.param)):Tekton 会在 PipelineRun 执行期间解析这些参数。这些参数引用 PipelineRun 自身的spec.params。
在 PipelineRun 定义中使用 PAC 变量语法引用 Repository CR 参数:
注意:请将示例镜像 alpine:latest 替换为集群可以拉取的镜像,例如内部 registry 中的镜像。此示例使用 pipelineSpec 内联定义流水线;有关所需集群设置,请参见使用 pipelineSpec 内联定义流水线中的说明。
工作原理:
- 创建 PipelineRun 之前:PAC 将所有
{{ variable }}语法替换为 Repository CR 参数和内置变量中的实际值 - 创建 PipelineRun:PAC 创建 PipelineRun,此时所有变量都已替换
- 执行期间:Tekton 从 PipelineRun 的
spec.params中读取数据,并解析$(params.<name>)语法
转换示例:
- 在 Git Repository 中:
value: "{{ environment }}" - PAC 将其替换为:
value: "production"(来自 Repository CR 参数) - 创建的 PipelineRun 中包含:
- name: environment/value: "production" - Task 脚本使用:
$(params.environment)→ Tekton 将其解析为"production"
参数优先级
参数按以下顺序展开(从高到低):
- PipelineRun 参数:在 PipelineRun 中显式定义的参数
- 命令和传入 Webhook 参数:GitOps 命令(例如
/test)的key=value参数,这些参数只会覆盖已为Repository定义或已被 PAC 识别的参数(请参见在命令中传递参数),以及传入 Webhook 请求的参数。只有当传入 Webhook 参数的名称列在与该请求匹配的 Repository 的incoming规则的params中时,PAC 才会接受该参数。否则,PAC 会丢弃整个请求:调用方仍会收到 HTTP200响应,响应正文为空,并且不会创建PipelineRun。接受的请求会收到 HTTP202响应,正文为{"status":202,"message":"accepted"}。请求完成后,可在 Repository 的命名空间(kubectl get pipelineruns -n <namespace>)中列出PipelineRun进行检查。原因error processing incoming webhook: param <name> is not allowed in incoming webhook CR仅显示在 PAC controller 日志中;读取该原因需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常只有集群管理员具备此权限 - Repository 参数:在 Repository CR 中定义的参数
- 动态变量:PAC 动态变量(例如
{{ revision }}、{{ repo_url }})
示例:特定环境的配置
使用 Repository 参数配置不同的环境。每个 Repository 都会引用其自身命名空间中的 Secret my-repo-auth,如先决条件中所列:
生产环境 Repository:
预发布环境 Repository:
两个 Repository 可以使用相同的流水线定义,参数会自动从 Repository CR 中填充。
组合使用高级功能
您可以在单个 Repository CR 中组合使用所有高级功能:
最佳实践
1. 并发限制
- 为每个 Repository 设置限制:根据集群资源以及 Repository 的每个
PipelineRun所请求的资源,为concurrency_limit设置限制;示例用例中针对高流量 Repository 使用3,针对资源密集型流水线使用2。不要为其PipelineRun使用cancel-in-progress的 Repository 设置限制:当 Repository 具有限制(无论是直接设置还是从全局 Repository 继承)时,新运行不会取消较早的运行,并且 PAC 会在Repository上记录事件error cancelling in progress pipelineRuns: cancel in progress is not supported with concurrency limit(请参阅正在取消) - 关注排队的 PipelineRun:达到限制后,新的
PipelineRun会以状态标签queued等待;如并发限制不起作用中所示,使用pipelinesascode.tekton.dev/state列列出它们
2. 源分支配置
- 选择两个源中的一个:
pipelinerun_provenance仅接受source(触发分支,默认值)或default_branch(名称为 Repository 默认分支的分支);不能指定其他分支 - 测试流水线更改:使用
default_branch时,无论拉取请求或合并请求来自哪个分支,PAC 都会从名称为 Repository 默认分支的分支(例如main)读取.tekton/定义。在其 Repository 使用source的 Git Repository 中,在合并前测试对.tekton/的更改,例如测试非生产环境中的 Repository;PAC 对每个 Git Repository URL 仅接受一个 Repository - 记录更改:明确记录哪个分支包含流水线定义
3. 自定义参数
- 使用有意义的名称:选择清晰、具有描述性的参数名称
- 保持值简单:为参数使用简单的字符串值
- 记录参数:记录每个参数的作用及其使用时机
- 避免使用 Secret:不要通过 Repository 参数传递凭据。无论
{{ name }}在生成的PipelineRun中出现在哪里,PAC 都会以明文写入参数值;即使该值通过secret_ref从 Secret 获取(name和key),而不是通过value获取,也是如此:secret_ref仅会将该值保留在 Repository CR 之外。应改为从 Kubernetes Secret 将凭据挂载到 Task 中,例如使用env.valueFrom.secretKeyRef或 Secret workspace。对于必须保留在 Repository CR 外部、但可以出现在PipelineRun中的值,请使用secret_ref。PAC 会从 Repository 命名空间读取secret_refSecret;如果该 Secret 不存在,PAC 会记录 Repository 事件ParamsError(error processing repository CR custom params: secrets "<secret-name>" not found),仍会创建PipelineRun,并保留未替换的{{ name }}
故障排除
并发限制不起作用
-
验证是否设置了限制:
对于并发限制为 1 的 Repository,步骤 2 和 3 中的示例使用了该限制。示例输出:
输出为空表示 Repository 本身未设置 concurrency_limit。Repository 从全局 Repository继承的限制会生效,但不会写入 Repository,因此还要读取 PAC 命名空间中全局 Repository pipelines-as-code 的 spec.concurrency_limit;这需要对该命名空间中的 Repository 具有读取权限,通常只有集群管理员具备此权限。
-
检查排队的 PipelineRun:达到限制后,PAC 仍会为每个新事件创建一个
PipelineRun,但会使其保持待处理状态(spec.status: PipelineRunPending),并带有状态标签queued。同一 Repository 中正在运行的PipelineRun完成后,PAC watcher 会按创建顺序启动下一个排队的运行:
示例输出:
Repository 状态仅列出已完成的 PipelineRun;排队中的 PipelineRun 不会出现在其中。
-
验证 PAC watcher 日志:队列由 PAC watcher 而不是 controller 处理。其日志行不包含单词
concurrency,PAC 也不会将其记录为Repository上的事件。读取日志需要对 PAC 命名空间中的 Pod 日志具有读取权限,通常只有集群管理员具备此权限。使用-l时,kubectl logs只会打印最后 10 行,除非设置了--tail;因此,该命令会读取最近 10 分钟内的所有行。如果运行更早启动,请增大--since。将<pac-namespace>替换为你的 PAC 命名空间(默认值:tekton-pipelines):
示例输出(仅显示消息):
对于必须等待的 PipelineRun,watcher 还会写入 added pipelineRun (...) to running queue;下一行 no new PipelineRun acquired 表明它尚未启动。
参数未展开
-
验证是否定义了参数:
输出为空表示 Repository 本身未设置
params。如果全局 Repository 设置了params,Repository 会继承这些参数(请参阅创建全局 Repository CR下的行为),因此还要读取全局 Repository 的spec.params。 -
检查参数语法:确保使用
{{ param }}语法引用 Repository CR 参数,而不是$(params.param) -
验证变量替换:检查已创建的 PipelineRun,确认 PAC 是否替换了变量:
-
检查 PipelineRun:确认参数是否在 PipelineRun 定义中被覆盖
后续步骤
- 指南 - Repository 基本设置教程
- 在 Git 中定义 PipelineRun - PipelineRun 文件和触发器注解
- 传入 Webhook - 面向外部系统的直接 HTTP 触发器
- 常见问题 - 故障排除指南