Skip to content
zone9

5. Region configuration

Regions are described in a versioned YAML file, not in the database. The code knows no difference between regions; every difference is in this file. Secrets are referenced by environment variable name and never appear in it.

Shape

Section titled “Shape”
regions:
  - id: <region-id>
    display_name: "<Human name>"
    enabled: true
    read_only: false            # true → write jobs are refused


    proxmox:
      api_url: https://<node>:8006
      token_id: zone9-rw@pve!ctl
      token_secret_env: ZONE9_PVE_<REGION>_TOKEN
      max_concurrent_requests: 8
      task_timeout_seconds: 600


    nodes:                      # placement candidates. A node not listed never
      - name: <node-1>          # receives a virtual machine
      - name: <node-2>


    storage:
      vm_storage: <storage-id>
      replication_enabled: true
      replication_schedule: "*/60"
      max_usage_percent: 80


    placement:
      ram_reserve_mb: 20480     # memory left for the hypervisor itself
      cpu_overcommit: 3.0


    network:
      public_bridge: <bridge>
      default_network_mode: vxlan     # vlan | vxlan
      sdn_zone: <zone>
      vnet_mtu: 1450                  # VXLAN header costs 50 bytes
      public_gateway_v4: <edge address>


    images:                     # catalogue slug → Proxmox template id
      ubuntu-24.04: <vmid>
      windows-2025-std: <vmid>
      talos-v1.13.10: <vmid>
      gateway: <vmid>
      lb: <vmid>
      s3: <vmid>


    edge:
      kind: fortigate           # none | fortigate
      api_url: https://<edge>
      token_env: ZONE9_FORTI_<REGION>_TOKEN
      mode: analyze             # analyze | apply
      object_prefix: z9

The fields that matter most

Section titled “The fields that matter most”

read_only — refuses write jobs while still serving reads. The honest way to take a region out of service for maintenance without pretending it is gone.

nodes — placement only considers nodes on this list. Adding a hypervisor to the cluster does not make it a target until you list it, which is what you want when you add a node and have not finished preparing it.

placement.ram_reserve_mb — memory withheld from placement for the hypervisor itself. Set it too low and you eventually place a machine onto a node that cannot start it.

vnet_mtu — 1450 for VXLAN over a normal 1500-byte network. Wrong here means small packets work and large ones vanish.

edge.mode — start in analyze. It reads and refuses writes, so you can confirm the adapter sees what you expect before it changes anything.

images — the map from catalogue entry to Proxmox template. An entry with no template in a region simply does not appear in that region’s catalogue, which is how you roll an image out one region at a time.

Adding a region

Section titled “Adding a region”
  1. Prepare Proxmox and the network in the new region (1, 2).
  2. Install an agent there (4).
  3. Add a block to this file with enabled: false.
  4. Build the templates and fill in images (6).
  5. Set enabled: true.

Users then see the region in the catalogue. Nothing moves between regions — a region is a separate world by design.

Changing it

Section titled “Changing it”

The file is versioned; change it, review it, deploy it. Two changes deserve care:

  • Removing a node from nodes stops new placement there. Machines already on it stay where they are.
  • Changing vm_storage affects new disks only.