Skip to content

Add bootstrapping guide to the documentation - #161

Open
damyan wants to merge 3 commits into
mainfrom
enh/add-bootstrap-guide
Open

damyan wants to merge 3 commits into
mainfrom
enh/add-bootstrap-guide

Conversation

@damyan

@damyan damyan commented Nov 19, 2026

Copy link
Copy Markdown
Member

Note: ansible roles coming as a separate delivery

Signed-off-by: Damyan Yordanov <damyan.yordanov@sap.com>
@damyan
damyan requested a review from afritzler November 19, 2026 16:10
@damyan
damyan requested a review from a team as a code owner November 19, 2026 16:10
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 1126ce0b-05cf-45e9-b22a-34184f30fdbc
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@johamster johamster left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, left a couple of minor comments.

nav: [
{text: 'Home', link: '/'},
{text: 'Overview', link: '/overview/'},
{text: 'Tutorials',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with "Tutorials" but would suggest "Getting Started" as an alternative.

I do have a PR open to add some stubs for other chapters, i.e., canary blueprint and lights-out to running cluster guide (#160), currently in the "Overview" section. If we used "Getting Started", both would fit here, in my opinion.

With "Overview" only the light-out guide fits.

Opinions?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just saw that the IaaS page already as a "Getting Started" section. That collides with my suggestion.

We could either

  • accept that we have two "Getting Started"
  • don't rename the section here
  • Move/rename the "Getting Started" from IaaS.

Opinions?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I personally prefer tutorials, obviously, but I can go with all three alternatives. @afritzler Do you have opinion on that one?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume you took the guide verbatim from the infra-scripts guide? It mentions "role(s)" which currently are not publicly available, right?

What about adding a short section in the very beginning that those roles are about to be published?

> [!IMPORTANT]
> The ansible roles and Ignition generator (ignition/generate-management-ignition.sh) referenced in this
> guide will be published soon. Until then, all steps can be executed manually from the manifests and
> commands shown here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, adding it. Dropped the ignition-generator mention though: the delivered roles ship the Ignition inlined into the KubeadmControlPlane template (the generator script stays internal), so only the ansible roles are the pending-publication part.

Added as a VitePress ::: info admonition (GitHub's > [!IMPORTANT] blocks don't render on the docs site).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe rename the file to a more speaking name, e.g., mgmt-cluster-bootstrap(-guide).md? Other bootstrapping tutorials might follow making it harder to differentiate.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to mgmt-cluster-bootstrap.md and updated the nav link; the label is now "Management Cluster" so later bootstrapping tutorials can sit alongside it.

Comment thread docs/tutorials/bootstrap.md Outdated

### 3.3 Ignition userdata

The control-plane Ignition config comes from `./ignition/` (the repo's source of truth for node userdata), generated fresh by `ignition/generate-management-ignition.sh` during the capi-cluster role and attached to the `KubeadmControlPlane`'s `containerLinuxConfig.additionalConfig` as a file. Highlights of what the generated config does:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw, here for example we reference the "repo". That is probably confusing to externals.

I wouldn't try to fix this now. Publish it and we can improve on it afterwards!

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually fixed it here - the "repo" reference is gone. The generating scripts aren't part of the published delivery (the Ignition ships inlined in the manifests), so I reworded this section to describe the inlined
config instead of pointing at an internal source tree.

Comment thread docs/tutorials/bootstrap.md Outdated

- **Approve kubelet serving CSRs**: Because we set `serverTLSBootstrap: true`, the kubelet requests its serving certificate via CSR. Approve the pending CSRs signed by `kubernetes.io/kubelet-serving`.
- **Patch the node's `podCIDRs`**: kubeadm does not assign one because the metal stack runs with `--allocate-node-cidrs=false` (pod CIDRs are assigned by the cloud-controller-manager on CAPI clusters). Patch the node manually with the node's `/112` pod CIDR - a sub-range of its `/64` host prefix, offset to `::1:0` so it does not overlap the node's own `::1` loopback (see [Prerequisites](#prerequisites-before-running-any-phase)), e.g. `2001:db8:1111:1::1:0/112` for mgmt-1.
- **Prepend the cluster DNS to `/etc/resolv.conf`**: Add the CoreDNS *external* LoadBalancer address (`SVC_CIDR::1:a`) as the first nameserver on the inband machines so kubectl and curl can resolve in-cluster service names like `metaldata.ironcore.dev` and `boot.onmetal.de` that CoreDNS rewrites internally. In Phase 2 we deploy CoreDNS as a `LoadBalancer` service; the load balancer assigns each `SVC_CIDR::XYZ` cluster IP a publicly routable counterpart at `SVC_CIDR::1:XYZ`. In this case: cluster IP `SVC_CIDR::a` maps to external IP `SVC_CIDR::1:a`. The inband machines use the external address because they do not sit on the cluster's service network. We use [metal-load-balancer-controller](https://github.com/ironcore-dev/metal-load-balancer-controller) with FRR to announce these addresses via BGP; alternatively, use a publicly available load balancer like MetalLB.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: At all other places, it is metaldata.example.com except here. Did we miss that in the original document?

Suggested change
- **Prepend the cluster DNS to `/etc/resolv.conf`**: Add the CoreDNS *external* LoadBalancer address (`SVC_CIDR::1:a`) as the first nameserver on the inband machines so kubectl and curl can resolve in-cluster service names like `metaldata.ironcore.dev` and `boot.onmetal.de` that CoreDNS rewrites internally. In Phase 2 we deploy CoreDNS as a `LoadBalancer` service; the load balancer assigns each `SVC_CIDR::XYZ` cluster IP a publicly routable counterpart at `SVC_CIDR::1:XYZ`. In this case: cluster IP `SVC_CIDR::a` maps to external IP `SVC_CIDR::1:a`. The inband machines use the external address because they do not sit on the cluster's service network. We use [metal-load-balancer-controller](https://github.com/ironcore-dev/metal-load-balancer-controller) with FRR to announce these addresses via BGP; alternatively, use a publicly available load balancer like MetalLB.
- **Prepend the cluster DNS to `/etc/resolv.conf`**: Add the CoreDNS *external* LoadBalancer address (`SVC_CIDR::1:a`) as the first nameserver on the inband machines so kubectl and curl can resolve in-cluster service names like `metaldata.example.com` and `boot.onmetal.de` that CoreDNS rewrites internally. In Phase 2 we deploy CoreDNS as a `LoadBalancer` service; the load balancer assigns each `SVC_CIDR::XYZ` cluster IP a publicly routable counterpart at `SVC_CIDR::1:XYZ`. In this case: cluster IP `SVC_CIDR::a` maps to external IP `SVC_CIDR::1:a`. The inband machines use the external address because they do not sit on the cluster's service network. We use [metal-load-balancer-controller](https://github.com/ironcore-dev/metal-load-balancer-controller) with FRR to announce these addresses via BGP; alternatively, use a publicly available load balancer like MetalLB.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, fixed.

Comment thread docs/tutorials/bootstrap.md Outdated
5. `stateless` - stateless address configuration.
6. `metal` - matches incoming DHCP requests by client MAC against `metal-config-<zone>.yaml` (mgmt-2 only at this stage) and creates an `Endpoint` CR (an IronCore metal-operator CRD) for each seen client MAC. metal-operator reconciles those `Endpoint`s and drives the BMC discovery flow from there (see [metal-operator architecture](https://ironcore.dev/metal-operator/architecture.html)). This is why a BMC's DHCPv6 request is the trigger for discovery, not the DHCP lease itself.
7. `leases` - lease bookkeeping, from `leases-config.yaml`.
- **ConfigMaps**: The OOB kustomization applies a `nameSuffix: -oob`, so the generated ConfigMaps are `metal-config-oob`, `leases-config-oob`, and `ntp-config-oob`, and the deployment is `fedhcp-oob` (all referenced with these suffixed names). FeDHCP's main `config` ConfigMap is likewise suffixed. Generated via `configMapGenerator`. The `-oob`-suffixed names are what [6.2.1](#62-update-discovery-configuration) updates with the full mgmt server MAC set.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: Probably there used to be a section 6.2.1 but I can't see it anymore and the link references 6.2.

Suggested change
- **ConfigMaps**: The OOB kustomization applies a `nameSuffix: -oob`, so the generated ConfigMaps are `metal-config-oob`, `leases-config-oob`, and `ntp-config-oob`, and the deployment is `fedhcp-oob` (all referenced with these suffixed names). FeDHCP's main `config` ConfigMap is likewise suffixed. Generated via `configMapGenerator`. The `-oob`-suffixed names are what [6.2.1](#62-update-discovery-configuration) updates with the full mgmt server MAC set.
- **ConfigMaps**: The OOB kustomization applies a `nameSuffix: -oob`, so the generated ConfigMaps are `metal-config-oob`, `leases-config-oob`, and `ntp-config-oob`, and the deployment is `fedhcp-oob` (all referenced with these suffixed names). FeDHCP's main `config` ConfigMap is likewise suffixed. Generated via `configMapGenerator`. The `-oob`-suffixed names are what [6.2](#62-update-discovery-configuration) updates with the full mgmt server MAC set.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

- rename bootstrap.md to mgmt-cluster-bootstrap.md and update the nav
- add an info admonition that the ansible roles will be published soon
- describe the inlined Ignition instead of the internal generator script
- fix metaldata.example.com inconsistency and a stale 6.2.1 link

Signed-off-by: Damyan Yordanov <damyan.yordanov@sap.com>
@damyan
damyan requested a review from johamster November 20, 2026 16:58
- rewrite all numbered-section cross-links to VitePress heading anchors
  (dots become hyphens, a leading digit gets an underscore), fixing 17
  broken in-page links
- promote the Phase 2.1-2.4 component lists to 2.x.y sub-headings so
  references resolve precisely (e.g. CoreDNS -> 2.4.4, metaldata -> 2.4.2)

Signed-off-by: Damyan Yordanov <damyan.yordanov@sap.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants