Host State Machine?

Hi there,

I’m writing some design documentation, and thought I would document the series of states that a host goes through (including some of the post-OS-install states we have).

Can someone point me to any documentation? Or help me create a rough picture? I was thinking the machine might look something like:

digraph G {
  "New" -> "Discovered" [label="Run Discovery OS"];
  "Discovered" -> "Ungrouped" [label="discovery rules\n(failure)"];
  "Discovered" -> "Grouped" [label="discovery rules\n(success)"];
  "Grouped" -> "Deployed" [label="deploy OS\n(success)", weight=2];
  "Grouped" -> "Deploy Failure" [label="deploy OS\n(failure)", weight=2];
  "Deployed" -> "Grouped" [label="change group\nto deploy\ndifferent OS"];

You can paste that into the online Graphviz tool to see what it would look like.


There is no such doc and you are more than welcome to add this to the plugin doc:

I am not sure about Grouped/Ungrouped. When rule fails, host stays in Discovered state.

There are basically three main states (STI model classes):

  • Discovered host - this is obvious, just a host with name, IP/MAC, subnet associated and list of facts
  • Unmanaged host - host with name, facts and puppet data associated (created when a host checks in via puppet master)
  • Managed host - host created explicitly via UI/CLI/API or via discovery

You can transfer between managed and unmanaged hosts, there is a UI/API/CLI command.

Thanks for the reply.

In the fully automated flow, hosts never are unmanaged right? Or are they unmanaged to start, and only become managed after the OS is installed? I guess I’m asking if the three states you listed are orthogonal, and how host transitions happen between them (beyond the manual action you mentioned).

Perhaps “group” and “is managed” should become state vars inside each of the primary states in the graph. e.g. Maybe a host can go from “Deployed (managed=true)” --> “Deployed (managed=false)” after operator UI/CLI/API action?

Is there a “building” state during the OS installation? I’m okay with introducing conceptual or implicit states to help explain the process.

Unmanaged state is usually only used by users who use Foreman just as UI for Puppet. So yes, it kinda stays aside in traditional discovery workflow.

Group is weird term, maybe you think that you have “managed host with associated hosgroup”. Beware, there can also be unmanaged hosts with hostgroups.

There is a state (boolean) flag called “build” and when true, host is in build mode. This mode expires after 6 hours in case OS installation went bad (configurable). This is the only state when client (OS installer) can get to provisioning template.

Hosts also have special “status framework”. You see this on the left page in host detail page. It reports various statuses across features. Things like OS installation (pending, failed, expired, complete), configuration (pending, out of sync, pending, alerts, active, no changes) and various plugins add more. There is an overall status which can be: OK, WARN, ERROR and according to this main icon is rendered: green, yellow, red.

When you have your doc complete, can you submit the main text into our docs please? We need this.

I’m happy to. The problem is that I’m a total noob, so I want to submit a pull request that has a chance of being correct.

How does this look? My text would mention that this is just the zero-touch flow with the discovery plugin, and doesn’t talk about unmanaged nodes.

I rendered an image for you, if you don’t want to futz with WebGraphviz:

digraph G {
  graph [fontname=helvetica];
  node [fontname=helvetica, style=filled, fontcolor=white];
  edge [fontname=helvetica, style="setlinewidth(2)"];

  "New" [fillcolor=darkgreen];
  "Discovered" [fillcolor=darkgreen];
  "Assigned to\nHost Group" [fillcolor=darkgreen];
  "OS Provisioned" [fillcolor=darkgreen];

  "New" -> "Discovered" [label=" Run Discovery OS ", weight=10, distance=20];
  "Discovered" -> "Discovered" [label=" Discovery Rules \nFailure", weight=10];
  "Discovered" -> "Assigned to\nHost Group" [label=" Discovery Rules \nSuccess", weight=10];
  "Assigned to\nHost Group" -> "Assigned to\nHost Group" [label="Timeout / \n Build Failure "];
  "Assigned to\nHost Group" -> "OS Provisioned" [label=" Build Success ", weight=10];
  "OS Provisioned" -> "Assigned to\nHost Group" [label=" Change group \nto deploy\ndifferent OS"];


Edit: After talking with my team, they said that “building” isn’t really a distinct state. e.g. Once a host gets assigned a host group with a configured OS, the installation begins immediately. So I updated the state graph to make the build process an edge instead of “building” being a distinct state.

1 Like

This is correct, except you can also have hosts without hostgroup assigned, so the naming could be improved. We call them simply (managed) hosts.