JFrog 连接器

JFrog 连接器是一个与平台无关的连接器,可用于连接到 JFrog Artifactory 实例。

你可以使用 JFrog 连接器,在 CICD pipeline 中安全访问托管于 JFrog Artifactory 的私有 Maven、NPM 和 PyPI repository,或者在 Kubernetes workload 中使用它来执行无需凭证的 package 操作。

此外,你可以跨 namespace 集中管理 JFrog Artifactory 的访问配置,避免在每个 namespace 中重复配置凭证。

概述

本文档涵盖以下内容:

  • 集成要求:目标 JFrog Artifactory 实例的前提条件
  • 创建 JFrog 连接器
  • 高级功能:Maven、NPM 和 PyPI 的代理能力与配置文件

集成要求

JFrog Artifactory 前提条件

  • Kubernetes cluster 可访问的 JFrog Artifactory 实例
  • 具有适当 repository 权限的用户凭证

创建一个简单的 JFrog 连接器

以下是创建基础 JFrog 连接器的方法:

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(optional):

指定 JFrog Artifactory 实例的认证方式。

  • spec.auth.name:对于 JFrog 连接器应为 basicAuth。

  • spec.auth.secretRef:指定包含 JFrog Artifactory 实例认证信息的 secret。该 secret 应创建在与连接器相同的 namespace 中。

可选的 Metadata 字段:

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

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

JFrog 连接器的能力

认证

JFrog 连接器支持以下认证类型:

  • 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 状态文档。

所需的凭证权限

配置的凭证所需的权限取决于你打算如何使用它。

例如:

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

出于安全最佳实践,我们建议使用满足最低要求权限的凭证。当需要额外权限时,请创建具有更高权限 secret 的独立连接器,并使用 namespace 隔离来控制哪些用户可以访问每个连接器。

JFrog 连接器代理和配置文件

为了让客户端能够在无需凭证的情况下访问 JFrog Artifactory,JFrog 连接器提供了一个代理服务器,用于自动注入认证信息。

在创建 Connector 后,系统会自动为目标 JFrog Artifactory 实例提供一个 proxy service。

proxy endpoint 会记录在 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 package 操作
yarnrc.yarnrc.ymlYarn package 操作
pipconfpip.confPyPI package 下载
pypirc.pypircPyPI package 发布

Maven 配置:settings.xml

JFrog 连接器为 Maven 提供 settings.xml 配置文件,该文件会将 artifact 下载路由到连接器 proxy,再转发到 JFrog Artifactory Maven repository。

配置参数:

  • mirrorRepository(可选):用作 Maven mirror 的 JFrog Artifactory repository key。若省略,生成的 settings.xml 将不包含 <mirrors> 部分。

示例 CSI volume 定义:

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 连接器为 NPM/Yarn 提供 .npmrc 和 .yarnrc.yml 配置文件,这些文件会将请求路由到连接器 proxy,再转发到 JFrog Artifactory NPM repository。

配置参数:

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

示例 CSI volume 定义:

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 连接器为 PyPI 工具提供 pip.conf 和 .pypirc 配置文件,这些文件会将请求路由到连接器 proxy,再转发到 JFrog Artifactory PyPI repository。

配置参数:

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

示例 CSI volume 定义:

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 volume 参数说明:

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

JFrog 的 configuration.params

关于 configuration.params 的通用格式、验证流程和合并行为,请参见 Connectors CSI Driver 文档中的 configuration.params。

每种 JFrog 配置支持的参数如下:

ConfigurationParameterRequiredDefaultDescription
settingsmirrorRepositoryNo""settings.xml 中用于 Maven mirror 的 JFrog Artifactory repository key
npmrcregistryNo"".npmrc 中用于 NPM registry URL 的 JFrog Artifactory NPM repository key
npmrcstrictSSLNo"true"是否要求 SSL("true" 或 "false");在 .npmrc 中写入为 strict-ssl
yarnrcregistryNo"".yarnrc.yml 中用于 Yarn registry URL 的 JFrog Artifactory NPM repository key
yarnrcstrictSSLNo"true"是否要求 SSL;在 .yarnrc.yml 中写入为 enableStrictSsl
pipconfrepositoryNo""pip.conf 中用于 index URL 的 JFrog Artifactory PyPI repository key
pypircdeployRepositoryNo"".pypirc 中用于发布 URL 的 JFrog Artifactory PyPI repository key

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

延伸阅读

参考资料