GeekIt

Tekton(tkn)命令速查

安装与版本、Pipeline 与 PipelineRun、Task 与 TaskRun、参数工作区 SA、Trigger、Hub 与 Bundle、脚本化与报错排查等 133 条命令

共 133 条命令 · 10 类场景 · 点击右侧图标可复制

命令 / 片段说明复制
tkn version查看 CLI 版本,以及已安装的 Tekton 组件版本
tkn version -C pipeline只看 Pipeline 组件版本,排查版本不匹配先看它
tkn version -C trigger查看 Trigger 组件版本
tkn version -C chain查看 Tekton Chains(签名)组件版本
brew install tektoncd-climacOS 安装
dnf install tektoncd-cliRHEL/Fedora 系安装
apt install tektoncd-cliDebian/Ubuntu 安装
go install github.com/tektoncd/cli/cmd/tkn@latestGo 安装,可拿最新特性
tkn --help查看全部子命令
tkn completion bash > /etc/bash_completion.d/tkn开启补全,子命令与参数非常多
kubectl get crd | grep tekton确认 Tekton CRD 是否已安装
tkn 依赖 kubeconfig集群不通时它是第一个报错的,先确认 kubectl 能用
命令 / 片段说明复制
tkn pipeline list列出当前命名空间的 Pipeline
tkn pipeline list -A跨命名空间列出全部 Pipeline
tkn pipeline describe my-pipeline查看 Pipeline 的参数、Task 顺序与最近运行
tkn pipeline start my-pipeline交互式触发,未给参数会提示输入
tkn pipeline start my-pipeline -p repo-url=https://git.example.com/app.git -p revision=main一次指定多个参数,CI 中最常用
tkn pipeline start my-pipeline --use-param-defaults全部使用默认值,适合冒烟验证
tkn pipeline start my-pipeline -s pipeline-sa指定 ServiceAccount,权限问题先查这里
tkn pipeline start my-pipeline -w name=source,claimName=source-pvc绑定已有 PVC 作为工作区
tkn pipeline start my-pipeline --showlog触发并直接跟随日志,日常最顺手
tkn pipeline start my-pipeline --dry-run只打印将要创建的 PipelineRun,不真正执行
tkn pipeline start my-pipeline -o name只输出生成的 PipelineRun 名称,便于脚本续接
tkn pipeline start my-pipeline --prefix-name生成带前缀的运行名,便于批量区分
tkn pipeline start -f pipeline.yaml直接运行本地 YAML,无需先在集群创建
tkn pipeline logs my-pipeline查看该 Pipeline 最近一次运行的日志
tkn pipeline delete my-pipeline删除 Pipeline 定义,不影响已产生的运行记录
tkn pipeline start my-pipeline --timeout 1h覆盖默认超时,长构建任务需要放宽
命令 / 片段说明复制
tkn pipelinerun list列出运行记录,含状态与耗时
tkn pipelinerun describe my-run查看各 Task 状态、参数、工作区与实际耗时
tkn pipelinerun logs my-run -f实时跟随日志,排查卡住必用
tkn pipelinerun logs my-run -t build只看指定 Task 的日志,长流水线效率更高
tkn pipelinerun logs my-run --all输出全部 Task 与 step 的日志
tkn pipelinerun logs my-run --step按 step 拆分展示(视版本)
tkn pipelinerun cancel my-run取消运行,卡死时先取消再排查
tkn pipelinerun delete my-run删除单条运行记录,释放关联资源
tkn pr listpr 是 pipelinerun 的简写,命令更长时可省字
tkn pipelinerun describe --last查看最近一次运行,不用先查名字
tkn pipelinerun logs --last -f跟随最近一次运行日志
tkn pipelinerun list -o json | jq ".items[].metadata.name"批量取运行名,做脚本处理
kubectl get pipelineruntkn 报错时退回 kubectl,状态与原因更原始
kubectl describe pipelinerun my-run查看 Events 里的调度与拉镜像失败原因
命令 / 片段说明复制
tkn task list列出命名空间内的 Task
tkn task list -A跨命名空间列出
tkn task describe build查看 Task 的输入参数、工作区与 step 定义
tkn task start build单独运行 Task,调试单个步骤很实用
tkn task start build -p image-tag=v1.2.3传入参数
tkn task start build -w name=source,claimName=source-pvc绑定工作区,缺工作区会直接失败
tkn task start build --showlog运行并跟随日志
tkn task start build --use-param-defaults用默认参数快速验证 Task 是否可用
tkn task start build --dry-run只生成 TaskRun,不执行
tkn task start build -o name输出 TaskRun 名称
tkn clustertask list列出集群级 Task(所有命名空间可见)
tkn clustertask describe git-clone查看官方 git-clone 的参数定义
tkn clustertask start git-clone -p url=https://git.example.com/app.git直接运行 ClusterTask
tkn task delete build删除 Task 定义
命令 / 片段说明复制
tkn taskrun list列出 TaskRun 与状态
tkn taskrun describe build-run查看 step 状态、Pod 名与失败原因
tkn taskrun logs build-run查看日志
tkn taskrun logs build-run -f --all跟随全部 step 的日志
tkn taskrun logs build-run --step-name build只看某个 step,日志量大时必备
tkn taskrun cancel build-run取消执行
tkn taskrun delete build-run删除记录
tkn taskrun delete --keep 5只保留最近 5 条,控制 CRD 数量
tkn taskrun list -o json | jq ".items[] | {name: .metadata.name, reason: .status.conditions[0].reason}"批量看失败原因
kubectl logs <pod> -c step-build直接看容器日志,绕过 tkn
kubectl get taskrun -o wide查看 STARTED 与 DURATION 列
命令 / 片段说明复制
-p key=value传字符串参数,多个参数可重复 -p
-p key=value1,value2数组类型参数用逗号分隔
--use-param-defaults未传的参数走默认值,避免逐个指定
-w name=shared,claimName=my-pvc使用已有 PVC
-w name=shared,volumeClaimTemplateFile=template.yaml按模板动态创建 PVC,用完可随运行清理
-w name=cache,emptyDir=使用 emptyDir,不需要持久化时最省事
-w name=cfg,config=my-config挂载 ConfigMap 作为工作区
-w name=sec,secret=my-secret挂载 Secret,证书与凭据常用
-s pipeline-sa指定 ServiceAccount,决定 Pod 的权限
kubectl create sa pipeline-sa创建专用 SA
kubectl patch serviceaccount pipeline-sa -p "{\"secrets\":[{\"name\":\"regcred\"}]}"把镜像拉取凭证挂到 SA 上
kubectl create rolebinding pipeline-sa-edit --clusterrole=edit --serviceaccount=default:pipeline-sa给 SA 授权,权限不足是常见失败原因
$(tasks.build.results.image)Task 间通过 results 传值,是流水线串联的关键
when 表达式按条件跳过某个 Task,替代已废弃的 Conditions
finally 段无论成败都执行的收尾 Task,用于通知与清理
retries: 2 与 timeout: 10m在 Task 或 Pipeline 上声明重试与超时
命令 / 片段说明复制
tkn triggerbinding list列出 TriggerBinding(从事件提取参数)
tkn triggerbinding describe my-binding查看提取了哪些字段,如 body.repository.url
tkn triggertemplate list列出 TriggerTemplate(定义要创建的资源)
tkn triggertemplate describe my-template查看模板参数与生成的 PipelineRun
tkn clustertriggerbinding list列出集群级 TriggerBinding
tkn eventlistener list列出 EventListener 与地址
tkn eventlistener describe my-el查看触发器链路与 Service 名称
tkn eventlistener logs my-el查看事件接收日志,webhook 排障第一现场
kubectl port-forward svc/el-my-el 8080:8080本地转发端口,用 curl 手动触发验证
curl -X POST -H "Content-Type: application/json" -d @payload.json http://localhost:8080手工投递事件,验证 Trigger 链路
CEL interceptor 过滤用 body.ref 等条件筛选分支,避免无效触发
kubectl get eventlistener -o yamltkn 信息不足时直接看 CR 定义
命令 / 片段说明复制
tkn hub search git-clone在 Tekton Hub 搜索可复用 Task
tkn hub install task git-clone安装官方 git-clone Task
tkn hub install task git-clone --version 0.9指定版本,避免默认版本不兼容
tkn hub install pipeline build-and-deploy安装整条 Pipeline
tkn hub upgrade task git-clone升级到新版本
tkn hub downgrade task git-clone回退版本,升级后不兼容时用
tkn hub list查看本地已安装的 Hub 资源
tkn bundle push registry.example.com/tekton/app:v1 -f task.yaml把定义打包成 OCI 镜像,便于分发
tkn bundle list registry.example.com/tekton/app:v1查看 Bundle 内的资源清单
离线环境先 install 后导出 YAMLHub 需外网,内网可导出后再 kubectl apply
命令 / 片段说明复制
tkn pipeline list -o jsonJSON 输出,便于 jq 解析
tkn pipelinerun list -o yamlYAML 输出,便于对比与存档
tkn pipeline list -o name只输出资源名,直接喂给下一个命令
tkn pipeline list -o template自定义字段输出(视版本),报表场景好用
tkn pipelinerun list --no-headers去掉表头,awk 处理更干净
tkn pipelinerun list -o json | jq -r ".items[] | [.metadata.name, .status.conditions[0].reason] | @tsv"导出运行名与状态,做巡检报表
tkn pipeline start app --showlog --prefix-nameCI 中运行并实时输出日志
tkn pipeline start app -o name | xargs kubectl wait --for=condition=Succeeded --timeout=30m等待运行结束,脚本化必备
echo $?tkn 命令失败会返回非零,可配合 set -e
tkn pipeline start app --dry-run -o yaml先看将创建的对象,确认无误再执行
tkn + kubectl 组合tkn 负责交互,kubectl 负责兜底与等待
命令 / 片段说明复制
tkn pipelinerun delete --keep 10只保留最近 10 条运行,避免 CRD 堆积
tkn pipelinerun delete --keep-since 24h按时间保留,跑得频繁时更合适
tkn pipelinerun delete --all清空全部运行记录,操作前先确认
tkn taskrun delete --keep 5TaskRun 同样需要定期清理
no pipelines found命名空间不对,用 -A 或 -n 指定
pipelineruns.tekton.dev not foundTekton 未安装或 CRD 缺失
Error: pipeline run failed运行失败,用 describe 看具体 Task 与 reason
TaskRun timeout超时被中断,检查 timeout 设置与卡住的 step
serviceaccount not foundSA 不存在或用错命名空间
workspace 未绑定 / missing workspace必须传 -w,且名字要与定义一致
unable to create pod多为 PVC Pending、资源不足或镜像拉取失败
failed to resolve taskTask 名写错或不在同一命名空间
cannot unmarshal / unknown fieldtkn 与 CRD 版本不匹配,升级 CLI 或 CRD
Error: connect refused 或 timeoutkubeconfig 或 API Server 不通
Step 卡在 Pending看 kubectl describe pod 的 Events,常见是镜像或亲和性
日志里没有输出但状态失败多半在 init 或拉镜像阶段就失败,需看 pod 事件
权限不足被拒绝SA 的 RoleBinding 缺失,或需要 clusterrole

