生产环境 DevOps 实战 | 第 8 天：在 Kubernetes 上安装 Tekton Pipelines——kubectl 与 operator 两种方式

第 8/60 天

引言

Tekton 是云原生 CI/CD 领域的事实标准，所有流水线组件都以 Kubernetes CRD（Custom Resource Definition）的形式运行。但正因如此，安装 Tekton 并不是简单的 apt install 或 brew install——你需要理解它的部署模型、版本兼容性，以及在生产环境中的最佳实践。

在上一篇文章中，我们了解了 Tekton 的核心概念（Task、Pipeline、PipelineRun、Step）。本文将深入实操层面，手把手教你如何在 Kubernetes 集群上安装 Tekton Pipelines，并对比两种主流安装方式：kubectl 直接安装 vs Tekton Operator。内容包括前置检查、安装步骤、配置调优、版本升级策略，以及生产环境中的常见陷阱。

核心概念

Tekton 安装架构

Tekton Pipelines 的安装本质上是向 Kubernetes 集群中注册一组 CRD 和对应的控制器 Deployment：

两种安装方式对比

环境要求

• Kubernetes 集群：v1.24+（Tekton v0.56+ 要求）
• kubectl：v1.24+
• 集群资源：至少 2 核 CPU、4GB 内存（用于运行控制器）
• RBAC 权限：cluster-admin 或足够的权限创建 CRD、Namespace、Deployment

实战步骤

步骤一：环境检查

在开始安装前，先确认集群状态是否满足要求。

# 检查 Kubernetes 版本
kubectl version --short

# 检查集群节点状态
kubectl get nodes

# 检查是否有足够的资源
kubectl describe nodes | grep -E "cpu|Memory"

# 确认 kubectl 有 cluster-admin 权限
kubectl auth can-i create crd --all-namespaces

步骤二：方式一——kubectl 直接安装 Tekton Pipelines

这是最快捷的方式，适合开发环境或快速验证。

# 安装最新稳定版 Tekton Pipelines
kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml

# 等待所有组件就绪
kubectl wait --for=condition=Ready pods --all -n tekton-pipelines --timeout=300s

# 验证安装
kubectl get pods -n tekton-pipelines
kubectl get crd | grep tekton

预期输出应类似：

NAME                                      READY   STATUS    RESTARTS   AGE
tekton-pipelines-controller-xxxxx         1/1     Running   0          2m
tekton-pipelines-webhook-xxxxx            1/1     Running   0          2m

NAME                                       CREATED AT
clustertasks.tekton.dev                    2026-08-19T07:00:00Z
pipelines.tekton.dev                       2026-08-19T07:00:00Z
pipelineruns.tekton.dev                    2026-08-19T07:00:00Z
tasks.tekton.dev                           2026-08-19T07:00:00Z
taskruns.tekton.dev                        2026-08-19T07:00:00Z

如果需要安装特定版本（推荐生产环境锁定版本），使用版本标签替换 latest：

# 安装指定版本，例如 v0.56.0
kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.56.0/release.yaml

# 查看所有可用版本
curl -s https://api.github.com/repos/tektoncd/pipeline/releases | jq -r '.[].tag_name'

步骤三：方式二——通过 Tekton Operator 安装

Operator 方式适合生产环境，支持声明式配置和版本管理。首先需要安装 OLM（Operator Lifecycle Manager），然后部署 Tekton Operator。

# tekton-operator.yaml
# 1. 安装 OLM（如果尚未安装）
---
apiVersion: v1
kind: Namespace
metadata:
  name: olm
---
# 2. 安装 Tekton Operator
apiVersion: v1
kind: Namespace
metadata:
  name: tekton-operator
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: tekton-operator
  namespace: tekton-operator
spec:
  targetNamespaces:
  - tekton-operator
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: tekton-operator
  namespace: tekton-operator
spec:
  channel: alpha
  name: tekton-operator
  source: operatorhubio-catalog
  sourceNamespace: olm

或者使用更简单的 YAML 安装方式（不依赖 OLM）：

# 直接安装 Tekton Operator（不依赖 OLM）
kubectl apply --filename https://storage.googleapis.com/tekton-releases/operator/latest/release.yaml

# 等待 Operator 就绪
kubectl wait --for=condition=Ready pods --all -n tekton-operator --timeout=300s

安装完成后，通过 TektonConfig CR 声明式地配置 Tekton 组件：

# tekton-config.yaml
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all  # 可选：lite, all
  targetNamespace: tekton-pipelines
  config:
    # 自定义流水线配置
    pipelines:
      default-timeout-minutes: "60"
      default-service-account: "tekton-worker"
      metrics.prometheus-port: "9090"
    # 功能开关
    feature-flags:
      enable-tekton-oci-bundles: "true"
      enable-api-fields: "alpha"
  # 可选组件
  pruner:
    disabled: false
    resources:
      - pipelinerun
      - taskrun
    keep: 100
    schedule: "0 0 * * *"  # 每天清理一次

将此配置应用到集群：

kubectl apply -f tekton-config.yaml

步骤四：验证安装并运行第一个测试任务

无论使用哪种方式安装，安装完成后都应验证功能是否正常：

# hello-task.yaml
apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: hello-world
spec:
  steps:
    - name: say-hello
      image: alpine:3.18
      script: |
        #!/bin/sh
        echo "Hello, Tekton Pipelines!"
        echo "Tekton version: $(kubectl get tektonconfig config -o jsonpath='{.status.version}' 2>/dev/null || echo 'unknown')"
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: hello-world-run
spec:
  taskRef:
    name: hello-world
  params:
    - name: message
      value: "Tekton 安装验证成功！"

