Connector 生成

概述

某些后端会在单个服务后提供多个软件包生态系统。例如,一个 Nexus 或 JFrog Artifactory 实例可以从同一主机提供 npm、Maven 和 PyPI 存储库。无需要求用户为每个生态系统手动创建一个 Connector,聚合器 Connector 可以在 spec.generators 中声明其子项,控制器会为每个条目实例化一个子 Connector, 并将其绑定到相应生态系统的 ConnectorClass。

此功能分为两部分:

  • 在 ConnectorClass 上,spec.generation.supportedClasses 是一个允许列表,其中包含此类聚合器可以为其生成子项的 ConnectorClass 名称。它表示类作者确认这些子类可以服务于此聚合器生成的路径范围地址。
  • 在 Connector 上,spec.generators 声明要实例化的子 Connector。每个条目包含一个子 ConnectorClass 名称、一个地址以及可选的 auth/params。

以下示例声明了一个 Nexus 聚合器,该聚合器生成一个 npm、一个 Maven 和一个 PyPI 子 Connector:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: nexus-aggregator
  namespace: my-namespace
spec:
  connectorClassName: nexus
  address: "https://nexus.example.com"
  auth:
    name: basicAuth
    secretRef:
      name: nexus-credentials
  generators:
  - name: nexus-npm
    connectorClassName: npm
    address: "{{.connector.spec.address}}/repository/npm-proxy/"
  - name: nexus-maven
    connectorClassName: maven
    address: "{{.connector.spec.address}}/repository/maven-public/"
  - name: nexus-pypi
    connectorClassName: pypi
    address: "{{.connector.spec.address}}/repository/pypi-proxy/"

控制器会将其协调为三个子 Connector——nexus-npm、 nexus-maven 和 nexus-pypi——它们位于同一命名空间中,均由 聚合器负责,并携带标识标签,同时将聚合器的 GenerationReady 条件设置为 True。

解决的问题

一个后端,多个生态系统。单个 Nexus/JFrog 主机提供 npm、Maven 和 PyPI。将每个生态系统建模为独立的 Connector,意味着用户需要重复配置相同的主机、凭据和代理连接三次,并手动确保它们保持同步。

路径范围寻址。每个生态系统位于同一主机下的不同路径中(Nexus 上为 /repository/<name>/, JFrog 上为 /artifactory/api/<type>/<repo>/)。生成器使聚合器只需拥有一次主机和凭据, 而每个子项携带生态系统专属的路径范围地址。

作为一个单元的生命周期。子项由聚合器负责,因此删除聚合器会级联删除其子项,而从 spec.generators 中移除某个条目会准确清理相应的子项,不会留下孤立的 Connector。

数据结构

ConnectorClass — spec.generation

ConnectorClass 通过声明其支持的子类,选择作为聚合器:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: nexus
spec:
  generation:
    supportedClasses:
    - npm
    - maven
    - pypi
字段描述
spec.generation.supportedClasses一组 ConnectorClass 名称。生成器条目只能引用此列表中的类;引用任何其他类的条目都会被准入 webhook 拒绝,原因是 ClassNotSupported。此列表是类作者作出的契约,表示这些子类可以为聚合器的路径范围地址提供服务。

聚合器类本身通常不提供按生态系统划分的 ResourceInterface — 这些由生成的子 Connector 提供,每个子 Connector 都携带自己的 ConnectorClass 和 ResourceInterface。

Connector — spec.generators

spec.generators 中的每个条目描述一个子 Connector。该条目内联了 Connector 自身 spec 中的相同字段(地址、身份验证、参数等), 另外还包含一个 name:

字段描述
name条目标识。逐字用作子 Connector 的 metadata.name,并写入子项的 connectors.cpaas.io/generator-entry 标签。必须是有效的 DNS-1123 标签(≤ 63 个字符),且在父对象的命名空间内唯一。
connectorClassName子 ConnectorClass。必须存在于父类的 spec.generation.supportedClasses 中。
address子项的地址。支持针对父对象的花括号路径模板(参见地址模板)。必须解析为绝对 URL。
auth可选。如果省略,当子类声明了兼容的身份验证 secretType 时,子项会继承父对象的身份验证。
params可选。根据子类声明的参数进行验证;未知参数会被拒绝。

生成的子 Connector

对于每个有效条目,控制器都会在父对象的命名空间中创建(并持续维护)一个子 Connector,其中包含:

  • 指向父对象的 ownerReference(controller: true、 blockOwnerDeletion: true),因此删除父对象时会级联删除子对象;

  • 身份 标签:

    标签值
    connectors.cpaas.io/generated-by父 Connector 的名称
    connectors.cpaas.io/generator-entry条目的 name
  • 一个用于标识父对象的注解 connectors.cpaas.io/managed-by-generator。

控制器将条目视为事实来源:如果子项的 spec (例如其 address)在控制器外部被更改,下一次协调时会将其恢复为声明的值。