运维常用组合

触发并盯日志tkn pipeline start app -p revision=main -s pipeline-sa -w name=source,claimName=source-pvc --showlog
失败排查tkn pipelinerun list → tkn pipelinerun describe <run> → tkn pipelinerun logs <run> -t build → kubectl describe pod <pod>
调试单个 Tasktkn task start build -p image-tag=test -w name=source,claimName=source-pvc --showlog
CI 中等待结果run=$(tkn pipeline start app -o name) → kubectl wait --for=condition=Succeeded --timeout=30m $run
Webhook 联调kubectl port-forward svc/el-my-el 8080:8080 → curl -X POST -d @payload.json http://localhost:8080 → tkn eventlistener logs my-el
定期清理tkn pipelinerun delete --keep-since 72h → tkn taskrun delete --keep 10

实战要点

1. 先 tkn version -C

CLI 与 Pipeline/Trigger 组件版本不一致会导致反序列化失败,排查前先对齐

2. start 之后看 reason

describe 里的条件 reason 比日志更早说明问题,例如超时、SA 不存在

3. 日志按 Task 过滤

长流水线用 -t 指定 Task,比翻全量日志快得多

4. 工作区必须显式绑定

缺失 -w 是最常见的启动失败原因,且报错信息通常很含糊

5. 结果靠 results 串

