生产环境 DevOps 实战 | 第 14 天：tkn CLI 完全指南——用命令行管理 Tekton 资源

第 14/60 天

引言

在 Kubernetes 上部署了 Tekton Pipelines 之后，日常管理任务——查看 Task 状态、触发 PipelineRun、调试失败的 Step、查看日志——如果全靠 kubectl 操作 CRD 资源，效率极低。tkn（Tekton CLI）就是为此而生：它封装了 Tekton 所有 CRD 资源的常用操作，提供一套简洁、直观的命令行体验。

对于生产环境运维，掌握 tkn 意味着：
– 快速排查流水线故障（日志查看、Step 状态、Pod 事件）
– 手动触发和取消 PipelineRun
– 批量管理 Task、Pipeline、Trigger 资源
– 自动化脚本集成（CI/CD 排障、告警响应）

本文将系统讲解 tkn 的安装、配置、所有核心命令及生产场景最佳实践。

核心概念

tkn 与 kubectl 的定位差异

维度	kubectl	tkn
操作对象	所有 K8s 资源（Pod、Deployment、CRD）	仅 Tekton 资源（Task、Pipeline、Run 等）
输出格式	通用 YAML/JSON	专为 Tekton 定制的状态视图
日志查看	需要 kubectl logs -f pod -c step	tkn tr logs -f 一行搞定
资源列表	类型列表 + 过滤	按状态、时间、名称分组展示
学习成本	需要了解 CRD 资源结构	面向 Tekton 用户，语义化命令

一句话总结：kubectl 是 Kubernetes 的瑞士军刀，tkn 是 Tekton 的专用手术刀。

tkn 核心资源映射

Tekton CRD	tkn 命令缩写	功能
Task	t	定义单个构建/测试步骤
TaskRun	tr	Task 的一次执行实例
Pipeline	p	多个 Task 的有序编排
PipelineRun	pr	Pipeline 的一次执行实例
TriggerTemplate	tt	定义触发时的资源模板
TriggerBinding	tb	绑定事件参数到模板
EventListener	el	监听 webhook 事件
ClusterTask	ct	集群级可用 Task

实战步骤

第一步：安装 tkn CLI

方式一：通过 Homebrew（macOS/Linux）

# macOS
brew install tektoncd-cli

# Linux
brew install tektoncd-cli

方式二：下载二进制（推荐 Linux 生产环境）

