JFrog Connector

JFrog Connector 是一种与平台无关的 Connector,可用于连接 JFrog Artifactory 实例。

您可以在 CICD 流水线中使用 JFrog Connector,安全地访问托管在 JFrog Artifactory 中的私有 Maven、NPM 和 PyPI 仓库;也可以在 Kubernetes 工作负载中使用它执行软件包操作,而无需凭证。

此外,您还可以集中管理跨命名空间的 JFrog Artifactory 访问配置,避免在每个命名空间中重复配置凭证。

概述

本文档涵盖:

  • 集成要求:目标 JFrog Artifactory 实例的先决条件
  • 创建 JFrog Connector
  • 高级功能:Maven、NPM 和 PyPI 的代理功能与配置文件

集成要求

JFrog Artifactory 先决条件

  • Kubernetes 集群可访问的 JFrog Artifactory 实例
  • 具有适当仓库权限的用户凭证

创建简单的 JFrog Connector

以下介绍如何创建基本的 JFrog Connector:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: jfrog-connector
spec:
  connectorClassName: jfrog
  address: https://jfrog.example.com

字段参考

spec.connectorClassName:

jfrog(常量),指定用于 JFrog Artifactory 集成的 ConnectorClass 名称。

spec.address:

JFrog Artifactory 基础 URL,例如:https://jfrog.example.com。

spec.auth(可选):

指定 JFrog Artifactory 实例的身份验证方法。

  • spec.auth.name:对于 JFrog Connector,应为 basicAuth。

  • spec.auth.secretRef:指定包含 JFrog Artifactory 实例身份验证信息的 secret。该 secret 应在与 Connector 相同的命名空间中创建。

可选元数据字段:

  • cpaas.io/description:JFrog Connector 的描述信息,例如:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: jfrog-connector
      annotations:
        cpaas.io/description: "Connect to team JFrog Artifactory instance"

JFrog Connector 的功能

身份验证

JFrog Connector 支持以下身份验证类型:

  • basicAuth:基于用户名和密码的身份验证,对应的 secret 类型为:kubernetes.io/basic-auth

例如:

apiVersion: v1
stringData:
  username: your-jfrog-username
  password: your-jfrog-password
kind: Secret
metadata:
  name: jfrog-secret
type: kubernetes.io/basic-auth

有关完整的状态信息,请参阅Connector 状态文档。

所需凭证权限

已配置凭证所需的权限取决于您的使用方式。

例如:

  • 下载操作:如果只需要下载依赖项,凭证仅需对目标仓库具有读取权限。
  • 部署操作:如果需要发布构件,凭证必须同时具有目标仓库的读取和写入权限。

出于安全最佳实践的考虑,我们建议创建仅具有所需最小权限的凭证。如果需要额外权限,请使用权限更高的 secret 创建单独的 Connector,并通过命名空间隔离控制哪些用户可以访问每个 Connector。

本地 Generic 仓库流水线集成

平台为与 JFrog Artifactory Local Generic 仓库交换文件的 Pipeline Integrations 提供 jfrog-raw-repository ResourceInterface。仓库选择器不提供 Remote 或 Virtual 仓库。

在 Pipeline 编辑器中配置 Integration 时:

  1. 选择一个 JFrog Connector。
  2. 选择一个仓库。列表仅包含软件包类型为 Generic 且仓库类型为 LOCAL 的仓库。
  3. 对于下载操作,打开文件路径。平台会递归加载仓库的完整文件列表。在本地输入文本以筛选已加载的、相对于仓库的路径,然后选择结果。无需输入通配符。

所选值是完整的、相对于仓库的路径,不包含仓库键、基础 URL 或开头的斜杠,例如:

releases/2026/report.json

Integration 会向兼容的 Task 暴露 Connector address、仓库键、相对 path 以及一个 auth 工作区。路径是可选的,因此 上传 Task 可以选择仓库,并单独提供其目标路径。

Connector 凭证需要 JFrog Read 权限,以列出仓库、列出文件并从所选仓库下载。上传 Task 还需要 JFrog Deploy/Cache(w)权限。配置 Integration 的用户需要对以下 Connector API 资源具有 get 权限:

  • connectors/apis/jfrog/artifactory/api/repositories
  • connectors/apis/jfrog/artifactory/api/storage/{repository}

