Alauda DevOps Pipelines Docs
  • 简体中文

    • tkn pac 命令参考

    tkn pac 是 Pipelines-as-Code 的官方 CLI 插件。它可自动完成一次性设置（创建 Repository 资源、注册 webhook、生成起始 .tekton/pipelinerun.yaml），这些操作原本需要通过 kubectl apply 和 Git 提供商的 Web UI 手动完成。

    本页是面向偏好 CLI 工作流的用户的命令参考。有关使用普通 manifest 的推荐端到端操作步骤，请参阅 配置 GitHub Repository 和 配置 GitLab Repository。

    目录

    前提条件安装 tkn pac 插件验证安装Repository 命令tkn pac create repositorytkn pac listtkn pac repo describeGenerate 命令tkn pac generateResolve 命令tkn pac resolve全局选项最佳实践1. Repository 管理2. Pipeline 生成故障排除未找到命令连接问题下一步

    前提条件

    • 已安装 tkn CLI
    • 已安装 tkn pac 插件
    • 已配置 kubectl 以访问你的集群
    • PAC 组件已部署

    安装 tkn pac 插件

    从 Tekton CLI Releases 下载 tkn，然后从 tkn pac Releases 安装 pac 插件。

    请使用官方 tkn pac 项目发布指南中的任一方法安装 tkn pac，并确保可执行文件已位于你的 PATH 中。

    验证安装

    # 验证 tkn CLI
tkn version

    示例输出：

    Client version: 0.43.0
Pipeline version: v0.65.0
    # 验证 tkn-pac 插件
tkn pac version

    示例输出：

    0.39.2

    Repository 命令

    tkn pac create repository

    根据 pipeline run 模板创建一个新的 Pipelines as Code repository 和 namespace。

    基本语法：

    tkn pac create repo

    交互模式：

    该命令将提示你输入以下信息：

    1. Git repository URL（自动从当前目录检测）
    2. pipelines 所属的 namespace（默认：project-pipelines）
    3. Git 提供商特定信息（例如 GitLab 的 project ID）
    4. PAC controller URL（自动检测）
    5. Webhook secret（自动生成）
    6. Git 提供商 access token
    7. Git 提供商 API URL（因提供商而异）

    执行内容：

    • 在你的 Kubernetes 集群中创建 Repository CR
    • 自动配置 Git 提供商 webhook
    • 创建包含 Git 提供商凭据的 Kubernetes Secret
    • 在你的 repository 中生成 .tekton/pipelinerun.yaml 模板

    示例：

    cd /path/to/your/repo
tkn pac create repo

    示例输出（交互式提示）：

    ? Enter the Git repository URL: https://gitlab.com/user/repo
