Add Regions and Nodes¶

Each availability zone has exactly one container node, so adding capacity means adding an availability zone, and optionally a new region (location) to hold it.

An environment installed with the current provisioner¶

Add the new node to hosts.yml in your existing inventory, with its own az, container_network, container_network_name, and app_domain. Give it an existing region, or a new one. The node needs a blank data disk, named by docker_data_device unless the group variable on nodes already names it correctly.
If the node is in a new facility, add a metrics server for that site too, and optionally a backup server, and set the same site on all of them.
If you manage the load balancer DNS records yourself, create them for the new availability zone. With the bundled nameservers, the installer writes them for you.
Re-run the installer against the whole inventory:
```
make site ENV=prod
```

The run creates the new location, availability zone, node, and load balancer in the controller, and updates the metrics servers and every server's firewall to include the new node. Existing servers are brought back in line with your inventory, but nothing already in the controller is overwritten.

The run also links the default user group to every availability zone, so customers in that group can order in the new one. Links are only ever added, never removed. If you deliberately keep an availability zone off the default user group, such as an internal one, set controller_seed_link_regions: new in your inventory before the run: the default group is then linked only to the availability zones that run creates. This requires controller 9.7.10 or later.

Don't limit the run to the new region

--limit region_<name> selects only that region's nodes. The controller, metrics, backup, and nameservers are left out, so the run skips registering the node with the controller, updating the shared servers, and writing the new load balancer records, and still finishes without an error. A new availability zone needs the controller, its site's metrics server, and every shared server's firewall, so run the installer against the whole inventory when you add one.

A limited run is fine for re-applying configuration to a node that is already registered, as long as this copy of the provisioner has completed at least one full run. See the warning in Run the installer.

An environment installed with the previous (v1) installer¶

Environments built with the earlier, Debian-based installer can't be re-run with the current provisioner. Instead, attach mode adds a new Ubuntu 26.04 region to them, and makes only additive changes to your existing servers.

Before you start:

Upgrade the controller to 9.7.10 or later. The installer checks this before changing anything.
Build a separate inventory containing your existing shared servers (controller, metrics, backup, registry, and nameservers) and the one new node. Don't include any existing nodes: an existing node marked as existing stops the run, and one that isn't marked would be rebuilt from scratch.
Mark every existing shared server with existing_env: true. Don't mark the new node.
Copy secret_key_base exactly from /etc/default/computestacks on the existing controller into your secrets.yml. The installer checks it and stops if it doesn't match.
Use your existing backups_key and your existing metrics server's basic-auth credentials.
Describe your existing backup server with backup_host_path: /mnt and backup_borg_remote_path: /usr/bin/borg. Without them, backups from the new node fail.
Give the new node its own app_domain, different from cs_app_zone.
Give the new node a blank data disk, named by docker_data_device, exactly as for a new installation.
With dns_driver: powerdns, include your existing nameservers in the same shape as a full inventory: a nameservers group with ns_primary and ns_followers, each marked existing_env: true. The run then writes the new availability zone's load balancer records on the existing primary nameserver. Without the nameservers in the inventory, or with powerdns_manage_lb_records: false, create the load balancer records yourself before the run.
If you set tailscale_authkey, set tailscale_enabled explicitly on every server in the inventory.

Then run:

make add-region ENV=prod

Don't use --limit with attach mode. The run pauses once to show you the changes it will make to the controller, and it restarts the portal, which causes up to a minute of downtime.

Attach mode links the default user group only to the availability zone it creates (link_regions: new in the controller's bootstrap manifest), so customers in that group can order there. Availability zones you had deliberately kept off the default group stay off it.

To re-run the checks for an attached region later, use make add-region-validate ENV=prod rather than make validate.

Read the provisioner's attach mode guide before you start. It lists every change made to the existing servers and every setting that must match your existing environment. For how the current provisioner differs from the v1 installer, role by role, see Coming from v1. Attach mode doesn't convert your existing servers to the current provisioner; they keep their v1 configuration.