BYOK8s requirements

Under Bring Your Own Kubernetes (BYOK8s), you provision the cluster to Akka’s specification and install Teleport to grant access. Akka then configures the cluster as an application-plane region, runs smoke tests, and hands it over. This model runs in your cloud or your own data center.

This page lists the cloud-agnostic requirements. For a complete, self-contained setup guide for your cloud, follow the per-cloud page: BYOK8s on AWS, BYOK8s on Azure, or BYOK8s on GCP. Each of those includes everything below plus its cloud specifics.

Download the full BYOK8s setup as a PDF, or the full overview.

Once the region is running, do not change any provisioned infrastructure without first informing Akka. It could break the Akka region.

Installation flow

  1. Understand: review the technical overview and contact your Akka Success Team for a BYOK8s package.

  2. Capacity planning: size the environment with your Akka Success Team.

  3. Infrastructure requirements: agree on DNS subdomain zones, certificate provider, and related decisions.

  4. Infrastructure provisioning: provision the network, cluster, and database, and set up the egress domain allowlist.

  5. Customer smoke tests: run the checklist below before handing the cluster to Akka.

  6. Teleport: install the Akka-provided Teleport Helm chart. Deploy it promptly: the join token has a 3-hour TTL.

  7. Installation: Akka configures the cluster as an application-plane region and sets up platform observability. You seed database credentials into the namespaces Akka provides.

  8. Akka smoke tests: Akka attaches the region to the Federation Plane and runs smoke tests.

  9. Region handover: Akka assigns the region to your organization. A production-labeled region is not fully handed over until you complete the region-readiness steps.

Infrastructure requirements

Requirement Specification

Kubernetes

Version 1.34 at minimum. Cilium or Calico is mandatory for network-policy enforcement. Configure it as an overlay network only when the cloud-native CNI is unfeasible due to IPAM constraints.

Cluster CIDRs

/17 for the pod network and /17 for the service network.

Network

Minimum /21 CIDR block from your IPAM allocation, subdivided into three database subnets (/27 each) and three private subnets (/24 each).

Nodes

16 vCPU / 64 GB RAM instances (for example AWS m5.4xlarge, GCP n2d-standard-16, Azure Standard_D16s_v6). Minimum one node. Kubernetes autoscales the node count with demand.

Service Mesh

Akka deploys Linkerd, currently the only supported service mesh.

Load Balancer

Public Layer 4 by default. An internal load balancer is supported, and a subnet or IP can be specified on supported clouds.

DNS and Certificates

Two subdomain DNS zones, one for platform APIs and one for deployed services (for example akka.acme.com, apps.akka.acme.com), plus cert-manager ClusterIssuer objects for automatic certificate generation on both.

PostgreSQL

Version 17 or later, provisioned and configured by you, highly available across zones (RDS on AWS, CloudSQL on GCP, Azure Database for PostgreSQL flexible server).

CSI Driver

The cloud-specific secrets-store CSI (Container Storage Interface) driver provider.

Registry

Platform images can be pulled through your Artifactory, using Akka’s container registry as a mirror.

Database credentials

Seed the connection credentials (username, password, host, database name) as Kubernetes Secrets into both the kalix-system and kalix-management-system namespaces. You create these namespaces if needed, but do not manage them: AAO imports them into its management scope and reconciles them. Akka recommends the external-secrets operator to mirror credentials from your cloud secret store.

Access

Within a customer-provisioned cluster, Akka uses least-privilege permissions scoped to the Akka-managed namespaces and limits its access to customer-owned Kubernetes resources.

Capacity planning

Database size is driven by total application data operations per second at peak load. Work with your Akka Success Team to determine sizing.

DB Size Data ops/sec CPU Memory (GB) Storage (GB) Max Connections

XSmall

1,000

1

4

100

200

Small

3,000

2

16

200

500

Medium

6,000

4

32

400

1,000

Large

12,000

8

64

800

1,500

XLarge

24,000

16

128

1,600

2,000

Egress allowlist and Teleport

Akka reaches the cluster through Teleport, which uses ports 3023, 3024, and 3026 in addition to 443. Teleport is a certificate authority and identity-aware proxy; the non-standard ports segment traffic types, and the security boundary is mutual TLS rather than the port. The full egress hostname and IP allowlist (Teleport, console, Federation Plane, Control Tower, observability, and container registry endpoints) is on the data flows page.

Customer smoke-testing checklist

  • Check connectivity between the database instance and the Kubernetes cluster.

  • Ensure the ClusterIssuer is ready and in a good state, and verify all tokens it uses.

  • In multi-region configurations, ensure traffic flows in both directions between regions.

Choose your cloud

Each page is a complete, self-contained setup: the requirements above plus that cloud’s specifics.

  • BYOK8s on AWS: Route 53, IRSA, EKS, RDS for PostgreSQL, and external-secrets.

  • BYOK8s on Azure: resource providers, EncryptionAtHost, and Azure Database for PostgreSQL.

  • BYOK8s on GCP: Cloud SQL, private services access, and Cloud DNS.