Skip to content

Genestack Console

Genestack is this repository. It is the scripts, Ansible playbooks, and charts that install OpenStack on Kubernetes.

Genestack Console is a different program. Install it on its own Linux server. Clone this repository onto that same server, then open the console in a browser. From that page you:

  • save the settings for one cloud
  • turn the physical servers on and off
  • give a server an IP address and a boot file while you install an operating system on it
  • run the scripts in this repository and read the log

That server is the deploy host. The deploy host is the machine that performs the install. The cluster is the Kubernetes and OpenStack cloud the scripts in this repository build. The deploy host never joins the cluster. It stays just outside the cloud, so you reach the servers from this machine and not through the cluster. If the cluster stops answering, you can still power the servers and run the install from here. The console, the saved settings, the job log, and the passwords you save there stay on that machine.

We recommend the deploy host be L2 with the servers you are installing. L2 means they are on one local network. On that network the console can give a server an IP address and a boot file itself. The section below says how that boot works.

When the deploy host cannot be L2 with a site, install the console agent on a computer that is. The agent gives out the addresses and the boot files at that site, and it connects out to the console. You still run the job from the console. One console often looks after several sites this way, such as more than one datacenter in the same private cloud.

The console is published on its own: PIndustries/genestack-console. This page is the chapter in the Genestack manual. The pages after it walk through the program. Install details for a Mac or Windows, and how a release is cut, stay in that repository.

Install the console

On the deploy host:

curl -fsSL https://get.genestack.dev/console.sh | bash

That address redirects to the current installer attached to a GitHub Release. The script installs the program under /opt/genestack-console and starts a web page at 127.0.0.1:8080. The page listens only on the deploy host until you change server.host.

From a laptop, forward that port:

ssh -L 8080:127.0.0.1:8080 <deploy-host>

Open http://127.0.0.1:8080/ui. The first screen is Guided setup. The first admin password is written to /opt/genestack-console/ADMIN_CREDENTIALS.txt. The file mode is 0600.

The build described here is v2026.10.07.21. The Linux file on that release is genestack-console-linux-amd64. version.json on the same release names that file. Use those assets when you need this exact version. The curl command above follows whatever the latest release is. The same release also has the disk and the CD in the next section. The list of files is genestack.dev/releases.

Back up two things together: /opt/genestack-console/config.yaml, and the console database. The database holds the users and the sessions. Passwords stored in it are encrypted with a key from config.yaml. A copy of the database without that file cannot be decrypted.

Boot the console as an appliance

The command above puts the program on a Linux server you already have. The same release ships a boot image for a machine that does not have an operating system yet. The image is Ubuntu 26.04 with the console already on it. SSH is installed and does not start. The page listens on port 8080 on the machine's addresses, so you open http://<address>:8080/ui without an SSH forward.

Two files are on the release:

  • genestack-console-appliance-2026.10.07.21-amd64.qcow2.xz is a virtual machine disk with the console already installed. Decompress it and boot it.
  • genestack-console-appliance-2026.10.07.21-amd64.iso is a CD. Boot it and type the disk to install onto. That disk is wiped. The installed system is the same appliance as the virtual machine disk.

The first boot writes the admin password on the machine console, in /opt/genestack-console/ADMIN_CREDENTIALS.txt. The resize, the OpenStack import, and the install prompt are in The appliance.

This CD is the console itself. The ISO named later on this page is a different file. That one is an image for a server you are installing into the cloud.

Where the files go

Clone this repository first. Getting the code is that step. On the deploy host the checkout lives at /opt/genestack.

bootstrap.sh, in that checkout, creates /etc/genestack. That directory is the inventory and the settings the install reads. One file it writes is /etc/genestack/provider, which records which Kubernetes installer this environment uses. The console reads that file. Talos and Kubespray are the two values. Genestack after Kubernetes is the same work either way.

Talos is the preferred way to provision bare metal. Talos is an operating system that boots a machine straight into Kubernetes. The Talos steps on this page follow Talos Linux: wipe the disks, boot Talos, then send the machine config. Set the provider file to talos for that environment.

Kubespray is the other installer. It adopts machines that already have an operating system, then Genestack continues the same way. bootstrap.sh writes kubespray into the provider file when that file does not exist yet. That is the file's initial value, not a preference for bare metal you are provisioning.