Task 之间用 $(tasks.x.results.y) 传值,不要在脚本里硬编码

6. 清理要自动化

PipelineRun 会持续堆积,用 --keep 或 TTL 控制器定期回收

共 133 条 tkn 命令 · 示例中的资源名、命名空间与地址请替换为实际环境

关于Tekton(tkn)命令速查

在线 Tekton CLI(tkn)命令速查手册,按安装与版本、Pipeline 管理、PipelineRun 与日志、Task 与 ClusterTask、TaskRun、参数与工作区、Trigger 与 EventListener、Hub 与 Bundle、输出格式与脚本化、清理与常见报错排查等 10 类场景整理 130 余条常用命令与参数组合,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 tkn version 与 -C pipeline/trigger/chain 组件版本 与 brew/dnf/apt/go install 安装 与 tkn completion bash/zsh/fish 补全、pipeline list 与 describe 与 start 的 -p/--param 与 --use-param-defaults 与 --last 与 -s/--serviceaccount 与 -w/--workspace 的 name= 与 claimName= 与 volumeClaimTemplateFile= 与 emptyDir= 与 config= 与 secret= 与 --showlog 与 --dry-run 与 -o name/json/yaml 与 --filename 与 --prefix-name 与 --timeout 与 tkn pipeline logs 与 delete,pipelinerun list 与 describe 与 logs 的 -f/--follow 与 -t/--task 与 --all 与 --step 与 cancel 与 delete 的 --keep/--keep-since/--all/--prs 与 --grace-period,task list/describe/start 的 -i 已废弃说明 与 taskrun list/describe/logs/cancel/delete 与 clustertask list/describe/start 与 clustertriggerbinding,以及 params 的 array/object 类型写法 与 results 与 workspaces 与 when expressions 与 finally 与 retries 与 timeout 与 sidecar 日志、triggerbinding 与 triggertemplate 的 list/describe 与 eventlistener list/describe/logs 与 Trigger 的 interceptors/CEL 过滤与 webhook 调试、tkn hub search/install/upgrade/downgrade task 与 pipeline 与 tkn bundle push/ list 与 OCI registry 存储,还有 -o json/yaml/name/template 与 --no-headers 与 jq 组合 与 CI 中的 --showlog --prefix-name 与 kubectl get pipelinerun 交叉排查,以及 no pipelines found、pipelineruns.tekton.dev not found(CRD 未安装)、Error: pipeline run failed、TaskRun timeout、serviceaccount not found、workspace 未绑定、unable to create pod(PVC pending/资源不足)、failed to resolve task、cannot unmarshal、tkn 版本与 CRD 版本不匹配 等报错排查。适用于 Kubernetes 上的 CI/CD 流水线手工触发与排查、Task 与 Pipeline 定义调试、参数与工作区调优、Webhook 触发链路验证、GitOps 环境发布与回滚、Tekton Hub 组件引入,以及 DevOps、SRE 与平台工程面试复习。

