Skip to main content


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


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.

Considerations and Limitations

  • Multi-regional deployment of the Akuity Platform does not constitute a backup or high-availability solution.
  • Argo CD instances cannot be moved to another region after creation.
  • Region names cannot not be modified once Argo CD instances are deployed to it.
  • Region assignments to Organizations require manual database changes.
  • Argo CD URLs will use a unique regional subdomain.


  • 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.
  • Network connectivity to the database instance in your primary region from all non-primary regions.
  • A DNS zone for each region matching the region's name.
  • A wildcard SSL certificate for each region with SANs matching the region's name.

Enable Multi-Region

Helm Values

The Helm values used for your non-primary region/s will typically match your primary region. The only exception is your non-primary region/s should have .platformController.shard set to the name desired for that region (ex. us-west).


The Helm value set for .platformController.shard is incorporated into the FQDN for instances in that region. For example, instances assigned to a shard named us-west would use an FQDN like <instance-id> Instances assigned to a shard named us-central would use an FQDN like <instance-id> Instances not assigned to a shard will use the usual FQDN form of <instance-id>

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.


Adjusting Database Configurations of Non-Primary Shards

Each non-primary region/shard will need it's own database in addition to being able to access the database configured in the primary region. The K3S database connection strings for each shard will need to be overridden to make the shard connect to its own database. To make this change using Kustomize, use the following 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>

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


echo -n ' port=5432 sslmode=require dbname=postgres user=myuser password=mypassword' | base64

(Optional) Using a Custom Shard Name in the Primary Region

To assign a unique shard name to your primary region, you can apply the follow Kustomize patch:

- target:
kind: Deployment
name: platform-controller
patch: |-
- op: add
path: /spec/template/spec/containers/0/args/-
value: --shard=<region_name>

If the primary region is configured using a unique shard name, instances created in an organization without any assigned shards will be undeployable. Note that the primary region can still be used alongside other shards without specifying a unique shard name.

Assigning Shards to Organizations

In order to assign an Argo CD instance to a region, that region's shard must first be assigned to an organization in the Akuity Platform.

To assign shards to an organization, you must update the database in the primary region and explicitly specify which shards each organization is allowed to deploy to.

  1. Connect to the database.
    psql " port=5432 sslmode=require dbname=postgres user=myuser password=mypassword"
  2. Update the organization with the shards you wish to assign
    UPDATE organization SET feature_gates='{"shards":["<shard_name>","<shard_name>"]}' WHERE name='<org_name>';

The JSON list of shard names should be expanded to contain the names of all desired shards to be made available to an organization.


The primary region can be made an option in the Region dropdown even if a unique shard name has not been specified. If a unique name has not been specified for the primary region, this can be done by setting one of the shard names in the shards list of the SQL query above as empty (""). The primary region will then become an option during instance creation with the region name us0.

Creating an Instance

Once sharding has been enabled for an organization, you will see a new Region dropdown with a list of the shard names you assigned to the organization in the previous step.

Region dropdown


If you are missing this dropdown, verify that you assigned at least 2 shards to the organization in the previous section.


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

  1. Change your kubectl context to the region/shard you assigned your instance to.
  2. Run kubectl get ns.
  3. A new argocd-<instance_id> namespace should appear.