Alauda DevOps Pipelines Docs
  • 简体中文

    • tkn pac 命令参考

    适用于普通用户

    本指南涵盖用于仓库管理、Pipeline 生成和解析的 tkn pac CLI 命令。

    本指南提供 tkn pac CLI 插件命令的完整参考，包括仓库管理、Pipeline 生成和解析。

    目录

    前提条件安装 tkn pac 插件验证安装仓库命令tkn pac create repositorytkn pac listtkn pac repo describeGenerate 命令tkn pac generateResolve 命令tkn pac resolve全局选项最佳实践1. 仓库管理2. Pipeline 生成故障排查找不到命令连接问题后续步骤

    前提条件

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

    安装 tkn pac 插件

    请参阅 tkn pac Releases 了解最新版本。

    请使用官方 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

    仓库命令

    tkn pac create repository

    根据 PipelineRun 模板创建一个新的 Pipelines as Code 仓库和 namespace。

    基本语法：

    tkn pac create repo

    交互模式：

    该命令会提示你输入以下内容：

    1. Git 仓库 URL（可从当前目录自动检测）
    2. Pipeline 所在的 namespace（默认：project-pipelines）
    3. Git 提供商特定信息（例如 GitLab 的 project ID）
    4. PAC controller URL（自动检测）
    5. Webhook secret（自动生成）
    6. Git 提供商访问令牌
    7. Git 提供商 API URL（因提供商而异）

    功能：

    • 在你的 Kubernetes 集群中创建一个 Repository CR
    • 自动配置 Git 提供商 webhook
    • 使用 Git 提供商凭据创建 Kubernetes Secret
    • 在仓库中生成 .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

    有关详细用法，请参阅 Configure Repository。

    tkn pac list

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

    基本语法：

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

    示例：

    # 列出当前 namespace 中的所有仓库
tkn pac list

# 列出特定 namespace 中的仓库
tkn pac list -n project-pipelines

# 列出所有 namespace 中的仓库
tkn pac list -A

    tkn pac repo describe

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

    基本语法：

    tkn pac repo describe <repository-name>

    选项：

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

    输出包括：

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

    示例：

    # 描述当前 namespace 中的仓库
tkn pac repo describe my-repo

# 描述特定 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 任务

    示例：

    # 进入你的仓库
cd /path/to/your/repo

# 生成 pipeline 模板
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

    执行一个 Pipeline 运行，仿佛它由 Pipelines as Code 服务拥有。这对于在本地测试 Pipeline 定义而无需创建新提交非常有用。

    “Resolve” 是什么意思？

    resolve 命令会处理你的 PipelineRun 定义，并：

    • 将 PAC 变量（例如 {{repo_url}}、{{revision}}）替换为实际值
    • 解析 task 注解（如有需要，从 Tekton Hub 获取 task）
    • 验证 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 仓库派生的默认参数值：

    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

    自动检测：

    当在源代码仓库中运行时，该命令会尝试：

    • 检测当前 Git 信息
    • 自动解析以下参数：
      • 当前 revision（commit SHA）
      • 分支名称
      • 仓库 URL
      • 仓库名称

    示例：

    # 从当前目录解析 pipeline
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

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

      # 使用自定义参数进行解析
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 定义
    • 在不创建提交的情况下调试 pipeline 问题
    • 在提交前验证 pipeline 语法
    • 测试参数解析

    全局选项

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

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

    最佳实践

    1. 仓库管理

    • 使用描述性名称：选择清晰的仓库名称
    • 按 namespace 组织：将相关仓库分组到各自的 namespace 中
    • 定期监控：使用 tkn pac list 监控仓库状态

    2. Pipeline 生成

    • 审查生成的模板：始终检查并自定义生成的 pipeline
    • 本地测试：使用 tkn pac resolve 在提交前测试 pipeline
    • 版本控制：将 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. 检查权限：确保你拥有所需权限

    后续步骤