Skip to Content

Host types

A host has a type, from a machine Rookery only logs in to up to a whole workstation. What each type allows, and how to add a host by its address.

Rookery does not have to set a machine up to work with it. A host is anything Rookery reaches and logs in to, and its type says what Rookery does with it:

TypeWhat is on the hostWhat Rookery does with it
sshNothing of RookeryLogs in over SSH for a terminal, commands and the inventory
managedrookeryd and boxAlso sessions, the channel, files, actions and secrets
nodeA server's part of the profile: rookeryd, a firewall and plugin featuresAlso applying, roll-outs and plugin features, such as the engines that host machines (Nodes)
workstationThe whole profileAlso the desktop, the accounts and what plugins install, such as agents, cloud seeds and the USB installer

The type is part of the host's profile, as type. A profile that doesn't say is a workstation. What the host has right now is asked of it. The overview and the Hosts tab show both when they differ, such as for a controller installed by hand.

Capabilities

Capabilitysshmanagednodeworkstation
Terminal and commands over SSH, inventoryyesyesyesyes
Install the controller aloneyesupdate itby applyingby applying
Sessions, channel, files, units, logs, processesnoyesyesyes
The actions status, update and rebootnoyesyesyes
Secrets and registry logins sent to the hostnoyesyesyes
Plugin features, their actions and servicesnonoyesyes
Apply and roll-outnonoyesyes
Cloud seed and USB installernononoyes
Desktop and access linksnononoyes

The screens, the commands and the API all use the same check in Rookery. An action the type rules out is still listed, as unavailable, with the reason and what changes the type. Asked for anyway, the server refuses it with 501 not_available. A roll-out leaves hosts that aren't workstations and says how many it left.

Adding a machine that exists

A machine you can already log in to is added by its address, and Rookery leaves it as it is.

rookery host add forge 192.0.2.4 --user ops
OptionDefaultFor
--user USERYour SSH configurationThe SSH user
--port PORTYour SSH configurationThe SSH port
--auth AUTHrookeryHow Rookery logs in: rookery, key:NAME, password or ssh
--type TYPEsshThe type it is meant to be
--no-contactSave it without logging in

After saving the host, Rookery logs in the way first contact does. It tries its own key, and if the machine refuses it, it asks for a password or a private key that logs in once to install the key. It records the host's SSH host key and prints its fingerprint. When your ~/.ssh/known_hosts knows the address and the server runs on your machine, Rookery takes the host key from there. With a Rookery server elsewhere, the host is saved on the server, which logs in with its own keys and records the key the host shows it. Host keys has more.

Then Rookery asks the host what it is. A machine that Rookery set up before has a controller that says its type, and Rookery offers to change the profile here when the host has more than --type gave. Without a terminal it prints the command.

A workstation or a node keeps its profile on the host as well. Rookery offers to adopt it from there:

rookery host adopt forge

A host with Rookery's controller alone has nothing more to keep, and Rookery offers to save its type:

rookery host set forge type=managed

rookery host set HOST type=TYPE only changes the profile here. A host's page says the same when its controller reports more than its profile says. Rookery refuses to install the controller alone on a host that is a workstation or a node, whatever its profile here says. It asks the host's controller first, and the playbook checks the host's own record and the profile it keeps.

In the terminal UI, create a host on the home screen and choose Existing host, SSH only on the Install tab. The address and the login are all the set-up asks for, and Run saves the host. For a managed host, choose Existing host over SSH and set Type to managed. Run then installs the controller.

Over the API, hosts.save takes a profile with only the type and access:

curl --unix-socket "$XDG_RUNTIME_DIR/rookery/serve.sock" -X PUT \
  -d '{"type": "ssh", "access": {"address": "192.0.2.4", "user": "ops"}}' \
  http://rookery/v1/hosts/forge/profile

The host's trust-key action then installs the server's key, with a password used once in its arguments (Actions).

A server for machines

A server that hosts Incus or Docker machines is a node. Rookery applies it like a workstation, without the desktop and the accounts, and its features install the engines and register their provisioners. A server that the recipes set up before is taken in the same way.

Installing the controller

rookery run forge install-controller

The controller is rookeryd and box with the files they read, from the same part of the role that a full apply runs. Nothing else of a workstation is installed: no accounts, desktop, agents or plugins. The SSH user is the account sessions run as, and its home is where the file calls may go. The host's type becomes managed, and its actions are status, update, reboot and secrets.

The same is the host's action Install the controller on its overview, and over the API as install-controller. On a managed host it's called Update the controller: run it after updating Rookery, as Rookery's own version is all such a host is compared with. A workstation's controller comes with applying its configuration, so the action is not offered there.

Rookery also refuses it on a host that is a workstation or a node whatever its profile here says. It asks the host's controller first. The role checks again on the host before it changes anything. It stops when the host's record says workstation or node. It also stops when rookeryd there serves an account other than the SSH user. Installing the controller alone on such a host would take the workstation's controller apart. The overview and rookery action list say when a host is more than its profile, and how to adopt it.

A host without systemd

On a host with systemd the controller is a service that starts at boot. Without systemd, as in most containers, the controller is installed but nothing on the host starts it. Rookery says so and waits a minute for it to answer, and the install fails when it doesn't. Something on the host then has to run /usr/local/bin/rookeryd, as the init of a container can.

Changing the type

FromToHow
sshmanagedInstall the controller
ssh or managednoderookery host set HOST type=node, list its features, and apply (Nodes)
ssh, managed or nodeworkstationSet Type to workstation in the set-up, fill in the rest of the tabs, and apply

Rookery never takes a host back to a type with less, and never removes what it installed. A node is not applied over a workstation that Rookery set up, as nothing would look after its desktop, agent and accounts any more. Making a profile a node's takes the fields of the agent and the operator out of it.

Edit on GitHub

Last updated on

On this page