JFrog Connector

The JFrog connector is a platform-agnostic connector that you can use to connect to JFrog Artifactory instances.

You can use the JFrog Connector to securely access private Maven, NPM, and PyPI repositories hosted in JFrog Artifactory in CICD pipelines, or use it in Kubernetes workloads to perform package operations without credentials.

Additionally, you can centralize the management of JFrog Artifactory access configurations across namespaces, avoiding the need to repeat credentials in each namespace.

Overview

This document covers:

  • Integration Requirements: Prerequisites for target JFrog Artifactory instances
  • Creating a JFrog connector
  • Advanced Features: Proxy capabilities and configuration files for Maven, NPM, and PyPI

Integration Requirements

JFrog Artifactory Prerequisites

  • JFrog Artifactory instance accessible from the Kubernetes cluster
  • User credentials with appropriate repository permissions

Creating a simple JFrog connector

Here's how to create a basic JFrog Connector:

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

Fields Reference

spec.connectorClassName:

jfrog (constant), specifies the ConnectorClass name for JFrog Artifactory integration.

spec.address:

JFrog Artifactory base URL, for example: https://jfrog.example.com.

spec.auth(optional):

Specifies the authentication method for the JFrog Artifactory instance.

  • spec.auth.name: should be basicAuth for JFrog connector.

  • spec.auth.secretRef: specifies the secret that contains the authentication information of the JFrog Artifactory instance. The secret should be created in the same namespace as the connector.

Optional Metadata fields:

  • cpaas.io/description: Description information for the JFrog connector, for example:

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

Capabilities of JFrog Connector

Authentication

The JFrog connector supports the following authentication types:

  • basicAuth: Username and password-based authentication, corresponding secret type: kubernetes.io/basic-auth

For example:

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

For comprehensive status information, see Connector Status Documentation.

Credential Permissions Required

The required permissions for the configured credential depend on how you intend to use it.

For example:

  • Download operations: If you only need to download dependencies, the credential only requires read permissions for the target repository.
  • Deploy operations: If you need to publish artifacts, the credentials must have both read and write permissions for the target repository.

For security best practices, we recommend creating credentials with minimal required permissions. When additional privileges are needed, create separate Connectors with more privileged secrets and use namespace isolation to control which users can access each Connector.

Local Generic Repository Pipeline Integrations

The platform provides the jfrog-raw-repository ResourceInterface for Pipeline Integrations that exchange files with a JFrog Artifactory Local Generic repository. The repository selector does not offer Remote or Virtual repositories.

When configuring the Integration in the Pipeline editor:

  1. Select a JFrog Connector.
  2. Select a repository. The list contains only repositories whose package type is Generic and whose repository type is LOCAL.
  3. For a download, open File Path. The platform recursively loads the repository's complete file list. Enter text to filter the loaded repository-relative paths locally, then select a result. You do not need to enter wildcard characters.

The selected value is the complete repository-relative path without the repository key, base URL, or a leading slash, for example:

releases/2026/report.json

The Integration exposes the Connector address, repository key, relative path, and an auth workspace to compatible Tasks. The path is optional, so an upload Task can select a repository and provide its destination path separately.

The Connector credential requires JFrog Read permission to list repositories, list files, and download from the selected repository. Upload Tasks also require JFrog Deploy/Cache (w) permission. The user who configures the Integration needs get permission on these Connector API resources:

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

The aggregated cpaas:connectors-jfrog-apis:view role normally supplies these permissions.

A successful File List request returns HTTP 200. An empty repository, or a local File Path filter with no match, appears as an empty option list. Requests without valid platform authentication return HTTP 401; invalid Artifactory credentials typically return an upstream HTTP 401. Missing platform API get permission or JFrog Read permission typically returns HTTP 403. A nonexistent repository may return HTTP 404, but this behavior can vary by Artifactory version, so clients must not rely on HTTP 404 alone.

Subconnector Generation

A single JFrog Artifactory instance usually fronts several package ecosystems — npm, Maven and PyPI — under different API paths. Rather than creating one Connector per ecosystem (or mounting the per-format configuration files described below), you can declare a JFrog aggregator Connector that generates one child Connector per ecosystem: set spec.generation.supportedClasses: [npm, maven, pypi] on the JFrog ConnectorClass and list the ecosystems in the JFrog Connector's spec.generators. The controller materializes per-class npm / maven / pypi child Connectors that share the aggregator's host and credentials, and pipelines consume packages through those children.

This is the recommended way to serve multiple ecosystems from one JFrog Artifactory instance. For the full model — address templating, auth inheritance, the GenerationReady condition, recovery and lifecycle — see Connector Generation.

