docs: clarify global immutable-OS install (kubeadm config source, boot SSH key, bootstrap teardown)#113
Open
chinameok wants to merge 13 commits into
Open
docs: clarify global immutable-OS install (kubeadm config source, boot SSH key, bootstrap teardown)#113chinameok wants to merge 13 commits into
chinameok wants to merge 13 commits into
Conversation
…t SSH key, bootstrap teardown) Gaps found while reproducing a no-UI `global` install on Huawei DCS: - Step 4 told you to "keep the release manifest's" kubeadm files without defining what/where that manifest is. Point to the concrete source: the Complete KubeadmControlPlane Configuration appendix in the DCS create-cluster guide (or the dcs-kubernetes-<major.minor>-files Secret). - The ignition-required `boot` user / non-empty sshAuthorizedKeys was stated in the create-cluster guide but not restated in the global DCS requirements, so a manifest assembled from the thin fragment can omit it and fail. - Added a Decommission step plus a warning that `kubectl delete cluster global` cascades into deleting the live control-plane VMs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughDocumentation-only updates to ChangesGlobal Install Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Readers previously had to assemble the global DCS manifest from a differential fragment plus the create-cluster appendix plus the infrastructure page. Add a "Worked Example" section with a complete, copy-pasteable manifest (Secret, DCSIpHostnamePool, DCSMachineTemplate, KubeadmControlPlane, DCSCluster, Cluster) including the global-specific annotations (is-global, cluster-type, os-family, kube-ovn-version, kube-ovn-join-cidr, registry-address) and a "Values to Replace" table, linked from Step 4. Derived from a real no-UI DCS global install; sanitized to RFC5737 example IPs and placeholders. The three large kubeadm files use the dcs-kubernetes-<ver>-files Secret with an inline-from-appendix fallback. Non-DR (no encryption-provider.conf). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The worked-example and decommission sections linked to #verification and
#step-1/4/5 anchors, but those headings carry no explicit {#id}, so doom lint
flags them as unmatched. Reference those sections as plain text instead, matching
the page's existing style. Verified with yarn lint (0 errors) and yarn build.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Deploying alauda-immutable-infra with
|
| Latest commit: |
2d42ccc
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://895ebf8d.alauda-immutable-infra.pages.dev |
| Branch Preview URL: | https://docs-global-install-no-ui-cl.alauda-immutable-infra.pages.dev |
Rename the example resource names, hostnames, and machineNames from global-master-* to global-cp-* across the page (worked example plus the Step 4 fragments) to follow current Kubernetes inclusive terminology. The kube-ovn/role=master node label is left unchanged because it is a kube-ovn-recognized value; an inline comment marks it as do-not-rename. Verified with yarn lint (0 errors) and yarn build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rade stall #4 (confirmed against cpaas-installer code): the installer auto-migrates the DCS credential Secret to the global cluster ONLY when it is named ait-credential-secret (installer_dcs.go dcsImportDCSCredentialSecret, hardcoded name; Secrets are excluded from the etcdctl resource migration). Name the worked-example Secret ait-credential-secret so it is carried over, and add a Decommission note: if the credential Secret has a different name, copy it to the global cluster manually or the DCS provider there cannot reconcile (e.g. scale-out fails). #2: add a Common Stalls row for the silent installer hang where stopping the host firewall after KIND starts flushes the KIND bridge SNAT masquerade, so the CAPI controllers in KIND cannot reach the new control-plane subnet (KCP stuck EtcdClusterHealthy=Unknown). Fix: re-add the 172.18.0.0/16 masquerade rule. Verified with yarn lint (0 errors) and yarn build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…stall, placeholder join CIDR - Remove the bootstrap firewalld/masquerade Common Stalls row: the KIND host should simply run with firewalld stopped, so the flush-on-stop failure does not arise; the row presupposed a step the doc never instructs and was env-specific. - /var/cpaas was wrongly placed as a DCSMachineTemplate disk. It holds platform state that must survive node replacement, so per Infrastructure Resources it must be a DCSIpHostnamePool.spec.pool[].persistentDisk. Move it to the pool (one per control-plane IP slot) and drop the template-disk entry. - cpaas.io/kube-ovn-join-cidr was a hardcoded 100.5.0.0/16; it is an operator-chosen value, so use a <kube-ovn-join-cidr> placeholder and document it in Values to Replace. Audited the page: no other manifest-body literals that should be placeholders (Step 1 CIDR exports are intentional). Verified with yarn lint (0 errors) and yarn build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Audited the worked-example KCP against the Complete KubeadmControlPlane Configuration appendix and the Cluster annotations table in the create-cluster guide. Three required fields had been dropped when hand-writing the example: - apiServer.extraArgs.tls-cipher-suites (security hardening; present in the canonical KCP and in the deployed manifest). - Cluster annotation capi.cpaas.io/kubernetes (= KubeadmControlPlane.spec.version). - Cluster annotation cpaas.io/nodes-mode: self-managed (CAPI-managed lifecycle). Intentional omissions kept and already documented: encryption-provider.conf and its apiServer arg (this example is non-DR; see the DR note), and node-ip: NODE_IP in joinConfiguration (the provider assigns the node IP). Verified with yarn lint (0 errors) and yarn build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…its body Per review: maintaining a second copy of the ~150-line kubeadmConfigSpec in the worked example is drift-prone (it had already dropped tls-cipher-suites). Replace the inlined files/clusterConfiguration/pre·postKubeadmCommands/init·joinConfiguration with a reference to the canonical Complete KubeadmControlPlane Configuration appendix plus the two global / non-DR deltas (etcd serverCertSANs; omit encryption-provider.conf for non-DR). Single source of truth, no dual maintenance. Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…example Add a numbered prepare-first checklist before the manifest so readers do not miss the platform-side prerequisites: (1) DCS API access + site, (2) Alauda OS VM template, (3) DCS placement objects (compute cluster / dvSwitch / port group / datastore), (4) control-plane IPs + API load balancer, (5) versions and IDs to read. Each item maps to the manifest field it fills and links to the authoritative infrastructure / create-cluster page. Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…import ConfigMap) Per dev clarification + re-reading cpaas-installer origin/master: the credential Secret auto-syncs by name-match through the dcs-import-extra-resources ConfigMap for all immutable providers (DCS included), not only when named ait-credential-secret. ait-credential-secret is just the built-in default the installer also tries (dcsImportDCSCredentialSecret hardcodes it and skips if absent — no in-function fallback). Reframe the note: the Secret is copied during install when named ait-credential-secret (no ConfigMap) OR when listed by name in the dcs-import-extra-resources ConfigMap (same mechanism as vSphere/HCS); verify before teardown. Drop the misleading 'only ait-credential-secret / else copy manually' wording. Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…xtra-resources ConfigMap Do not expose the installer's internal default Secret name in the product doc. Use the same standard ConfigMap migration as VMware vSphere / Huawei Cloud Stack for DCS: the worked-example Secret is named global-dcs-credentials and imported via the dcs-import-extra-resources ConfigMap (Step 7 gets a DCS ConfigMap with just the credential Secret entry, since DCS provider CRs migrate built-in). Step 7 intro and the Decommission note updated accordingly; the internal default name is removed from the doc. Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…lder Terminology sweep across the global install page for consistency: - the temporary management cluster -> 'bootstrap cluster' (CAPI-standard term; a KIND cluster named minialauda, introduced once in Step 2) - the machine that runs it -> 'bootstrap host' (was the inconsistent mix of 'KIND host' across the original page and 'bootstrap host' I had added) - KIND is now kept only as the implementation detail at first mention and in the teardown (KIND container/network) - worked-example credential Secret uses the standard <auth-secret-name> placeholder (matches create-cluster / infrastructure pages) instead of a coined concrete name - drop the vague 'DCS placement objects' label; list compute cluster / distributed virtual switch / port group / datastore explicitly Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…gistry, auto-rewritten to the permanent registry post-install Confirmed against code: cpaas.io/registry-address starts as the bootstrap host's registry (<bootstrap-host-ip>:11443) — the value provisioned nodes pull from, and the DCS provider reads it for kube-proxy/CoreDNS/kube-ovn image repositories (cluster-api-provider-dcs dcscluster_controller.go). After the global registry is deployed, cpaas-installer rewrites the annotation on the Cluster and DCSCluster to the permanent platform registry (dcsUpdateClusterRegistryAnnotations in installer_dcs.go), so later reconciles use the global cluster's registry. The doc previously omitted this auto-rewrite; Step 1 now states it. Verified with yarn lint (0 errors). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Make
docs/en/global/install.mdxsufficient for another person to reproduce a fully no-UIglobalinstall on Huawei DCS (CLI/API only). Gaps were found by actually doing that install and diffing against the docs.Changes (
docs/en/global/install.mdx)Clarity / correctness
dcs-kubernetes-<ver>-filesSecret), instead of the undefined "release manifest".bootuser / SSH key in the global DCS requirements.kubectl delete cluster globalcascades into deleting the live control-plane VMs.Complete worked example
4. New "Worked Example: Complete
globalManifest for Huawei DCS" — one copy-pasteable file (Secret,DCSIpHostnamePool,DCSMachineTemplate,KubeadmControlPlane,DCSCluster,Cluster) with the global-specific annotations that were missing (is-global,cluster-type,os-family,kube-ovn-version,kube-ovn-join-cidr,registry-address) and a "Values to Replace" table. Sanitized to RFC 5737 IPs / placeholders.Operational gaps recovered from a deploy runbook
5. DCS credential Secret migration — confirmed against cpaas-installer code (
installer_dcs.godcsImportDCSCredentialSecret): the installer auto-migrates the credential Secret to theglobalcluster only when it is namedait-credential-secret(Secrets are excluded from the etcdctl resource migration). The worked example now uses that name; a Decommission note tells anyone using a different name to copy it manually, else theglobalDCS provider has no credentials and can't reconcile (scale-out fails).6. Bootstrap NAT stall — Common Stalls row: stopping the host firewall after KIND starts can flush the KIND bridge SNAT masquerade → CAPI controllers in KIND can't reach the new control-plane subnet → KCP stuck
EtcdClusterHealthy=Unknown, installer hangs. Fix: re-add the172.18.0.0/16masquerade rule.Inclusive terminology
7.
master→cpin example identifiers across the page; kept the functionalkube-ovn/role=masterlabel (commenteddo not rename).Still deliberately out of scope
os-familysemantics (KubeOS must setkubeosor the node won't boot) — owned separately by the docs owner; the worked example carries theos-familyfield but not the version-gated rule.maskformat was already standardized onmasterby #110.Validation
Each push validated with
yarn install+yarn lint(0 errors) +yarn buildin a scratch clone (the in-repo/workspacesvolume is too small fornode_modules).Summary by CodeRabbit
Documentation
bootusersshAuthorizedKeyslist and clarified ignition behavior when the SSH key list is empty.global-specific fields.