# 获取最新版本
TKN_VERSION=$(curl -s https://api.github.com/repos/tektoncd/cli/releases/latest | grep tag_name | cut -d'"' -f4)
echo "Latest version: $TKN_VERSION"

# 下载 Linux amd64 版本
curl -LO https://github.com/tektoncd/cli/releases/download/${TKN_VERSION}/tkn_${TKN_VERSION#v}_Linux_x86_64.tar.gz

# 解压并安装
tar xvzf tkn_${TKN_VERSION#v}_Linux_x86_64.tar.gz -C /usr/local/bin/ tkn

# 验证安装
tkn version

方式三：包管理器（Ubuntu/Debian）

# 添加 Tekton 仓库
apt-get update && apt-get install -y gnupg
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add -
echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | tee /etc/apt/sources.list.d/google-cloud.list

# 安装
apt-get update && apt-get install -y google-cloud-sdk-kubectl-oidc
# 注意：官方推荐直接下载二进制，包管理器版本可能滞后

第二步：配置 kubectl 上下文

tkn 依赖当前的 kubectl 上下文来连接 Kubernetes 集群：

# 检查当前上下文
kubectl config current-context

# 切换到目标集群（如果有多个）
kubectl config use-context production-cluster

# 验证连接
kubectl cluster-info

# 查看 tkn 是否可用
tkn task list -n tekton-pipelines 2>/dev/null || echo "tkn 已就绪"

第三步：Task 与 TaskRun 管理

创建和查看 Task：

# 列出所有 Task
tkn t list -n default

# 查看 Task 详情（YAML 格式）
tkn t describe build-image -n default

# 查看 Task 的 YAML 定义
tkn t show build-image -n default

手动触发 TaskRun：

# 触发一个 TaskRun（不指定参数时使用默认值）
tkn task start build-image 
  --param IMAGE_NAME="nginx" 
  --param IMAGE_TAG="1.25" 
  --workspace name=source,claimName=shared-workspace 
  -n default

# 使用资源 spec 替代已有的 PVC
tkn task start build-image 
  --param IMAGE_NAME="nginx" 
  --param IMAGE_TAG="1.25" 
  --workspace name=source,emptyDir="" 
  -n default

查看 TaskRun 日志和状态：

# 查看所有 TaskRun
tkn tr list -n default

# 查看特定 TaskRun 的日志
tkn tr logs build-image-run-abcde -n default -f

# 查看 TaskRun 的详细状态
tkn tr describe build-image-run-abcde -n default

# 取消正在运行的 TaskRun
tkn tr cancel build-image-run-abcde -n default

第四步：Pipeline 与 PipelineRun 管理

Pipeline 操作：

# 列出所有 Pipeline
tkn p list -n default

# 查看 Pipeline 的 DAG（有向无环图）依赖关系
tkn p describe ci-pipeline -n default

# 将 Pipeline 导出为 YAML
tkn p export ci-pipeline -n default > ci-pipeline-backup.yaml

创建 PipelineRun：

# 从 Pipeline 创建 PipelineRun（交互式参数输入）
tkn pipeline start ci-pipeline -n default

# 非交互式，指定所有参数
tkn pipeline start ci-pipeline 
  --param repo-url="https://github.com/example/app.git" 
  --param branch="main" 
  --param image-name="registry.example.com/app" 
  --param image-tag="v1.0.0" 
  --workspace name=shared-workspace,claimName=workspace-pvc 
  --service-account build-bot 
  -n default

# 使用已有的 PipelineRun 作为参数模板
tkn pipeline start ci-pipeline 
  --last 
  -n default

PipelineRun 生命周期管理：

# 列出 PipelineRun（按状态过滤）
tkn pr list -n default
tkn pr list -n default --limit 10
tkn pr list -n default -S  # 按状态排序

# 查看实时日志
tkn pr logs -f -n default
tkn pr logs ci-pipeline-run-abcde -f -n default

# 查看具体 Step 的日志
tkn pr logs ci-pipeline-run-abcde 
  --step build-and-push 
  -f -n default

# 取消 PipelineRun
tkn pr cancel ci-pipeline-run-abcde -n default

# 删除 PipelineRun（清理已完成的任务）
tkn pr delete ci-pipeline-run-abcde -n default

# 批量删除所有失败的 PipelineRun
tkn pr delete --all -n default -p failed

第五步：Triggers 资源管理

# 列出 Triggers 资源
tkn tt list -n default
tkn tb list -n default
tkn el list -n default

# 查看 EventListener 的状态和事件历史
tkn el describe github-listener -n default

# 查看 EventListener 的日志（查看 webhook 处理情况）
tkn el logs github-listener -f -n default

第六步：生产环境实用技巧

输出格式控制：

# JSON 输出（用于脚本处理）
tkn pr list -n default -o json
tkn tr list -n default -o json

# 自定义列输出
tkn pr list -n default -o jsonpath='{range .items[*]}{.metadata.name}{"t"}{.status.conditions[0].reason}{"n"}{end}'

跨命名空间视图：

# 查看所有命名空间的 PipelineRun
tkn pr list --all-namespaces

# 查看特定命名空间
tkn pr list -n tekton-pipelines
tkn pr list -n app-team-a
tkn pr list -n app-team-b

自动补全配置：

# Bash 自动补全
source <(tkn completion bash)
echo "source <(tkn completion bash)" >> ~/.bashrc

# Zsh 自动补全
source <(tkn completion zsh)
echo "source <(tkn completion zsh)" >> ~/.zshrc

# 验证补全
tkn <TAB><TAB>  # 应显示所有子命令
tkn pr <TAB><TAB>  # 应显示所有 pr 子命令

常见问题

Q1: tkn 命令返回 Error: failed to list 或 not found

原因： 当前 kubectl 上下文指向的集群没有安装 Tekton Pipelines，或者命名空间不存在。

解决方案：

# 确认 Tekton 是否已安装
kubectl get crd | grep tekton

# 确认命名空间
kubectl get ns | grep -E 'tekton|default'

# 检查上下文
kubectl config current-context
kubectl config view --minify | grep namespace

Q2: 如何查看长时间运行的 PipelineRun 的中间日志？

场景： PipelineRun 正在运行，想查看当前执行到哪个 Step 及其日志。

解决方案：

# 实时跟随日志（自动切换到当前执行的 Step）
tkn pr logs -f -n default

# 查看当前 Step 状态
tkn pr describe ci-pipeline-run-abcde -n default | grep -A 5 "Step State"

# 查看 Pod 事件
kubectl describe pod -l tekton.dev/pipelineRun=ci-pipeline-run-abcde -n default

Q3: tkn pr cancel 后 PipelineRun 仍然显示 Running？

原因： cancel 命令发送了终止信号，但 Pod 可能正在清理资源或执行 preStop hook。

解决方案：

# 强制删除（注意：会丢失日志）
tkn pr delete ci-pipeline-run-abcde -n default

# 或者直接删除底层 Pod（Tekton 会自动标记为 Cancelled）
kubectl delete pod -l tekton.dev/pipelineRun=ci-pipeline-run-abcde -n default

Q4: tkn 命令输出太长，如何只显示关键信息？

场景： 在生产环境中有大量 PipelineRun，需要快速找到失败的。

解决方案：

# 按状态过滤
tkn pr list -n default -S  # 按状态排序，失败的在最前

# 使用 JSONPath 提取
tkn pr list -n default -o jsonpath='{range .items[*]}{.metadata.name}{"t"}{.status.conditions[0].reason}{"n"}{end}'

# 只看最近 3 条
tkn pr list -n default --limit 3

Q5: 如何将 tkn 集成到自动化脚本中？

场景： 需要在告警响应脚本中自动取消所有失败的 PipelineRun。

解决方案：

#!/bin/bash
# 自动清理失败的 PipelineRun 脚本
NAMESPACE="${1:-default}"

echo "检查命名空间 $NAMESPACE 中的失败 PipelineRun..."

# 获取所有失败的 PipelineRun
FAILED_RUNS=$(tkn pr list -n "$NAMESPACE" -o json | 
  jq -r '.items[] | select(.status.conditions[0].reason=="Failed") | .metadata.name')

if [ -z "$FAILED_RUNS" ]; then
  echo "没有失败的 PipelineRun"
  exit 0
fi

echo "发现失败的 PipelineRun:"
echo "$FAILED_RUNS"

# 删除失败的 PipelineRun
for run in $FAILED_RUNS; do
  echo "正在删除: $run"
  tkn pr delete "$run" -n "$NAMESPACE" --ignore-running
done

echo "清理完成"

总结

tkn CLI 是 Tekton 运维的核心工具，掌握它能大幅提升日常流水线管理效率。本文所学要点：

1. 安装与配置：推荐二进制下载方式，确保版本与集群中的 Tekton Pipelines 匹配；tkn 依赖 kubectl 上下文，切换集群前需确认目标
2. 核心命令：tkn t 管理 Task/TaskRun，tkn p 管理 Pipeline/PipelineRun，tkn tr/pr logs 是调试流水线的第一入口
3. 生产技巧：自动补全节省日常操作时间，JSON 输出便于脚本集成，--last 参数快速重试
4. 故障排查：tkn pr describe 查看 DAG 执行状态，tkn pr logs -f 实时跟踪日志，tkn pr cancel 和 tkn pr delete 控制生命周期

下一篇文章将进入第 3 周——镜像构建与 Harbor 实战，敬请期待！