配置 Kubernetes 目录源

artifacthub-shim 可以直接从 Kubernetes 索引 Tekton Task、Pipeline 和 StepAction 对象。当目录资源由 GitOps 管理,并且不应维护单独的 Git 检出时,这种方式非常有用。

配置层

Kubernetes 目录源分为三层进行配置。每一层由不同的角色负责,并在不同的时间应用:

层级时间负责人控制内容
1. 功能启用安装或 Helm 升级集群管理员config.* 下的 Chart 值。这些值定义是否启用 Kubernetes 源,以及 shim 可以读取哪些 namespace。
2. 注册应用仓库 ConfigMap 时平台或团队管理员ConfigMap 上的可见性 label 或 annotation,以及 data.repository.yaml。这些配置定义谁可以使用该目录,以及 shim 从何处读取资源。
3. 编写应用 Tekton 资源时目录作者每个 Task、Pipeline 或 StepAction 上的 artifacthub-shim.alauda.io/catalog 和 app.kubernetes.io/version。这些配置定义哪些对象属于该目录。

本页面上的每个 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/project label。同一项目中的消费者 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: 键:

config:
  kubernetesSources:
    enabled: true
    allowedNamespaces:
      - team-a-catalog

然后升级 Chart,使 shim 在 team-a-catalog 中获得 get/list/watch Roles。

2. 为 Tekton 资源添加 label

目录作者应用两个必需的 label。将版本加引号,以免 YAML 将 1.2 解析为浮点数:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: build
  namespace: team-a-catalog
  labels:
    artifacthub-shim.alauda.io/catalog: team-a-tasks
    app.kubernetes.io/version: "1.2.3"
spec:
  steps:
    - name: build
      image: alpine:3.20
      script: echo build

3. 使用预期的可见性注册源

在项目 namespace 中创建仓库 ConfigMap,而不是在 shim namespace 中创建。显式设置可见性 label。

将目录共享给所有 cpaas.io/project label 等于所有者 Namespace label 的 namespace:

apiVersion: v1
kind: ConfigMap
metadata:
  name: team-a-k8s-catalogs
  namespace: team-a
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "project"
data:
  repository.yaml: |
    kubernetesRepositories:
      - namespace: team-a-catalog
        repositories:
          - name: team-a-tasks
            displayName: Team A Tasks
            kind: task

将目录限制为仅 ConfigMap 所有者 namespace:

apiVersion: v1
kind: ConfigMap
metadata:
  name: team-a-k8s-catalogs
  namespace: team-a
  labels:
    artifacthub-shim.alauda.io/repository: "true"
    artifacthub-shim.alauda.io/repository-visibility: "namespace"
data:
  repository.yaml: |
    kubernetesRepositories:
      - namespace: team-a-catalog
        repositories:
          - name: team-a-tasks
            displayName: Team A Tasks
            kind: task
TIP

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 可以使用项目范围的目录:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-team-a-task
  namespace: team-a-dev
spec:
  taskRef:
    resolver: hub
    params:
      - name: catalog
        value: team-a-tasks
      - name: type
        value: artifact
      - name: kind
        value: task
      - name: name
        value: build
      - name: version
        value: "1.2.3"

完整的可见性选项(global、project、namespace 以及显式 Namespace allowlist annotation)记录在目录可见性中。

shim namespace 中的自动全局目录

当您需要集群范围的目录,且 Tekton 资源已经位于 shim namespace 中时,可以跳过 ConfigMap,改用自动发现。

Chart 的 config.kubernetesSources.enabled 值默认已启用。在 shim 运行的 namespace 中,为资源添加以下 labels:

metadata:
  labels:
    artifacthub-shim.alauda.io/catalog: team-catalog
    app.kubernetes.io/version: "1.2.3"

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:

spec:
  taskRef:
    resolver: hub
    params:
      - name: catalog
        value: team-catalog
      - name: type
        value: artifact
      - name: kind
        value: task
      - name: name
        value: build
      - name: version
        value: "1.2.3"

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 会替换此默认值:

    kubernetesRepositories:
      - namespace: team-a-catalog
        repositories:
          - name: team-a-tasks
            displayName: Team A Tasks
            kind: task
            selector:
              matchLabels:
                catalog.example.com/team: team-a
              matchExpressions:
                - key: catalog.example.com/enabled
                  operator: In
                  values: ["true"]

selector: {} 会有意匹配目标 namespace 中所选 kind 的每个资源,应谨慎使用。

目标 namespace 必须是 shim namespace,或列在 config.kubernetesSources.allowedNamespaces 中;此 Helm 设置控制对 Tekton 资源的读取,与 config.globalConfigMapSources.allowedNamespaces 无关,后者控制哪些 namespace 可以注册全局可见的 repository ConfigMap。

字段参考

此源类型支持的顶层 repository.yaml 字段:

字段必需描述
kubernetesRepositories否要从此 ConfigMap 注册的 Kubernetes 源列表。同一文件中仍可声明 Git repository。

支持的 kubernetesRepositories[] 字段:

字段必需描述
namespace否存储 Tekton 资源的 namespace。默认为 ConfigMap 所属的 namespace。必须是 shim namespace,或列在 config.kubernetesSources.allowedNamespaces 中。
repositories是从该 namespace 中选择的目录条目。

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

字段必需描述
name是resolver 和 API 路径使用的稳定目录名称,以及默认的 artifacthub-shim.alauda.io/catalog label 值。
displayName否目录的人类可读名称。
kind是task、pipeline 或 stepaction 之一。
selector否可选的 Kubernetes label selector。省略时使用 artifacthub-shim.alauda.io/catalog=<name>。selector: {} 会匹配该 kind 的每个资源。
disabledPackages否repository 本地的软件包或版本禁用规则。请参阅禁用目录软件包。
legacyCatalogAliases否对于相同的 kind,可解析到此 repository 的历史目录名称。API 响应仍返回规范的 name。

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 和相互竞争的源之间均不区分大小写且必须唯一。

重复项处理分为两个步骤:

  1. 刷新时首先为每个目录名称选择一个胜出者。源优先级依次为内置目录、由 shim namespace 所有的 ConfigMap 源、由其他 namespace 所有的 ConfigMap 源,最后是自动 label 发现;在同一层级内使用源标识的字典序打破平局。显式 ConfigMap 源始终优先于同一目录名称的自动发现。
  2. 完成上述选择后,任何剩余冲突都会被标记为 Invalid,而不是进行合并。

这两个步骤相互独立。优先级决定保留哪个源;经过该选择后仍发生冲突的重复项会被拒绝。

验证

应用 Tekton 资源和可选的 repository ConfigMap 后,如果使用的是 ConfigMap 形式,请检查 ConfigMap Events:

kubectl describe configmap team-a-k8s-catalogs -n team-a

预期的 Events:

  • RepositoryConfigAccepted 表示已接受 repository.yaml。
  • RepositorySourceReady 表示 Kubernetes 源已建立索引,现在对其可见性范围允许的使用者可见。

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

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

确认带有 label 的资源存在于目标 namespace 中:

kubectl get task,pipeline,stepaction -n team-a-catalog --show-labels

如果源不可见,请先参阅 排查 repository 源可见性。

了解更多