JFrog Connector Proxy and Configuration Files

To provide clients with the ability to access JFrog Artifactory without credentials, the JFrog connector provides a proxy server to automatically inject authentication information.

Upon Connector creation, the system automatically provisions a proxy service for the target JFrog Artifactory instance.

The proxy endpoint is recorded in 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

The JFrog ConnectorClass provides the following configuration files that can be mounted via Connectors CSI Driver:

Configuration NameGenerated FileUse Case
settingssettings.xmlMaven operations via proxy
npmrc.npmrcNPM package operations
yarnrc.yarnrc.ymlYarn package operations
pipconfpip.confPyPI package download
pypirc.pypircPyPI package publish
Deprecated in favor of subconnector generation

Mounting these per-format configuration files directly (settings / npmrc / yarnrc / pipconf / pypirc) is deprecated. Prefer Subconnector Generation, which materializes per-class npm / maven / pypi child Connectors that pipelines consume instead of these raw configuration mounts.

Maven Configuration: settings.xml

The JFrog connector provides a settings.xml configuration file for Maven that routes artifact downloads through the connector proxy to the JFrog Artifactory Maven repository.

Configuration Parameters:

  • mirrorRepository (optional): The JFrog Artifactory repository key to use as the Maven mirror. If omitted, the generated settings.xml will not include a <mirrors> section.

Example CSI volume definition:

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

Example generated 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 Configuration: .npmrc and .yarnrc.yml

The JFrog connector provides .npmrc and .yarnrc.yml configuration files for NPM/Yarn that route requests through the connector proxy to a JFrog Artifactory NPM repository.

Configuration Parameters:

  • registry (optional, default ""): The JFrog Artifactory NPM repository key, used to build the NPM/Yarn registry URL. When empty, .npmrc / .yarnrc.yml is rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enable npm install / yarn install / publish.
  • strictSSL (optional, default "true"): If set, the connector writes this value to .npmrc (strict-ssl) and .yarnrc.yml (enableStrictSsl)

Example CSI volume definition:

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 Configuration: pip.conf and .pypirc

The JFrog connector provides pip.conf and .pypirc configuration files for PyPI tools that route requests through the connector proxy to a JFrog Artifactory PyPI repository.

Configuration Parameters:

  • repository (optional, default ""): The JFrog Artifactory PyPI repository key (for pip.conf). When empty, pip.conf is rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enable pip install.
  • deployRepository (optional, default ""): The JFrog Artifactory PyPI repository key for publishing (for .pypirc). When empty, .pypirc is rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enable twine upload.

Example CSI volume definition:

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"}}'

Using Connectors CSI Driver to Mount Configuration Files

CSI volume parameter descriptions:

  • csi.readOnly: Fixed value true
  • csi.driver: The Connector CSI Driver, fixed as connectors-csi
  • csi.volumeAttributes: CSI Volume attributes
    • connector.name: Name of the JFrog Connector
    • connector.namespace: Namespace of the JFrog Connector; if not specified, the Pod's namespace is used
    • configuration.names: Configuration name. Supported values: settings (Maven), npmrc, yarnrc, pipconf, pypirc
    • configuration.params: JSON string with runtime parameters for each named configuration

configuration.params for JFrog

For the general format, validation flow, and merge behavior of configuration.params, see configuration.params in the Connectors CSI Driver documentation.

The parameters accepted by each JFrog configuration are:

ConfigurationParameterRequiredDefaultDescription
settingsmirrorRepositoryNo""JFrog Artifactory repository key for the Maven mirror in settings.xml
npmrcregistryNo""JFrog Artifactory NPM repository key for the NPM registry URL in .npmrc
npmrcstrictSSLNo"true"Whether to require SSL ("true" or "false"); written to .npmrc as strict-ssl
yarnrcregistryNo""JFrog Artifactory NPM repository key for the Yarn registry URL in .yarnrc.yml
yarnrcstrictSSLNo"true"Whether to require SSL; written to .yarnrc.yml as enableStrictSsl
pipconfrepositoryNo""JFrog Artifactory PyPI repository key for the index URL in pip.conf
pypircdeployRepositoryNo""JFrog Artifactory PyPI repository key for the publish URL in .pypirc

When a parameter defaults to "" and the caller omits the corresponding entry from configuration.params, the rendered file contains a placeholder comment block (starting with # WARNING: empty configuration) that names the missing parameter and shows the JSON snippet needed to supply it — the CSI mount still succeeds and downstream tooling can detect the empty state without the Pod failing to start.

Further Reading

References