配置 Kubernetes 目录源
artifacthub-shim 可以直接从 Kubernetes 索引 Tekton Task、Pipeline 和 StepAction 对象。当目录资源由 GitOps 管理,并且不应维护单独的 Git 检出时,这种方式非常有用。
目录
配置层前提条件与项目或单个 namespace 共享目录1. 允许 shim 读取目录 namespace2. 为 Tekton 资源添加 label3. 使用预期的可见性注册源4. 从消费者 namespace 解析目录shim namespace 中的自动全局目录ConfigMap 定义的源字段参考RBAC 和刷新行为源的唯一性和优先级验证了解更多配置层
Kubernetes 目录源分为三层进行配置。每一层由不同的角色负责,并在不同的时间应用:
本页面上的每个 config.* 键都是 Helm Chart 值,而不是仓库 ConfigMap 中的字段。请使用 helm upgrade 更改这些值;在 ACP 上,则使用 ModuleInfo.spec.config.extraConfigValues。请参阅
Chart 配置。
为 Tekton 资源添加 label(第 3 层)无法将目录的作用域限定到某个 namespace 或项目。自动发现始终是全局的。当目录必须仅对某个 namespace 或某个项目可见时,请使用仓库 ConfigMap(第 2 层)。
前提条件
- 已安装并准备就绪
artifacthub-shim。 config.kubernetesSources.enabled为true。这是 Chart 的默认值。- 使用 ConfigMap 注册源时,
config.enableConfigMapSources为true。 - 当目录应仅对一个 namespace、一个项目或显式 Namespace allowlist 可见时,
config.scopedConfigMapSources.enabled为true。这是 Chart 的默认值。 - 存储 Tekton 资源的目标 namespace 必须是 shim namespace,或是
config.kubernetesSources.allowedNamespaces中的条目。ConfigMap 所有者 namespace 不会被隐式允许。 - 对于项目可见性,ConfigMap 所有者 Namespace 必须具有
cpaas.io/projectlabel。同一项目中的消费者 namespace 必须共享该 label。
与项目或单个 namespace 共享目录
这是常见任务的复制粘贴路径:将 Tekton 资源保留在一个 namespace 中,并允许同一项目中的其他 namespace,或仅允许一个消费者 namespace 解析这些资源。
根据需要替换示例名称:
- Shim 安装 namespace:
artifacthub-shim-system - 目录资源 namespace:
team-a-catalog - ConfigMap 所有者 namespace:
team-a - 同一项目中的另一个消费者 namespace:
team-a-dev - 项目标识:
team-a
1. 允许 shim 读取目录 namespace
集群管理员将资源 namespace 添加到 Helm allowlist。在 ACP 上,将相同的键放在 ModuleInfo.spec.config.extraConfigValues 下,且不要添加外层的 config: 键:
然后升级 Chart,使 shim 在 team-a-catalog 中获得 get/list/watch Roles。
2. 为 Tekton 资源添加 label
目录作者应用两个必需的 label。将版本加引号,以免 YAML 将 1.2 解析为浮点数:
3. 使用预期的可见性注册源
在项目 namespace 中创建仓库 ConfigMap,而不是在 shim namespace 中创建。显式设置可见性 label。
将目录共享给所有 cpaas.io/project label 等于所有者 Namespace label 的 namespace:
将目录限制为仅 ConfigMap 所有者 namespace:
shim namespace 中的仓库 ConfigMap 默认使用 global。在任何其他 namespace 中,它默认使用 namespace,这意味着只有其自身 namespace 可以使用该目录。若要将其共享给项目中的其他 namespace,必须显式设置 artifacthub-shim.alauda.io/repository-visibility: project。将 shim namespace 示例复制到团队 namespace 中,会将默认值从集群范围静默更改为仅所有者可用;源仍可能处于 Ready 状态,但其他 namespace 永远无法解析它。
name 字段既是对外显示的目录名称,也是默认的 label selector 值。使用上述示例时,除非设置 selector,否则 shim 会选择 artifacthub-shim.alauda.io/catalog=team-a-tasks。
4. 从消费者 namespace 解析目录
team-a-dev 中的 TaskRun 可以使用项目范围的目录:
完整的可见性选项(global、project、namespace 以及显式 Namespace allowlist annotation)记录在目录可见性中。
shim namespace 中的自动全局目录
当您需要集群范围的目录,且 Tekton 资源已经位于 shim namespace 中时,可以跳过 ConfigMap,改用自动发现。
Chart 的 config.kubernetesSources.enabled 值默认已启用。在 shim 运行的 namespace 中,为资源添加以下 labels:
catalog label 的值是 Artifact Hub 目录名称。所有匹配的资源都会自动加载到全局源中。自动发现的源始终是全局的,无法设置作用域;如果需要 namespace 或项目范围的作用域,请使用与项目或一个 namespace 共享目录中的 ConfigMap 形式。自动发现也只会扫描 shim namespace。
版本 label 是必需的,用于表示当前目录版本;Kubernetes 资源不会作为历史版本保留。移除目录 label 后,该资源会在下一次 watch 或定期刷新时被禁用。
格式错误的资源会被跳过并生成 Warning,而同一源中的有效资源会继续提供服务。如果所有匹配的资源都无效,则整个源会失败并产生永久错误,而不是提供空目录,也不会复用最近一次正常内容。
为匹配的 Tekton Hub resolver kind 使用生成的目录名称。目录名称在 Task、Pipeline 和 StepAction 源之间不区分大小写且必须唯一,因此不要对不同 kind 重复使用同一个 label 值。resolver 仍使用显式的 kind 参数来选择资源类型。例如,TaskRun 可以解析自动发现的 Task:
PipelineRun pipelineRef 以及 TaskRun 中的 StepAction 引用使用相同的 catalog、type、kind、name 和 version 参数。
不存在单独的 globalSources 列表。目录 label 是 shim namespace 中资源的显式启用/禁用约定,从而避免在 Helm 配置中重复列出资源名称。
ConfigMap 定义的源
当源 namespace 与 shim namespace 不同时、需要自定义 selector,或目录不能设为全局目录时,请使用 repository ConfigMap。
如果在 kubernetesRepositories[] 下省略 namespace,则默认为拥有 repository ConfigMap 的 namespace。此默认值不会绕过 config.kubernetesSources.allowedNamespaces:shim namespace 外部的目标仍需显式列出。
启用 Kubernetes 源时,会严格解码 repository.yaml schema,因此会拒绝 matchLabel 等未知字段。在 chart upgrade 期间,设置 config.kubernetesSources.enabled=false 会忽略完整的 kubernetesRepositories 部分,而同一 ConfigMap 中的 Git repository 仍保持活动状态。
省略 selector 时,shim 使用 artifacthub-shim.alauda.io/catalog=<the entry's name field>。name 既是对外可见的目录名称,也是默认的 label 值。在同一 repositories[] 条目上显式设置 selector 会替换此默认值:
selector: {} 会有意匹配目标 namespace 中所选 kind 的每个资源,应谨慎使用。
目标 namespace 必须是 shim namespace,或列在 config.kubernetesSources.allowedNamespaces 中;此 Helm 设置控制对 Tekton 资源的读取,与 config.globalConfigMapSources.allowedNamespaces 无关,后者控制哪些 namespace 可以注册全局可见的 repository ConfigMap。
字段参考
此源类型支持的顶层 repository.yaml 字段:
支持的 kubernetesRepositories[] 字段:
支持的 kubernetesRepositories[].repositories[] 字段:
RBAC 和刷新行为
chart 会为 shim namespace 中的 Tekton 资源授予 get/list/watch。
对于 config.kubernetesSources.allowedNamespaces 中的每个 namespace,chart 都会生成一个具有相同 verbs 的 namespaced Role 和 RoleBinding。默认不会创建全局范围的 Tekton 读取权限。如果 operator 单独管理 RBAC,请向 shim ServiceAccount 授予相同的权限。
资源 watch 事件会触发刷新;定期刷新仍作为遗漏事件或 API watch 重启时的后备机制。检查源状态和 pod 日志,获取目录名称、kind、目标 namespace、selector、警告以及上次刷新时间。如果源不可见,请验证版本 label、目标 namespace allowlist、selector 语法、ServiceAccount RBAC 以及目录可见性。
当 Kubernetes API List 暂时失败时,受影响 kind 最近一次成功的自动发现结果仍可用,并且该源状态会变为 Degraded;其他 kind 会继续刷新。永久性的 API 或权限失败只会移除受影响的自动 kind,直到再次成功完成发现。
设置 config.kubernetesSources.enabled=false 会同时禁用自动 label
发现和 ConfigMap kubernetesRepositories;Git repository 仍可正常工作。
源的唯一性和优先级
目录名称在所有受支持的 kind 和相互竞争的源之间均不区分大小写且必须唯一。
重复项处理分为两个步骤:
- 刷新时首先为每个目录名称选择一个胜出者。源优先级依次为内置目录、由 shim namespace 所有的 ConfigMap 源、由其他 namespace 所有的 ConfigMap 源,最后是自动 label 发现;在同一层级内使用源标识的字典序打破平局。显式 ConfigMap 源始终优先于同一目录名称的自动发现。
- 完成上述选择后,任何剩余冲突都会被标记为 Invalid,而不是进行合并。
这两个步骤相互独立。优先级决定保留哪个源;经过该选择后仍发生冲突的重复项会被拒绝。
验证
应用 Tekton 资源和可选的 repository ConfigMap 后,如果使用的是 ConfigMap 形式,请检查 ConfigMap Events:
预期的 Events:
RepositoryConfigAccepted表示已接受repository.yaml。RepositorySourceReady表示 Kubernetes 源已建立索引,现在对其可见性范围允许的使用者可见。
也可以直接列出最近的 repository ConfigMap Events:
确认带有 label 的资源存在于目标 namespace 中:
如果源不可见,请先参阅 排查 repository 源可见性。