配置 Tekton 使用 ArtifactHub Shim

概述

artifacthub-shim 提供 Tekton Hub resolver 和 DevOps Hub UI 使用的、与 Artifact Hub 兼容的 API。安装 artifacthub-shim 后，请更新 TektonConfig 资源，使 catalog 请求使用该 shim，而不是内置的 Tekton Hub 组件。

本指南使用默认的 artifacthub-shim Service 和 namespace。如果您希望保留或重新启用内置的 Tekton Hub，请参阅启用内置 Tekton Hub。

先决条件

开始之前，请确保：

已安装 artifacthub-shim，且其 API workload 已就绪。
artifacthub-shim-system namespace 中存在 artifacthub-shim-api Service。
已安装的 artifacthub-shim 版本支持 optional 和 legacyCatalogAliases repository 字段。
名为 config 的 TektonConfig 资源存在。
您有权限更新 TektonConfig，并读取 Tekton target namespace 中的 workloads。
如果您计划使用本指南中的命令迁移现有 SSH Secret，请安装 jq。

如果您正在替换现有的内置 Tekton Hub，请先不要禁用它。首先按照从内置 Tekton Hub 迁移自定义 catalog 执行，验证已迁移的 source，并配置 TektonConfig。然后，当您不再需要旧 Hub 作为 fallback 时，再按照禁用内置 Tekton Hub 执行。

从内置 Tekton Hub 迁移自定义 catalog

release-4.10 会保留现有的内置 Tekton Hub，但不会自动将自定义 catalog 配置迁移到 artifacthub-shim。在禁用内置 Hub 之前，请手动完成以下步骤。

检查现有的 Catalog 配置

确定 Tekton target namespace。如果 spec.targetNamespace 为空，则使用 tekton-pipelines：

$ PIPELINES_NAMESPACE="$(kubectl get tektonconfig config \
    -o jsonpath='{.spec.targetNamespace}')"
$ [ -n "${PIPELINES_NAMESPACE}" ] || PIPELINES_NAMESPACE=tekton-pipelines

检查 TektonHub 资源和渲染后的 API ConfigMap：

$ kubectl get tektonhub hub -o yaml

$ kubectl -n "${PIPELINES_NAMESPACE}" get configmap tekton-hub-api \
    -o jsonpath='{.data.CATALOGS}{"\n"}'

TektonHub 资源包含用户配置的 spec.catalogs 条目。渲染后的 CATALOGS 数据也可能包含 catalog 条目和 disabledPackages 规则。对比这两个来源，并为每个 catalog 保留最完整的值。

legacy catalog 的映射如下：

Legacy Tekton Hub 值	ArtifactHub Shim 值
`name: <catalog>`	Task repository `name: <catalog>`
`name: <catalog>`	Pipeline repository `name: <catalog>-pipelines`，并设置 `legacyCatalogAliases: [<catalog>]`
`name: <catalog>`	StepAction repository `name: <catalog>-stepactions`，并设置 `legacyCatalogAliases: [<catalog>]`
`sshUrl` 或 `sshurl`	`gitRepositories[].url`；优先使用此值而不是 legacy 的 `url`
没有 SSH URL 的 `url`	`gitRepositories[].url`
`revision`	`gitRepositories[].revision`；如果旧值为空，则使用 `main`
`contextDir` 或 `contextdir`	`task`、`pipeline` 和 `stepaction` 路径的前缀
`disabledPackages`	复制到每个生成的 `repositories[]` 条目

legacy 的 org、type 和 provider 字段不是 artifacthub-shim 所必需的。

迁移 Git 凭证

对于公开 Git repository，请省略 credentialRef。对于 SSH repository，请在与 repository ConfigMap 相同的 namespace 中创建一个 Secret。标准的 legacy Secret 名为 tekton-hub-api-ssh-crds，其私钥存储在 id_rsa 下；artifacthub-shim 期望使用 sshPrivateKey 或 ssh-privatekey，并且需要 known_hosts。

如果 legacy Secret 包含 id_rsa 和 known_hosts，则可以使用以下命令复制编码后的值，而不会输出明文凭证：

$ kubectl -n "${PIPELINES_NAMESPACE}" get secret tekton-hub-api-ssh-crds -o json | \
    jq '{
      apiVersion: "v1",
      kind: "Secret",
      metadata: {
        name: "artifacthub-shim-legacy-tekton-hub-ssh-creds",
        namespace: "artifacthub-shim-system"
      },
      type: "Opaque",
      data: {
        sshPrivateKey: .data.id_rsa,
        known_hosts: .data.known_hosts
      }
    }' | kubectl apply -f -

旧的 id_rsa.pub 值不是必需的。如果旧 Secret 使用了其他私钥字段，请改为选择该值。在应用新 Secret 之前，请确认 known_hosts 包含 Git server 的 host key。

对于 HTTPS repositories，引用的 Secret 可以包含 username 和 password，或 token。如果 Git server 使用内部 CA，请在同一个 Secret 中添加 ca.crt。切勿将凭证嵌入 Git URL 或 repository ConfigMap 中。

注册迁移后的 Catalog Source

在 artifacthub-shim namespace 中创建带标签的 ConfigMap。以下示例迁移 legacy catalog team-a，其资源存储在 catalogs/devops 目录下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: artifacthub-shim-legacy-tekton-hub-catalogs
  namespace: artifacthub-shim-system
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: ssh://git@git.example.com/team-a/tekton-catalog.git
        revision: main
        credentialRef:
          name: artifacthub-shim-legacy-tekton-hub-ssh-creds
        repositories:
          - name: team-a
            displayName: Team A Tasks
            kind: task
            path: catalogs/devops/task
            optional: true
            disabledPackages:
              - name: deprecated-resource
                versions:
                  - "0.1"
          - name: team-a-pipelines
            displayName: Team A Pipelines
            kind: pipeline
            path: catalogs/devops/pipeline
            optional: true
            legacyCatalogAliases:
              - team-a
            disabledPackages:
              - name: deprecated-resource
                versions:
                  - "0.1"
          - name: team-a-stepactions
            displayName: Team A StepActions
            kind: stepaction
            path: catalogs/devops/stepaction
            optional: true
            legacyCatalogAliases:
              - team-a
            disabledPackages:
              - name: deprecated-resource
                versions:
                  - "0.1"

