JFrog Connector
JFrog connector 是一种与平台无关的 Connector,可用于连接 JFrog Artifactory 实例。
您可以使用 JFrog Connector 在 CICD 流水线中安全访问托管于 JFrog Artifactory 的私有 Maven、NPM 和 PyPI 仓库,或在 Kubernetes 工作负载中使用它执行软件包操作,而无需凭证。
此外,您还可以集中管理跨命名空间的 JFrog Artifactory 访问配置,避免在每个命名空间中重复配置凭证。
目录
概述集成要求创建简单的 JFrog connector字段参考JFrog Connector 的功能身份验证所需凭证权限本地 Generic 仓库流水线集成子 Connector 生成JFrog Connector 代理和配置文件Maven 配置:settings.xmlNPM 配置:.npmrc 和 .yarnrc.ymlPyPI 配置:pip.conf 和 .pypirc使用 Connectors CSI Driver 挂载配置文件JFrog 的 configuration.params延伸阅读参考资料概述
本文档涵盖:
- 集成要求:目标 JFrog Artifactory 实例的先决条件
- 创建 JFrog connector
- 高级功能:Maven、NPM 和 PyPI 的代理功能与配置文件
集成要求
JFrog Artifactory 先决条件
- Kubernetes 集群可以访问 JFrog Artifactory 实例
- 具有适当仓库权限的用户凭证
创建简单的 JFrog connector
以下介绍如何创建基本的 JFrog Connector:
字段参考
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 的描述信息,例如:
JFrog Connector 的功能
身份验证
JFrog connector 支持以下身份验证类型:
basicAuth:基于用户名和密码的身份验证,对应的 secret 类型:kubernetes.io/basic-auth
例如:
有关完整的状态信息,请参阅 Connector 状态文档。
所需凭证权限
配置的凭证所需权限取决于您的使用方式。
例如:
- 下载操作:如果仅需下载依赖项,凭证只需具有目标仓库的读取权限。
- 部署操作:如果需要发布制品,凭证必须同时具有目标仓库的读取和写入权限。
根据安全最佳实践,我们建议创建仅具有所需最小权限的凭证。需要额外权限时,请使用权限更高的 secret 创建单独的 Connector,并使用命名空间隔离来控制哪些用户可以访问各个 Connector。
本地 Generic 仓库流水线集成
平台为与 JFrog Artifactory Local
Generic 仓库交换文件的
Pipeline Integrations 提供 jfrog-raw-repository ResourceInterface。仓库选择器不提供 Remote 或 Virtual
仓库。
在 Pipeline 编辑器中配置 Integration 时:
- 选择一个 JFrog Connector。
- 选择一个仓库。列表仅包含软件包类型为
Generic且仓库类型为LOCAL的仓库。 - 对于下载操作,打开 File Path。平台会递归加载仓库的完整文件列表。输入文本可在本地筛选已加载的、相对于仓库的路径,然后选择结果。无需输入通配符。
所选值是完整的、相对于仓库的路径,不包含仓库键、基础 URL 或开头的斜杠,例如:
Integration 会向兼容的 Task 暴露 Connector address、仓库键、相对路径
path 以及一个 auth 工作区。路径是可选的,因此
上传 Task 可以选择仓库,并单独提供其目标路径。
Connector 凭证需要 JFrog Read 权限,才能列出仓库、列出文件以及从所选仓库下载文件。上传
Task 还需要 JFrog Deploy/Cache(w)权限。配置 Integration 的用户需要对这些 Connector API
资源具有 get 权限:
connectors/apis/jfrog/artifactory/api/repositoriesconnectors/apis/jfrog/artifactory/api/storage/{repository}
聚合的 cpaas:connectors-jfrog-apis:view 角色通常会提供这些权限。
成功的文件列表请求返回 HTTP 200。空仓库或本地
File Path 筛选器没有匹配项时,会显示为空选项列表。
没有有效平台身份验证的请求返回 HTTP 401;无效的
Artifactory 凭证通常返回上游 HTTP 401。缺少平台 API
get 权限或 JFrog Read 权限时,通常返回 HTTP 403。不存在的仓库可能返回 HTTP 404,但此行为
可能因 Artifactory 版本而异,因此客户端不得仅依赖 HTTP 404。
子 Connector 生成
单个 JFrog Artifactory 实例通常会在不同 API 路径下提供多个软件包生态系统——npm、Maven 和 PyPI。您无需为每个生态系统创建一个 Connector,也无需挂载下文所述的各格式配置文件,而是可以声明一个 JFrog aggregator Connector,为每个生态系统生成一个子 Connector:在 JFrog ConnectorClass 上设置 spec.generation.supportedClasses: [npm, maven, pypi],并在 JFrog Connector 的 spec.generators 中列出各生态系统。控制器会实例化按类划分的 npm / maven / pypi 子 Connector,这些子 Connector 共享聚合 Connector 的主机和凭证,流水线通过这些子 Connector 使用软件包。
这是从一个 JFrog Artifactory 实例提供多个生态系统的推荐方式。有关完整模型——地址模板化、身份验证继承、GenerationReady 条件、恢复和生命周期——请参阅 Connector 生成。
JFrog Connector 代理和配置文件
为了让客户端无需凭证即可访问 JFrog Artifactory,JFrog connector 提供代理服务器,以自动注入身份验证信息。
创建 Connector 后,系统会自动为目标 JFrog Artifactory 实例配置代理服务。
代理端点记录在 status.proxy.httpAddress 中:
JFrog ConnectorClass 提供以下配置文件,这些文件可通过 Connectors CSI Driver 挂载:
直接挂载这些各格式配置文件(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 卷定义示例:
生成的 settings.xml 示例:
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 卷定义示例:
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 卷定义示例:
使用 Connectors CSI Driver 挂载配置文件
CSI 卷参数说明:
csi.readOnly:固定值truecsi.driver:Connector CSI Driver,固定为connectors-csicsi.volumeAttributes:CSI 卷属性connector.name:JFrog Connector 的名称connector.namespace:JFrog Connector 的命名空间;如果未指定,则使用 Pod 的命名空间configuration.names:配置名称。支持的值:settings(Maven)、npmrc、yarnrc、pipconf、pypircconfiguration.params:包含每个命名配置运行时参数的 JSON 字符串
JFrog 的 configuration.params
有关 configuration.params 的通用格式、验证流程和合并行为,请参阅 Connectors CSI Driver 文档中的 configuration.params。
每个 JFrog 配置接受的参数如下:
当参数默认值为 "" 且调用方从 configuration.params 中省略相应条目时,生成的文件会包含占位符注释块(以 # WARNING: empty configuration 开头),其中会标明缺失的参数,并显示用于提供该参数所需的 JSON 片段——CSI 挂载仍会成功,下游工具可以检测到空状态,而不会导致 Pod 启动失败。