Multi-region infrastructure

A region group is a group of regions that can participate in Akka’s multi-region features. For two services in different regions to replicate data between each other, their regions need to be part of the same region group. Region groups are isolated from each other, and cannot communicate or authenticate between each other. Region groups are typically used for different environments, for example, there may be a production region group, and a development region group.

All cross-region communication is authenticated using mutual Transport Layer Security (mTLS). Every client, and every service, has a certificate issued to it, and unless both sides authenticate with each other using the client and server certificate, the communication is blocked.

Each region group has a separate root Certificate Authority (CA). The root CA is used to issue client and server certificates for mTLS authentication. Since each region group uses a different Root CA, authenticated communication between region groups is impossible and thus effectively isolated, since client certificates issued to services in one region group won’t be trusted by services in any other region group.

All region group CAs are created on and managed by the Akka Federation Plane. It’s here that they are rotated. The private keys for the root CAs are never shared anywhere outside the Akka Federation Plane. For each region in a region group, an intermediate CA certificate is issued, managed and rotated by the Akka Federation Plane. This certificate has name restrictions allowing the intermediate CA to only issue certificates for its local domain names. There are two local domain names for a region, they are *.${AKKA_REGION_APPS_HOSTNAME} and *.${AKKA_REGION_PLATFORM_HOSTNAME}. The Akka Federation Plane has a job that periodically syncs intermediate CA keys and certificates, along with the root CA certificate, to all regions. The root CA certificate can be a list of CA certificates, this is to allow root CA rotation.

The multi-region ingress allows services to communicate with each other across regions. Each service is provisioned with its own client certificate issued by that region’s intermediate CA, this is done by the deployment operator. The SAN of the client certificate is in the format <service-name>.<project-id>.svc.${AKKA_REGION_APPS_HOSTNAME}. The ingress is hosted at ingress.svc.${AKKA_REGION_APPS_HOSTNAME}. When authenticating, the ingress determines the service and project name, and validates that the destination project matches the incoming project — thus preventing the ingress from being used to cross project isolation boundaries. It then adds the client SAN to a header, so that the Akka SDK runtime can perform further authorization as required.

By default, Akka provisions server certificates for auto-generated hostnames (e.g., <generated-name>.${AKKA_REGION_APPS_HOSTNAME}) by solving DNS-01 challenges using Let’s Encrypt. However, using Let’s Encrypt DNS-01 challenges isn’t always feasible or possible, particularly for BYOC/BYOK8s customers who bring their own DNS zones that Akka does not control. To support these cases, Akka allows customers to provide their own certificate provider configuration in the form of a cert-manager ClusterIssuer. When configured, the operator picks up the customer-provided ClusterIssuer and uses it in place of the default issuer to automatically provision certificates for auto-generated hostnames.

Customers can configure their own hostnames using the Akka CLI. In this case, TLS certificates are manually provisioned by the customer. The customer creates a TLS secret using akka secret create tls, and then configures the ingress route to use this certificate via akka route update --server-certificate-secret. This requires that the custom hostname is configured as a CNAME record pointing to the region’s apps hostname.

For detailed instructions, see the custom server certificates documentation.

For customers using a secondary_apps_domain_name for region or cluster-level failover routing, the same customer-provided ClusterIssuer used for auto-generated hostname certificates is reused to automatically provision certificates for the secondary hostname. This configuration enables DNS-level health checks and global traffic management patterns. The DNS structure follows a two-tier pattern: *.${SECONDARY_APPS_HOSTNAME} is configured as a CNAME record pointing to ${SECONDARY_APPS_HOSTNAME}. The ${SECONDARY_APPS_HOSTNAME} itself is configured as an A record pointing to the load balancer IP addresses. This separation is what enables failover routing with health monitoring at the A record level, since CNAME records do not support health checks.