Ubuntu is a different next boot. It installs one machine and stops. It is not a value in the provider file. A Kubespray environment can adopt that machine afterward.

Path What it is
/opt/genestack This repository, on the deploy host. The console runs the scripts from here.
/etc/genestack Inventory and settings. bootstrap.sh creates the directory. You still edit the files the way the rest of this manual describes.
/opt/genestack-console The console program. It is installed beside this checkout. It is not a folder inside it.
submodules/genestack-console The console source, pinned in this repository the same way Kubespray is pinned. A normal clone does not download it.
127.0.0.1:8080 The console web page, on the deploy host.

The pin is PIndustries/genestack-console at release v2026.10.03. That pin is the source snapshot in this repository. The program, the disk, and the CD named above are the later release. The submodule is marked ignore = all, so a normal clone skips it. Fetch the source when you want it next to this tree:

git submodule update --init submodules/genestack-console

What you do in the console

An environment is one cloud: a lab, one rack, or one region. A tenant is the group of people allowed to use that cloud. Jobs and passwords for the cloud stay inside the environment.

Point the environment at /opt/genestack and at the /etc/genestack directory bootstrap.sh already created. Saving settings in the console does not change those directories by itself. A job copies the saved settings onto the deploy host, then runs the install scripts from this tree. The log of that job stays on the environment.

The console database on the deploy host holds the passwords, the kubeconfig, and the management-port passwords. A job writes kubesecrets.yaml so the install scripts can read it, and removes that file when the job finishes, including when the job fails or is cancelled. A kubeconfig the job created is stored in that database and then removed from the deploy host. A kubeconfig path that was already on the host stays. How a job runs is the longer account of that cleanup.

When the install has finished, the same environment is where you look at Kubernetes, act on namespaces, nodes, and pods, run the OpenStack service steps, and download two credential files. The kubeconfig is how you talk to Kubernetes. The talosconfig is how you talk to Talos. Skyline is the OpenStack web page for people using the cloud day to day. The console is the page for the people who build the cloud.

People who sign in have one of three roles: viewer, operator, or admin. An API key in config.yaml is the emergency login, for when the user accounts cannot be used.

How a server gets an operating system

Where the deploy host is L2 with the servers, the console answers DHCP and serves the boot file on that network. DHCP is how a machine asks for an IP address. The boot file is the small program the network card downloads when the server is told to start from the network instead of from its disk. Both services run inside the console. This is how a server gets an operating system. Talos and Ubuntu are the two the console installs from the network. Talos is the preferred boot. Ubuntu leaves the machine out of the cluster so Kubespray can adopt it. You do not install a separate DHCP server, or another program, to boot the machines.

Each server has two addresses you type in.

  • The management port. Vendors call it the BMC, iLO, or iDRAC. It is a small controller inside the server that stays on when the main computer is off. The console uses it to power the server, and to ask the server to boot from the network one time.
  • The port on the L2 network. The console, or the agent at a remote site, matches that port by its MAC address. A MAC address is the hardware address of the network card.

Every server has its own next boot.

  • Disk is the default. A server you have never asked the console to install boots from its own disk.
  • Commission is a small system that runs from memory. It wipes the starts of the fixed disks and sends one report back to the console.
  • Talos is offered to that server only after the report has been accepted. The Talos machine config is sent after the wipe. It is not placed on the boot command line.
  • Ubuntu installs that one machine. It uses the whole disk. The login user is ubuntu and the key is the environment SSH public key the console already keeps. The seed is data/pxe/ubuntu/<hostname>/. Place the kernel and initrd at data/pxe/ubuntu/vmlinuz and data/pxe/ubuntu/initrd. The job does not download them. This boot does not install OpenStack or Kubernetes, and it does not require the commission wipe. The node name has to be a hostname, and the node needs a PXE MAC.

A server the console has not selected downloads a short script and then returns to its own disk. It is left alone.

For a server you did select:

  1. The console writes the wipe program for that MAC address and asks the management port to network-boot the server once.
  2. The wipe program clears the disks and posts one report. Sending the same report again does not wipe the disks again.
  3. The console switches that server to Talos and network-boots it once.
  4. Talos comes up in maintenance. Maintenance means Talos is running and waiting for its configuration. The job then continues with the Talos Linux steps in this manual.

Those four steps are the Talos path. Install Ubuntu is a separate next boot. It writes that machine's seed and can power the machine from the network. It does not run the wipe, and it does not continue into OpenStack.

