配置自定义 Git 仓库

功能概述

artifacthub-shim 可以从 Git 仓库加载额外的 Tekton catalog 资源。仓库通过带标签的 ConfigMap 声明。如果 Git 仓库是私有的或使用内部 CA,其仓库条目可以引用同一被监视 namespace 中的 Secret。

同一个 Git 仓库条目也可以声明 extraResources 目录。当 config.extraResourceSync.enabled=true 时,这些目录会作为 ConfigMap 同步到集群。

每个嵌套仓库的 name 都会成为 Artifact Hub API 路径、UI 路径以及 Tekton hub resolver catalog 参数使用的外部 catalog 名称。请将其视为稳定标识符。

有关资源 manifest 结构以及 catalog package 期望的标签和注解,请参阅 Author Catalog Resources。

先决条件

  • artifacthub-shim 已安装并可用。
  • config.enableConfigMapSources 为 true。
  • 你可以在 artifacthub-shim 所监视的 namespace 中创建 ConfigMap 和 Secret。默认情况下,这是安装 namespace。
  • 要从其他 namespace 注册全局可见的仓库,config.globalConfigMapSources.enabled 必须为 true。该选项默认已启用。config.globalConfigMapSources.allowedNamespaces 可限制哪些 namespace 可以将仓库提升为全局可见。
  • 要注册 namespace、project 或显式 allowlist 仓库,config.scopedConfigMapSources.enabled 必须为 true。该选项默认已启用。
  • Git 仓库遵循预期的 catalog 布局。
  • 当你希望导入 extraResources 目录时,必须启用运行时 ConfigMap 资源同步。默认仅允许 kube-public namespace。

仓库布局

path 字段指向 Git 仓库中的一个 resource-kind 目录。在该路径下,每个 package 都有版本目录。

task/
  run-script/
    0.1/
      README.md
      run-script.yaml
pipeline/
  build-deploy/
    0.2/
      README.md
      build-deploy.yaml
stepaction/
  echo-message/
    0.1/
      README.md
      echo-message.yaml

对于每个版本目录,artifacthub-shim 会先查找 <package>.yaml 或 <package>.yml。如果都不存在,则回退到单个 Tekton YAML 文件,其中 Kubernetes kind 与配置的源 kind 匹配。

Repository ConfigMap

每个 repository ConfigMap 必须具有 artifacthub-shim.alauda.io/repository: "true" 标签以及一个 repository.yaml data key。repository.yaml 载荷必须包含 gitRepositories 列表。每个 gitRepositories[] 项声明一个 Git 源。每个嵌套的 repositories[] 项声明一个从该 Git 源加载的、对外可见的 catalog repository。如果 ConfigMap 中任意项无效,artifacthub-shim 会拒绝整个 ConfigMap。

位于由 config.namespace 配置的主监视 namespace 中的 ConfigMap 会保留现有行为,并默认对全局可见。位于其他 namespace 的 ConfigMap 默认仅在该 namespace 内可见。将 artifacthub-shim.alauda.io/repository-visibility 设置为 global、project 或 namespace,即可选择显式作用域。Project 成员关系仅根据所属 Namespace 的标签 cpaas.io/project 推导。

注解 artifacthub-shim.alauda.io/repository-visible-namespaces 的优先级高于可见性标签。其逗号分隔值是一个精确的 Namespace allowlist;条目会被去除首尾空白并去重,且可以跨 project。空值、无效的 Namespace 名称,或不包含任何现有 Namespace 的列表都会使整个 ConfigMap 作用域失效,并从 serving index 中移除其先前内容。当只有部分 Namespace 条目不存在时,这些条目会被忽略,其余存在的 Namespace 仍将接收该 repository。

apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-team-a-catalogs
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-a/tekton-catalog.git
        revision: main
        repositories:
          - name: team-a-tasks
            displayName: Team A Tasks
            kind: task
            path: task
          - name: team-a-pipelines
            displayName: Team A Pipelines
            kind: pipeline
            path: pipeline
          - name: team-a-stepactions
            displayName: Team A StepActions
            kind: stepaction
            path: stepaction
        extraResources:
          - path: config

跨 namespace 的全局 Repository ConfigMap

