ARTIFACTORY: Understanding the Impact of a JPD URL Change on Federated Members

Introduction

Changing the URL of a JFrog Platform Deployment (JPD) is a significant operation that impacts your JFrog platform. This article guides you through the implications and necessary steps when such a change occurs, specifically as they relate to Federated members. These URL changes are often driven by business, security, or infrastructure needs, including network topology changes (like a domain name or IP address update), the introduction of a new proxy or load balancer, or migration scenarios (such as moving from on-premise to a cloud provider or between cloud regions). Regardless of the reason, the impact on Federated members is critical and requires careful consideration to maintain seamless operations.

Important: 

• This feature is available only when all Federation members are using version 7.55.1 or above.
• As a fallback, it is possible to change the base URL more aggressively by canceling the Federation, changing the base URL, and then recreating the Federation. Please note this has a huge impact on the system since it requires recreating each Federated repository from scratch. This procedure is outlined in our KB article: How to change the BaseURL in a Federated Repository Environment? 

Impact of JPD URL Changes on Federated Members

When a JPD's Custom URL Base is changed, it's crucial to understand that these updates do not automatically propagate to the configurations of its Federated members. Each member of a Federated Repository has its URL explicitly configured, and these must be manually updated to maintain synchronization.
Let's illustrate this with a scenario involving three JPDs: JPD-US, JPD-EU, and JPD-IN. Each JPD hosts two Federated repositories: jl-generic-local and jl-docker-local.

Federation Configuration for jl-generic-local Repository (Before Change):

Configured URL for Member

Federation Configuration for jl-docker-local Repository (Before Change): When a change occurs to a URL on one of our JPDs—for example, if JPD-EU's URL changes to https://jpd-deveu.com—the Federated member URLs on JPD-US and JPD-IN that point to JPD-EU need to be updated as well. Failure to update these configurations will result in those members falling out of sync with the other JPDs.

Process for Updating Federated Member URLs
Updating Federated member URLs after a JPD's URL changes involves a three-step process:

1. Update the Custom Base URL on the Affected JPD: First, the Custom Base URL on the JPD that underwent the change (e.g., JPD-EU) needs to be updated. Refer to Change the Base URL (or Change the Federated Base URL depending upon the use case) for further details.
2. Generate and Share New Pairing Tokens: After the base URL is updated, new pairing tokens for JPD-EU need to be generated and shared among the other JPDs. See here for more details.
3. Replace Old URLs with New URLs via REST API: Finally, you need to replace the Base URL of the old URL with the new URL using a REST API call. This requires a POST request against the JPDs that hold the outdated Federated member configurations.

For our example where JPD-EU's URL changed from https://jpd-eu.com to https://jpd-deveu.com, you would execute a POST request against JPD-US and JPD-IN at the endpoints https://jpd-us.com/artifactory/api/federation/replaceUrl and https://jpd-in.com/artifactory/api/federation/replaceUrl, respectively, with the following JSON body:

{
    "oldBaseUrl": "https://jpd-eu.com/artifactory",
    "newBaseUrl": "https://jpd-deveu.com/artifactory"
}

Subsequently, the configurations in all Federated repositories using the old Base URL will be updated reflecting the new one. In this case, jl-generic-local and jl-docker-local will reflect the below:

Federation Configuration for jl-generic-local Repository (After Change):

Federation Configuration for jl-docker-local Repository (Before Change):

Illustrative Screenshots:

The below screenshots illustrate an updated Federated member after executing the above replaceUrl API. Here we have changed the Base URL from using http with a port designation to using https without a port:

Before the update:
 

After the update:
 

Post-Update Verification

After updating, we recommend following the steps outlined here to test the functionality of the Federation after changing the base URL.

Further Resources

Please see our documentation for complete details and context on Changing the Base URL in Federated Repositories.