配置自定义 Git 仓库
目录
功能概述先决条件仓库布局Repository ConfigMap跨 namespace 的全局 Repository ConfigMapNamespace 级 Repository ConfigMapProject 级 Repository ConfigMap精确 Namespace allowlist可选 kind 路径和历史 catalog 别名ConfigMap 资源同步支持的凭证示例公共 HTTPS Repository带 Token 的 HTTPS Repository带 Username 和 Password 的 HTTPS Repository带 known_hosts 的 SSH Repository带内部 CA 的 HTTPS Repository与 Hub Resolver 一起使用验证了解更多功能概述
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-publicnamespace。
仓库布局
path 字段指向 Git 仓库中的一个 resource-kind 目录。在该路径下,每个 package 都有版本目录。
对于每个版本目录,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。
跨 namespace 的全局 Repository ConfigMap
当插件或管理员在与 artifacthub-shim 监视 namespace 不同的 namespace 中拥有 repository ConfigMap,但 catalog 仍应全局可见时,请使用此模式。全局 repository ConfigMap 发现默认已启用,并覆盖所有 namespace。启用此功能时,chart 会授予 artifacthub-shim 集群范围的 ConfigMap、引用的 Secret 和 Events 读取权限。
如果设置了 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。
Project 级 Repository ConfigMap
所有 cpaas.io/project 标签等于所属 Namespace 标签的 Namespace 都可以使用该 catalog。如果所属对象没有 project 标签,则该作用域无效。
精确 Namespace allowlist
该注解会覆盖任何 global、project 或 namespace 标签:
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 值:
支持的顶层 repository.yaml 字段:
支持的 gitRepositories[] 字段:
支持的 gitRepositories[].repositories[] 字段:
可选 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 示例:
在此配置下,仍使用 catalog: team-a 的旧 Pipeline 引用会解析到规范的 team-a-pipelines repository。新的引用应直接使用 catalog: team-a-pipelines。
支持的 gitRepositories[].extraResources[] 字段:
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。
资源路径必须始终位于 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 添加以下注解:
支持的凭证
引用的 Secret 可以包含以下一个或多个 key:
每个 Git repository 都可以引用不同的 Secret。
示例
公共 HTTPS Repository
当 Git repository 不需要认证时,请使用此模式。
带 Token 的 HTTPS Repository
对于通过 HTTPS 接受 personal access token 或 deploy token 的 Git provider,请使用 token。当省略 username 时,artifacthub-shim 会在 Git credential 提示中使用 oauth2 作为 username。
带 Username 和 Password 的 HTTPS Repository
当 Git server 需要 username 和 password 组合时,请使用此模式。
带 known_hosts 的 SSH Repository
SSH 认证请使用 sshPrivateKey 或 ssh-privatekey。Secret 还必须提供 known_hosts;默认情况下,host key 验证是严格的。
带内部 CA 的 HTTPS Repository
当 Git server 提供由内部 CA 签名的证书时,请使用 ca.crt。你可以在同一个 Secret 中将 ca.crt 与 token、username 或 password 组合使用。
与 Hub Resolver 一起使用
嵌套的 repositories[].name 是 hub resolver 使用的 catalog 值。例如,上述声明的 team-a-tasks repository 可通过
catalog: team-a-tasks 使用:
验证
应用 ConfigMap 和可选 Secret 后,请检查 repository ConfigMap 上的 Events:
期望的 Events:
RepositoryConfigAccepted表示repository.yaml已被接受。RepositorySourceReady表示 repository 源已完成索引,并且现在对 DevOps Hub UI 和 hub resolver 客户端可见。
你也可以直接列出最近的 repository ConfigMap Events:
如果 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 状态,以判断当前配置是否健康。