当插件或管理员在与 artifacthub-shim 监视 namespace 不同的 namespace 中拥有 repository ConfigMap,但 catalog 仍应全局可见时,请使用此模式。全局 repository ConfigMap 发现默认已启用,并覆盖所有 namespace。启用此功能时,chart 会授予 artifacthub-shim 集群范围的 ConfigMap、引用的 Secret 和 Events 读取权限。

apiVersion: v1
kind: ConfigMap
metadata:
  name: team-b-global-catalogs
  namespace: team-b-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "global"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-b/tekton-catalog.git
        revision: main
        credentialRef:
          name: team-b-git-credential
        repositories:
          - name: team-b-global-tasks
            displayName: Team B Global Tasks
            kind: task
            path: task

如果设置了 credentialRef.name,Secret 会在与 repository ConfigMap 相同的 namespace 中解析。跨 namespace 源 namespace 中的 Secret 变更会在下一次 repository refresh 时被拾取;更新 repository ConfigMap 也会立即触发刷新。

Namespace 级 Repository ConfigMap

这是主监视 namespace 之外 repository ConfigMap 的默认行为。只有 team-a 中的 workloads 和感知 namespace 的 UI 请求可以使用该 catalog。

metadata:
  namespace: team-a
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "namespace"

Project 级 Repository ConfigMap

所有 cpaas.io/project 标签等于所属 Namespace 标签的 Namespace 都可以使用该 catalog。如果所属对象没有 project 标签,则该作用域无效。

metadata:
  namespace: team-a
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "project"

精确 Namespace allowlist

该注解会覆盖任何 global、project 或 namespace 标签:

metadata:
  namespace: team-a
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "project"
  annotations:
    artifacthub-shim.alauda.io/repository-visible-namespaces: team-a,team-c

Scoped ConfigMap 不得声明 extraResources。credentialRef 始终在 repository ConfigMap 所在的 Namespace 中解析 Secret,且不能引用其他 Namespace 中的 Secret。

感知 Namespace 的 UI API 会在搜索、分页、批量查找和内容读取之前过滤 Task、Pipeline 和 StepAction 记录。Hub ResolutionRequest 的创建也会经过扩展验证 webhook 的检查。被拒绝的请求会报告 CATALOG_VISIBILITY_DENIED;未知 catalog 和内部策略错误则会放行,以便 Hub resolver 返回其原生结果。

支持的 kind 值:

KindTekton resource
taskTask
pipelinePipeline
stepactionStepAction

支持的顶层 repository.yaml 字段:

字段必需描述
gitRepositories是要从此 ConfigMap 注册的 Git 源列表。

支持的 gitRepositories[] 字段:

字段必需描述
url是Git 仓库 URL。
revision是要检出的 branch、tag 或 commit。
credentialRef.name否包含 Git 凭证的 Secret 名称。
repositories否从该 Git 源加载的 catalog repositories。除非设置了 extraResources,否则为必需。
extraResources否从该 Git 源同步的 ConfigMap 资源目录。除非设置了 repositories,否则为必需。

支持的 gitRepositories[].repositories[] 字段:

字段必需描述
name是resolver 和 API 路径使用的稳定 catalog 名称。请将此值用作 hub resolver 的 catalog 参数。
displayName否人类可读的 catalog 名称。
kind是task、pipeline 或 stepaction 之一。
path是Git 仓库中的相对 catalog 路径。
disabledPackages否repository 本地的 package 或版本禁用规则。
optional否当为 true 时,缺失或空的 path 会作为 Ready 发布,且不包含任何 package。默认值为 false。
legacyCatalogAliases否在迁移期间可解析到此 repository 的历史 catalog 名称。API 响应仍会返回规范化的 name。

可选 kind 路径和历史 catalog 别名

仅当 repository 条目有意表示一个可能尚不存在的 kind 目录时,才使用 optional: true。这主要适用于已迁移的 Tekton Hub catalogs,其中旧 catalog 只有 task/、只有 pipeline/,或 mixed kind 覆盖。对于手写的 repository 条目,严格校验仍是默认行为。

legacyCatalogAliases 在迁移期间保留旧的 resolver 引用。该别名按 kind 作用域划分:一个 Pipeline 别名不会解析为同名的 Tasks。自引用别名会被忽略。如果一个别名指向多个 repositories,或与该 kind 的另一个规范 repository 名称冲突,shim 只会禁用该别名,并保持所有规范 repository 处于 ready 状态。