地址模板

生成器条目的 address 是一个 Go text/template,会针对父 Connector 进行评估。可用上下文为:

{
  "connector": {
    "metadata": { "name": "...", "namespace": "..." },
    "spec":     { "address": "..." }   // trailing "/" trimmed
  },
  "entry": { "name": "..." }
}

父对象的 spec.address 会去除末尾的 / 后公开,因此惯用写法 {{.connector.spec.address}}/repository/npm-proxy/ 会生成干净的 URL。 模板使用 missingkey=error:引用不存在的字段会使条目失败,原因是 InvalidAddress,而不是渲染为空片段。

generators:
- name: nexus-npm
  connectorClassName: npm
  address: "{{.connector.spec.address}}/repository/npm-proxy/"

状态和条件

聚合器的生成结果汇总在 GenerationReady 条件中。此条件仅具有信息性——它报告子项生成的状态,但不会控制聚合器自身的 Ready 条件(生成器条目失败时,聚合器仍可能处于 Ready 状态,反之亦然)。

原因含义
Materialized所有条目均已通过验证,其子 Connector 均已就绪。GenerationReady = True。
ClassNotSupported条目引用了一个不在父类 supportedClasses 中的 connectorClassName。创建或更新时会被准入 webhook 拒绝。
ClassNotFound条目引用了受支持的类名,但集群中不存在相应的 ConnectorClass。
InvalidParams条目提供了子类未声明的参数(或无效的枚举值)。
AuthIncompatible条目继承了父级身份验证配置,但子类未声明与之兼容的身份验证 secretType。
InvalidAddress条目的 address 不是有效的绝对 URL,或其模板引用了未知字段。
InvalidName条目的 name 不是有效的 DNS-1123 标签。
NameConflict目标子项名称已被不归属于此聚合器的 Connector 占用。控制器绝不会接管或覆盖外部 Connector。
ChildRejectedAPI server 拒绝创建子 Connector(例如,子类 webhook 拒绝了该请求)。

恢复

  • 验证失败(ClassNotFound、InvalidParams、 AuthIncompatible、InvalidAddress、InvalidName)会在 根本原因修复后恢复——编辑 spec.generators,或创建缺失的子 ConnectorClass,这会触发新一轮协调。
  • NameConflict 会大约每 1 分钟自动重新入队,因此冲突的 Connector 被删除或重命名后,聚合器即可恢复。
  • ChildRejected 会大约每 5 分钟自动重新入队,因此子类准入问题解决后,聚合器即可恢复。

生命周期

操作结果
向 spec.generators 添加条目为该条目创建一个新的子 Connector。
从 spec.generators 移除条目删除相应的子项(通过 generator-entry 标签匹配);其他子项不受影响。
带外编辑子 Connector控制器将子 Connector 的 spec 恢复为其条目声明的值。
删除聚合器 Connector所有子 Connector 都会通过其 ownerReference 级联删除。

示例

生成 npm / Maven / PyPI 子 Connector 的 Nexus 聚合器

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: nexus
spec:
  # ... address / auth / proxy omitted ...
  generation:
    supportedClasses:
    - npm
    - maven
    - pypi
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: nexus-aggregator
  namespace: my-namespace
spec:
  connectorClassName: nexus
  address: "https://nexus.example.com"
  auth:
    name: basicAuth
    secretRef:
      name: nexus-credentials
  generators:
  - name: nexus-npm
    connectorClassName: npm
    address: "{{.connector.spec.address}}/repository/npm-proxy/"
  - name: nexus-maven
    connectorClassName: maven
    address: "{{.connector.spec.address}}/repository/maven-public/"
  - name: nexus-pypi
    connectorClassName: pypi
    address: "{{.connector.spec.address}}/repository/pypi-proxy/"

生成的三个子 Connector 都带有聚合器的 ownerReference,以及 generated-by: nexus-aggregator / generator-entry: <name> 标签:

$ kubectl -n my-namespace get connector \
    -l connectors.cpaas.io/generated-by=nexus-aggregator
NAME          CLASS   ADDRESS
nexus-maven   maven   https://nexus.example.com/repository/maven-public/
nexus-npm     npm     https://nexus.example.com/repository/npm-proxy/
nexus-pypi    pypi    https://nexus.example.com/repository/pypi-proxy/

JFrog 聚合器的工作方式相同,但使用 JFrog 针对各生态系统的 API 路径:

  generators:
  - name: jfrog-npm
    connectorClassName: npm
    address: "{{.connector.spec.address}}/artifactory/api/npm/npm-local/"
  - name: jfrog-maven
    connectorClassName: maven
    address: "{{.connector.spec.address}}/artifactory/maven-local/"
  - name: jfrog-pypi
    connectorClassName: pypi
    address: "{{.connector.spec.address}}/artifactory/api/pypi/pypi-local/"

参考