Skip to Content

Testing against a simulated server

Run a Rookery server with hosts and provisioners that reach no machine, so an application's tests can use the real API in CI.

rookery serve --simulate runs the real server on a scratch store. Its routes, roles, tokens, jobs, events and portal are the ones a real server has. The hosts, the provisioners and the tailnet are simulated, so nothing connects to another machine. An application's tests go through a host's whole life in seconds, with no SSH, Ansible or cloud account.

rookery serve --simulate --listen 127.0.0.1:7777

It prints where its state is, where it listens, its token and a setup key:

Simulated rookery server: its hosts and provisioners reach no machine. State in /tmp/rookery-simulated-x1Yz, removed when it ends
Listening on /tmp/rookery-simulated-x1Yz/run/rookery/serve.sock
Listening on http://127.0.0.1:7777 for the token (token in /tmp/rookery-simulated-x1Yz/data/rookery/serve.token)
Token: 3f9c…
Setup key: 81ad…

Send the token as Authorization: Bearer TOKEN, as with any Rookery server. The token and the setup key belong to this throw-away server alone, so it prints them. rookery login http://127.0.0.1:7777 with the setup key works too, and rookery ui then shows simulated in its header.

Telling it apart

Nobody should take a simulated server for a real one:

WhereWhat it says
Every HTTP answer, refusals includedThe header rookery-simulated: 1
version of the server"simulated": true
version of each host's controller"simulated": true
The output of an applyapplying, simulated: nothing is installed
The screenssimulated beside the name in the header

Options

OptionEnvironmentMeans
--simulateROOKERY_SIMULATE=1Run a simulated server
--listen ADDRESS:PORTListen over HTTP too. Any address is allowed without --expose
--seed FILEROOKERY_SIMULATE_SEED holds the JSON itselfThe world it starts with. See The seed
--delay SECONDSROOKERY_SIMULATE_DELAYHow long one step takes. 2 by default, 0 for none, and fractions such as 0.1 work
--data DIRKeep the state in DIR and leave it there. DIR is empty or holds an earlier simulation
--keepLeave the scratch directory when the server ends

The state is a new directory under TMPDIR. The server removes it when it ends on Ctrl+C or SIGTERM. It never reads or writes your own configuration. --data refuses Rookery's own configuration and data directories, any directory that holds them or lies in them, and a directory with files of something else in it. The server's socket is in its scratch directory, so your own rookery commands keep using your own server.

The seed

A seed is a JSON file that a test starts from. Every field can be left out.

seed.json
{
  "token": "made-up-token-for-the-tests-0123456789",
  "hosts": {
    "studio": {"applied": true},
    "forge": {"profile": {"type": "node", "access": {"address": "192.0.2.7", "user": "ops"}}}
  },
  "provisioners": {"sim": {"type": "sim/cloud", "settings": {"region": "sim-2"}}},
  "secrets": {"api_token": "made-up"}
}
FieldHolds
tokenThe token for HTTP, at least 32 characters. Without it the server makes one
hostsSaved hosts by name. profile is the host's profile as hosts.save takes it, and applied: true makes the host start applied at this Rookery's version
provisionersRegistered provisioners by name, as provisioners.save takes them. Without any, sim is registered as sim/cloud
secretsSecrets by name

A host without an address gets one of 192.0.2.0/24, and one without access.user gets ops. A workstation without builder gets an empty one.

What is real and what is simulated

PartReal or simulated
Routes, the portal, roles, tokens, setup keysReal
The store, secrets, registries, settings, the key-value store, the inboxReal, on the scratch store
Jobs and their output, the events streamReal
A host's actions, sessions and filesReal rookeryd in single-user mode, one per host in the scratch directory. Its commands run through a shell of its own
A host's processesOnly what its rookeryd started
A host's portsRefused, as they would be the ports of the machine the server runs on
A host's units, logs and powerNot there, as on any rookeryd in single-user mode
Applying a host, and installing its controllerSimulated. Progress lines come over a few steps, then the records a real apply leaves
A host before its first applyHas no controller, as a fresh machine has none
ProvisionersThe built-in sim/cloud. Other plugins' provisioners run as they are
The tailnetSimulated. Its keys are made up and join nothing
Rolling out, rotating keys and adoptingNot simulated, and their actions say they are unavailable
First contact over SSH, seeds and installersNot simulated, and unavailable too

A host's shell

A session or an action on a simulated host doesn't run programs of the machine. Its shell knows these commands and answers any other with exit code 127:

CommandDoes
echo, hostname, whoamiWhat they do on Linux, as the host NAME and the user agent
id, uname, pwd, dateThe same
ls, catRead the host's home in the scratch directory. A path outside it is refused
sleep N, true, false, exit NAs in a shell
status, smoke, update, reboot, secretsThe host's actions, with made-up output
failFails with exit code 3, to test how failures are shown
helpLists them

; separates commands in one line. A terminal session gets a prompt and runs each line typed.

The provisioner sim/cloud

It makes nothing, and keeps what it made in the scratch directory.

KindVerbsAnswers
machinecreate, start, stop, logs and destroyAn address of 192.0.2.0/24. Rookery then applies the host, as with a provisioner of the apply set-up. The host's controller does not answer when the machine is stopped
servicecreate, start, stop, change, logs, exec and destroyAn endpoint http on port 80 of an address of 192.0.2.0/24. exec runs echo, hostname, true and false. Its action restart restarts it

The provisioner lists what it made, and its page has a collection images of three images. Its actions images and inspect read them. Endpoints of 192.0.2.0/24 lead nowhere, and resources.connect refuses every endpoint of a simulated server.

Timings

Each step takes the delay, two seconds by default:

WhatSteps
Create a machine or a service2, and a machine's apply after them
Apply a host1.5 for a node or a managed host, 2.5 for a workstation
Start, stop, change, remove, restart1

The server looks at a simulated host again after one step, where a real server waits up to ten seconds. A test that polls hosts.get sees a host stop or start within a step. With --delay 0 everything is as fast as the store, and the order of jobs and events stays the same.

Running it in continuous integration

GitHub Actions starts a service container before the job's steps and cannot change its command. The environment turns the published image into a simulated server instead:

.github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      rookery:
        image: ghcr.io/aiviarium/rookery:VERSION
        env:
          ROOKERY_SIMULATE: "1"
          ROOKERY_SIMULATE_DELAY: "0.2"
          ROOKERY_SIMULATE_SEED: >-
            {"token": "made-up-token-for-the-tests-0123456789",
             "hosts": {"studio": {"applied": true}}}
        ports:
          - 7777:7777
        options: >-
          --health-cmd "curl -fsS http://127.0.0.1:7777/"
          --health-interval 2s --health-retries 15
    steps:
      - uses: actions/checkout@v4
      - run: npm test
        env:
          ROOKERY_URL: http://127.0.0.1:7777
          ROOKERY_TOKEN: made-up-token-for-the-tests-0123456789

The token is made up for the tests and opens nothing else, so it can stay in the workflow. Elsewhere, start the image with its command:

docker run --rm -p 7777:7777 ghcr.io/aiviarium/rookery:VERSION serve --simulate --listen 0.0.0.0:7777

A test on a machine with Rookery installed starts rookery serve --simulate itself and reads the token from its output. SIGTERM ends it. Rookery's own test of this, crates/rookery/tests/simulate.rs, does that and goes through a host's whole life.

Edit on GitHub

Last updated on

On this page