为 PAC 创建 Git Secret
当您通过 Webhook(而不是 GitHub App)将仓库与 PAC 集成时,Repository 资源会引用一个 Kubernetes Secret,其中包含两项凭证:
- PAC 在正常流水线处理期间用于调用 Git provider API 的 Git 访问令牌,例如读取仓库元数据以及发布评论或提交状态。
- Git provider 在传送事件时包含的 Webhook Secret,PAC 可据此验证请求是否来自预期来源。
本指南将为 GitHub Webhook 模式和 GitLab Webhook 模式创建此 Secret。GitHub App 模式不需要每个仓库单独的 Secret,因为控制器使用集群范围的 App 凭证。
目录
PAC 如何读取 Secret前提条件步骤 1:创建 Git 访问令牌步骤 2:选择 Webhook Secret步骤 3:创建 Kubernetes Secret步骤 4:从 Repository 引用 Secret集中式 Webhook 注册令牌验证更新凭证平台约定后续步骤PAC 如何读取 Secret
PAC 通过 Repository.spec.git_provider 字段查找 Secret:
- 将
type设置为此 Repository 使用的 Git provider,例如github或gitlab。 - 如果在
secret上省略key,PAC 将读取provider.token。 - 如果在
webhook_secret上省略key,PAC 将读取webhook.secret。 secret.name和webhook_secret.name可以指向同一个Secret,也可以分别指向两个不同的对象。
Secret 必须与 Repository 资源位于同一命名空间中。例外情况是 Repository 同时从全局 Repository CR 继承 secret 和 webhook_secret:此时 PAC 会从全局 Repository 所在的命名空间(PAC 命名空间)读取令牌和 Webhook Secret。请以相同方式设置 secret 和 webhook_secret:两者都位于 Repository 中,并引用其自身命名空间中的 Secret;或者两者都从全局 Repository CR 继承。请参阅创建全局 Repository CR中的行为。
前提条件
- 具有在该仓库上创建 Personal Access Token(PAT)权限的 Git provider 帐户。
- 用于 Repository 资源的目标命名空间。
- 对该命名空间的
kubectl访问权限。 jqCLI,用于验证。
步骤 1:创建 Git 访问令牌
在 Git provider 上创建 PAT。此令牌存储在 Repository 命名空间中,PAC 在正常的流水线处理期间使用它。请将 Webhook 管理权限保留在集中式凭证中,除非你确实希望每个 Repository 所有者都存储一个能够创建或编辑 provider Webhook 的令牌。
请立即复制令牌。大多数 provider 只会显示一次令牌。
默认启用自动 Webhook 注册(tektoncd-enhancement-config ConfigMap 中的 pac-webhook-registration.enabled: true;请参阅通过 TektonConfig 配置增强功能)。启用此功能后,请创建一个具有 Webhook 管理权限的独立集中式凭证。创建该凭证需要对 Webhook 注册控制器命名空间中的 Secret 具有写入权限(默认安装中的 tekton-pipelines),通常需要集群管理员权限。请参阅集中式 Webhook 注册令牌。
步骤 2:选择 Webhook Secret
Webhook Secret 是 PAC 与 Git provider 之间共享的字符串。PAC 会根据此值验证传入的事件。
你可以使用任何足够随机的字符串,例如由密码管理器生成的密码。必须将相同的值存储在 Kubernetes Secret 中,并配置到 Git provider 的 Webhook 中。
如果你希望从命令行生成,可以使用 openssl:
示例输出:
Webhook Secret 是必需的。PAC 会在启动该事件的 PipelineRun 之前,检查 Git provider Webhook 发送的每个事件是否与此值匹配;传入 Webhook 端点的请求不使用此 Secret,而是根据其自己的 incoming Secret 进行检查(请参阅传入 Webhook)。GitLab Webhook 必须将相同的值作为其 Secret token 发送。在 GitLab 上,即使检查失败,PAC 仍会返回 HTTP 202,但会丢弃该事件且不会创建 PipelineRun;它记录的消息取决于 Webhook 是否发送了 Secret token。不带 Secret token 的 Webhook 会产生 could not validate payload, check your webhook secret?: no X-Gitlab-Token header detected: webhook validation requires a token for security;当自动注册为未引用 Webhook Secret 的 Repository 创建 Webhook 时,也会产生此消息,因为此时控制器注册 Webhook 时不会设置 Secret token。向未引用 Webhook Secret 的 Repository 发送 Secret token 的 Webhook 会产生 could not validate payload, check your webhook secret?: no webhook secret configured: set webhook secret in repository CR or secret。在 GitHub Webhook 模式下,PAC 也会返回 HTTP 202,丢弃此类事件且不会创建 PipelineRun。当 GitHub Webhook 没有 Secret 时,控制器随后会记录一行以 an error occurred: client setup failed: 开头、以 could not validate payload, check your webhook secret?: no signature has been detected, for security reason we are not allowing webhooks that has no secret 结尾的日志;当自动注册为未引用 Webhook Secret 的 Repository 创建 Webhook 时,也是这种情况;如果 Webhook 有 Secret 但 Repository 未引用 Secret,则会记录以 could not validate payload, check your webhook secret?: no webhook secret has been set, in repository CR or secret 开头的日志。
步骤 3:创建 Kubernetes Secret
创建一个 Secret,使用默认键存储这两个值。在 bash 或 zsh 中运行这些命令:在 POSIX sh(例如 dash)中,read -rs 会失败并使变量为空。read -rs 会将值读入 shell 变量而不显示该值,因此令牌和 Webhook Secret 不会出现在屏幕上或 shell 历史记录中。请分别单独运行每个 read -rs 行,然后粘贴值并按 Enter:如果将该行与后续行一起粘贴,不支持括号粘贴的 shell 会将下一行读取为该值。首先从步骤 1 读取 Git provider 令牌:
然后从步骤 2 读取共享的 Webhook Secret 字符串:
然后创建 Secret。unset 会在创建 Secret 后删除这些变量:
示例输出:
或者,也可以从 manifest 创建:
将 manifest 保存为 secret.yaml 并应用:
步骤 4:从 Repository 引用 Secret
在 Repository 资源中,将 git_provider.secret 和 git_provider.webhook_secret 都指向刚创建的 Secret。由于使用了默认键,可以省略 key 字段:
对于自托管 GitLab,还要将 git_provider.url 设置为 GitLab 基础 URL,如示例所示;如果不设置此项,PAC 可以使用此令牌向 https://gitlab.com 报告运行的最终状态。对于 GitLab.com,将其设置为 https://gitlab.com。
如果将凭证存储在非默认键下,请在两个字段上显式设置 key。
集中式 Webhook 注册令牌
要自动注册 Webhook,请将具有高权限的 Webhook 管理令牌保存在 Webhook 注册控制器命名空间中带有标签的 Secret 中。当 Repository 所有者不应存储能够创建或编辑 provider Webhook 的令牌时,这种方式非常有用。
集中式 Secret 仅由 Webhook 注册控制器用于注册或更新 Git provider Webhook。PAC 仍从 Repository.spec.git_provider.webhook_secret 读取 Webhook Secret,因此每个 Repository 都必须保留此引用;该引用在 Repository 中设置,或与全局 Repository CR 中的 secret 一起继承(请参阅How PAC reads the Secret)。
集中式令牌需要以下权限:
对于每种 provider 类型和 provider URL,在 Webhook 注册控制器命名空间中准确创建一个匹配的集中式 Secret。该命名空间是 tektoncd-enhancement-controller Deployment 所在的命名空间;在默认安装中为 tekton-pipelines;请将 <controller-namespace> 替换为该命名空间。在此处创建 Secret 需要对该命名空间中的 Secrets 具有写入权限,通常需要集群管理员权限:
对于 GitHub.com,使用 https://api.github.com 作为 provider URL。对于 GitHub Enterprise,使用 Enterprise API URL,例如 https://github.example.com/api/v3。
示例:
匹配规则:
- Secret 必须位于 Webhook 注册控制器运行所在的命名空间中。在默认安装中,该命名空间为
tekton-pipelines。 - Secret 必须具有
pac.tekton.alauda.io/provider-credential: "true",以便控制器将其作为集中式凭证进行监视。 provider-type必须匹配spec.git_provider.type。- 匹配前会规范化
pac.tekton.alauda.io/provider-url注解。对于 GitLab,https://gitlab.example.com和https://gitlab.example.com/api/v4都会匹配同一 provider。对于 GitHub Enterprise,请使用 API URL,例如https://github.example.com/api/v3。 - 如果多个 Secret 匹配同一 provider,注册会失败并显示
AmbiguousCredential。 - 如果
spec.git_provider.secret包含可用令牌,则会首先尝试使用该令牌。如果该令牌缺少 Webhook 管理权限,控制器会使用匹配的集中式 Secret 重试。
验证
确认 Secret 存在,并且两个键都包含值:
对于 26 个字符的令牌以及 Step 2 的 openssl 命令打印的 32 个字符的 Webhook Secret,示例输出如下:
这些数字是经过 base64 编码的值的长度。例如,具有 0 的键为空,可能是因为 Step 3 中的 read -rs 失败;请使用更新凭证中的命令再次设置两个值,这些命令会原地更新现有 Secret。对于已存在的 Secret,再次运行 Step 3 中的 kubectl create secret generic 命令会因 error: failed to create secret secrets "<secret-name>" already exists 而失败。长度超过 0 并不能说明值正确;下面的事件检查可以验证这一点。
启用自动 Webhook 注册后,请在创建 Repository 后立即检查它,如配置 GitLab Repository或配置 GitHub Repository的 Step 4 中所示。如果 git_provider.webhook_secret 引用的 Secret 不存在,或者它引用的键为空,Webhook 注册控制器会将 pac.tekton.alauda.io/webhook-registration-status 注解设置为 Failed,并将 pac.tekton.alauda.io/webhook-registration-reason 设置为 MissingWebhookSecret。
PAC 仅在处理 Repository 的事件时读取 Secret,因此创建 Repository 资源不会记录与其相关的任何日志。要检查 Secret,请发送一个事件(例如推送提交),并确认已创建 PipelineRun;在 GitLab 上,还要确认其状态显示在提交或合并请求中(请参阅配置 GitLab Repository)。此检查需要项目上存在 Webhook,该 Webhook 可以自动注册或手动注册;还需要在 .tekton/ 下存在其注解与事件匹配的 PipelineRun。没有这些条件,即使 Secret 正确,也不会创建 PipelineRun。如果没有出现 PipelineRun,请读取 PAC 命名空间中的控制器日志。这需要对其中 Pod 日志的读取权限,通常只有集群管理员具备该权限;下面的 Secret 缺失错误不会作为 Repository 上的事件记录。使用 -l 时,kubectl logs 仅打印最后 10 行,除非设置了 --tail,因此该命令会读取最近 10 分钟内的每一行;如果事件更早,请增大 --since:
如果 Repository 引用或继承的 Secret 不存在于 PAC 读取它的命名空间中(请参阅 PAC 如何读取 Secret),日志会针对该事件显示 cannot get secret from repository: secrets "<name>" not found,并且不会创建 PipelineRun。
在 GitLab 上,令牌问题会以以下两种方式之一表现出来:
-
如果 GitLab 拒绝令牌(例如令牌错误),PAC 不会创建
PipelineRun。控制器日志行取决于事件。对于推送事件,PAC 无法读取.tekton/,日志会显示failed to list .tekton dir: GET https://<gitlab-host>/api/v4/projects/<id>/repository/tree: 401 {message: 401 Unauthorized}。对于合并请求事件或合并请求评论,PAC 会先检查对源项目的访问权限,日志会显示failed to access GitLab source repository ID <id>: please ensure token has 'read_repository' scope on that repository,随后显示 GitLab 返回的错误。 -
如果令牌可以读取 Repository,但缺少
api作用域(例如read_api令牌),PAC 会创建并运行PipelineRun,但提交或合并请求上不会显示状态。Repository 会记录带有403 {error: insufficient_scope}的FailedToSetCommitStatus事件;无需访问 PAC 命名空间即可查看该事件。事件只会保留有限时间,因此请在事件发生后尽快检查:
如果自托管 GitLab 的 FailedToSetCommitStatus 事件显示 POST https://gitlab.com/api/v4/projects/<id>/statuses/<sha>,则 Repository 没有 git_provider.url;请按照Step 4中的说明进行设置。
请参阅常见问题获取完整的故障排查清单。
更新凭证
通过原位更新 Secret 轮换令牌。下面的命令适用于一个 Secret,该 Secret 按照Step 3中的说明,在默认键 provider.token 和 webhook.secret 下保存两个值;如果 Repository 设置了其他 key 名称,或引用了两个 Secret(请参阅 PAC 如何读取 Secret),请在命令中使用相应的键名和 Secret 名称。与 Step 3 一样,请在 bash 或 zsh 中运行命令,并单独运行每一行 read -rs 命令,然后粘贴值并按 Enter。首先读取新令牌:
然后将 Secret 的 webhook.secret 键中的当前 Webhook Secret 复制到变量中,以便更新时保留该值。该命令不会显示该值;它需要读取 Secret 的权限:
如果该键为空(Verification中的 0),请改为读取Step 2中的 Webhook Secret:
然后更新 Repository 引用的 Secret,并删除这些变量:
对于使用Step 3中的 kubectl create secret generic 命令创建的 Secret,第一个 kubectl apply 会警告 Secret 缺少 kubectl.kubernetes.io/last-applied-configuration 注解;Secret 仍会完成更新,最后一行输出为 secret/<secret-name> configured。
然后运行Verification中的检查。
PAC 会在每个传入事件发生时读取 Secret,因此无需重启控制器。自动 Webhook 注册也会对直接引用的 Repository Secret 的更改作出响应,而无需在这些 Secret 上设置标签。
更新集中式 Webhook 注册凭证时,Webhook 注册控制器会刷新与旧的或新的提供商标签和 URL 匹配的 Repository。删除集中式凭证标签或更改提供商 URL 后,依赖旧凭证的现有 Repository 会再次进行协调,并报告当前凭证状态。
平台约定
启用时机。当许多 Repository 以 Webhook 模式接入 PAC,且每个 Repository 否则都需要使用自己的高权限令牌来创建提供商 Webhook 时,请应用这些约定。项目只需在自己的命名空间中创建一个 Secret,并在其 Repository 中引用该 Secret。GitHub App 模式不使用每个 Repository 的 Secret 或自动 Webhook 注册,因此这些约定不适用于该模式。
推荐值。每个 Repository 都引用其自身命名空间中的一个 Secret,该 Secret 保存 provider.token 和 webhook.secret:按照 Step 3 中的说明创建该 Secret,并在 spec.git_provider.secret 和 spec.git_provider.webhook_secret 中同时引用它;其令牌仅具有 Step 1 中列出的 Repository 本地权限。Webhook 管理令牌集中存储:在 Webhook 注册控制器命名空间中(默认安装中为 tekton-pipelines),每种提供商类型和提供商 URL 各设置一个带标签的 Secret,如集中式 Webhook 注册令牌中所述。控制器会先尝试使用 Repository 令牌;由于该令牌没有 Webhook 管理权限,控制器会回退到集中式令牌,为每个 Repository 注册 Webhook。可选地,PAC 命名空间中的全局 Repository CR 可以保存共享的 git_provider 设置,使 Repository 只需声明其 url 和 git_provider.type。当 Repository 通过这种方式继承 secret 和 webhook_secret 时,PAC 会从 PAC 命名空间(默认安装中为 tekton-pipelines)读取其令牌和 Webhook Secret,而不是从 Repository 的命名空间读取(请参阅How PAC reads the Secret),因此每个继承 secret 的 Repository 都使用相同的令牌。保留 Repository 本地令牌的 Repository 必须设置自己的 git_provider.secret 和 git_provider.webhook_secret。此功能处于 Technology Preview 阶段,请参阅创建全局 Repository CR。要确认注册正常工作,请检查每个项目 Repository 的 pac.tekton.alauda.io/webhook-registration-status 注解是否为 Registered(控制器不会注册全局 Repository CR),具体说明请参阅配置 GitLab Repository和配置 GitHub Repository中的步骤 4。要停止使用集中式令牌,请先为每个保留自动注册的 Repository 的令牌授予集中式 Webhook 注册令牌中列出的 Webhook 管理权限,然后从集中式 Secret 中移除 pac.tekton.alauda.io/provider-credential 标签或删除该 Secret。如果某个 Repository 自身的令牌缺少该权限,则会显示 Failed,原因是 ProviderAPIError,并且控制器会保留其现有 Webhook。要停止使用全局 Repository CR,请参阅停止使用全局 Repository CR。
先决条件。必须通过 tektoncd-enhancement-controller 启用自动 Webhook 注册;有关 pac-webhook-registration.* 设置,请参阅通过 TektonConfig 配置增强功能。平台团队需要具有在 Webhook 注册控制器命名空间中创建 Secret 的权限,以及持有集中式 Webhook 注册令牌中所列 Webhook 管理权限的提供商身份。如果提供商 API 使用私有 CA,则必须先完成配置自定义证书中的控制器信任配置。