运行测试：

# 应用测试任务
kubectl apply -f hello-task.yaml

# 查看 TaskRun 日志
kubectl logs --selector=tekton.dev/taskRun=hello-world-run --all-containers --tail=50

# 确认 TaskRun 成功
kubectl get taskrun hello-world-run -o jsonpath='{.status.conditions[0].status}'
# 输出应为 "True"

步骤五：生产环境配置优化

安装完成后，针对生产环境进行核心配置优化：

# tekton-pipelines-configmap.yaml
# 修改 tekton-pipelines-controller 的 ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-timeout-minutes: "120"       # 流水线超时从 60 分钟改为 120 分钟
  default-service-account: "tekton-worker"  # 默认 ServiceAccount
  default-pod-template: |
    securityContext:
      runAsNonRoot: true
      runAsUser: 1000
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-tekton-oci-bundles: "true"    # 启用 OCI 包
  enable-api-fields: "alpha"           # 启用 Alpha API 特性
  results-from: "sidecar-log"          # Results 从 sidecar 日志获取
  send-cloudevents: "false"            # 未配置 CloudEvents 时关闭

# 应用优化配置
kubectl apply -f tekton-pipelines-configmap.yaml

# 滚动重启控制器以加载新配置
kubectl rollout restart deployment/tekton-pipelines-controller -n tekton-pipelines
kubectl rollout status deployment/tekton-pipelines-controller -n tekton-pipelines

# 配置 HPA 实现控制器自动扩缩容
cat <<EOF | kubectl apply -f -
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: tekton-pipelines-controller
  namespace: tekton-pipelines
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: tekton-pipelines-controller
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
EOF

常见问题

Q1：安装后 Pod 一直处于 CrashLoopBackOff 状态

原因： 最常见的原因是 Webhook 证书问题，或集群的准入控制器（ValidatingWebhookConfiguration）配置冲突。

解决：

# 检查 Webhook 日志
kubectl logs -n tekton-pipelines deployment/tekton-pipelines-webhook

# 如果证书有问题，手动重启 Webhook
kubectl delete pod -n tekton-pipelines -l app=tekton-pipelines-webhook

# 检查是否有其他 webhook 拦截了 Tekton 的请求
kubectl get validatingwebhookconfigurations | grep tekton

Q2：安装后执行流水线报 “no matches for kind TaskRun in version tekton.dev/v1”

原因： Tekton CRD 未正确注册，或集群中已存在旧版本的 CRD 冲突。

解决：

# 检查 CRD 是否已注册
kubectl get crd | grep tekton.dev

# 如果 CRD 缺失，重新安装
kubectl replace --force -f https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml

# 确保 Tekton 版本与 Kubernetes 版本兼容
# Tekton v0.56+ 需要 K8s v1.24+
kubectl version --short

Q3：kubectl apply release.yaml 时报 “the server is currently unable to handle the request”

原因： 集群 API Server 负载过高，或 Webhook 超时。常见于资源有限的单节点集群。

解决：

# 分批安装 CRD
kubectl apply -f https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml --server-side

# 或使用 --validate=false 跳过校验
kubectl apply -f https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml --validate=false

# 如果是 Webhook 超时，可以临时移除 Webhook
kubectl delete validatingwebhookconfiguration tekton-pipelines-webhook
kubectl delete mutatingwebhookconfiguration tekton-pipelines-webhook

Q4：Operator 安装后 TektonConfig 状态一直是 “NotReady”

原因： Operator 依赖的组件（如 OLM CatalogSource）未就绪，或网络原因无法拉取镜像。

解决：

# 检查 Operator 日志
kubectl logs -n tekton-operator deployment/tekton-operator

# 检查 CatalogSource 状态
kubectl get catalogsource -n olm

# 如果是镜像拉取问题，在国内环境建议配置镜像加速
# 参考：https://github.com/tektoncd/operator/blob/main/docs/install.md#install-with-custom-images

Q5：如何升级 Tekton Pipelines？

升级策略取决于安装方式：

• kubectl 方式： 直接 apply 新版本 YAML，Tekton 会自动处理 CRD 迁移和滚动更新
  bash
kubectl apply --server-side -f https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.57.0/release.yaml

• Operator 方式： 更新 TektonConfig 中的版本字段
  yaml
# 在 TektonConfig 中指定版本
spec:
pipeline:
version: "v0.57.0"
  然后等待 Operator 自动完成升级流程。

重要： 升级前务必阅读 Tekton 官方的 Migration Guide，因为 API 版本变更（如 v1beta1 → v1）可能导致旧资源无法使用。

总结

本文完整介绍了 Tekton Pipelines 的两种安装方式及其配置要点，核心要点如下：

1. kubectl 直接安装适合快速验证和开发环境，一条命令即可完成；Tekton Operator 适合生产环境，支持声明式配置、版本管理和多集群编排。
2. 安装完成后，务必通过 ConfigMap 优化 default-timeout-minutes、default-service-account 等参数，并配置 HPA 实现控制器高可用。
3. 无论哪种方式，安装后都应运行一个 Hello World 任务验证功能完整性，并检查 CRD 注册状态。
4. 生产环境推荐锁定版本（避免使用 latest），并提前规划升级策略，每次升级前阅读官方 Migration Guide。
5. 安装过程中的常见问题（CrashLoopBackOff、CRD 冲突、Webhook 超时）都有对应的排查手段，掌握这些可以大大缩短故障恢复时间。

下一篇文章，我们将深入编写第一个 Tekton Task，带你从零构建一个实际的容器镜像构建任务。