Tekton 安装部署实战指南

手把手带你跑通第一个 Pipeline

目录

• 一、Tekton 是什么？

• 二、核心概念速览

• 三、安装实战

• 3.1 安装 Tekton Pipelines

• 3.2 安装 tkn CLI

• 3.3 安装 Tekton Dashboard

• 四、跑通第一个 Pipeline

• 五、常见问题与排查

• 六、下一步学习路径

一、Tekton 是什么？

你有没有经历过这种场景——Jenkins 的 Pipeline 写得挺嗨，但每次加个节点、升级插件，就开始怀疑人生？或者 GitLab CI 很好用，但一涉及多集群部署、跨项目复用，就开始头疼？

说白了就是，传统的 CI/CD 工具在云原生这个环境下，显得有点水土不服。

而 Tekton 就是来解决这个问题的。它是 Kubernetes 原生的 CI/CD 框架，前身是 Knative 的 build-pipeline 项目，后来独立出来成了现在的 Tekton。你不需要额外搭建 Jenkins Master，直接在 K8s 集群上用 CRD（自定义资源）定义你的构建流水线，每一个 Task 跑在一个独立的 Pod 里。

怎么理解呢？

• Task = 一个函数，你定义它"做什么"

• TaskRun = 调用一次这个函数，执行一次

• Pipeline = 工作流编排，把多个 Task 串起来，前一个的输出给后一个

好比做一道菜：Task 是"切菜"和"炒菜"两个步骤的菜谱，TaskRun 是你今天真正动手切了一次菜，Pipeline 是一份完整的菜单——先切菜、再炒菜、最后装盘。

不过，在开始动手之前，得先搞清楚几个核心概念，不然你装完了也不知道该怎么用。

二、核心概念速览

刚开始接触 Tekton，你只需要搞明白下面这几个，其他的遇到再说。

Task 和 TaskRun

Task 是执行一系列命令的模板，里面可以定义多个 steps，每个 step 跑在一个容器里。所有 steps 共享一个 Pod 内的存储卷。

TaskRun 才是真正执行 Task 的实例。你定义一个 Task 只是写好菜谱，TaskRun 才是真的下厨。

下面就是一个最朴素的 Hello World Task：

apiVersion: tekton.dev/v1kind: Taskmetadata:  name: hello-worldspec:  steps:    - name: say-hello      image: busybox:latest      command:        - echo      args:        - "Hello, Tekton!"

要跑它，你需要创建一个 TaskRun：

apiVersion: tekton.dev/v1kind: TaskRunmetadata:  name: hello-world-runspec:  taskRef:    name: hello-world

创建之后，Tekton 会自动起一个 Pod 来跑这个 Task。跑完之后 Pod 会停在 Completed 状态，不会自动删除——方便你看日志。

Pipeline 和 PipelineRun

Pipeline 是把多个 Task 按顺序串起来。前面的 Task 跑完了，后面的才开始。你也可以用 runAfter 或者 from 来控制依赖关系。

PipelineRun 和 TaskRun 一样，是 Pipeline 的实际执行实例。

一个重要的弃用提醒：PipelineResource

有同学要问了：原文里不是有个 PipelineResource 吗？

解释一下：它现在已经 Deprecated（弃用）了。PipelineResource 原本用来定义输入输出（比如 GitHub 源码、Docker 镜像地址），但后来社区发现这个抽象太复杂、不够灵活。

替代方案是：

• Workspaces：共享存储卷，用来在 Task 之间传文件。相当于给你一个共享文件夹，Task A 往里写，Task B 往里读。

• Results：轻量级的键值对输出，适合传递字符串类型的结果（比如镜像 Tag、构建产物路径）。

如果你是新手，直接用 Workspaces 就行了，不用碰 PipelineResource。

说到这，我们先捋一捋

先装 Tekton，再装 CLI 工具，再装 Dashboard（可选但推荐），然后跑一个真实的 Pipeline 看看效果。顺序别搞反了。

三、安装实战

3.1 安装 Tekton Pipelines

安装 Tekton 核心组件其实就一条命令的事：

kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.65.0/release.yaml

