Migrate to the Artifactory Federation Service

Migrate your repository Federations (including configuration, states, and events) from the legacy Federation service in Artifactory to the standalone Artifactory Federation Service (RTFS) using the JFrog CLI.

This topic covers the following tasks:

• Install the Migration Plugin
• Run the Migration
• Verify Migration Status

Who can perform this task: Platform Administrators (self-managed)

Prerequisites:

• All items in the Migration Readiness Checklist are confirmed
• The Artifactory Federation Service is installed and activated
• No Full Sync operations are in progress (verify using the following commands)

jf rt curl api/federation/status/stateSummary
jf rt curl "api/federation/status/stateList?status=FULL_SYNC_RUNNING,FULL_SYNC_PREPARING,PENDING_FS"

Install the Migration Plugin

Before you can migrate, install the JFrog CLI federation-migrator plugin, which installs the jar of the migration tool and performs all required migration operations with one command.

To install the migration plugin:

• Run the following command to install the migration plugin from the official registry of JFrog CLI plugins:

  Bash

  jf plugin install federation-migrator

Large Environments and Behavior During Migration

Use the following guidance when planning migration for large federated footprints (for example, thousands of Federated repositories and tens of millions of artifacts):

• Federation during migration: Federation continues to work while migration runs. Artifactory does not fully move processing to RTFS until migration completes. Artifactory remains available, but avoid high-volume uploads and other heavy Federation tasks until migration completes.
• Do not run Full Sync during migration: Running Full Sync during migration can interfere with the migration flow. Verify that none are in progress before you start using the commands shown in the Prerequisites section.
• Mixed Legacy Federation and RTFS across JPDs: You can run a topology where one instance or site uses Legacy Federation (for example, Artifactory 7.104.x) and another uses RTFS (for example, 7.133.x). This is consistent with hybrid coexistence during transition, as described in the Migration Overview and Decision Guide.
• How long migration takes: JFrog does not publish a fixed duration or a universal ETA. Actual time depends on topology, current lag, network behavior, queued Federation events, and configuration size. It does not depend only on the number of Federated repositories or total artifact storage. For very large environments, plan the window with JFrog Support.
• Kubernetes CPU and memory: Increasing pod-level CPU or memory for Artifactory or RTFS isn't generally required solely as a precaution for migration. Use sizing that matches your normal production load. Scale resources only if monitoring indicates sustained pressure or backlog growth.
• JFrog does not define a special migration limit for repository count or total artifact volume. Migration focuses on Federation metadata, states, and events rather than moving binary data payloads.

Enable or Disable RTFS in an HA Cluster

In an HA cluster, the Artifactory node that handles your request applies the RTFS change first, then notifies the other nodes. If notification fails (for example, during a rolling upgrade), that node keeps the new state. Artifactory does not roll it back. The API or migration tool (jf federation-migrator) may return an error, and Federation can run slower than usual until every node is aligned.

Look for these messages in artifactory-service-federation.log on the node that handled the request. They appear only on that node.

ERROR - Error occurred during the propagation of initial federation client, current node with regarding RTFS state is: <true|false>

Migrating to RTFS (rtfsEnabled = true):

WARN - Some nodes failed to migrate to RTFS, federation-health-check-job will try to re-enable RTFS on those nodes during the coming 80 seconds

This WARN can appear in the log, but the Federation health-check job doesn't enable RTFS on lagging HA nodes. The job, which has a default interval of 80 seconds (see artifactory.federation.health.check.job.sec in Recovery and Auto-Healing), auto-reconnects a broken RTFS gRPC client and re-registers the Federation queue when migration has at least started. If other nodes remain out of alignment after the health-check interval, remediate those nodes manually (for example, retry the migration or restart the lagging nodes), then confirm RTFS is healthy.

Disabling RTFS or returning to legacy Federation (rtfsEnabled = false):

WARN - Current node disabled RTFS, A manual restart is needed for the other nodes to align them as well

Manually restart every other HA node. This means all instances except the one that already disabled RTFS. Lagging nodes do not receive Federation events while RTFS is disabled, so Federation can stay slow until you restart them. If a node still fails to align after restart, the issue is likely with that node itself.

For recovery steps if this persists, see Troubleshooting Federated Repositories.

Run the Migration

After installing the plugin, run the migration command to transfer your Federation configurations, states, and events to RTFS.

To run the migration:

• Run the following command:

  Bash

  jf federation-migrator migrate_rtfs <base url without /artifactory> <scoped token>

  Where:

  • <base url without /artifactory> is the base URL of your Artifactory instance
  • <scoped token> is a scoped access token. For details, see Generate Scoped Tokens.

  For example:

  Bash

  jf federation-migrator migrate_rtfs mycompany.jfrog.io <scoped token>

Command Options

The following table describes the available command options.

Verify Migration Status

After running the migration, confirm that it completed successfully.

To verify migration status:

1. Check the migration status:

   Bash

   curl -X GET -uadmin:password "http://{{artifactory_url}}/artifactory/api/federation/migration/status"

   If the service has been enabled, this API returns one of the following statuses:

   • MIGRATION_STARTED
   • MIGRATING_EVENTS_TO_RTFS
   • MIGRATION_COMPLETED
   • COMPLETED_WITH_ERRORS

   If the service has not been enabled, this API returns: Status not configured

2. Confirm migration completion:

   Bash

   curl -X GET -uadmin:password "http://{{platform_url}}/artifactory/api/federation/rtfs"

   The API returns true if migration has completed successfully.

3. Verify the Federation dashboard. The new Federation monitoring dashboard should be available in the platform UI. In the Administration module, go to Platform Monitoring > Federation Status.

Observability When Migrating to RTFS

Migrating to the standalone Artifactory Federation Service (RTFS) changes how you monitor Federation through REST APIs, Open Metrics, and logs. Plan updates to observability tools (for example, New Relic, Sumo Logic, Datadog, or a custom Prometheus exporter) before production cutover.

Legacy to RTFS metric mapping, selected examples:

Next Steps

• Federation Dashboard
• Migration Rollback

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Migration Overview and Decision Guide
• Artifactory Federation Service (RTFS)
• Frequently Asked Questions on Migration