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.
TOC
OverviewIntegration RequirementsCreating a simple JFrog connectorFields ReferenceCapabilities of JFrog ConnectorAuthenticationCredential Permissions RequiredLocal Generic Repository Pipeline IntegrationsSubconnector GenerationJFrog Connector Proxy and Configuration FilesMaven Configuration: settings.xmlNPM Configuration: .npmrc and .yarnrc.ymlPyPI Configuration: pip.conf and .pypircUsing Connectors CSI Driver to Mount Configuration Filesconfiguration.params for JFrogFurther ReadingReferencesOverview
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:
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 bebasicAuthfor 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:
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:
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:
- Select a JFrog Connector.
- Select a repository. The list contains only repositories whose
package type is
Genericand whose repository type isLOCAL. - 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:
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/repositoriesconnectors/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:
The JFrog ConnectorClass provides the following configuration files that can be mounted via Connectors CSI Driver:
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 generatedsettings.xmlwill not include a<mirrors>section.
Example CSI volume definition:
Example generated settings.xml:
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.ymlis rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enablenpm 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:
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 (forpip.conf). When empty,pip.confis rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enablepip install.deployRepository(optional, default""): The JFrog Artifactory PyPI repository key for publishing (for.pypirc). When empty,.pypircis rendered with a placeholder comment instead of failing the CSI mount; supply this parameter to enabletwine upload.
Example CSI volume definition:
Using Connectors CSI Driver to Mount Configuration Files
CSI volume parameter descriptions:
csi.readOnly: Fixed valuetruecsi.driver: The Connector CSI Driver, fixed asconnectors-csicsi.volumeAttributes: CSI Volume attributesconnector.name: Name of the JFrog Connectorconnector.namespace: Namespace of the JFrog Connector; if not specified, the Pod's namespace is usedconfiguration.names: Configuration name. Supported values:settings(Maven),npmrc,yarnrc,pipconf,pypircconfiguration.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:
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.