docs: create a flow diagram of the Ignition services#2195
docs: create a flow diagram of the Ignition services#2195cadejacobson wants to merge 10 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.
docs/ignition-flow.md
Outdated
| D1a --> D2 | ||
| D1b --> D2 | ||
| D2 --> D3 |
There was a problem hiding this comment.
This part of the flow could be misleading. Requesting cloud-specific configs (D2) and opening a config device like /dev/sr0 (D3) are typically alternative actions that depend on the detected platform, rather than sequential steps. The current diagram with D2 --> D3 suggests one follows the other. It would be more accurate to represent them as alternative paths.
docs/ignition-flow.md
Outdated
| N4["systemd-networkd.service - Network Configuration"] | ||
| N5["network.target reached"] | ||
| N6["Get DHCP address"] | ||
| N1 --> N2 --> N3 --> N4 --> N5 --> N6 |
There was a problem hiding this comment.
The order of operations in the network stack appears to be incorrect. The network.target (N5) is reached only after the network is fully configured, which includes acquiring an IP address via DHCP (N6). Therefore, N6 should come before N5 in the sequence.
| N1 --> N2 --> N3 --> N4 --> N5 --> N6 | |
| N1 --> N2 --> N3 --> N4 --> N6 --> N5 |
docs/ignition-flow.md
Outdated
| classDef service fill:#42a5f5,stroke:#1565c0,stroke-width:2px,color:#000 | ||
| classDef target fill:#ffa726,stroke:#e65100,stroke-width:2px,color:#000 | ||
|
|
||
| class A,B,C,D,E,F,H,I,J,K,N4 service |
There was a problem hiding this comment.
The node N1 represents systemd-networkd.service but it's not styled as a service. For consistency, it should be included in the service class definition.
| class A,B,C,D,E,F,H,I,J,K,N4 service | |
| class A,B,C,D,E,F,H,I,J,K,N1,N4 service |
docs/ignition-flow.md
Outdated
| N3["Link up"] | ||
| N4["systemd-networkd.service - Network Configuration"] | ||
| N5["network.target reached"] | ||
| N6["Get DHCP address"] |
There was a problem hiding this comment.
if ignition-fetch.service is after network.target, how do we know if the DHCP succeeded?
There was a problem hiding this comment.
When running through the services and targets (at least on Flatcar), the actual queries to the cloud platforms may be started before the DHCP request has been completed. For example, here are some of the journalctl logs from a recent machine:
We see:
- The link come up
- The system reach
network.target Ignition-fetch.servicebegin (which is also corroborated in the systemd service file found below:)- Calls to the IMDS user-data begin and fail (presumably because DHCP has not been completed)
- The DCHPv4 address 10.0.0.4 return
- IMDS user-data is successfully queried (attempt 7)
To answer your question, ignition-fetch.service does not necessarily know that DHCP has succeeded, but it relies on DHCP to do so before the calls to IMDS exhaust the retries.
| get_dhcp_address --> online_request_cloud_configs | ||
|
|
||
| %% --- Disk & Mount Services --- | ||
| FETCH_ONLINE --> kargs_service["ignition-kargs.service"] |
There was a problem hiding this comment.
I think we could mention that a reboot might occur here (and we restart the flow from the beginning) - if a kernel argument is added / removed from the kernel command line.
There was a problem hiding this comment.
I updated the flowchart to include the reboot section!
| afterburn_hostname_service -.-> files_service | ||
| files_service --> 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.
Ignition has a ignition-delete-config.service that takes care of deleting the user-data configuration from the cloud provider (only supported for VMWare at this moment, but I'd started a discussion a while ago for Azure to investigate on a similar feature and/or protect user-data access)
There was a problem hiding this comment.
This is great to know about! I had not encountered this as I am primarily running on Azure.
From what I am reading, ignition-delete-config.service seems to be a bit disconnected from the flow of the rest of Ignition. It seems to operate before sysinit.target, but I do not find any other references to sysinit.target in the codebase. Since these two are disjointed, do you have any recommendation on how to include it in the flowchart? I could put it in its own subgraph, but am not sure where to link it. Thanks!
|
Ah, I am noticing that GitHub's rendering is rather different than the default VSCode preview: Allow me some time to fix this. 😁 |
| subgraph NETWORK ["Network Stack"] | ||
| direction TB | ||
| networkd_service["systemd-networkd.service"] | ||
| find_primary_nic["Find primary NIC"] |
There was a problem hiding this comment.
networkd doesn't have a concept of "primary NIC", it's DHCPing on all NICs
|
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 |
3 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.