聚合的 cpaas:connectors-jfrog-apis:view 角色通常会提供这些权限。

成功的文件列表请求返回 HTTP 200。空仓库或本地文件路径筛选器无匹配项时,会显示为空选项列表。 没有有效平台身份验证的请求返回 HTTP 401;无效的 Artifactory 凭证通常返回上游 HTTP 401。缺少平台 API get 权限或 JFrog Read 权限时,通常返回 HTTP 403。不存在的仓库可能返回 HTTP 404,但此行为 可能因 Artifactory 版本而异,因此客户端不得仅依赖 HTTP 404。

子 Connector 生成

单个 JFrog Artifactory 实例通常会在不同 API 路径下提供多个软件包生态系统——npm、Maven 和 PyPI。您可以声明一个 JFrog 聚合器 Connector,而不是为每个生态系统创建一个 Connector(或挂载下文所述的各格式配置文件):在 JFrog ConnectorClass 上设置 spec.generation.supportedClasses: [npm, maven, pypi],并在 JFrog Connector 的 spec.generators 中列出各生态系统。控制器会为每个类生成 npm / maven / pypi 子 Connector,这些子 Connector 共享聚合器的主机和凭证,流水线通过这些子 Connector 使用软件包。

这是从单个 JFrog Artifactory 实例提供多个生态系统的推荐方式。有关完整模型——地址模板化、身份验证继承、GenerationReady 条件、恢复和生命周期——请参阅 Connector 生成。

JFrog Connector 代理和配置文件

为了使客户端能够在无需凭证的情况下访问 JFrog Artifactory,JFrog Connector 提供代理服务器以自动注入身份验证信息。

创建 Connector 后,系统会自动为目标 JFrog Artifactory 实例配置代理服务。

代理端点记录在 status.proxy.httpAddress 中:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: jfrog-connector
spec:
  # connector spec fields
status:
  conditions:
    # status conditions
  proxy:
    httpAddress:
      url: http://c-jfrog-connector.default.svc.cluster.local

JFrog ConnectorClass 提供以下配置文件,这些文件可通过 Connectors CSI Driver 挂载:

配置名称生成的文件使用场景
settingssettings.xml通过代理执行 Maven 操作
npmrc.npmrcNPM 软件包操作
yarnrc.yarnrc.ymlYarn 软件包操作
pipconfpip.confPyPI 软件包下载
pypirc.pypircPyPI 软件包发布
应优先使用子 Connector 生成,已弃用

直接挂载这些各格式配置文件(settings / npmrc / yarnrc / pipconf / pypirc)已被弃用。请优先使用子 Connector 生成;该功能会生成每个类对应的 npm / maven / pypi 子 Connector,流水线应使用这些子 Connector,而不是直接挂载原始配置文件。

Maven 配置:settings.xml

JFrog Connector 为 Maven 提供 settings.xml 配置文件,通过 Connector 代理将构件下载请求路由到 JFrog Artifactory Maven 仓库。

配置参数:

  • mirrorRepository(可选):用作 Maven 镜像的 JFrog Artifactory 仓库键。如果省略,生成的 settings.xml 将不包含 <mirrors> 部分。

CSI 卷定义示例:

volumes:
- name: maven-settings
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "jfrog-connector"
      configuration.names: "settings"
      configuration.params: '{"settings":{"mirrorRepository":"libs-release"}}'

生成的 settings.xml 示例:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" ...>
  <proxies>
    <proxy>
      <id>connectors-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>connectors-proxy-service.connectors-system.svc.cluster.local</host>
      <port>80</port>
      <username>NAMESPACE/CONNECTOR_NAME</username>
      <password>TOKEN</password>
      <nonProxyHosts>localhost</nonProxyHosts>
    </proxy>
  </proxies>
  <mirrors>
    <mirror>
      <id>jfrog-connector-mirror</id>
      <url>https://jfrog.example.com/artifactory/libs-release</url>
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>
</settings>

NPM 配置:.npmrc 和 .yarnrc.yml

JFrog Connector 为 NPM/Yarn 提供 .npmrc 和 .yarnrc.yml 配置文件,通过 Connector 代理将请求路由到 JFrog Artifactory NPM 仓库。