核心能力

  • 涵盖 tkn version 与 -C pipeline/trigger/chain 组件版本 与 brew/dnf/apt/go install 安装 与 tkn completion bash/zsh/fish 补全、pipeline list 与 describe 与 start 的 -p/--param 与 --use-param-defaults 与 --last 与 -s/--serviceaccount 与 -w/--workspace 的 name= 与 claimName= 与 volumeClaimTemplateFile= 与 emptyDir= 与 config= 与 secret= 与 --showlog 与 --dry-run 与 -o name/json/yaml 与 --filename 与 --prefix-name 与 --timeout 与 tkn pipeline logs 与 delete,pipelinerun list 与 describe 与 logs 的 -f/--follow 与 -t/--task 与 --all 与 --step 与 cancel 与 delete 的 --keep/--keep-since/--all/--prs 与 --grace-period,task list/describe/start 的 -i 已废弃说明 与 taskrun list/describe/logs/cancel/delete 与 clustertask list/describe/start 与 clustertriggerbinding,以及 params 的 array/object 类型写法 与 results 与 workspaces 与 when expressions 与 finally 与 retries 与 timeout 与 sidecar 日志、triggerbinding 与 triggertemplate 的 list/describe 与 eventlistener list/describe/logs 与 Trigger 的 interceptors/CEL 过滤与 webhook 调试、tkn hub search/install/upgrade/downgrade task 与 pipeline 与 tkn bundle push/ list 与 OCI registry 存储,还有 -o json/yaml/name/template 与 --no-headers 与 jq 组合 与 CI 中的 --showlog --prefix-name 与 kubectl get pipelinerun 交叉排查,以及 no pipelines found、pipelineruns.tekton.dev not found(CRD 未安装)、Error: pipeline run failed、TaskRun timeout、serviceaccount not found、workspace 未绑定、unable to create pod(PVC pending/资源不足)、failed to resolve task、cannot unmarshal、tkn 版本与 CRD 版本不匹配 等报错排查

