docs: create a flow diagram of the Ignition services#2195
docs: create a flow diagram of the Ignition services#2195cadejacobson wants to merge 28 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.
|
|
||
| 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.
| 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.
|
@cadejacobson I saw you updated the branch, did you have a chance to see my comments?, if so please feel free to push back or comment on them. |
Thank you for your comments @prestist! I had fixed a portion of the requests and planned to come back in the next few days for the rest but got caught in other tasks so it slipped my mind. I have now addressed all but the last comment, that one being the comment here. As we were learning how Ignition ran, we spent much of our time reading the logs from the tool's output at each stage. We took many different sets of configurations and used that to build the branching that made most of the flowchart. Part of what led to me stepping back from pushing corrections was me attempting to find a better way to represent these stages to make them less misleading. I was not able to come up with an effective alternative solution to this point, as the items here are pulled from the logs during a given stage. This may include the engine's logs, but from an outside perspective, these all appear to be in the same "stage", as ignition was invoked with the As a proof of concept, I did remove much of the engine logic from the subgraph for |
Thank you for working on this, I think for the first pass this is amazing. We can absolutely circle back on updating the stages in later iterations. Let me noodle it a bit an see if I can figure out something for it to help represent it, if not we can just merge this as is and have a followup PR later. Thank you again @cadejacobson!!! |
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.