当旧的 contextDir 为空时，请使用 task、pipeline 和 stepaction 作为路径。即使其中某个目录不存在，也要保留这三个条目：optional: true 会使缺失或为空的 kind 路径处于 Ready 状态，且包数为零。

规范的 repository 名称必须在全局范围内唯一。不过，legacyCatalogAliases 是按资源 kind 作用域划分的。因此，现有的 Task、Pipeline 和 StepAction resolver 引用都可以继续使用 catalog: team-a；Pipeline 请求会解析到 team-a-pipelines，而 StepAction 请求会解析到 team-a-stepactions。API 响应会返回规范的 repository 名称。新的引用应直接使用规范名称。

现有显式设置了 type: tekton 的引用仍然必须改为 type: artifact。未指定 type 的引用将使用本指南后续配置的 default-type: artifact 值。

应用 ConfigMap 并检查其 Events：

$ kubectl apply -f artifacthub-shim-legacy-tekton-hub-catalogs.yaml

$ kubectl -n artifacthub-shim-system describe configmap \
    artifacthub-shim-legacy-tekton-hub-catalogs

RepositoryConfigAccepted 表示配置已被接受。请等待每个 source 的 RepositorySourceReady，然后再切换 TektonConfig。通过 DevOps Hub 或带有 type: artifact 和原始 catalog 名称的 Hub resolver 引用，测试旧 catalog 使用到的每一种资源 kind。

有关完整的 repository schema、凭证格式、Events 和 resolver 示例，请参阅配置自定义 Git Repositories。

配置 TektonConfig

编辑 TektonConfig/config，并将以下字段合并到 spec.pipeline 中：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    enable-hub-resolver: true
    hub-resolver-config:
      artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
      default-artifact-hub-pipeline-catalog: catalog-pipelines
      default-artifact-hub-task-catalog: catalog
      default-kind: task
      default-type: artifact
    options:
      disabled: false
      deployments:
        hubs-wrapper:
          spec:
            replicas: 0
      ingress:
        hubs-wrapper:
          spec:
            ingressClassName: cpaas-system
            rules:
              - http:
                  paths:
                    - backend:
                        service:
                          name: hubs-wrapper
                          port:
                            number: 80
                      path: /__disabled-hubs-wrapper(/|$)(.*)
                      pathType: ImplementationSpecific

WARNING

请将这些字段与现有的 spec.pipeline 配置合并。不要替换整个 section：其中包含其他 feature flags、performance settings 和 environment-specific customizations。如果 options 已经包含其他 Deployment 或 Ingress 覆盖项，也请一并保留。

此配置会进行以下更改：

启用 Hub resolver，并使用 artifacthub-shim 暴露的、与 Artifact Hub 兼容的 API。
对 Tasks 使用 catalog，对 Pipelines 使用 catalog-pipelines。
当 resolver 引用省略这些值时，对 kind 为 task 的 Artifact Hub resources 进行使用。
将旧的 hubs-wrapper Deployment 的副本数缩减为零，并将其 Ingress 从 /hub 移走，从而允许 artifacthub-shim plugin 提供 DevOps Hub endpoint。
保持 Tekton Pipelines 组件启用。options.disabled: false 字段不会启用 hubs-wrapper；其零副本会禁用该单独的 Deployment。

如果 artifacthub-shim 安装在其他 namespace 中，请在 artifact-hub-api 中替换 artifacthub-shim-system。如果 Service 名称已自定义，也请同时替换 artifacthub-shim-api。

验证配置

等待 TektonConfig 变为 ready：

$ kubectl wait --for=condition=Ready tektonconfig/config --timeout=600s

如果您还没有确定 Tekton target namespace，请现在确定。如果 spec.targetNamespace 为空，则使用 tekton-pipelines：

$ PIPELINES_NAMESPACE="$(kubectl get tektonconfig config \
    -o jsonpath='{.spec.targetNamespace}')"
$ [ -n "${PIPELINES_NAMESPACE}" ] || PIPELINES_NAMESPACE=tekton-pipelines

检查 operator 重新协调后的 resolver 配置：

$ kubectl -n "${PIPELINES_NAMESPACE}" get configmap hubresolver-config -o yaml

输出必须包含以下值：

data:
  artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
  default-artifact-hub-pipeline-catalog: catalog-pipelines
  default-artifact-hub-task-catalog: catalog
  default-kind: task
  default-type: artifact

验证 Hub resolver 已启用，并且 legacy wrapper 已停止：

$ kubectl -n "${PIPELINES_NAMESPACE}" get configmap resolvers-feature-flags \
    -o jsonpath='{.data.enable-hub-resolver}{"\n"}'
true

$ kubectl -n "${PIPELINES_NAMESPACE}" get deployment hubs-wrapper \
    -o jsonpath='{.spec.replicas}{"\n"}'
0

有关 artifacthub-shim 安装选项和 resolver 集成细节，请参阅配置 Tekton 集成。

#配置 Tekton 使用 ArtifactHub Shim

#目录

#概述

#先决条件

#从内置 Tekton Hub 迁移自定义 catalog

#检查现有的 Catalog 配置

#迁移 Git 凭证

#注册迁移后的 Catalog Source

#配置 TektonConfig

#验证配置