docs: create a flow diagram of the Ignition services#2195
docs: create a flow diagram of the Ignition services#2195cadejacobson wants to merge 25 commits intocoreos:mainfrom
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This is a great initiative to visualize the Ignition boot flow, which will be very helpful for new contributors. The diagram is well-structured. I've left a few comments with suggestions to improve the accuracy of the flow in the 'Network Stack' and 'Ignition Fetch' sections, and a minor styling suggestion for consistency. Overall, this is a valuable addition to the documentation.
|
Ah, I am noticing that GitHub's rendering is rather different than the default VSCode preview: Allow me some time to fix this. 😁 |
|
in the diagram there's this concept of merging discussed, but what's unclear on both is what artifacts are for each stage. When fetch-offline checks /usr/lib/ignition/, what happens if there is some config there? Does ignition.json get written out and ignition-fetch.service gets skipped? We should clarify the outputs and add the conditional for fetch.service on /run/ignition.json |
This is great feedback! Thank you. I updated the flowchart to include more information about when certain configs are present. To the best of my knowledge, I do not see fetch-offline or fetch acting on the configs it notices in the |
| subgraph FETCH_ONLINE ["Ignition Fetch"] | ||
| direction TB | ||
| online_detect_platform["Detect platform"] | ||
| online_check_configs["Check configs at:"] |
There was a problem hiding this comment.
these three nodes can all be merged, but also I don't think it actually does anything? Isn't ignition-fetch just wasting cycles here and can be optimized out? Does it do anything from reading usr/lib/ignition/base.d, usr/lib/ignition/base.platform.d configs?
There was a problem hiding this comment.
I do not believe Ignition-fetch uses anything it finds in these directories but I think that makes those operations worthy to include here in the flowchart. As something that has potential to be optimized out and improve performance, I think it is worth leaving in until a maintainer decides those extra cycles were by design, and we can eliminate them from their own section in the documentation.
docs/ignition-flow.md
Outdated
|
|
||
| FILES --> quench_service["ignition-quench.service"] | ||
| quench_service --> initrd_setup_root["initrd-setup-root-after-ignition.service"] | ||
| quench_service --> complete_target["ignition-complete.target"] |
There was a problem hiding this comment.
is ignition-quench still a thing? what controls the first boot aspect of ignition?
There was a problem hiding this comment.
Ignition-quench was one of the service files that Flatcar added to their version of ignition. When the initial flowchart was made, I used Flatcar but have since migrated to use CoreOS. I also removed that initrd-setup-root-after-ignition service for the same reason.
The first boot aspect is controlled by ignition.firstboot, and more information about that can be read here: https://github.com/coreos/ignition/blob/main/grub2/05_ignition.cfg
There was a problem hiding this comment.
iirc I think the latest flatcar removes it because I didn't see it in their latest main branch
There was a problem hiding this comment.
It does seem to exist in the flatcar-master branch of the Flatcar bootengine still, but it has been moved to the 50-59 range instead of the original 30 range. That is linked here: https://github.com/flatcar/bootengine/blob/7d9895ce55617b18a78294975197975ac17b5bc3/dracut/53ignition/ignition-quench.service
prestist
left a comment
prestist
left a comment
There was a problem hiding this comment.
This is going to be great to have, thank you for working on this! just a few changes needed.
|
|
||
| %% --- Firstboot Path --- | ||
| firstboot_check -->|Yes| complete_gate["ignition-complete.target activated"] | ||
| complete_gate --> setup_pre["ignition-setup-pre.service"] |
There was a problem hiding this comment.
Technically ignition-setup-pre.service and ignition-setup.service is currently distro specific. It would be good to annotate that in some way.
| network_target["network.target reached"] | ||
| networkd_service --> network_config --> network_target | ||
| end | ||
| setup --> NETWORK |
There was a problem hiding this comment.
Typically the distro is responsible for sequencing network bring-up between ignition-fetch-offline.service and ignition-fetch.service. The ignition-fetch-offline.service unit explicitly states that. It would be good to annotate this as well.
|
|
||
| FILES --> complete_target["ignition-complete.target reached"] | ||
|
|
||
| complete_target --> delete_config["ignition-delete-config.service"] |
There was a problem hiding this comment.
Hmm, I think this runs on the real root, not in the initramfs?
And its under a condition of it being firstboot.
| %% --- Network Stack --- | ||
| subgraph NETWORK ["Network Stack"] | ||
| direction TB | ||
| networkd_service["systemd-networkd.service"] |
There was a problem hiding this comment.
Im pretty sure Ignition's unit files only reference network.target, not systemd-networkd.service. The network manager in use is entirely a distro choice
| setup --> fetch_offline["ignition-fetch-offline.service"] | ||
|
|
||
| %% --- Fetch Offline Details --- | ||
| subgraph FETCH_OFFLINE ["Ignition Fetch Offline"] |
There was a problem hiding this comment.
I think this is a really good attempt but there are a few things that are a little misleading here.
In reality, this is done by the engine (internal/exec/engine.go), not by the individual stages. For example, fetch-offline's Run() method only checks whether the already-acquired config requires networking and creates the neednet flag if so.
The way these stages are currently represented it looks like a lot of extra work. It gets the point across but is not correct from a code perspective. The reality is that each of Fetch_offline, fetch_online, Files, all have the results of this work from the engine.go.
- fetch_offline run https://github.com/coreos/ignition/blob/main/internal/exec/stages/fetch_offline/fetch-offline.go#L71-L78
- fetch run https://github.com/coreos/ignition/blob/main/internal/exec/stages/fetch/fetch.go#L66-L69
- files run https://github.com/coreos/ignition/blob/main/internal/exec/stages/files/files.go#L74-L76
Also the detect platform is not something any of this code does, its taking the platforom id which is an external input passed from --platfrom on the clia from the env var. It feels a little missleading in its current representation im not sure what the correct way to express that would be tho.
4 participants
While looking through the Ignition booting documentation, I was attempting to piece together how each service interacts with each other and ended up creating a flowchart of the ordering of some of the services. I figured this visual diagram could be useful to other new contributors to the project, and am happy to expand on, or correct, any relationship here as needed.