Tekton Pipeline 安装与初始化配置指南

目标：说明 Tekton 作为 Kubernetes 原生的 CI/CD 框架为何不适配传统 Compose 部署，并给出在 Kubernetes 集群上分步安装 Tekton Pipelines、Triggers 与 Dashboard 的完整命令行流程，以及安装后的初始化配置（命名空间、RBAC、默认 ServiceAccount、feature-flags）与验证步骤。命令与 YAML 采用 Tekton 官方发布模板。

⚠️ 宿主前置：本文全部 kubectl 操作与验证回显都需要一个可用的 Kubernetes 集群，并完成本机与集群 API 的联通配置；在无集群环境上无法复现，下述预期输出仅作参考。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（作为管理机）
系统架构：x86_64
Kubernetes：v1.30+（目标集群）
命令行：kubectl、tkn
Pipelines 命名空间：tekton-pipelines
Dashboard 命名空间：tekton-dashboard
目标特性：Pipelines 控制器、Triggers 事件、Dashboard 界面、feature-flags 初始化

二、前置条件

一个可用的 Kubernetes 集群，且 kubectl cluster-info 能联通其 API Server。
本机具备 root 权限，网络可访问 storage.googleapis.com/tekton-releases。
已安装 kubectl、curl、tar。

三、关于 Compose 适用性的诚实说明

Tekton 是运行在 Kubernetes 之上的 CRD + 控制器体系，其"进程"以 Kubernetes Deployment/Pod 形式由集群调度，而非传统意义上的单个可执行程序进程。因此：

不存在官方 docker-compose.yaml：Tekton 官方只提供面向 Kubernetes 的 release.yaml 清单，通过 kubectl apply 交付，没有 Compose 编排文件。
docker compose up 语义不适用：Compose 面向宿主机单机编排普通服务进程；而 Tekton 需要注册 CRD、Webhook 与控制器到集群管控面，交由集群调度与伸缩，无法用 Compose 复现同等能力。
本文档因此改为"安装 + 初始化配置"主线：主标题避开 Compose 命名，正文按 Kubernetes 原生安装顺序展开，既诚实说明 Compose 不适配，又完整覆盖安装与初始化。

💡 结论：在 Kubernetes 场景下，请采用本指南的 kubectl apply 部署方式；若必须在单机快速体验，也应先有一个可用 Kubernetes 集群，而不是用 Compose 模拟 Tekton 服务。

四、安装 Tekton Pipelines

4.1 应用官方发布清单

kubectl apply -f https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml

预期输出（需要一个可用的 Kubernetes 集群）：

customresourcedefinition.apiextensions.k8s.io/clustertasks.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/pipelines.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/tasks.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/pipelineruns.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/taskruns.tekton.dev created
service/tekton-pipelines-controller created
service/tekton-pipelines-webhook created
deployment.apps/tekton-pipelines-controller created
deployment.apps/tekton-pipelines-webhook created
# 其余 RBAC / ServiceAccount 等资源新建提示省略

4.2 校验控制器与 Webhook

kubectl get pods --namespace tekton-pipelines

预期输出：

NAME                                     READY   STATUS    RESTARTS   AGE
tekton-pipelines-controller-<hash>       1/1     Running   0          70s
tekton-pipelines-webhook-<hash>          1/1     Running   0          70s

五、安装 Tekton Triggers

Triggers 提供 CRD TriggerTemplate、TriggerBinding、EventListener，用于把外部事件（Git push / Webhook）转换为 PipelineRun。

kubectl apply -f https://storage.googleapis.com/tekton-releases/triggers/latest/release.yaml
kubectl apply -f https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.yaml

预期输出（节选）：

customresourcedefinition.apiextensions.k8s.io/clusterinterceptors.triggers.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/eventlisteners.triggers.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/triggerbindings.triggers.tekton.dev created
customresourcedefinition.apiextensions.k8s.io/triggertemplates.triggers.tekton.dev created
deployment.apps/tekton-triggers-controller created
deployment.apps/tekton-triggers-webhook created

💡 说明：interceptors.yaml 提供 github、gitlab、cel 等 ClusterInterceptor，用于解析与过滤 Webhook 载荷。Triggers 控制器会复用 tekton-pipelines 命名空间。

六、安装 Tekton Dashboard

kubectl apply -f https://storage.googleapis.com/tekton-releases/dashboard/latest/tekton-dashboard-release.yaml
kubectl get pods -n tekton-dashboard

预期输出：

NAME                                READY   STATUS    RESTARTS   AGE
tekton-dashboard-<hash>            1/1     Running   0          40s

本地预览界面：

kubectl port-forward service/tekton-dashboard -n tekton-dashboard 9097:9097
# 浏览器访问 http://127.0.0.1:9097

七、初始化配置

7.1 规划命名空间

为 CI/CD 资源单列命名空间，避免污染默认空间：

kubectl create namespace cicd
kubectl get namespaces

7.2 为运行账号配置默认 ServiceAccount 与 RBAC

运行 Pipeline/Task 需要 ServiceAccount；默认使用命名空间的 default ServiceAccount。赋予其所需 RBAC（访问 Tekton CR）：

# tekton-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tekton-cicd-crb
subjects:
  - kind: ServiceAccount
    name: default
    namespace: cicd
roleRef:
  kind: ClusterRole
  name: tekton-pipelines-controller-cluster-access
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f tekton-rbac.yaml

