Skip to main content

Multi-Region

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.

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.

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.

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.
  • 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).

info

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>.cd.us-west.mydomain.com. Instances assigned to a shard named us-central would use an FQDN like <instance-id>.cd.us-central.mydomain.com. Instances not assigned to a shard will use the usual FQDN form of <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.

Kustomizations​

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:

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/shard.

Example:

echo -n 'host=db.us-west.mydomain.com 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:

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

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 "host=db.us-west.mydomain.com 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>';
info

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

info

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

note

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

Validation​

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.