Artifactory Versions Must be Identical
You will need to verify that the JFrog Artifactory version is identical across all the Artifactory instances hosting the Federated members to be included in the Federation.
JFrog Platform Deployments (JPDs) Clocks Must be Synchronized
If the federated repository artifacts are simultaneously updated on two (or more) member federated repositories, the update that is registered last will overwrite the other update(s). Therefore, to ensure consistent, predictable and trackable behavior of the system as a whole, the server clocks of all the machines running a federated members must be synchronized.
Configure the Custom Base URL in the General Setting of the Administration module. The Base URL supports detecting member JFrog Deployments (JPDs) in your organization.
Applies to Self-Hosted Deployment
The Custom Base URL is relevant to Self-Hosted deployments and not applicable in SaaS.
Changing the BaseURL in a Federated Repository Environment
You cannot modify the Base URL if you have Federated repositories set up with remote mirroring. Therefore, you will first need to remove the remote members from the Federation and to click Save.
After changing the base URL, proceed to set up the Federated repositories with the original Federated members. For all the remote members to be populated with new settings, it is recommended to wait for a short period of a time, between removing the remote members and changing the base URL.
Establish Trust Between the JPDs
You will need to establish trust between the JPDs in your Federated Repository. The options for enabling trust depend on whether this you have a Cloud or a Self-hosted deployment.
JFrog Enterprise/ Enterprise+ SaaS customers:
- Set up a binding token to create bi-directional trust between the JPDs.
Choose from one of the following options:
- Set up bindings between relevant JPDs: Using binding tokens enable admins to create trust between managed JFrog Platform Deployments (JPDs) once the JPDs have been added to the Mission Control instance, thus simplifying the setup across JPDs
- Enable a Circle of Trust: This option is intended for customers who are interested in providing full access to the other JPDs, access which is granted automatically once the Circle of Trust is implemented.
Federated Repositories that using binding tokens (i.e., no Circle of Trust) require an enabled Mission Control microservice in their Artifactory, since the token is created by Mission Control.
Setting Up a Federated Repository
Using the UI
- From the Administration module, navigate to Repositories | Repositories.
- Click Add Repository and select Federated Repository.
- Configure the Basic and Advanced repository settings similarly to configuring a Local Repository.
Note that it is mandatory to assign a Repository Key that will be added as the prefix to the Federated repository and displayed on all the sites.
- In the Federation tab, proceed to add the repositories located on other JFrog Platform Deployments (JPDs) to the Federation.
- Click Add Repository.
- In the Add Repositories dialog, add the repositories to the Federation using one of these methods:
- Deployments: If you have JFrog Mission Control installed, the repositories on the remote JFrog Platform Deployments will automatically be populated. If the repository with the identical name doesn't exist on the remote JFrog Platform Deployment, proceed to click Create New to duplicate this repository.
URL: Manually add a predefined URL path to the repository. If the repository does not exist on the remote JFrog Platform Deployment, it will be created automatically according to the following sytax.
- Click Save.
You will be routed back to the Basic tab.
- Click Create Federated Repository.
- Click Save.
Using the REST API
The following repository REST APIs support working with Federated repositories:
Pausing/ Resuming Federated Synchronization
You can pause and resume synchronization of the artifacts from your source Federated repository to the other member repositories.
Removing Repositories from the Federation
Admins on any of the federated members can remove themselves and other members from the Federation. Note that you can delete the initial repository and the Federation will continue to function between the remaining federated members.
- From the Administration module, click Repositories | Repositories and click the Federated tab to view a list of Federations.
- Select the Federation repository from the list and click the Federation tab.
- Click the x located on the top right of the repository.
If a remote JFrog Platform Deployment (JPD) is not accessible due to network connectivity issues or if the remote JPD is down, you need to manually make changes on the target JPD to complete the removal of the Federated member.
Converting a Local Repository to a Federated Repository
Using the REST API
You can convert a local repository to a Federated repository using the Convert Local Repository to a Federated Repository REST API.
You can convert an existing local repository to a Federated repository by clicking Convert in the Local repository Advanced tab.
- In the Repositories tab under the Administration module, select a local repository in the Local Repository list.
- Click the Advanced tab and in the Convert to Federated repository section, click Convert.
The Convert to Federated Repository dialog opens.
- Click Convert.
- Run the full sync using the Federated Repository Full Sync REST API.
The Local repository is moved to the Federated tab.
Converted Local Repositories Remain Federated
Removing the repository from the Federation does not automatically revert the repository to a local repository. Removing a repository from the Federation simply disconnects the bi-directional sync; however, the repository still remains Federated.
Converting a Build-Info Repository to a Federated Repository
Build-Info repositories can be set as a federated member in a Federation.
From Artifactory 7.35, you can convert an existing Build-Info repository to a Federated repository using the Artifactory REST API.
Step 1: Convert the build-info repository to a federated repository
Step 2: Add members to the build-info federation
The federated repository cannot be converted back to a local Build Info repository.
Step 1: Convert the Build-Info repository to a Federated repository
Step 2: Add member to the build-info Federation
Once you have converted the build-info repository into a federated build-info repository, proceed to add members to the federation using the Update Repository Configuration REST API
For more information, see Repository Configuration JSON.
Working with Federated Artifacts
Once you have created the Federation, the Federated repositories are automatically displayed in your Artifact browser.
Any of the CRUD actions that you perform are automatically applied on the member Federated repositories. Users can perform actions according to their permission sets. The logic is applied according to the last action performed on the Artifact by any of the users in the Federation.
Geo Synchronized Topology Use case: Setting a Federated Base URL
Did You Know?
The Geo synchronized topology is an extension of the full mesh topology whereby several Artifactory instances are connected to a GeoDNS.In this use case, the desired outcome is to have the exact same configuration (repository names, users, groups, permission targets) in all of the instances connected to the routing server. Users can then deploy and resolve from the same repositories without the need to change the configuration in their build tool according to the server they are been routing to (this can be done for DR purposes as well as for dividing a load in multiple locations to different instances). For these users, everything is behind the scenes and they just connect to Artifactory through one dedicated URL.
Setting an Initial Federated Repository URL
Geo Synchronized Topology requires that all Platform Deployments (Artifactory instances) be configured with the same Custom Base URL. Federated repositories must have their unique Custom Base URL in order to distinguish between the Federated members in the different Platform Deployments.
To work with Federated repositories within a Geo synchronised topology, add the
federatedRepoUrlBase parameter to the Global Configuration Descriptor file, which is the the global Artifactory configuration file, used to provide a default set of configuration parameters.
The following XML Tag should be added under the <systemProperties> section in the Global Configuration Descriptor.
federatedRepoUrlBase above is relevant ONLY to Federated Repositories and cannot be applied to other features.
For information on how to modify the Global Configuration Descriptor, see the Configuration Files Overview.
Migrating Federated Repositories to a Geo Synchronized Topology
From Artifactory version 7.21.13, you can migrate your existing Federated repositories to be configured with a dedicated Federated Repository URL instead of the Artifactory base URL.
Migrating in an HA Environment
When setting up Federated Repositories in an HA environment, ensure on both sites that only one HA node is up and running
- Disconnect all the Federated repositories in either one of the sites, using one of the following methods:
- One at a time in the Federated Repository page in the UI
- Directly through the Config Descriptor file.
$JFROG_HOME/artifactory/var/etc/artifactory/artifactory.config.xml and add the following XML tag.
Troubleshooting Federated Member Out-of-Sync Notifications
If any of the Federated members in your Federation are out of synch, the system triggers an out-of-sync notification. This can occur due to network failures or changes to your federated members.
You can manually push the updated configuration to the target Federated member, using one of these methods:
Run the Synchronize Federated Member's Configuration REST API.
- Directly in the JFrog Platform UI:
- In the JFrog Platform, navigate to the Administration module | Repositories | Federated.
- Select the relevant Federated member, and from the Actions list (located at the end of the list) select Push Configuration.