Collective replication distributes a shared configuration baseline from a source Collective to one or more target Collectives. The shared configuration can include policies, entitlements, conditions, roles, and more. Collective replication is designed to help organizations and managed service providers (MSPs) scale consistently across regions, tenants, and environments while maintaining a governed security and access posture.
Collective replication provides:
Centralized configuration distribution and scale-out to multiple target Collectives, whether in a single enterprise or across multiple tenants.
Ensured continuity and access even if parts of the environment are unreachable, degraded, or operating offline.
Environmental integrity with safe, reliable movement of a configuration between lifecycle stages, keeping non-production environments and disaster recovery environments functional.
Collective replication is a separately licensable feature. For more information, see the Licenses section.
Source Collective
The source Collective holds the entities that you want to replicate.
On the source Collective, administrators can:
Configure entities.
Configure replication target Collectives and assign tags to be replicated to each target Collective.
Decide which entities are replicated to each target Collective by applying the target Collective’s tag.
The source Collective acts as the central point of configuration distribution for all subscribed target Collectives.
Target Collective
The target Collective receives a selected subset of AppGate ZTNA entities from the source Collective.
The target Collective uses the Admin API over Port 8443 (not SPA) and a service on the Controller on which the replication was configured. It contains a replicated copy of only the entities that have been tagged for that target Collective.
Collective replication uses a pull-down model:
The target Collective connects to the source Collective.
The target Collective retrieves (pulls) the entities it needs using the admin API.
The source Collective does not maintain a constant connection to the target Collective, reducing dependency on continuous connectivity.
Registering a Target Collective
Before a target Collective can receive a configuration, it must be registered with the source Collective. To register the target Collective:
Generate a registration key in the Replication Targets page in the source Collective.
After creating a replication target in the source Collective, an administrator copies the registration key.
Use the registration key in the target Collective.
In the target Collective, paste the registration key in the Key field if the Replication Source page to connect to the source Collective.
Tag the entities to replicate.
In the source Collective, administrators apply one or several of the target Collective’s tags to specific entities (for example, Sites, policies, or entitlements).
Only entities with at least one of those tags are eligible for replication to that target Collective.
Replication Synchronization
Once registered, a target Collective keeps its configuration in sync with the source Collective in two ways:
Periodic Replication
The target Collective periodically pulls configuration from the source Collective over Port 8443 using the admin API. You can view when the next replication will occur in the Replication Source page next to Source Replication Status.
On-Demand Replication
In addition to scheduled replication, admins can trigger a manual replication from the admin UI:
From the replication target, go to the Replication Source page.
Select Actions > Replicate from source now.
Disconnecting and Reconnecting Replication
If you need to remove entities from the target Collective:
In the source Collective, go to Replication Targets.
Select Actions > Change item replication tags > Remove item replication tag.
Select tags to remove from the drop-down.
Wait for the next sync.
From Replication Source in the target Collective, select Actions > Disconnect.
If you don’t need to remove entities, simply disconnect.
When you reconnect a target Collective to the same source:
Previously replicated entities are automatically reclaimed by their matching IDs.
Reclaimed entities:
Become read-only again.
Have their configuration replaced with the current version from the source Collective.
Lose any changes made during the disconnected period.
To preserve custom changes made while disconnected, clone the entity before reconnecting.
Replicated Entities
The following AppGate ZTNA entities can be replicated:
Admin roles
Client profile groups
Conditions
Criteria scripts
Device claim scripts
Entitlement scripts
Entitlements
Identity providers
IP pools
MFA providers
Policies
Ringfence rules
Sites
Tags (only the tags configured for the target Collective)
User claim scripts
If you attempt to edit a replicated entity, you will see a message with the blue R icon stating that it cannot be modified. To make a replicated entity editable, you can clone the entity or disconnect the target Collective.
NOTE
Only the tags that are specified for the specific target will be included in the replicated entities
Entity Relationships and Order
Some entities depend on others, for example:
Sites are foundational and role-based. Many other entities refer to them.
Entitlements require that their referenced Sites already exist.
Because of these dependencies, it's important to tag all entities that rely on each other with the same tags. If they are not tagged properly, there will be replication warnings and the replication will be incomplete.
Secrets Management Between Collectives
Collective replication uses the normal Controller API in which secrets are not exposed, so secrets must be manually moved from the source Collective to the target Collective.
The following fields are considered secret:
Field Name | Admin UI Location |
|---|---|
Client Secret | Identity Providers > OIDC > Google OIDC Configuration > Enable |
Password | Sites > Cloud Resolvers > Illumio Resolvers |
Password | Sites > Cloud Resolvers > VMware VSphere Resolvers |
Password | Sites > Tunneling > Tunnel Traffic > Terminate tunneled… > PKCS #12 Files |
Secret | Sites > Cloud Resolvers > Azure Resolvers |
Service Access Key | Sites > Cloud Resolvers > AWS Resolvers > Access Method > Use Access Key |
Service Account Password | Identity Providers > LDAP/LDAP Certificate > LDAP Configuration |
Shared Secret | Identity Providers > RADIUS > RADIUS Configuration |
User Shared Secret | MFA Providers > Authentication > Authentication Mode > RADIUS server MFA |
User Shared Secret | MFA Providers > Authentication > Authentication Mode > Appgate SDP Challenge-Response MFA |
If you have not moved these fields to the Secrets store:
Refer to Configure Secrets to add the secret.
Go to the field and select Refer to local secret, then select the saved secret from the drop-down.
The secret then needs to be manually added to the target collective with the same name as in the source collective.
If the entities use a normal password entry or if the secret is missing, the replication of the entity will fail and there will be a warning in the Replication Status Details page.
Monitoring Replication Health
Replication Status Details
When Collective replication is initiated, you can view the status of the replication from:
The Replication Targets page by selecting the health status of a target.
The Replication Source page by selecting the replication under Source Replication Status.
Both of these will open the Replication Status Details window, displaying a list of entities and how many have completed replication. Possible statuses include:
Healthy. All entities were replicated successfully.
Warning. Only some entities were replicated.
Error. Replication has failed. Details about the errors are provided.