💡 说明：tekton-pipelines-controller-cluster-access 是 Pipelines 安装时创建、供控制器访问各类资源的 ClusterRole。若不想使用默认 SA，可创建独立 ServiceAccount 并在 PipelineRun/TaskRun 中通过 serviceAccountName 指定。

7.3 查看并调整 feature-flags

kubectl get configmap feature-flags -n tekton-pipelines -o yaml

说明（预期内容，以安装版本为准）：

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-api-fields: "stable"
  default-timeout-minutes: "60"
  default-cloud-events-sink: ""

需要实验性字段时，将 enable-api-fields 改为 alpha：

kubectl patch configmap feature-flags -n tekton-pipelines \
  -p '{"data":{"enable-api-fields":"alpha"}}'

⚠️ 注意：修改 ConfigMap 后 Webhook 会热加载，通常无需重启；但实验性字段可能与稳定行为不同，生产慎用 alpha。

7.4 为默认 ServiceAccount 配置私有仓库凭据（可选）

kubectl create secret docker-registry regcred \
  --docker-server=<registry> --docker-username=<user> --docker-password=<password> -n cicd
kubectl patch serviceaccount default -n cicd -p '{"imagePullSecrets":[{"name":"regcred"}]}'

⚠️ 说明：<registry>/<user>/<password> 为演示占位，请填入实际值或经密码管理工具注入；docker-registry 是 Kubernetes 内置的私有仓库凭据 Secret 类型（标准 imagePullSecrets）。

八、验证部署

8.1 创建 Task 并运行 TaskRun

# hello-task.yaml
apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: hello
spec:
  steps:
    - name: say-hello
      image: alpine
      command:
        - /bin/sh
      args:
        - -c
        - |
          echo "init ok"

kubectl create namespace cicd
kubectl apply -f hello-task.yaml -n cicd
kubectl create -f - <<'EOF'
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: hello-run
  namespace: cicd
spec:
  taskRef:
    name: hello
EOF

查看状态与日志：

tkn taskrun list -n cicd
tkn taskrun logs -f hello-run -n cicd

预期输出（节选）：

[say-hello] init ok

💡 说明：日志出现 [say-hello] init ok 即表明控制器成功调度并执行了第一步。

8.2 创建 Pipeline 并运行 PipelineRun

# pipeline-init.yaml
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: pipeline-init
  namespace: cicd
spec:
  tasks:
    - name: step-say
      taskRef:
        name: hello

kubectl apply -f pipeline-init.yaml
kubectl create -f - <<'EOF'
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-init-run
  namespace: cicd
spec:
  pipelineRef:
    name: pipeline-init
EOF
tkn pipelinerun list -n cicd
tkn pipelinerun logs -f pipeline-init-run -n cicd

💡 说明：PipelineRun 会先创建依赖的 TaskRun 再执行，日志与 TaskRun 日志一致。若在 Dashboard 中能同时看到 Pipeline 任务与运行成功状态，说明初始化完成。

九、常见问题（FAQ）

9.1 Triggers 的 EventListener 无法收到外部请求？

原因： EventListener Service 未暴露为可访问的 NodePort/负载均衡，或 Webhook 地址未配置。

解决： 检查 Service 暴露方式（kubectl get svc -n tekton-pipelines）；将 EventListener 的 spec.service.serviceType 设为 NodePort/LoadBalancer，或使用 Ingress/端口转发转发到对应地址。

9.2 默认 ServiceAccount 拉不到私有仓库镜像？

原因： 未给对应命名空间的 default SA 绑定 imagePullSecrets。

解决： 按 7.4 创建 docker-registry Secret 并 patch 到对应命名空间的 default SA。

9.3 Pipelines 控制器重启后配置丢失？

原因： 控制器配置（feature-flags 等）存放在 ConfigMap，若被误删或用 kubectl delete -f release.yaml 卸载会一并移除。

解决： 不要删除 tekton-pipelines 命名空间中的 feature-flags ConfigMap；配置变更用 kubectl patch configmap，避免手工替换整个文件。

9.4 修改 `enable-api-fields: alpha` 后部分字段不生效？

原因： 参数 alpha 需要 Webhook 重新加载，或对应字段仍需满足特定前置条件。

解决： 确认修改后 Webhook Pod 已完成滚动更新（kubectl rollout status deploy/tekton-pipelines-webhook -n tekton-pipelines）；仍不生效可重启 Webhook Deployment。

十、参考链接

本文档由 www.quzuo.net 平台开发

Tekton Pipeline 安装与初始化配置指南

Tekton Pipeline 安装与初始化配置指南

一、环境信息

二、前置条件

三、关于 Compose 适用性的诚实说明

四、安装 Tekton Pipelines

4.1 应用官方发布清单

4.2 校验控制器与 Webhook

五、安装 Tekton Triggers

六、安装 Tekton Dashboard

七、初始化配置

7.1 规划命名空间

7.2 为运行账号配置默认 ServiceAccount 与 RBAC

7.3 查看并调整 feature-flags

7.4 为默认 ServiceAccount 配置私有仓库凭据（可选）

八、验证部署

8.1 创建 Task 并运行 TaskRun

8.2 创建 Pipeline 并运行 PipelineRun

九、常见问题（FAQ）

9.1 Triggers 的 EventListener 无法收到外部请求？

9.2 默认 ServiceAccount 拉不到私有仓库镜像？

9.3 Pipelines 控制器重启后配置丢失？

9.4 修改 enable-api-fields: alpha 后部分字段不生效？

十、参考链接

9.4 修改 `enable-api-fields: alpha` 后部分字段不生效？