适用场景

适用于 Kubernetes 上的 CI/CD 流水线手工触发与排查、Task 与 Pipeline 定义调试、参数与工作区调优、Webhook 触发链路验证、GitOps 环境发布与回滚、Tekton Hub 组件引入,以及 DevOps、SRE 与平台工程面试复习。Tekton(tkn)命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Tekton(tkn)命令速查是免费的吗?需要注册或安装吗?
Tekton(tkn)命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Tekton(tkn)命令速查支持哪些功能?
涵盖 tkn version 与 -C pipeline/trigger/chain 组件版本 与 brew/dnf/apt/go install 安装 与 tkn completion bash/zsh/fish 补全、pipeline list 与 describe 与 start 的 -p/--param 与 --use-param-defaults 与 --last 与 -s/--serviceaccount 与 -w/--workspace 的 name= 与 claimName= 与 volumeClaimTemplateFile= 与 emptyDir= 与 config= 与 secret= 与 --showlog 与 --dry-run 与 -o name/json/yaml 与 --filename 与 --prefix-name 与 --timeout 与 tkn pipeline logs 与 delete,pipelinerun list 与 describe 与 logs 的 -f/--follow 与 -t/--task 与 --all 与 --step 与 cancel 与 delete 的 --keep/--keep-since/--all/--prs 与 --grace-period,task list/describe/start 的 -i 已废弃说明 与 taskrun list/describe/logs/cancel/delete 与 clustertask list/describe/start 与 clustertriggerbinding,以及 params 的 array/object 类型写法 与 results 与 workspaces 与 when expressions 与 finally 与 retries 与 timeout 与 sidecar 日志、triggerbinding 与 triggertemplate 的 list/describe 与 eventlistener list/describe/logs 与 Trigger 的 interceptors/CEL 过滤与 webhook 调试、tkn hub search/install/upgrade/downgrade task 与 pipeline 与 tkn bundle push/ list 与 OCI registry 存储,还有 -o json/yaml/name/template 与 --no-headers 与 jq 组合 与 CI 中的 --showlog --prefix-name 与 kubectl get pipelinerun 交叉排查,以及 no pipelines found、pipelineruns.tekton.dev not found(CRD 未安装)、Error: pipeline run failed、TaskRun timeout、serviceaccount not found、workspace 未绑定、unable to create pod(PVC pending/资源不足)、failed to resolve task、cannot unmarshal、tkn 版本与 CRD 版本不匹配 等报错排查。
Tekton(tkn)命令速查适合哪些场景使用?
适用于 Kubernetes 上的 CI/CD 流水线手工触发与排查、Task 与 Pipeline 定义调试、参数与工作区调优、Webhook 触发链路验证、GitOps 环境发布与回滚、Tekton Hub 组件引入,以及 DevOps、SRE 与平台工程面试复习。