Connector 生成

概述

某些后端会在单个服务后面提供多个软件包生态系统。例如,一个 Nexus 或 JFrog Artifactory 实例可以从一个主机提供 npm、Maven 和 PyPI 存储库。无需让用户为每个生态系统手动创建一个 Connector,聚合器 Connector 可以在 spec.generators 中声明其子项,控制器会为每个条目实例化一个子 Connector ——每个子 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.supportedClassesConnectorClass 名称集合。生成器条目只能引用此列表中的类;引用任何其他类的条目都会被准入 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。

控制器将条目视为事实来源:如果子 Connector 的 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条目引用的 connectorClassName 不在父类的 supportedClasses 中。创建或更新时会被准入 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 移除条目删除对应的子 Connector(通过 generator-entry 标签匹配);其他子 Connector 不受影响。
在外部编辑子 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/"

参考