PAC Resolver
普通用户
本指南面向普通用户,介绍如何使用 PAC resolver,从本地存储库、DevOps Hub 目录和远程 URL 自动解析并嵌入任务和 pipeline。
本指南介绍如何使用 Pipelines as Code (PAC) resolver,从三种来源自动解析并嵌入任务和 pipeline:存储库中定义的本地任务、由 artifacthub-shim 提供的 DevOps Hub 目录中的远程任务,以及来自远程 Git 存储库或 HTTP URL 的任务。
先决条件
- 已部署并运行 PAC 组件
- 已配置 Repository CR(请参阅 指南)
- 了解 Tekton PipelineRun 结构
关于 PAC Resolver
PAC resolver 会自动获取远程任务和 pipeline,并将其嵌入 PipelineRun 定义中。这样,您无需在 pipeline 代码中手动定义任务或使用 resolver 语法。
任务嵌入的工作方式
当 PAC 从 DevOps Hub 目录解析任务时:
- PAC 从 Hub 获取任务定义(YAML)
- PAC 将
taskRef 转换为 taskSpec,并将任务定义以内联方式嵌入 PipelineRun
- 嵌入的任务成为 PipelineRun 定义的一部分
- 该任务无需作为单独的 Task 资源存在于集群中
这意味着您可以使用目录中的任务,而无需手动复制其定义或在集群中创建 Task 资源。
支持的来源
- 本地任务:Git 存储库中定义的任务(使用 taskSpec 或 resolver 语法)
- DevOps Hub 目录:集群内
artifacthub-shim 目录中的任务和 pipeline
- 远程 URL:远程 Git 存储库或 HTTP URL 中的任务和 pipeline
PAC Resolver 的工作方式
了解 resolver 工作流有助于排查问题并优化 pipeline 配置。
Resolver 工作流
当 PAC 处理带有 resolver 注解的 PipelineRun 时,会执行以下步骤:
- 事件触发:Git 事件(推送、拉取请求等)触发 PAC controller
- 获取 Pipeline:PAC controller 从 Git 存储库获取 PipelineRun 定义
- 检测注解:PAC controller 扫描 resolver 指令的注解:
pipelinesascode.tekton.dev/task: "task-name"
pipelinesascode.tekton.dev/task-1: "task-name"
pipelinesascode.tekton.dev/pipeline: "pipeline-name"
- 解析任务:对于每个任务注解:
- PAC controller 查询配置的 Hub API。ACP DevOps 默认将其设置为集群内的
artifacthub-shim Service。
- 获取任务定义(YAML)
- 验证任务结构
- 嵌入任务:PAC 将解析后的任务定义嵌入 PipelineRun:
- PAC 将
taskRef 转换为 taskSpec,并将任务定义以内联方式嵌入每个任务条目
- 嵌入的任务成为 PipelineRun 定义的一部分,因此无需作为单独的 Task 资源存在于集群中
- 创建 PipelineRun:PAC 在 Kubernetes 中创建包含嵌入任务的最终 PipelineRun
- 执行:Tekton Pipeline controller 获取 PipelineRun 并执行它
详细示例:逐步解析
下面通过一个完整示例了解 resolver 的工作方式:
步骤 1:原始 PipelineRun 定义
您在存储库中定义 PipelineRun(.tekton/pipelinerun.yaml):
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
pipelinesascode.tekton.dev/task: "git-clone"
spec:
pipelineSpec:
tasks:
- name: fetch-code
taskRef:
name: git-clone
params:
- name: url
value: "https://github.com/tektoncd/catalog.git"
- name: revision
value: "main"
步骤 2:PAC Controller 处理注解
发生推送事件时,PAC controller:
-
从 Git 读取 PipelineRun:PAC 从存储库中获取 .tekton/pipelinerun.yaml 文件
-
检测注解:PAC 扫描类似 pipelinesascode.tekton.dev/task: "git-clone" 的任务注解
-
解析任务名称和版本:
- 仅任务名称(例如
"git-clone"):从 Hub 获取最新版本
- 包含版本(例如
"git-clone:0.1"):获取指定版本
- 版本选择:
- 未指定版本 → PAC 向 Hub 查询最新稳定版本
- 指定版本(格式:
task-name:version)→ PAC 获取该确切版本
- 版本格式遵循语义化版本规范(例如
0.1、0.9、1.2.3)
-
查询 Hub API:
- Hub URL:默认为
http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
- 目录类型:默认为
artifacthub
- 目录名称:默认为
catalog
- 查询最新版本:PAC 向 Hub 查询可用的最新版本
- 查询特定版本:PAC 请求注解中指定的确切版本
- 查询示例:
- 最新版本:
"git-clone" → Hub 返回最新版本
- 特定版本:
"git-clone:0.1" → Hub 返回版本 0.1
-
从 Hub 接收任务定义:Hub 返回完整的 Task YAML:
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: git-clone
spec:
params:
- name: url
description: git url to clone
- name: revision
description: revision to checkout
steps:
- name: clone
image: gcr.io/tekton-releases/git-init
script: |
#!/bin/sh
git clone $(params.url) $(workspaces.output.path)
cd $(workspaces.output.path)
git checkout $(params.revision)
版本选择最佳实践:
- 生产环境:指定确切版本(例如
"git-clone:0.1"),确保每次运行都解析到相同的已发布版本
- 开发/测试环境:使用最新版本(不添加版本后缀),自动获取新功能和 bug 修复
- 版本固定:版本会选择某个已发布的 Task 版本,但不会单独冻结该版本的内容。已发布版本是否可以更改取决于目录管理员维护目录的方式,因此请与管理员约定不要原地修改已发布版本(请参阅 ArtifactHub Shim Catalog)
- 版本更新:定期以受控方式检查并更新固定的版本
步骤 3:PAC 将任务嵌入 PipelineRun
PAC 将 taskRef 转换为 taskSpec,并将解析后的任务定义嵌入 PipelineRun:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
spec:
pipelineSpec:
tasks:
- name: fetch-code
# PAC converts taskRef to taskSpec and embeds the task definition
taskSpec:
params:
- name: url
description: git url to clone
- name: revision
description: revision to checkout
steps:
- name: clone
image: gcr.io/tekton-releases/git-init
script: |
#!/bin/sh
git clone $(params.url) $(workspaces.output.path)
cd $(workspaces.output.path)
git checkout $(params.revision)
params:
- name: url
value: "https://github.com/tektoncd/catalog.git"
- name: revision
value: "main"
步骤 4:在 Kubernetes 中创建 PipelineRun
PAC 在集群中创建最终的 PipelineRun。您可以进行验证:
kubectl get pipelinerun my-pipeline -n <namespace> -o yaml
示例输出(已缩略,显示嵌入的任务):
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
spec:
pipelineSpec:
tasks:
- name: fetch-code
# Task definition is embedded as taskSpec
taskSpec:
params:
- name: url
- name: revision
steps:
- name: clone
image: gcr.io/tekton-releases/git-init
script: |
#!/bin/sh
git clone $(params.url) $(workspaces.output.path)
params:
- name: url
value: "https://gitlab.com/user/repo"
- name: revision
value: "abc1234"
Resolver 时机
重要:任务解析发生在 PipelineRun 创建于 Kubernetes 之前。这意味着:
- 任务在 pipeline 定义时解析,而不是在执行时解析
- 如果无法解析任务,PipelineRun 创建将失败
- 您可以通过检查 Kubernetes 中的 PipelineRun YAML 来验证任务解析
- PAC 会缓存已解析的任务以提升性能
验证任务解析
要验证任务是否已正确解析:
-
检查 Kubernetes 中的 PipelineRun:
kubectl get pipelinerun <name> -n <namespace> -o yaml
查找各个任务中包含 taskSpec 的嵌入任务:
spec:
pipelineSpec:
tasks:
- name: fetch-code
taskSpec:
params:
- name: url
- name: revision
steps:
- name: clone
image: gcr.io/tekton-releases/git-init
script: |
#!/bin/sh
git clone $(params.url) $(workspaces.output.path)
params:
- name: url
value: "https://gitlab.com/user/repo"
- name: revision
value: "abc1234"
了解任务嵌入
PAC 会在各个任务中将 taskRef 转换为 taskSpec,从而嵌入已解析的任务。任务定义会以内联方式作为 PipelineRun 的一部分嵌入,并遵循标准 Tekton 语法。
-
检查 PAC Controller 日志:
kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i "task.*resolve" # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)
示例输出(显示任务解析):
{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}
-
验证每个任务是否已嵌入:已解析的任务不再包含 taskRef — PAC 会将其替换为内联的 taskSpec,因此成功时,读取 taskRef.name 的命令不会输出任何内容。以最终形式列出每个 pipeline 任务:
kubectl get pipelinerun <name> -n <namespace> -o json \
| jq -r '.spec.pipelineSpec.tasks[] | "\(.name)\t\(if .taskSpec then "embedded" else "unresolved taskRef: " + .taskRef.name end)"'
示例输出:
fetch-code embedded
lint embedded
仍显示 unresolved taskRef: 的条目表示该任务未解析。请检查任务是否列在 pipelinesascode.tekton.dev/task 注解中,然后查看上面的 controller 日志。
-
检查 PipelineRun 是否已成功创建:
kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.status.conditions[*].type}'
示例输出:
如果任务解析失败,PipelineRun 可能不会创建,或者会带有包含错误消息的 Failed 条件。
使用本地任务
本地任务是直接在 Git 仓库中定义的任务。PAC 支持两种使用本地任务的方式:
内联任务定义(taskSpec)
您可以使用 taskSpec 直接在 PipelineRun 中定义任务:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
spec:
pipelineSpec:
tasks:
- name: build
taskSpec:
steps:
- name: build
image: golang:1.21
script: |
#!/bin/sh
go build -o app ./cmd
- name: test
taskSpec:
steps:
- name: test
image: golang:1.21
script: |
#!/bin/sh
go test ./...
工作原理:
- 使用每个流水线任务中的
taskSpec 内联定义任务
- 不需要外部解析——任务属于 PipelineRun 定义的一部分
- 适用于简单的、特定于仓库的任务
引用仓库中的任务文件
您可以使用 PAC 注解引用存储在仓库中的任务文件,并使用仓库内任务的特殊语法。
重要信息:对于仓库中的任务,请使用带有 pipelinesascode.tekton.dev/task 或 pipelinesascode.tekton.dev/task-<N> 注解的格式。
仓库结构:
.tekton/
├── pipelinerun.yaml
└── tasks/
├── build-task.yaml
└── test-task.yaml
使用 PAC 注解的 PipelineRun 定义:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
# Reference local tasks using relative paths
pipelinesascode.tekton.dev/task: ".tekton/tasks/build-task.yaml"
pipelinesascode.tekton.dev/task-1: ".tekton/tasks/test-task.yaml"
spec:
pipelineSpec:
tasks:
- name: build
taskRef:
name: build-task
- name: test
taskRef:
name: test-task
runAfter: [build]
工作原理:
- 当您在任务注解中使用相对路径时,PAC 会自动解析并嵌入仓库中的任务
taskRef.name 中的任务名称应与 YAML 文件中定义的任务名称匹配
- 使用此方法时,
taskRef 不需要使用 resolver: git 语法
何时使用本地任务
在以下情况下使用本地任务:
- 任务特定于您的项目,不适合共享
- 需要完全控制任务定义和版本
- 任务会随代码库频繁变更
- 希望将任务和流水线一起保存在版本控制中
使用远程任务注解
您可以使用 PAC 注解引用 DevOps Hub catalog 或远程 HTTP URL 中的远程任务。PAC 会自动获取这些任务并将其嵌入 PipelineRun。
来自 DevOps Hub 的远程任务
从 DevOps Hub 引用单个任务:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
pipelinesascode.tekton.dev/task: "git-clone"
spec:
pipelineSpec:
tasks:
- name: fetch-code
taskRef:
name: git-clone
params:
- name: url
value: "https://github.com/tektoncd/catalog.git"
- name: revision
value: "main"
工作原理:
pipelinesascode.tekton.dev/task: "git-clone" 注解告知 PAC 从已配置的 Hub catalog 获取 git-clone 任务
- PAC 会自动将任务定义嵌入 PipelineRun
- 然后,您可以使用
taskRef.name: git-clone 引用该任务
来自 HTTP URL 的远程任务
您也可以从远程 HTTP URL 引用任务:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
# Reference task from remote URL
pipelinesascode.tekton.dev/task: "https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.9/git-clone.yaml"
spec:
pipelineSpec:
tasks:
- name: fetch-code
taskRef:
name: git-clone
params:
- name: url
value: "https://github.com/tektoncd/catalog.git"
- name: revision
value: "main"
工作原理:
- PAC 从指定的 HTTP URL 获取任务定义
- PAC 会自动将任务嵌入 PipelineRun
taskRef.name 中的任务名称应与远程 YAML 文件中定义的任务名称匹配
多个任务注解
使用带编号的注解引用多个任务:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: build-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
pipelinesascode.tekton.dev/task: "git-clone"
pipelinesascode.tekton.dev/task-1: "golangci-lint"
pipelinesascode.tekton.dev/task-2: "buildah"
spec:
pipelineSpec:
tasks:
- name: fetch
taskRef:
name: git-clone
params:
- name: url
value: "https://github.com/tektoncd/catalog.git"
- name: revision
value: "main"
- name: lint
taskRef:
name: golangci-lint
runAfter: [fetch]
- name: build
taskRef:
name: buildah
runAfter: [lint]
任务列表语法
您也可以使用方括号语法,在单个注解中指定多个任务:
metadata:
annotations:
pipelinesascode.tekton.dev/task-1: "[golangci-lint, buildah]"
这等同于:
metadata:
annotations:
pipelinesascode.tekton.dev/task-1: "golangci-lint"
pipelinesascode.tekton.dev/task-2: "buildah"
任务版本指定
默认情况下,PAC 会从 Hub 获取任务的最新版本。若要指定特定版本,请使用 task-name:version 格式。
PAC 按名称解析 Hub 任务,并可以使用 task-name:version 选择性地固定任务版本。
最新版本(推荐用于开发):
metadata:
annotations:
pipelinesascode.tekton.dev/task: "git-clone"
特定版本(推荐用于生产环境):
metadata:
annotations:
pipelinesascode.tekton.dev/task: "git-clone:0.9"
带版本的多个任务:
metadata:
annotations:
pipelinesascode.tekton.dev/task: "git-clone:0.9"
pipelinesascode.tekton.dev/task-1: "golangci-lint:0.4"
pipelinesascode.tekton.dev/task-2: "buildah" # Uses latest
自定义 Hub URL
默认的 hub-url 指向集群内部的 artifacthub-shim Service(http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local),无需配置。仅当 artifacthub-shim 部署在其他命名空间中,或您希望使用其他 Hub 实例时,才需要显式设置该值。在 TektonConfig CR 中进行配置:
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
platforms:
kubernetes:
pipelinesAsCode:
enable: true
settings:
# The address artifacthub-shim is installed at by default. Change only the
# namespace if it was deployed somewhere other than artifacthub-shim-system.
hub-url: "http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local"
hub-catalog-type: "artifacthub"
hub-catalog-name: "catalog"
# Or for an external Artifact Hub instance
# hub-url: "https://artifacthub.io"
# hub-catalog-type: "artifacthub"
# Or for a Tekton Hub instance - the catalog type has to change with it
# hub-url: "https://api.hub.tekton.dev/v1"
# hub-catalog-type: "tekton"
注意:只有 PAC controller 需要访问 Hub URL。对于 Artifact Hub providers,请不要追加 /api/v1;PAC 会在内部添加该路径。请始终将 hub-catalog-type 与 hub-url 一起设置:如果只更改 URL,随附的 artifacthub 值会保持不变,因此在未同时设置该值的情况下指向 Tekton Hub,会导致 PAC 使用 Artifact Hub API 查询该 Hub。
使用远程 Pipeline 注解
使用场景有限
pipelinesascode.tekton.dev/pipeline 注解受支持,但与其他提供 Pipeline 的方式相比,适用场景较少。要复用在仓库外维护的 Pipeline,我们建议使用 pipelineRef 和 Tekton resolver 引用它,如使用 pipelineRef 引用 Pipeline中所述。本节仅为完整性而包含。
该注解形式会从 DevOps Hub 获取 Pipeline,并将其嵌入 PipelineRun:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: my-pipeline
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
# Reference remote pipeline from DevOps Hub
pipelinesascode.tekton.dev/pipeline: "pipeline-name"
spec:
pipelineRef:
name: pipeline-name
params:
- name: image-url
value: "registry.example.com/myapp"
工作原理:
pipelinesascode.tekton.dev/pipeline: "pipeline-name" 注解指示 PAC 从配置的 Hub catalog 获取 Pipeline。PAC 使用一个 hub-catalog-name 设置,因此 artifacthub-shim 会将 Pipeline fallback 从 catalog 保持到 catalog-pipelines。
- PAC 会自动嵌入 Pipeline 定义
- 使用
pipelineRef.name 引用它
有关 catalog 源配置和资源编写,请参阅 ArtifactHub Shim Catalog。
注意:通常,我们建议使用 pipelineRef 引用 Pipeline,而不是使用 pipelineSpec 将完整定义内联:对于属于一个仓库的 Pipeline,请将其保存在 .tekton/ 下的 Pipeline 文件中,并按名称引用,如在 Git 中定义 Pipeline中所述;对于多个仓库共享的 Pipeline,请使用 Tekton resolver 引用它。内联 pipelineSpec 和此注解仍受支持。在 resolver 与此注解之间,PAC 会保持 resolver 形式的 pipelineRef 不变,因此运行记录会保留定义的来源;而该注解会将 Pipeline 的副本嵌入每次运行中。
组合使用远程 Task 和 Pipeline
与 Resolver 语法的比较
PAC 注解提供了 Tekton resolver 语法的替代方式,用于在内联 pipelineSpec 中引用 Task:
使用 PAC 注解
metadata:
annotations:
pipelinesascode.tekton.dev/task: "git-clone"
spec:
pipelineSpec:
tasks:
- name: clone
taskRef:
name: git-clone
使用 Resolver 语法
spec:
pipelineSpec:
tasks:
- name: clone
taskRef:
resolver: hub
params:
- name: name
value: git-clone
- name: kind
value: task
PAC 注解的优势:
上面的两个示例都使用 pipelineSpec 内联定义 Pipeline。对于多个仓库共享的 Pipeline,推荐使用带 Tekton resolver 的 pipelineRef,如引用共享 Pipeline 模板中所述。拒绝内联 pipelineSpec 的准入策略(例如使用 Kyverno 约束 Tekton Pipeline 执行中的 deny-pipelinerun-inline-pipelinespec 规则)会在实施该策略的命名空间中拒绝以类似上述两个示例的方式编写的运行;使用默认的 remote-tasks: "true" 时,也会拒绝 PAC 嵌入已解析 Pipeline 或 Task 的运行。
故障排除
找不到 Task
-
验证 Task 名称:检查 DevOps Hub 中的 Task 名称是否正确
-
检查 Hub URL:验证 Hub URL 配置是否正确
-
查看 PAC 日志:
kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i task
示例输出:
{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}
Task 解析失败
-
检查网络连接:确保 PAC controller 可以访问 artifacthub-shim
# Test Hub connectivity from PAC controller pod
kubectl exec -n <pac-namespace> \
$(kubectl get pod -n <pac-namespace> -l app=pipelines-as-code-controller -o jsonpath='{.items[0].metadata.name}') \
-- curl -I http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local/api/v1/packages/tekton-task/catalog/git-clone
可访问时的示例输出:
HTTP/1.1 200 OK
Content-Type: application/json
-
验证 Hub 配置:检查 PAC controller 实际接收到的 hub-url 值。pipelines-as-code ConfigMap 是权威来源,即 controller 读取的配置。它位于 PAC 命名空间 TektonConfig.spec.targetNamespace 中;以下命令使用默认的 tekton-pipelines,因此如果你的集群使用其他命名空间,请替换该值,否则查询会失败,看起来就像设置从未生效一样:
kubectl get configmap pipelines-as-code -n tekton-pipelines -o jsonpath='{.data.hub-url}'
示例输出:
http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
-
查看 Task 版本:确保指定的版本存在
# Query artifacthub-shim for the latest package detail
curl http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local/api/v1/packages/tekton-task/catalog/git-clone
示例输出(已缩略):
{
"id": 1,
"name": "git-clone",
"kind": "Task",
"latestVersion": {
"id": 1,
"version": "0.9"
},
"versions": [
{"version": "0.9"},
{"version": "0.8"},
{"version": "0.7"}
]
}
Task 未嵌入
- 验证注解语法:检查注解键和值的格式
- 检查 PipelineRun:确保
taskRef.name 与注解中的 Task 名称一致
- 查看 PAC controller 日志,检查是否存在嵌入错误
后续步骤