Skip to main content
Each app’s API is served through an AWS Application Load Balancer, and one load balancer holds at most 100 apps. AWS does not raise this limit. An installation that grows past about 90 apps adds load balancer shards: extra load balancers, each serving its own group of apps. Most installations never need a shard. If yours does, adding one is a config change plus one certificate name and one DNS record.

​
How shards work

The load balancer that provisioning creates is shard 0. Each shard you add has a number (1, 2, 3, …) and serves its apps on its own API hostname: Only the API hostname changes. The app’s frontend (my-app.apps.yourcompany.com) is the same on every shard.
  • Apps are placed at their first deploy. A new app goes on the lowest-numbered shard that has room. Shard numbers have no meaning beyond that: you can’t choose a shard for an app.
  • Apps never move. An app keeps its shard, and its API hostname, for its whole life. Apps that exist before you add shards stay on shard 0 with the URLs they have today.
  • A shard takes new apps only once its DNS record resolves. Until *.sN.api.<domain> points at the shard’s load balancer, deploys skip it.
  • Subdomains of the form s<number> (s1, s2, …) are reserved and can’t be used as app subdomains.
To find an app’s API host, open the app’s Deployments tab (Advanced → Custom domain → Reverse proxy targets), or run synthetiq production-app get <id> and read API host. Don’t derive it from the app’s domain.

​
Knowing when to add a shard

Deploys check capacity every time they run:
  • Warning: when every shard holds more than 80 apps, the deploy log says an administrator should add a shard.
  • Limit: when every shard holds 90 or more apps, a new app’s first deploy fails and tells the user to contact their administrator. Redeploys of existing apps are never blocked.
The 10-app gap below the 100 limit absorbs deploys that start at the same time. To see current capacity, run:
With AWS credentials for the registered account, status lists each shard and the number of apps on it:
Add the next shard when the warning appears. You then still have room for about 10 new apps per shard while the change goes through review.

​
Plan ahead in your certificate

Each shard’s listener needs a certificate covering *.sN.api.<domain>. To start, your API certificate only needs *.api.<domain>, for shard 0. To plan for capacity, you can optionally request it with spare shard names from the start:
  • *.api.apps.yourcompany.com
  • *.s1.api.apps.yourcompany.com through *.s9.api.apps.yourcompany.com
That is 10 names, the most an ACM certificate holds by default. Each name gets its own DNS validation record when you request the certificate, all created once. Shards then use the API certificate automatically, and adding one needs no new certificate. A certificate can’t gain names after it is issued. If your API certificate doesn’t list the shard you’re adding, either:
  • Request a separate certificate for the shard names (for example *.s1.api through *.s9.api) and set it as each shard’s api_cert_arn, or
  • Request a new API certificate with the extra names and update certs.api_cert_arn. Provisioning swaps the certificate on the existing load balancer in place.
Past shard 9, request another certificate for the next group of names (*.s10.api through *.s19.api), or ask AWS to raise the Domain names per ACM certificate quota.

​
Add a shard

1

Make sure a certificate covers the shard

The API certificate covers it if you issued it with spare shard names. Otherwise, issue one that covers *.sN.api.<domain> (see above) and wait for ISSUED.
2

Add the shard to the config

In _infra/synthetiq.yaml, list the shard under alb_shards:
A bare number uses certs.api_cert_arn. To use a different certificate, give the shard an entry:
Shard ids start at 1 and are permanent, because they are part of every API hostname on the shard. Add shards one at a time: an empty shard still costs a load balancer.
3

Preview and apply

Run synthetiq infra generate, review the new synthetiq-alb-shard-N stack in the changeset, then synthetiq infra provision. In CI, this is the usual pull request → review → merge loop. See Previewing & Applying Changes.
4

Create the shard's DNS record

provision prints one new record:Create it at your DNS provider (DNS-only if your provider proxies). provision warns while the record is missing, and the shard takes no new apps until it resolves. synthetiq infra status shows the same.

​
Vanity URLs on a shard

A vanity URL proxy forwards the API to the app’s internal API host. For an app on shard N, that is my-app.sN.api.<domain>, not my-app.api.<domain>. Copy it from Reverse proxy targets in the app’s Deployments tab.

​
Limits

  • Shards can’t be removed once apps are on them. Removing an entry from alb_shards does not delete its stack.
  • Load balancers per region default to 50 in AWS, which is room for about 4,500 apps. Raise it through Service Quotas if you need more.