Multi-Region

Multi-region functionality in the Akuity Platform enables the distribution of Argo CD and Kargo instances across clusters in different regions and/or cloud providers, allowing you to select where each instance is created. This is done using the sharding feature of the Akuity Platform.

danger

Multi-regional deployment of the Akuity Platform is an advanced function. Review this page in its entirety and ensure that you understand the requirements and limitations of this feature before proceeding.

Contact support before proceeding if anything is unclear.

How Sharding Works

A shard is one workload cluster. Each cluster's controllers reconcile only the instances placed on that cluster's shard.

• The default shard is the cluster you already run — the one hosting the portal, Dex, the database migration job, the notification controller and the scheduled jobs. It leaves the shard Helm value empty, and exactly one cluster in the installation may do so.
• Every additional region is a cluster installed with its own shard value (for example us1). Those clusters run their own platform controller and addon controller, but not the singleton components listed above.
• defaultShardName is the name the API and UI display for the default shard. It does not decide which cluster is the default — shard does.

If you only run one cluster, there is nothing to configure: that cluster is the default shard, and sharding only starts to matter once you install a second one.

note

Platform shards are unrelated to Kargo Stage shards, which assign Stage reconciliation to a particular Kargo agent. A platform shard selects the cluster an instance is provisioned in.

Considerations and Limitations

• Multi-regional deployment of the Akuity Platform does not constitute a backup or high-availability solution.
• Argo CD and Kargo instances cannot be moved to another region after creation.
• Region names, including defaultShardName, cannot be modified once instances are deployed to them.
• Instance URLs include a regional subdomain, so each region needs its own DNS records and certificate.
• Regions are made available to every organization in the installation. They cannot be restricted to specific organizations.
• If instances use IP allowlists, cross-region traffic requires each region's egress IPs to be allowed (see IP Allowlists).

Requirements

• A working Akuity Platform installation in your primary region.
• At least 1 organization created in the Akuity Platform.
• At least 1 additional Kubernetes cluster.
• At least 1 database instance per additional Kubernetes cluster, for that region's instance control planes.
• Network connectivity to the platform database in your primary region from all non-primary regions.
• A DNS zone and a wildcard certificate for each region, covering the region's subdomains (see Regional DNS and Certificates).

Enable Multi-Region

Helm Values

Value	Set it to	Notes
shard	Empty on the primary region; the region's name (for example us1) on every other region.	Cannot be changed after deployment. Must never equal defaultShardName.
defaultShardName	The name you want to display for the primary region (for example us0).	Identical on every cluster. Fixed after installation.
availableShards	The display names of every region, for example ["us0","us1"].	Identical on every cluster. Grants those regions to all organizations.

The values used for your non-primary regions otherwise match your primary region.

Primary region:

shard: ""
defaultShardName: us0
availableShards:
  - us0
  - us1

Non-primary region us1:

shard: us1
defaultShardName: us0
availableShards:
  - us0
  - us1

info

shard is incorporated into the FQDN for instances in that region. Instances assigned to a shard named us1 use an FQDN like <instance-id>.cd.us1.mydomain.com, and Kargo instances <instance-id>.kargo.us1.mydomain.com. Instances on the default shard keep the usual form, <instance-id>.cd.mydomain.com.

You will need to ensure that the SANs for the SSL certificate deployed in a region match the FQDNs that will be used in that region.

Include defaultShardName in availableShards — otherwise the primary region is not offered as a choice.

Naming the Primary Region

Set defaultShardName to give the primary region a name. Do not set shard on the primary region to name it — a non-empty shard turns the cluster into a workload region and stops the portal's singleton components from being deployed there.

defaultShardName is display-only and never re-homes an instance, but treat it as fixed once the platform is installed:

• Renaming it changes the region reported for every instance in the primary region. Terraform configurations with an explicit shard will then plan a destroy and recreate.
• It must never match another region's shard — a collision silently sends that region's new instances to the primary cluster.
• Keep it identical on every cluster.

The chart refuses to render if shard equals defaultShardName, or if availableShards is set while defaultShardName is empty.

Regional DNS and Certificates

Each region needs the four wildcard records and SANs from Getting Started, with the region's name inserted before the domain suffix. For a region named us1 under akuity.example.com:

• *.cd.us1.akuity.example.com
• *.cdsvcs.us1.akuity.example.com
• *.kargo.us1.akuity.example.com
• *.kargosvcs.us1.akuity.example.com

The primary region keeps its existing records — with defaultShardName set, its FQDNs do not gain a region segment.

IP Allowlists

Traffic between regions — the portal reaching an instance in another region, or a Kargo instance working with an Argo CD instance in another region — goes over the public regional FQDNs and arrives from the source cluster's egress IP (typically a NAT gateway or load balancer address). If your instances use IP allowlists, those egress IPs must be allowed:

• Set platformController.portalIPs on each non-primary region to the primary region's egress IPs. They are appended automatically to the allowlist of every allowlisted instance in that region, so the portal and UI keep working.

  platformController:
    portalIPs:
      - 203.0.113.10

• Instances in the primary region, and instances reached from another region's Kargo or Argo CD instance, get no automatic additions. Add the source region's egress IPs to the target instance's IP allowlist yourself.

Kustomizations

Adjusting Database Configurations of Non-Primary Regions

Each non-primary region will need its own database for the instance control planes, in addition to being able to access the platform database configured in the primary region. The K3S database connection strings for each region will need to be overridden to make the region connect to its own database. To make this change using Kustomize, use the following patches:

patches:
- target:
    kind: Secret
    name: akuity-platform
  patch: |-
    - op: replace
      path: /data/K3S_DB_CONNECTION
      value: <b64_conn_string>
    - op: replace
      path: /data/K3S_RO_DB_CONNECTION
      value: <b64_conn_string>

note

Replace <b64_conn_string> with a base64'd database connection string for that region.

Example:

echo -n 'host=db.us1.mydomain.com port=5432 sslmode=require dbname=postgres user=myuser password=mypassword' | base64

warning

Only the K3S_* connection strings are overridden. PORTAL_DB_CONNECTION must continue to point at the primary region's platform database on every cluster.

Creating an Instance

Once at least two regions are configured in availableShards, instance creation shows a Region dropdown listing them, for both Argo CD and Kargo instances.

note

If you are missing this dropdown, verify that availableShards lists at least 2 regions — a single region is selected implicitly and the dropdown is hidden.

Regions can also be selected without the UI:

Interface	Argo CD	Kargo
API / declarative manifest	spec.shard	spec.shard
CLI	—	akuity kargo instance create --shard us1
Terraform	akp_instance → argocd.spec.shard	akp_kargo_instance → kargo.spec.shard

In every case the value is the region's display name, and it is immutable after creation — changing it in Terraform plans a destroy and recreate. An instance in the primary region reports its region as defaultShardName.

Validation

To verify your instance has been or is being created in the selected region:

1. Change your kubectl context to the region you assigned your instance to.
2. Run kubectl get ns.
3. A new argocd-<instance_id> namespace (or kargo-<instance_id> for a Kargo instance) should appear.