配置参数:

  • registry(可选,默认值为 ""):用于构建 NPM/Yarn registry URL 的 JFrog Artifactory NPM 仓库键。为空时,.npmrc / .yarnrc.yml 会渲染为带占位符注释的内容,而不会导致 CSI 挂载失败;提供此参数即可启用 npm install / yarn install / 发布。
  • strictSSL(可选,默认值为 "true"):如果设置,Connector 会将此值写入 .npmrc(strict-ssl)和 .yarnrc.yml(enableStrictSsl)

CSI 卷定义示例:

volumes:
- name: npmrc
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "jfrog-connector"
      configuration.names: "npmrc"
      configuration.params: '{"npmrc":{"registry":"npm-local"}}'
- name: yarnrc
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "jfrog-connector"
      configuration.names: "yarnrc"
      configuration.params: '{"yarnrc":{"registry":"npm-local"}}'

PyPI 配置:pip.conf 和 .pypirc

JFrog Connector 为 PyPI 工具提供 pip.conf 和 .pypirc 配置文件,通过 Connector 代理将请求路由到 JFrog Artifactory PyPI 仓库。

配置参数:

  • repository(可选,默认值为 ""):JFrog Artifactory PyPI 仓库键(用于 pip.conf)。为空时,pip.conf 会渲染为带占位符注释的内容,而不会导致 CSI 挂载失败;提供此参数即可启用 pip install。
  • deployRepository(可选,默认值为 ""):用于发布的 JFrog Artifactory PyPI 仓库键(用于 .pypirc)。为空时,.pypirc 会渲染为带占位符注释的内容,而不会导致 CSI 挂载失败;提供此参数即可启用 twine upload。

CSI 卷定义示例:

volumes:
- name: pipconf
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "jfrog-connector"
      configuration.names: "pipconf"
      configuration.params: '{"pipconf":{"repository":"pypi-local"}}'
- name: pypirc
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "jfrog-connector"
      configuration.names: "pypirc"
      configuration.params: '{"pypirc":{"deployRepository":"pypi-local"}}'

使用 Connectors CSI Driver 挂载配置文件

CSI 卷参数说明:

  • csi.readOnly:固定值 true
  • csi.driver:Connector CSI Driver,固定为 connectors-csi
  • csi.volumeAttributes:CSI 卷属性
    • connector.name:JFrog Connector 的名称
    • connector.namespace:JFrog Connector 的命名空间;如果未指定,则使用 Pod 的命名空间
    • configuration.names:配置名称。支持的值:settings(Maven)、npmrc、yarnrc、pipconf、pypirc
    • configuration.params:包含每个命名配置运行时参数的 JSON 字符串

JFrog 的 configuration.params

有关 configuration.params 的常规格式、验证流程和合并行为,请参阅 Connectors CSI Driver 文档中的 configuration.params。

每个 JFrog 配置接受的参数如下:

配置参数必需默认值描述
settingsmirrorRepository否""settings.xml 中 Maven 镜像的 JFrog Artifactory 仓库键
npmrcregistry否"".npmrc 中 NPM registry URL 的 JFrog Artifactory NPM 仓库键
npmrcstrictSSL否"true"是否要求 SSL("true" 或 "false");作为 strict-ssl 写入 .npmrc
yarnrcregistry否"".yarnrc.yml 中 Yarn registry URL 的 JFrog Artifactory NPM 仓库键
yarnrcstrictSSL否"true"是否要求 SSL;作为 enableStrictSsl 写入 .yarnrc.yml
pipconfrepository否""pip.conf 中 index URL 的 JFrog Artifactory PyPI 仓库键
pypircdeployRepository否"".pypirc 中 publish URL 的 JFrog Artifactory PyPI 仓库键

当某个参数的默认值为 "" 且调用方从 configuration.params 中省略相应条目时,渲染的文件会包含一个占位符注释块(以 # WARNING: empty configuration 开头),其中会指出缺少的参数,并显示用于提供该参数所需的 JSON 片段——CSI 挂载仍会成功,下游工具可以检测到空状态,而不会导致 Pod 启动失败。

延伸阅读

参考资料