Controller node

The controller is the coordination point for the cloud. It records identities, images, networks, instance requests and scheduler state. When a user asks to start a VM, the controller decides whether the request is permitted, finds a compute host, sends work to it and records the result. The compute host performs the actual boot.

Put the controller on a stable, reachable address. Its failure affects the dashboard and control APIs even if an already-running guest continues to execute on a compute host. The Saphira role is a controller role only: it does not configure compute or storage services on this machine.

Install Saphira Linux first, and become root for the role setup. Use a wired, stable network path for the controller where possible: compute hosts will use its address for Keystone, RabbitMQ, image, placement, Nova and Neutron services.

Before starting, write down the controller address, a region label, the browser-facing console hostname, and three distinct secrets. The package documentation does not specify hardware minimums; do not copy unverified sizing numbers into a production plan. Give the controller capacity for its database, message queue, service processes, logs and image storage, then measure it under your workload.

The controller script embeds secrets in service connection settings. Use distinct, safely stored values that are suitable for those connection strings; the packaged documentation recommends letters, digits, _, @ and -. Never reuse the administrator password as the service password or database password.

For external browser consoles, the hostname must be served by a working TLS virtual host. The script can add a /vnc/ proxy block only when it finds the expected nginx configuration; it does not supply a general TLS deployment for you.

# Run as root. Installing the package fetches the role closure but does not configure or start OpenStack.
apk add saphira-openstack-controller

This installs the controller role’s dependencies: MariaDB, RabbitMQ, memcached, Keystone, Glance, Placement, Nova, Neutron, Horizon and the Saphira installer foundation. Installation is deliberately separate from configuration, so a package install does not create databases, credentials, endpoints or services by surprise.

A successful package transaction returns to the shell without a setup banner. That is expected: the next command performs the configuration.

# Start the interactive controller configuration.
saphira-openstack-setup-controller

The script writes configuration files, bootstraps databases and identity data, starts services and probes them. It refuses to overwrite an existing configuration unless you later give --force. Do not use --force as a first response to a failure: it overwrites the files the script owns and can hide the state you need to inspect.

When all phases complete, the script prints controller ready and tells you to join a compute node. It also obtains an administrator token and probes Keystone, Glance, Placement, Nova and Neutron. Successful protected API probes return HTTP 200 or 300; an unauthenticated request is not the same test.

# Read-only verification after a completed setup.
saphira-openstack-setup-controller --check

The check reads the saved controller address and probes Keystone, Glance, Placement, Nova, Neutron and Horizon. It changes nothing. Each line should report a reachable endpoint rather than a timeout, refused connection or HTTP 000.

# Inspect the service state that the setup script starts.
systemctl is-active mariadb rabbitmq-server memcached
systemctl is-active keystone glance placement nova-api nova-conductor nova-scheduler
systemctl is-active neutron-api neutron-rpc-server horizon

Each successful line is active. If a service is inactive, do not continue to create networks or boot guests: read the unit log for that service and fix the first failing layer.

Horizon is reached through the web service configured for the controller. Sign in with the Keystone administrator account only after the setup verification passes. The exact public URL and TLS policy are site-specific; the role script does not create a general HTTPS site. Confirm the browser sees the intended hostname and certificate before entering an administrator password.

After a controller and a discovered compute host are healthy, create the dependency chain in this order: a provider network and subnet with DHCP enabled, an image, then a flavor. An instance needs all three plus a compute host. The compute guide explains the launch workflow and why each proof is needed.

Do not mistake a dashboard page for proof that the backend works. A useful progression is: controller endpoint checks, live Neutron agents, a live Nova hypervisor, an image and network visible in Horizon, then an instance which is ACTIVE, has a lease, and is reachable by the method you configured.

Use the unit name from the failed phase. For example, a healthy Neutron HTTP API with agents timing out points at neutron-rpc-server, not the web dashboard. A Nova-to-Neutron empty 401 points at Keystone service-token roles, not the user’s browser session.

# Examples: inspect the current boot’s service logs without changing configuration.
journalctl -u neutron-rpc-server -b --no-pager
journalctl -u nova-api -b --no-pager
journalctl -u rabbitmq-server -b --no-pager
journalctl -u horizon -b --no-pager

Re-run the setup script after correcting the specific issue; it preserves existing configuration unless --force is supplied. Use --force only when you have inspected the existing files and intentionally want the script’s generated configuration to replace them.

The role provides no automated controller backup, upgrade workflow, high-availability setup or tested rollback procedure. Before upgrades or manual configuration changes, make and test your own recovery plan for MariaDB, service configuration, image data and secrets. One controller is a single control-plane failure point; adding a compute host adds capacity, not controller redundancy.

For the known failure modes and their specific checks, continue to the OpenStack pitfalls book. When the controller is verified, continue with the compute-node joining procedure.