Kubespray does not use that wipe. The machines already have an operating system, often from the Ubuntu next boot. Set the provider to kubespray and run the install. Kubernetes and OpenStack after that are the same.

An ISO image cannot be the first boot of a reinstall. An ISO does not wipe the disks, so the console rejects that choice on this path. That image is for the server you are installing. It is not the console appliance CD.

Where the deploy host cannot be L2 with the servers, the console agent does this job. Install it on a computer that is L2 with those servers. DHCP and the boot files for that site run on the agent. The agent connects out to the console, and you still start the job from the console. The agent install is in the console install guide linked below.

Warning

The wipe report has to reach the console. If some other machine hands out the boot file, and the report never arrives, the server stays on the wipe image. The console is what accepts the report and switches that server over to Talos.

Tip

Stop the job after the wipe if you want to inspect the disks before Talos is served. Stop after Talos if you want the server left in maintenance, and you do not want the job to continue into inventory and OpenStack.

my.genestack.dev

https://my.genestack.dev is the account page for a console you already installed. On that page you manage the account, connect the Mac, iPhone, iPad, and Apple Watch apps to the console, and ask for support. The apps sign in on that page. The page then opens your console.

The environment, the job log, and the management-port passwords stay in the console database on the deploy host, in /opt/genestack-console. People on the deploy host can sign in with a local user, an API key, or their company's login, and never open the account page.

How the sign-in is configured is written in Connect a console to my.genestack.dev.

What the code is doing

The installed program is one Linux binary and two processes. The first serves this page, the API, and, when the deploy host is L2 with the servers, DHCP and the boot file. The second is the worker. A click records a job. The worker runs it, so a long install is not stuck inside the browser request.

The source is the Python package app in the console repository.

Path What it is
app/main.py Starts the API process and attaches every route.
app/routers/ One file per area of the API. A route checks who you are, then reads or queues a job.
app/services/ The work those routes and jobs call: the settings document, the pipeline, DHCP, the management port.
app/modules/ The jobs. One folder per area. One Python file per operation. The folder's __init__.py lists those files and does not call them.
app/services/job_runner.py Prepares the environment, then calls the one function that matches the job.
app/worker/runner.py Claims queued jobs. Two workers cannot take the same row.
app/models.py, app/db.py The tables, and the code that opens them. There is no separate migration tool.
app/static/, app/templates/ui.html The web page. The shell is the HTML file. Each screen is a JavaScript file.
config.yaml Bind address, secret key, API keys, the database, and any extra module folders.
agent/ The program you install at a site this machine cannot reach at L2. It connects out.

The next pages walk through that split.

Page What it explains
The program The two processes, the database, who can sign in, the collector, and the agent.
How a job runs From the click, to the worker, to /opt/genestack, including the settings document and DHCP.
Jobs Every operation that ships, the pipeline stages, and how to add one.
The HTTP API How a call is authenticated, and which file serves which route.
The web page The sidebar, one environment, and what each screen file draws.

Adding an operation

An operation is one job the console knows how to run: power a server, push config, deploy. Each one is a Python file. The files for one area sit in a folder. The folder's __init__.py is the class that lists those files, in order. It does not call them.

The built-in folders live under app/modules/. Bare metal is app/modules/baremetal/. To add your own, make a folder with the same shape and put its path in modules.paths in config.yaml. The console loads it on startup. The full list, the pipeline, and the steps are on Jobs. The same layout, with a worked example, is Modules.

The rest of the manual

The first rows are the rest of this chapter. The links after them open the console repository. The binary named on this page is v2026.10.07.21. The source on main can be ahead of that tag. The source pin in this repository stays v2026.10.03.

You need Read
The two processes and the database The program
How a click becomes a command How a job runs
Every operation, and how to add one Jobs
The HTTP routes The HTTP API
The screens The web page
Install on Linux, a Mac, or Windows Install
Boot the console as an appliance The appliance
A lab with one local virtual machine Install AIO
The longer design notes Architecture
The account page and the Apple apps Connect a console to my.genestack.dev
Path-by-path HTTP reference API reference, and /swagger on a running console
How a release is cut Releasing

Note

This site is built from the main branch of Genestack. The console program is released on its own tags. If a step on this page and the v2026.10.07.21 binary disagree, follow the console repository at that tag.