这样会装一个稳定的发布版。当然 Tekton 更新比较频繁，建议去 Tekton Pipeline GitHub Releases 确认一下当前的最新版。

具体最新版本号，可以到 Tekton Pipeline GitHub Releases 确认。

问题 1：gcr 镜像拉不下来

这里有个坑： Tekton 官方的镜像托管在 gcr.io，国内网络环境大概率拉不下来。

我第一次配的时候，kubectl apply 下去之后，查 Pod 状态发现全是 ImagePullBackOff：

$ kubectlget pods -n tekton-pipelinesNAME                                           READY   STATUS             RESTARTS   AGEtekton-pipelines-controller-xxx                0/1     ImagePullBackOff   0          1mtekton-pipolicies-webhook-xxx                  0/1     ImagePullBackOff   0          1m

解决方法有两条路：

方案 A：配代理（推荐，一劳永逸）

如果你集群有 HTTP 代理出口，给 Containerd / Docker 配置代理拉 gcr.io 镜像。这个方案需要集群层面支持。

方案 B：用国内替代镜像（快速解决问题）

有些社区维护者会把镜像同步到 Docker Hub 或阿里云镜像仓库。你可以直接使用已经替换好镜像地址的 YAML 文件，或者自己去拉镜像然后 docker tag 重命名。

最简单的办法——先 docker pull 再 docker tag 推到你自己的镜像仓库，然后修改 YAML 中的 image 地址。

问题 2：webhook 启动慢，别急着下结论

创建完成之后，看一下命名空间的 Pod：

$ kubectlget pods -n tekton-pipelines -wNAME                                           READY   STATUS    RESTARTS   AGEtekton-pipelines-controller-59745c8bd6-nzzqb   1/1     Running   0          44stekton-pipelines-webhook-687fb7945b-p4xnp      0/1     Running   0          11m

你可能会愣一下——webhook 的 Pod 怎么一直是 0/1？是不是装错了？其实这不是错误，webhook 启动本来就需要一段时间，因为它要注册 Kubernetes 的 admission webhook，涉及证书签发和 API Server 通信。等一两分钟，它会变成 1/1。如果超过 3 分钟还卡在 0/1，再用 kubectl describe 看看 Events。

# 等 webhook 也 Ready$ kubectl wait -n tekton-pipelines --for=condition=ready pod -lapp=tekton-pipelines-webhook --timeout=180spod/tekton-pipelines-webhook-xxx condition met

3.2 安装 tkn CLI

装完核心组件后，我强烈建议你再装一下 CLI 工具 tkn，后面调试会舒服很多。

Mac 用户：

brew install tektoncd-cli

Linux 用户：

# 先查最新版本号（替换下面的 v0.39.0 为你看到的最新版）exportTKN_VERSION="0.39.0"wget https://github.com/tektoncd/cli/releases/download/v${TKN_VERSION}/tkn_${TKN_VERSION}_Linux_x86_64.tar.gztar -xvf tkn_${TKN_VERSION}_Linux_x86_64.tar.gzchmod+x tknsudomv tkn /usr/local/bin/

验证安装：

$ tkn version| Client version: v0.39.0（实际输出可能因版本略有差异）Pipeline version: v0.65.0

如果 Pipeline version 显示 unknown 或者版本号差太多，说明你安装的 CLI 版本和 Pipeline 版本不一致。建议两者保持大版本一致，至少 CLI 不低于 Pipeline 的版本。

3.3 安装 Tekton Dashboard（可选但推荐）

Dashboard 不是必须的，但对于新手来说，看一眼图形界面能帮你理解 Task 和 Pipeline 的生命周期。

kubectl apply --filename https://storage.googleapis.com/tekton-releases/dashboard/latest/release.yaml

同样，它会安装在 tekton-pipelines 命名空间。

问题 3：Dashboard 访问不了？Service 类型没改

默认安装后，Dashboard 的 Service 类型是 ClusterIP，只能在集群内部访问。

如果你想从本地浏览器直接看，有两个办法：

方法 1：用 Port-Forward（最省事，调试用）

先查一下 Dashboard 的实际端口：