迁移后的 catalog 示例:

gitRepositories:
  - url: https://git.example.com/team-a/tekton-hub-catalog.git
    revision: main
    repositories:
      - name: team-a
        displayName: Team A Tasks
        kind: task
        path: task
        optional: true
      - name: team-a-pipelines
        displayName: Team A Pipelines
        kind: pipeline
        path: pipeline
        optional: true
        legacyCatalogAliases:
          - team-a
      - name: team-a-stepactions
        displayName: Team A StepActions
        kind: stepaction
        path: stepaction
        optional: true

在此配置下,仍使用 catalog: team-a 的旧 Pipeline 引用会解析到规范的 team-a-pipelines repository。新的引用应直接使用 catalog: team-a-pipelines。

支持的 gitRepositories[].extraResources[] 字段:

字段必需描述
path是Git 仓库中相对的资源目录路径。该目录会被递归扫描。

ConfigMap 资源同步

extraResources 当前仅导入 apiVersion: v1、kind: ConfigMap 的文档,且这些文档必须通过设置 metadata.labels["artifacthub-shim.alauda.io/import"] 为 "true" 来显式启用。 请将此标签添加到存储在 Git 仓库中的 ConfigMap YAML。未加标签的 ConfigMap、非 ConfigMap 资源以及无关文件都会被跳过。每个导入的 ConfigMap 都必须设置 metadata.name 和 metadata.namespace。namespace 必须列在 config.extraResourceSync.allowedNamespaces 中;chart 默认值为 kube-public。

apiVersion: v1
kind: ConfigMap
metadata:
  name: team-a-tool-image
  namespace: kube-public
  labels:
    artifacthub-shim.alauda.io/import: "true"
data:
  image: registry.example.com/team-a/tool:v1

资源路径必须始终位于 Git 仓库 checkout 目录内。资源扫描期间不会跟随符号链接。

资源同步 controller 会自动为同步到集群内的 ConfigMap 添加 artifacthub-shim 所有权标签,例如 artifacthub-shim.alauda.io/controller-namespace、 artifacthub-shim.alauda.io/controller-name 和 artifacthub-shim.alauda.io/resource-set。如果同名 ConfigMap 已存在但没有匹配的所有权标签,artifacthub-shim 会跳过它,且不会接管或覆盖它。

当两个资源源声明了相同的目标 ConfigMap 时,冲突会按单个 ConfigMap 对象进行处理。同一来源中的其他 ConfigMaps 会继续同步。如果内置 catalog 声明了其中一个重复项,则以内置 catalog 版本为准;否则,重复的 ConfigMap 会被跳过,直到源 manifest 变得唯一。

当已同步的 ConfigMap 从源目录中消失时,artifacthub-shim 会将其从集群中删除。若要在 ConfigMap 从 Git 中移除后仍保留其同步副本,请向集群内的 ConfigMap 添加以下注解:

metadata:
  annotations:
    artifacthub-shim.alauda.io/resource-policy: keep

支持的凭证

引用的 Secret 可以包含以下一个或多个 key:

Secret key用途
usernameHTTPS username。
passwordHTTPS password。
tokenHTTPS token。当 password 为空时,将其用作 password。
sshPrivateKeySSH private key。
ssh-privatekeySSH private key 的替代 key 名称。
known_hostsSSH known hosts 内容。设置 sshPrivateKey 或 ssh-privatekey 时为必需。
ca.crt内部 HTTPS Git server 的 CA bundle。

每个 Git repository 都可以引用不同的 Secret。

示例

公共 HTTPS Repository

当 Git repository 不需要认证时,请使用此模式。

apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-public-tasks
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/platform/public-tekton-catalog.git
        revision: main
        repositories:
          - name: public-tasks
            displayName: Public Tasks
            kind: task
            path: task

带 Token 的 HTTPS Repository

对于通过 HTTPS 接受 personal access token 或 deploy token 的 Git provider,请使用 token。当省略 username 时,artifacthub-shim 会在 Git credential 提示中使用 oauth2 作为 username。

apiVersion: v1
kind: Secret
metadata:
  name: team-a-token
  namespace: artifacthub-shim-system
