#PAC 核心概念

本文档详细概述了 Pipelines-as-Code (PAC) 背后的核心概念、其架构，以及它如何与 Kubernetes 和 Git provider 集成。

#什么是 Pipelines as Code？

Pipelines-as-Code (PAC) 是一个组件，可让你直接在源代码仓库中定义和管理 Tekton Pipeline 工作流。与其在 Kubernetes 集群中维护 pipeline，不如：

• 将 pipeline 定义与代码一起存储在 Git 中
• 对 pipeline 配置进行版本控制
• 通过 Merge Request 审查 pipeline 变更
• 通过 Git 事件自动触发 pipeline

#架构概览

PAC 由多个协同工作的关键组件组成：

#核心组件

#1. Repository 概念

#1.1. Repository Custom Resource

Repository Custom Resource 定义了 Git repository 与 PAC controller 之间的连接。

关键字段：

• spec.url：Git repository URL
• spec.git_provider：Git provider 配置（类型、URL、凭据）
• spec.webhook：Webhook 配置（用于验证的 secret）

示例：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

#2. PAC Controller

PAC Controller 是主要组件，负责：

• 接收来自 Git provider 的 webhook events
• 从 Git repositories 获取 pipeline 定义
• 在 Kubernetes 中创建 PipelineRun resources
• 管理 Repository CRs（Custom Resources）

Deployment：作为 Kubernetes Deployment 部署在某个 namespace 中（默认：tekton-pipelines，但可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义）。

#3. PAC Watcher

PAC Watcher 监控 PipelineRun 的执行，并：

• 跟踪 pipeline 状态（pending、running、success、failure）
• 将状态报告回 Git provider
• 更新 commit status 和 Pull Request/Merge Request checks

Deployment：作为 Kubernetes Deployment 部署在某个 namespace 中（默认：tekton-pipelines，但可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义）。

#4. PAC Webhook

PAC Webhook 接收来自 Git provider 的 HTTP 请求：

• 验证 webhook 签名
• 处理 webhook payload
• 将事件转发给 PAC Controller

Deployment：作为 Kubernetes Service 部署，并可选通过 Ingress/NodePort 对外暴露。

#工作原理

#1. Repository 注册

当你使用 tkn pac create repo 配置 repository 时：

1. 在 Kubernetes 集群中创建一个 Repository CR
2. 在 Git provider 中配置一个指向 PAC controller 的 webhook
3. 创建一个包含 Git provider 凭据的 Kubernetes Secret
4. 生成一个基础的 .tekton/pipelinerun.yaml 模板

#2. 事件流

PAC Event Flow Diagram

当发生 Git event（push、pull request、merge request、comment）时：

1. Git provider 发送 webhook → PAC Webhook 接收该事件
2. Webhook 验证 → PAC 验证 webhook 签名
3. 事件处理 → PAC Controller 处理该事件
4. Repository 查找 → Controller 找到匹配的 Repository CR
5. Pipeline 获取 → Controller 从 Git 获取 pipeline 定义
6. PipelineRun 创建 → Controller 在 Kubernetes 中创建 PipelineRun
7. 状态监控 → PAC Watcher 监控 PipelineRun 执行
8. 状态报告 → Watcher 将状态报告回 Git provider

#3. Pipeline 执行

1. PAC Controller 基于 pipeline 定义创建 PipelineRun
2. Tekton Pipeline controller 获取该 PipelineRun
3. 按顺序执行 pipeline tasks
4. PAC Watcher 监控执行过程
5. 将状态报告回 Git provider

#平台支持

#Kubernetes

PAC 可以通过 Tekton Operator 部署到标准 Kubernetes 集群。尽管 resource 名称中包含 "OpenShift"，但一个 patch 已启用 PAC controller 对 Kubernetes 的支持。

Deployment：直接创建 OpenShiftPipelinesAsCode CR。

#Git Provider 集成

PAC 支持多个 Git provider，包括 GitHub、GitLab、Bitbucket Cloud 和 Bitbucket Data Center。每个 provider 都有特定的集成特性：

Webhook 配置：

• URL：PAC controller endpoint
• Secret：用于验证的 webhook secret
• Events：Push、Pull Request/Merge Request、Comments

状态报告：