kubectl get svc -n tekton-pipelines tekton-dashboard

记下端口号（不同版本可能不同，常见是 9097），然后：

kubectl port-forward -n tekton-pipelines service/tekton-dashboard 9097:9097

然后打开浏览器访问 http://localhost:9097

方法 2：改成 NodePort（适合内网环境）

kubectl patch svc -n tekton-pipelines tekton-dashboard -p'{"spec":{"type":"NodePort"}}'

然后查 NodePort 端口：

kubectl get svc -n tekton-pipelines tekton-dashboard

方法 3：配 Ingress（适合生产环境）

apiVersion: networking.k8s.io/v1kind: Ingressmetadata:  name: tekton-dashboard  namespace: tekton-pipelinesspec:  ingressClassName: nginx  rules:    - host: tekton.k8s.local      http:        paths:          - path: /            pathType: Prefix            backend:              service:                name: tekton-dashboard                port:                  number: 9097

创建完后，把 tekton.k8s.local 加到你的 hosts 文件（Linux/Mac 的 /etc/hosts），指向 Ingress 控制器所在节点的 IP。

四、跑通第一个 Pipeline

好了，装了那么多东西，概念也讲了，不如来动手跑一个真实的 Pipeline 感受一下。

4.1 创建 Task

先定义一个最简 Task，就干一件事——打印 Hello World：

cat <<EOF | kubectl apply -f -apiVersion: tekton.dev/v1kind: Taskmetadata:  name: hello-worldspec:  steps:    - name: say-hello      image: busybox:latest      command:        - echo      args:        - "Hello, Tekton!"EOF

4.2 创建 TaskRun 执行它

cat <<EOF | kubectl apply -f -apiVersion: tekton.dev/v1kind: TaskRunmetadata:  name: hello-world-runspec:  taskRef:    name: hello-worldEOF

然后查看执行状态：

$ tkn taskrun listNAME                STARTED         DURATION     STATUShello-world-run     1 minute ago    10 seconds   Succeeded

查看日志：

$ tkn taskrun logs hello-world-run[hello-world] Hello, Tekton!

看到 Hello, Tekton! 了？恭喜，你已经成功跑通了第一个 Task。

4.3 创建一个真正的 Pipeline（两个 Task 串联）

接下来我们把两个 Task 串起来——Task A 先打印消息，Task B 再打印"Done"。

先创建第二个 Task：

cat <<EOF | kubectl apply -f -apiVersion: tekton.dev/v1kind: Taskmetadata:  name: say-donespec:  steps:    - name: say-done      image: busybox:latest      command:        - echo      args:        - "All done!"EOF

然后定义 Pipeline：

cat <<EOF | kubectl apply -f -apiVersion: tekton.dev/v1kind: Pipelinemetadata:  name: hello-pipelinespec:  tasks:    - name: say-hello      taskRef:        name: hello-world    - name: say-done      taskRef:        name: say-done      runAfter:        - say-helloEOF

最后创建 PipelineRun 触发它：

cat <<EOF | kubectl apply -f -apiVersion: tekton.dev/v1kind: PipelineRunmetadata:  name: hello-pipeline-runspec:  pipelineRef:    name: hello-pipelineEOF

注意：如果你想多次运行，可以把 name 换成 generateName（比如 generateName: hello-pipeline-run-），这样每次会自动生成唯一名称，避免冲突。

查看 PipelineRun 状态：

$ tkn pipelinerun listNAME                   STARTED         DURATION     STATUShello-pipeline-run     30 seconds ago  20 seconds   Succeeded

查看详细日志：

$ tkn pipelinerun logs hello-pipeline-run

你会看到先打印 Hello, Tekton!，再打印 All done!。两个 Task 按顺序串起来了。

问题 4：Task 之间数据不共享——默认各跑各的 Pod

有同学要问了：Task A 生成了一个文件，Task B 怎么拿到？

默认情况下，Task 之间不共享数据。每个 Task 跑在自己的 Pod 里，Pod 之间是完全隔离的。

解决办法是使用 Workspaces。简单来说就是声明一个共享存储卷，挂载到多个 Task 里。你可以用 PVC、ConfigMap、或者 emptyDir（仅用于单次 PipelineRun 内共享）：