type: Opaque
stringData:
  token: <git-token>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-team-a-tasks
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-a/tekton-catalog.git
        revision: main
        credentialRef:
          name: team-a-token
        repositories:
          - name: team-a-tasks
            displayName: Team A Tasks
            kind: task
            path: task

带 Username 和 Password 的 HTTPS Repository

当 Git server 需要 username 和 password 组合时,请使用此模式。

apiVersion: v1
kind: Secret
metadata:
  name: team-b-basic-auth
  namespace: artifacthub-shim-system
type: Opaque
stringData:
  username: <git-username>
  password: <git-password>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-team-b-pipelines
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-b/tekton-catalog.git
        revision: release-1.0
        credentialRef:
          name: team-b-basic-auth
        repositories:
          - name: team-b-pipelines
            displayName: Team B Pipelines
            kind: pipeline
            path: pipeline

带 known_hosts 的 SSH Repository

SSH 认证请使用 sshPrivateKey 或 ssh-privatekey。Secret 还必须提供 known_hosts;默认情况下,host key 验证是严格的。

apiVersion: v1
kind: Secret
metadata:
  name: team-c-ssh
  namespace: artifacthub-shim-system
type: Opaque
stringData:
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    <private-key>
    -----END OPENSSH PRIVATE KEY-----
  known_hosts: |
    git.example.com ssh-ed25519 <host-key>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-team-c-stepactions
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: ssh://git@git.example.com/team-c/tekton-catalog.git
        revision: main
        credentialRef:
          name: team-c-ssh
        repositories:
          - name: team-c-stepactions
            displayName: Team C StepActions
            kind: stepaction
            path: stepaction

带内部 CA 的 HTTPS Repository

当 Git server 提供由内部 CA 签名的证书时,请使用 ca.crt。你可以在同一个 Secret 中将 ca.crt 与 token、username 或 password 组合使用。

apiVersion: v1
kind: Secret
metadata:
  name: internal-git-token
  namespace: artifacthub-shim-system
type: Opaque
stringData:
  token: <git-token>
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <ca-certificate>
    -----END CERTIFICATE-----
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-internal-tasks
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.internal.example.com/devops/tekton-catalog.git
        revision: main
        credentialRef:
          name: internal-git-token
        repositories:
          - name: internal-tasks
            displayName: Internal Tasks
            kind: task
            path: task

与 Hub Resolver 一起使用

嵌套的 repositories[].name 是 hub resolver 使用的 catalog 值。例如,上述声明的 team-a-tasks repository 可通过 catalog: team-a-tasks 使用:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-team-a-task
spec:
  taskRef:
    resolver: hub
    params:
      - name: type
        value: artifact
      - name: catalog
        value: team-a-tasks
      - name: kind
        value: task
      - name: name
        value: run-script
      - name: version
        value: "0.1.0"
  params:
    - name: script
      value: echo docs-verify

验证

应用 ConfigMap 和可选 Secret 后,请检查 repository ConfigMap 上的 Events:

kubectl describe configmap artifacthub-shim-team-a-catalogs \
  -n artifacthub-shim-system

期望的 Events:

  • RepositoryConfigAccepted 表示 repository.yaml 已被接受。
  • RepositorySourceReady 表示 repository 源已完成索引,并且现在对 DevOps Hub UI 和 hub resolver 客户端可见。

你也可以直接列出最近的 repository ConfigMap Events:

kubectl get events -n artifacthub-shim-system \
  --field-selector involvedObject.kind=ConfigMap,involvedObject.name=artifacthub-shim-team-a-catalogs

如果 repository 没有变得可见,请先检查 RepositoryConfigInvalid、RepositorySourceInvalid 或 RepositorySourceDegraded Events。使用 artifacthub-shim pod 日志作为辅助来源,以获取完整的 Git 或 manifest 解析细节。

对于持续的 Warning 状态,artifacthub-shim 会在每次 refresh 或资源同步尝试时重新记录该 Warning。Kubernetes 通常会将其保留为一个 Event,并增加计数和更新最后时间戳。如果 event TTL 清理移除了之前的 Event,下一次尝试可以再次创建它。

Kubernetes Events 仍然是历史记录,可能会在 event TTL 清理之前保留旧的 Warning 条目。请优先参考最新的 repository Event 和 /api/v1/snapshot source 状态,以判断当前配置是否健康。

了解更多