• Commit status 更新
• Pull Request/Merge Request status checks
• 基于 comment 的命令

认证：

• 具有适当 scope 的 Personal Access Token 或 App tokens（因 provider 而异）
• 存储在 Kubernetes Secret 中

有关特定 provider 的配置详情，请参阅：

• Configure Repository
• 文档中针对各 provider 的指南

#Pipeline 定义

#文件位置

默认情况下，PAC 会在以下位置查找 pipeline 定义：

• .tekton/pipelinerun.yaml（将处理所有 .tekton/*.yaml 的 PipelineRun manifest）
• .tekton/ 目录中的所有 .yaml 和 .yml 文件

#Pipeline 结构

PAC pipeline 是一个标准的 Tekton PipelineRun，并带有 PAC 特定的 annotations：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from PAC!"

#Event Annotations

PAC 使用 annotations 来确定何时触发 pipeline：

• pipelinesascode.tekton.dev/on-target-branch：事件的目标分支（例如，"[main]" 或 "[refs/heads/main]"）
• pipelinesascode.tekton.dev/on-event：事件类型（例如，"[push]" 或 "[pull_request]"）
• pipelinesascode.tekton.dev/on-comment：在 comment 命令时触发

更多详情请参阅 Event Annotations。

#变量和上下文

PAC 提供可在 pipeline 定义中使用的动态变量。变量使用 {{<var>}} 格式，并会在创建 PipelineRun 时由 PAC 自动展开。

更多详情请参阅 Parameterizing Commits and URLs。

#Git Context Variables

• {{repo_url}}：Repository 完整 URL
• {{revision}}：Commit 的完整 SHA revision
• {{source_branch}}：事件来源的分支名称
• {{target_branch}}：事件目标分支名称
• {{repo_owner}}：Repository 所有者
• {{repo_name}}：Repository 名称

#Event Context Variables

• {{sender}}：事件发送者的用户名或 account ID

#Pull Request / Merge Request Context Variables

• {{pull_request_number}}：Pull Request 或 Merge Request 编号（仅适用于 pull_request events）

有关可用变量及其用法的完整列表，请参阅 Parameterizing Commits and URLs。

#Task 解析

PAC 可以自动从多个来源解析 tasks：

1. Local Tasks：在 repository 中定义的 tasks
2. Tekton Hub：来自 Tekton Hub catalog 的 tasks
3. Remote URLs：来自远程 Git repositories 或 URL 的 tasks

更多详情请参阅 PAC Resolver。

#安全注意事项

#Webhook 安全

• Webhook secrets 用于验证传入请求
• Secrets 存储在 Kubernetes Secrets 中
• Git providers 验证 webhook 签名

#访问控制

• Repository CR 是 namespace 级别作用域
• RBAC 控制谁可以创建 Repository CR
• Git provider tokens 仅授予有限 scope，以确保安全

#Pipeline 权限

• PipelineRuns 在指定的 namespace 中运行
• ServiceAccounts 控制 pipeline 权限
• Secrets 会按需挂载

#最佳实践

#1. Repository 组织

• 将 pipeline 定义保存在 .tekton/ 目录中
• 使用具有描述性的 pipeline 名称
• 对所有 pipeline 变更进行版本控制

#2. Event 过滤

• 使用特定的分支模式
• 使用路径过滤来限制触发
• 分离 merge request 和 push pipeline

#3. Task 管理

• 尽可能使用 Tekton Hub tasks
• 创建可复用的 task 定义
• 对 task 定义进行版本控制

#4. 安全

• 不要在 pipeline 文件中硬编码 secrets
• 使用 Kubernetes Secrets
• 限制 pipeline 权限

#故障排除

#常见问题

1. Pipeline 未触发：检查 annotations 和分支名称
2. 未收到 webhook：验证 webhook URL 和 secret
3. 未找到 tasks：检查 task 引用和网络连通性
4. 未报告状态：验证 Git provider token 权限

有关详细的故障排除信息，请参阅 Common Issues。

#下一步

• Quick Start - 开始使用 PAC
• Manage PAC Component - 部署和管理 PAC
• Configure Repository - 设置 repository 集成
• Maintain Pipeline Code - 以代码方式定义 pipeline

#相关文档

• Pipeline As Code - Pipelines As Code 官方文档