apiVersion: tekton.dev/v1kind: Taskmetadata:  name: write-taskspec:  workspaces:    - name: shared-data  steps:    - name: write      image: busybox      command:        - sh        - -c      args:        - echo "hello from task A" > $(workspaces.shared-data.path)/message.txt

另一个 Task 挂载同一个 Workspace 就能读到这个文件。

五、常见问题与排查

1: 装完了 Pod 一直 CrashLoopBackOff？

如果 controller 或 webhook 的 Pod CrashLoopBackOff，先对照上面 3.1 节的两个踩坑 排查——大概率是 gcr 镜像拉不下来，或者 webhook 还没 Ready。

如果等了 3 分钟还是不行，看日志：

kubectl logs -n tekton-pipelines -lapp=tekton-pipelines-webhook

通常是证书问题或者 API Server 无法回调 webhook 地址。

检查方法：

kubectl describe pod -n tekton-pipelines -lapp=tekton-pipelines-webhook

看 Events 部分，一般能找到原因，比如镜像拉不下来、资源不足等。

2: gcr 镜像完全拉不下来怎么办？

前面说过了，方案有两个：

1. 集群配代理（推荐，长期方案）

2. 改用国内镜像仓库的替代版本（临时方案）

如果你用的是 Docker Hub，可以搜一下社区同步的镜像，比如 jpetazzo 等用户可能做过同步。但最可靠的方法还是配代理。

3: tkn 命令报错 "no such host" 或连接不上？

检查 kubeconfig 是否正确：

kubectl cluster-info

如果 kubectl 能用但 tkn 报错，可能是 tkn 版本太旧，升级到最新版：

# 检查版本tkn version# 去 https://github.com/tektoncd/cli/releases 下载最新版

4: Dashboard 打开后空白页？

通常是 Service 类型没改。默认 ClusterIP 只能在集群内部访问。参考上面 3.3 节用 kubectl port-forward 或者改 NodePort。

另外一个可能是 浏览器缓存问题，清一下缓存或者用无痕模式试试。

5: Task 一直 Pending 不执行？

Task 在 Pod 里执行，Pod Pending 通常是资源不足：

kubectl describe pod -l tekton.dev/task=hello-world

看 Events 中的调度失败原因。常见原因：

• 集群节点资源不足（CPU/内存不够）

• 有节点污点（taint），Pod 没有对应的容忍

• PVC 未就绪（如果用 Workspaces 的话）

6: Pipeline version 显示 unknown？

tkn CLI 和 Pipeline 版本不匹配。升级 CLI：

# 或者重新下载对应版本tkn version

只要 Pipeline 核心能跑，unknown 不影响功能，只是版本显示问题。

六、建议下一步学习路径

跑通了第一个 Pipeline，你已经入门了。接下来可以往这几个方向深入：

1. Tekton Catalog：社区共享的 Task 和 Pipeline 仓库，现在已迁移到 ArtifactHub，可以直接搜你想用的 Task（比如 Git Clone、Docker Build、Kubectl Deploy），不用自己造轮子。

2. Tekton Triggers：配合 GitHub/GitLab Webhook，实现"代码 Push 自动触发 Pipeline"。这是 Tekton 真正发挥威力的地方。

3. Workspaces + Results：深入理解 Task 之间如何传数据。Workspaces 传大文件，Results 传小参数。

4. 进阶实战：搭建一个完整的 CI 流水线——Git Clone → 单元测试 → 构建镜像 → 推送镜像 → Kubernetes 部署。把这 5 个 Task 串起来，就是一个 Mini DevOps 平台了。

5. 官方文档：tekton.dev/docs 是最好的参考，尤其是 Pipeline 的 YAML 参考和 Task 的各种配置方式。

最后说一句：Tekton 的学习曲线是有的，但一旦你搞懂了 Task → Pipeline → Triggers 这条线，你会发现它比 Jenkins 清爽得多。遇到问题别硬扛，多看 Pod 日志，我踩过的坑，你大概率也会踩一遍，没事，踩过去了就是经验。