What Are Federated Repositories

Federated repositories are a repository type in JFrog Artifactory (rclass: "federated") that enables multi-site artifact management across geographically distributed JFrog Platform Deployments (JPDs). A Federated repository functions similarly to a local repository on the local JPD but is grouped logically with other Federation members located on remote JPDs to create a Federation. Artifacts and metadata in one JPD are mirrored to the Federation members in the remote JPDs that together comprise the Federation.

Unlike standard replication where a single source pushes to targets, federation creates a peer-to-peer topology where each member can independently accept deployments while keeping all other members in sync.

How Federation Works

flowchart TB
    subgraph jpd1 ["JPD Site A (US-East)"]
        fedA["Federated Repo: libs-release"]
    end

    subgraph jpd2 ["JPD Site B (EU-West)"]
        fedB["Federated Repo: libs-release"]
    end

    subgraph jpd3 ["JPD Site C (APAC)"]
        fedC["Federated Repo: libs-release"]
    end

    subgraph rtfs ["Federation Service (RTFS)"]
        sync["Event Processing and Sync"]
    end

    fedA <-->|"Bidirectional Sync"| sync
    fedB <-->|"Bidirectional Sync"| sync
    fedC <-->|"Receiving Only"| sync

    classDef component fill:#41b375,stroke:#389b65,stroke-width:1px,color:#fff;
    class fedA,fedB,fedC,sync component;

    style jpd1 fill:none,stroke:#41b375,stroke-width:1px;
    style jpd2 fill:none,stroke:#41b375,stroke-width:1px;
    style jpd3 fill:none,stroke:#41b375,stroke-width:1px;
    style rtfs fill:none,stroke:#41b375,stroke-width:1px;

    linkStyle default stroke:#8e9aaf,stroke-width:1.5px;

When a developer deploys an artifact to the Federated repository on JPD Site A:

1. The deployment triggers an event that is captured by the Federation Service (RTFS).
2. RTFS evaluates the repository's member configuration and mirror modes.
3. The artifact, along with its metadata and properties, is replicated to all other members based on their configured mode.
4. Each member updates its local state to reflect the new artifact.

For example, if Federated repository A in "JPD A" and Federated repository B in "JPD B" are members of the same Federation, deploying a file to Federated repository A in "JPD A" triggers a copy of the file to Federated repository B in "JPD B". Similarly, deploying a file to Federated repository B in "JPD B" triggers a copy of the file to Federated repository A in "JPD A". Configuration changes are also synchronized based on the latest update.

A Federation is a collection of Federated repositories in up to 10 JPDs at different sites that are automatically configured for full bi-directional replication.

Because the file isn't downloadable until its metadata arrives, verify the metadata's arrival by checking whether the file appears in the tree browser or the database of the target member.

Starting from version 7.74, if you use JFrog SaaS, you can confirm the file's arrival by looking for the following log message:

"Finished the handle mirror event for repo <REPO_KEY> and message: <MESSAGE>"

Where:

• <REPO_KEY>: The key of the Federated repository being synchronized.
• <MESSAGE>: The event message that was successfully processed.

For example:

"Finished the handle mirror event for repo libs-release-local and message: sync-complete"

Use Cases

Federated repositories provide Enterprise organizations divided across multiple geographical sites with a single source of truth for their binaries as if they were one seamless unit. They support the following use cases:

• Distributed development teams
• Remote production environment
• Increased artifact availability in a multi-site environment

Key Concepts at a Glance

The following concepts are essential to understanding Federated repositories.

Key Characteristics

• Federated repositories use a persistent queue to ensure that events are maintained even if a system failure or restart occurs.
• Metadata events are updated asynchronously among Federation members. Because of the persistent queue, the Federation mechanism ensures that all events are eventually synchronized.
• There is no dependency among Federation members, nor is there member priority when synchronizing the metadata. A member which is slow to respond or experiencing heavy traffic does not impact the other members.
• When the same file is sent from two locations simultaneously, conflict resolution is performed based on timestamps where the last event received overrides previous events. This is why clock synchronization is critical to proper functioning of the Federation. For more information, see Prerequisites.

Supported Package Types

Federated repositories support all Artifactory package types except TerraformBackend. This includes Maven, Docker, npm, PyPI, NuGet, Go, Helm, Generic, and many more. See Supported Package Types for the full list.

Frequently Asked Questions

This section provides answers to frequently asked questions about Federated repositories.

Related Topics

• Federation Members and Topology
• Synchronization and Conflict Resolution
• Create Your First Federation