Repository navigation
Conversation
damyan
commented
Nov 19, 2026
Signed-off-by: Damyan Yordanov <damyan.yordanov@sap.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
johamster
left a comment
There was a problem hiding this comment.
Looks good, left a couple of minor comments.
| nav: [ | ||
| {text: 'Home', link: '/'}, | ||
| {text: 'Overview', link: '/overview/'}, | ||
| {text: 'Tutorials', |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Well, I personally prefer tutorials, obviously, but I can go with all three alternatives. @afritzler Do you have opinion on that one?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
|
||
| ### 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: |
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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.
|
|
||
| - **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. |
There was a problem hiding this comment.
Minor: At all other places, it is metaldata.example.com except here. Did we miss that in the original document?
| - **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. |
| 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. |
There was a problem hiding this comment.
Minor: Probably there used to be a section 6.2.1 but I can't see it anymore and the link references 6.2.
| - **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. |
- 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>
- 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>