? Enter the namespace where the pipeline should run (default: default): project-pipelines
? Enter the GitLab project ID: 12345678
? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 
? Enter the webhook secret (default: auto-generated): 
? Enter the GitLab access token: glpat-xxxxxxxxxxxxxxxxxxxx
? Enter the GitLab API URL (default: https://gitlab.com): 
✓ Repository CR created successfully
✓ Webhook configured in GitLab
✓ Secret created
✓ Template generated at .tekton/pipelinerun.yaml

    有关按提供商分类的端到端操作步骤，请参阅 指南。

    tkn pac list

    列出所有 Pipelines as Code repositories，并显示关联运行的最近状态。

    基本语法：

    tkn pac list

    列出特定 namespace 中的资源：

    tkn pac list -n <namespace>

    输出格式：

    REPOSITORY          NAMESPACE          URL                                    LAST RUN STATUS
my-repo            project-pipelines  https://gitlab.com/user/repo       Succeeded
another-repo       production         https://gitlab.com/user/another    Running

    选项：

    • -n, --namespace <namespace>：指定要列出 repositories 的 namespace（默认：当前 kubectl context 的 namespace）
    • -A, --all-namespaces：列出所有 namespace 中的 repositories
    • -o, --output <format>：输出格式（default、json、yaml、wide）

    示例：

    # List all repositories in current namespace
tkn pac list

# List repositories in specific namespace
tkn pac list -n project-pipelines

# List repositories in all namespaces
tkn pac list -A

    tkn pac repo describe

    描述一个 Pipelines as Code repository 及其关联运行。

    基本语法：

    tkn pac repo describe <repository-name>

    选项：

    • -n, --namespace <namespace>：指定 repository 所在的 namespace（默认：当前 kubectl context 的 namespace）
    • -o, --output <format>：输出格式（default、json、yaml）

    输出内容包括：

    • Repository CR 详情
    • Git 提供商配置
    • Webhook 配置
    • 最近的 PipelineRun 状态
    • 最近一次运行信息

    示例：

    # Describe repository in current namespace
tkn pac repo describe my-repo

# Describe repository in specific namespace
tkn pac repo describe my-repo -n project-pipelines

    示例输出：

    Repository: my-repo
Namespace: project-pipelines
URL: https://gitlab.com/user/repo
Git Provider: gitlab
Status: Ready

Recent Runs:
  - pipelinerun-abc123: Succeeded (2 minutes ago)
  - pipelinerun-def456: Running (5 minutes ago)
  - pipelinerun-ghi789: Failed (10 minutes ago)

    Generate 命令

    tkn pac generate

    生成一个简单的 PipelineRun 模板。

    基本语法：

    tkn pac generate

    功能：

    • 自动从目录中检测当前 Git 信息
    • 使用基础语言检测能力
    • 根据检测到的语言添加额外任务
    • 创建 .tekton/pipelinerun.yaml 模板

    语言检测：

    该命令会检测项目语言并添加相应任务：

    • Python：检测 setup.py 或 requirements.txt，添加 pylint 任务
    • Go：检测 go.mod，添加 golangci-lint 任务
    • Node.js：检测 package.json，添加 npm 任务
    • Java：检测 pom.xml，添加 maven 任务

    示例：

    # Navigate to your repository
cd /path/to/your/repo

# Generate pipeline template
tkn pac generate

    示例输出：

    ✓ Pipeline template generated at .tekton/pipelinerun.yaml

    生成的模板示例：

    apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: generated-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 generated pipeline!"

    Resolve 命令

    tkn pac resolve

    以仿佛由 Pipelines as Code service 拥有的方式执行 pipeline run。这对于在不创建新 commit 的情况下在本地测试 pipeline 定义非常有用。

    “Resolve” 的含义是什么？

    resolve 命令会处理你的 PipelineRun 定义，并执行以下操作：

    • 将 PAC 变量（如 {{repo_url}}、{{revision}}）替换为实际值
    • 解析 task 注解（如有需要，从已配置的 DevOps Hub catalog 获取 tasks）
    • 验证 pipeline 结构
    • 展示最终的 PipelineRun 外观

    重要：该命令不会在你的集群中创建 PipelineRun。它只会在本地处理并验证 pipeline 定义。

    基本语法：

    tkn pac resolve -f <pipeline-file>

    选项：

    • -f, --file：pipeline 文件或目录的路径（必需）
    • -p, --param：覆盖参数值（格式：key=value）
    • -o, --output：输出格式（yaml、json 或 default）

    从文件解析：

    tkn pac resolve -f .tekton/pull-request.yaml

    从目录解析：

    tkn pac resolve -f .tekton/

    该命令会处理目录中的所有 .yaml 和 .yml 文件。

    覆盖参数：

    你可以覆盖从 Git repository 派生出的默认参数值：

    tkn pac resolve -f .tekton/pipelinerun.yaml \
  -p revision=main \
  -p repo_name=my-repo

    多个文件：

    你可以多次使用 -f 标志：

    tkn pac resolve -f .tekton/pipeline1.yaml -f .tekton/pipeline2.yaml

    自动检测：

    当从源码 repository 运行时，该命令会尝试：

    • 检测当前 Git 信息
    • 自动解析以下参数：
      • 当前 revision（commit SHA）
      • branch name
      • repository URL
      • repository name

    示例：

    # Resolve pipeline from current directory
cd /path/to/your/repo
tkn pac resolve -f .tekton/pipelinerun.yaml

    示例输出：

    Resolved pipeline:
- revision: abc1234
- repo_url: https://gitlab.com/user/repo
- branch: main
✓ Pipeline resolved successfully

    输出格式：

    该命令会将解析后的 PipelineRun YAML 输出到 stdout。你可以：

    • 保存到文件：tkn pac resolve -f .tekton/pipelinerun.yaml > resolved.yaml

    • 直接查看：tkn pac resolve -f .tekton/pipelinerun.yaml

    • 用于验证：在提交前检查变量是否已正确解析

      # Resolve with custom parameters
tkn pac resolve -f .tekton/pipelinerun.yaml \
  -p revision=feature-branch \
  -p repo_name=custom-repo

    示例输出：

    Resolved pipeline:
- revision: feature-branch
- repo_url: https://gitlab.com/user/custom-repo
- branch: feature-branch
✓ Pipeline resolved successfully

    使用场景：

    • 在本地测试 pipeline 定义
    • 在不创建 commit 的情况下调试 pipeline 问题
    • 在提交前验证 pipeline 语法
    • 测试参数解析

    全局选项

    所有 tkn pac 命令都支持以下全局选项：

    • -h, --help：显示命令帮助
    • -v, --version：显示版本信息
    • --kubeconfig：kubeconfig 文件路径
    • --context：要使用的 Kubernetes context

    最佳实践

    1. Repository 管理

    • 使用描述性名称：选择清晰的 repository 名称
    • 按 namespace 组织：在 namespace 中对相关 repositories 进行分组
    • 定期监控：使用 tkn pac list 监控 repository 状态

    2. Pipeline 生成

    • 审查生成的模板：始终审查并自定义生成的 pipelines
    • 本地测试：使用 tkn pac resolve 在提交前测试 pipelines
    • 版本控制：将 pipeline 定义提交到 Git

    故障排除

    未找到命令

    如果找不到 tkn pac 命令：

    1. 验证安装：

      tkn pac version

      示例输出：

      0.39.2

    2. 检查 PATH：确保 tkn-pac 位于你的 PATH 中

    3. 重新安装：如有需要，重新安装该插件

    连接问题

    如果命令无法连接到集群：

    1. 验证 kubectl：测试 kubectl 连接
    2. 检查 context：验证 Kubernetes context
    3. 查看权限：确保你拥有所需权限

    下一步