Adding a compute node to a running Kolla-Ansible deployment¶
How to bring a new hypervisor into a deployment that already runs workloads: prepare the host, add it to the inventory, deploy only to it, and prove it works before letting the scheduler place instances on it.
Context¶
Adding capacity is the most frequent change made to a running Kolla-Ansible deployment, and usually the least
risky one: a compute node runs no clustered service, so nothing on the control plane has to change membership. The
risk comes from the commands around it. bootstrap-servers can restart Docker and every container of a host it
touches, and a deploy without --limit walks every host of the inventory and restarts whatever configuration it
finds changed.
This page follows the Kolla-Ansible 2026.1 guide Adding and removing hosts, and adds what an operator checks before and after. It covers a libvirt/KVM compute node. Ironic compute services and new controllers are different cases (a new controller changes the membership of MariaDB, RabbitMQ and other clusters; see the guide).
Topology¶
Nothing changes on the controllers. The new host joins the compute group and gets the containers that group runs
in the inventory: nova_compute, nova_libvirt, nova_ssh, the Neutron agent of the chosen back-end
(neutron_openvswitch_agent and openvswitch_* with ML2/OVS, ovn_controller and openvswitch_* with ML2/OVN, plus
the OVN metadata agent), and the common containers (fluentd, kolla_toolbox, cron).
flowchart LR
subgraph control["controllers (unchanged)"]
c1[controller-1]
c2[controller-2]
c3[controller-3]
end
subgraph computes
k1[compute-01]
k2[compute-02]
kn["compute-03 (new)"]
end
control --- k1
control --- k2
control -. "deploy --limit compute-03" .- kn
Network design¶
The new host needs the same interfaces, with the same names, as the computes already deployed, or its own values in
host_vars: network_interface (and api_interface if separate), tunnel_interface for VXLAN or Geneve,
neutron_external_interface if computes carry provider networks or distributed floating IPs, and the storage
network if instances or volumes use Ceph. The MTU must match the rest of the deployment. See
network interfaces, VLANs and MTU.
The deploy host must reach it over SSH as the Ansible user, and the new host must reach the internal VIP, the registry and, with Ceph, the monitors.
Storage design¶
Nothing to change in Kolla-Ansible for a new compute: the Ceph client configuration and keyrings under
/etc/kolla/config/nova/ are copied to every compute by the deploy. What to check is on the host itself: with a
local instance store, the disk or volume behind /var/lib/docker/volumes/nova_compute (or wherever the deployment
puts it) is prepared the same way as on the other computes.
Inventory and configuration layout¶
Add the host to the compute group of the inventory, and to nothing else unless the deployment puts other roles
on computes (for example network with distributed routing, or storage):
[compute]
compute-01
compute-02
# new host
compute-03
# per-host values only when this host differs from the others, in host_vars/compute-03.yml
Keep the host name stable and unique: Nova registers the compute service under the host's node name, and Kolla-Ansible waits for exactly that name to appear (see below). Reusing the name of a compute that was removed earlier needs the old service record cleaned up first; see the Kolla-Ansible guide on removing compute nodes.
Procedure¶
Run from the deploy host, with the Kolla-Ansible version that deployed the platform. Check it first: pip show
kolla-ansible, in the virtual environment Kolla-Ansible runs from, must give the series the running images come
from (openstack_release in globals.yml, or the image tags of docker ps on a running host).
1. Read-only checks before the change.
openstack compute service list --service nova-compute # every existing compute up and enabled
openstack network agent list # every agent alive (ML2/OVS), or OVN controllers up
ansible -i <inventory> compute-03 -m ping # the deploy host reaches the new host
2. Prepare the new host. bootstrap-servers installs Docker and the host packages Kolla-Ansible needs, and
writes /etc/hosts entries. For compute nodes, the upstream guide says that the limit of pull and deploy only
needs the new hosts; for bootstrap-servers it shows an optional --limit, and limiting it to the new host is what
keeps the running hosts out of it. Its play gathers facts for every host of the inventory, like deploy (see What
went wrong below). Its fact gathering allows failures (max_fail_percentage defaults to 100), so an unreachable
host does not stop the play for the others: the run carries on, reports that host as unreachable at the end, and
exits non-zero.
⚠️ State-changing. Installs packages and configures Docker on the hosts in the limit. Limited to the new host, it changes nothing on the running ones. Without
--limit, it runs on every host, can upgrade or restart Docker there and every container with it (the bootstrap servers guide, Subsequent bootstrap considerations). Never run it without a limit on a production deployment.
kolla-ansible bootstrap-servers -i <inventory> --limit compute-03
customize_etc_hosts (true by default) adds an entry for each host's API address to the /etc/hosts of the hosts in
the limit only. The existing hosts do not learn the new host's name this way. If anything on the platform resolves
compute host names through /etc/hosts rather than DNS, add the entry there yourself, or include them in a later,
batched bootstrap-servers run.
3. Pull the images on the new host. Read-only for the rest of the platform; it only downloads images.
kolla-ansible pull -i <inventory> --limit compute-03
4. Run the prechecks on it. Read-only.
kolla-ansible prechecks -i <inventory> --limit compute-03
5. Deploy to the new host only.
⚠️ State-changing. Creates and starts the compute containers on the new host and registers it with Nova. The running hosts are not reconfigured: with
--limit, Kolla-Ansible still gathers facts from every host (itsgather-factsplay delegates fact gathering to the limited hosts) but only changes the hosts in the limit. The new hypervisor is enabled as soon as it registers, so the scheduler can place new instances on it at once. Undo: the removal procedure of the guide.
kolla-ansible deploy -i <inventory> --limit compute-03
Near the end of the Nova part, Kolla-Ansible waits for the new nova-compute service to register (20 tries, 10
seconds apart), then runs nova-manage cell_v2 discover_hosts --by-service in a cell conductor container so that the
host is mapped to its cell. You do not run discover_hosts yourself. If the service never registers, the deploy
fails on that host with The following Nova compute services failed to register themselves: <host>; read
/var/log/kolla/nova/nova-compute.log on the new host: most often libvirt did not start, it cannot reach RabbitMQ, or
it registered under another host name (see
Nova compute services failed to register).
Placement or Keystone errors do not block the registration: such a host passes this wait but gets no resource
provider, which the openstack resource provider list check of step 6 catches.
6. Verify, then test with an instance.
openstack compute service list --service nova-compute --host compute-03 # up and enabled
openstack hypervisor list # compute-03 listed, state up
openstack network agent list --host compute-03 # its agent alive
openstack resource provider list --name compute-03 # a resource provider exists (osc-placement plugin)
⚠️ State-changing. Creates, then deletes, one test instance on the new host. Use a test project and a small flavor. Targeting a host with
nova:<host>is an administrator action.
openstack server create --flavor <flavor> --image <image> --network <network> \
--availability-zone nova:compute-03 test-compute-03
openstack server show test-compute-03 -c status -c addresses -c OS-EXT-SRV-ATTR:host
openstack server delete test-compute-03
The test instance reaches ACTIVE, gets its address, answers on the network and reaches its metadata, before
you delete it. Test right after the deploy: once a compute service is disabled, Nova marks its resource provider with the
COMPUTE_STATUS_DISABLED trait and the scheduler leaves it out, so a disabled host cannot be used for a test boot.
7. If the test fails, take the host out of scheduling while you look at it.
⚠️ State-changing. Stops the scheduler from placing new instances on this host. Instances already on it keep running. Undo: the same command with
--enable.
openstack compute service set --disable --disable-reason "new host, failed test" compute-03 nova-compute
8. Rebalance if needed. New instances go to the new host through the scheduler's weighers; running instances do not move by themselves. To move some, live-migrate them one at a time (the guide's example, administrator only):
⚠️ State-changing. Live-migrates a running instance: a short pause at the end of the migration, longer for instances with a lot of memory activity. Check the instance's flavor and storage allow it (see where instance disks live).
openstack server migrate --live-migration --host compute-03 --os-compute-api-version 2.30 <server-id>
Key choices and their consequences¶
| Choice | Alternative(s) | Why this one here | Consequence in operation |
|---|---|---|---|
--limit <new host> on bootstrap-servers, pull and deploy |
Run on the whole inventory | Nothing on the running hosts is touched; the upstream guide allows --limit with only the new hosts for computes |
Configuration drift on other hosts (a changed globals.yml not yet applied) stays unapplied; the operating guide warns that --limit has known bugs in general, so keep it to this documented use |
Deploy, not reconfigure |
reconfigure --limit |
The new host has no containers yet; deploy creates them |
None for the existing hosts |
| Test before rebalancing | Let the scheduler fill the host at once | A host with a broken network or storage path fails every instance it gets | Takes a test instance and a few minutes |
| Several new computes in one run | One at a time | Same commands, --limit compute-03,compute-04 |
Fewer runs; a failure on one host does not stop the others (Kolla-Ansible fails only the host whose service did not register, unless nova_compute_registration_fatal is true) |
What went wrong during deployment¶
Nothing observed yet: this page was written from the upstream guide and the 2026.1 roles, not from a run. Failures that the 2026.1 code makes predictable:
The following Nova compute services failed to register themselves:nova_computedid not register within about 200 seconds. Readnova-compute.logon the new host.- Facts missing for other hosts: the
gather-factsplay gathers facts for every host through the limited ones; if a host of the inventory is unreachable, templates that need its address can fail. Fix or remove the unreachable host first. - A pull error on the new host only (registry name, insecure registry, proxy): see pull fails with "http: server gave HTTP response to HTTPS client".
Version notes¶
Written against Kolla-Ansible 2026.1 (stable/2026.1): the --limit behaviour of the gather-facts play and the
registration wait in ansible/roles/nova-cell/tasks/wait_discover_computes.yml are read from that branch. The
procedure in the upstream guide has had the same shape for several releases; check the guide of your release.
Lessons learned¶
- Check the Kolla-Ansible version on the deploy host before anything else: deploying a new compute with a newer Kolla-Ansible than the rest of the platform deploys newer images to it.
- Keep
--limiton every command, and type the host name rather than a group, so that a typo fails instead of widening the run. - Test with an instance before the scheduler sends real workloads.
Validity and limits¶
- Written from the Kolla-Ansible 2026.1 documentation (Adding and removing hosts, Bootstrap servers, Operating
Kolla) and code; not run on a lab for this page. Status
draft. - Covers libvirt/KVM computes. Not covered: Ironic compute services, new controllers or network nodes, cells (with
enable_cells, the new host goes into its cell's compute group; see the Nova cells guide of Kolla-Ansible), and hosts with SR-IOV, PCI passthrough or GPUs, which need their own configuration before the deploy. - The
/etc/hostsremark follows from the bootstrap servers guide; whether anything on a given platform depends on those entries for computes was not tested.
Related¶
- Kolla-Ansible 2026.1: adding and removing hosts,
bootstrap servers,
operating Kolla (the
--limitwarning) - Nova 2026.1: cells v2 and host discovery
- Laying out the configuration: inventory and
host_vars
Provenance: written by agent:ozarland-author, from the Kolla-Ansible 2026.1 documentation and code. Reviewed in its pull request (see the page history). Checked by a human operator: not yet.
Worked for you, or not? Tell us in one line: your release, your topology, and what happened.