Installation Reference
This page describes what every provider shares: the installation directory, the common install-config.yaml fields, and the manifests, create, and destroy commands. Each provider's installation and parameter pages link here.
TOC
Installation DirectoryCommoninstall-config.yaml FieldsPlatform Node GroupsRendered ManifestsThe create CommandThe destroy CommandInstallation Directory
In this documentation, <install-dir> is the installation directory: a directory on the bootstrap node that holds one global installation. You choose its path, and you pass it to ac with --dir <install-dir>.
- Create the directory and write
install-config.yamlin it before you runac.acdoes not create either of them. If one is missing,acstops with an error. - Use a separate directory for each
globalinstallation. In a disaster recovery pair, each side has its own directory on its own bootstrap node. - Use the same directory for every
accommand of that installation, including when you runcreateagain.
You write install-config.yaml. ac writes everything else in the directory.
- Keep the file private (
chmod 600 <install-dir>/install-config.yaml), because it contains passwords. - Do not edit the files in
manifests/. - Keep the directory after the installation.
output/kubeconfigandlogs/exist only there.
Common install-config.yaml Fields
The file has four parts:
global: the registry and the platform identity.cluster: the network, keys, and encryption.provider.<name>: the infrastructure of one provider.- The node groups
controlPlaneandcomputes.
The following structure shows the fields that every provider uses. It is not a complete file. Copy the template of your provider instead. The template adds and describes the fields of that provider, such as the control plane endpoint, the node network, and the node disks. If a field is unknown or misspelled, ac fails before it changes anything, and the error names the field path.
computes is optional. Without it, the platform runs only on the control plane nodes.
Platform Node Groups
deployMode: base labels and taints a node group so that only the platform runs on it. If any node group uses base, the whole platform is installed in base mode. The base groups must then have at least one replica in total.
Rendered Manifests
To render the cluster objects without applying anything, run this command on the bootstrap node:
This step is optional, because create renders the objects the same way. manifests runs the checks that do not need a bootstrap cluster and writes the objects to <install-dir>/manifests/. create runs the remaining checks.
When manifests/ already exists, manifests and create ask whether to reuse it. Press Enter to reuse it. After you change install-config.yaml, answer n to render the manifests again. When standard input is not a terminal, pass --reuse-manifests=true or --reuse-manifests=false.
- Reusing applies the files on disk as they are, without checking them. A changed infrastructure credential, encryption key, or Bare Metal ServiceAccount signing key does not take effect.
- Rendering again replaces the whole
manifests/directory. A Secret that is already applied does not change. A changed infrastructure credential or encryption key still does not take effect. A changed Bare Metal ServiceAccount signing key stopscreatewith an error.
The create Command
Run create on the bootstrap node:
create does not accept --kubeconfig.
If create stops because of an interruption, an error, or a stage that exceeds --timeout, run the same command again. Work that is already complete is skipped.
- Every error prints the command that resumes the installation. Replace the leading
acin it with<extract-dir>/res/<arch>/ac. - When the registry check fails, the error also prints a variant with
--reuse-manifests=false. Run that variant after you correctglobal.registry. - Once the bootstrap cluster has started, do not change
global.registry; see Troubleshooting.
When create returns without an error, the installation is complete and the bootstrap cluster is removed. For what to keep, see Installation Directory. create only installs the cluster. To change the running cluster, see Manage Nodes on Alauda OS Clusters.
On the global cluster, do not delete the Cluster API Cluster global, its KubeadmControlPlane, or the infrastructure objects of the provider. Deleting them destroys the machines of the cluster. To remove the cluster, use destroy.
The destroy Command
Run destroy on a machine that can reach the global cluster with a kubeconfig, for example <install-dir>/output/kubeconfig. On the bootstrap node, run ac as <extract-dir>/res/<arch>/ac.
What the command deletes and keeps depends on the provider; see the Delete the global Cluster page of your provider. The command does not support Bare Metal. The following applies on every provider:
destroyrefuses to run when the target is not aglobalcluster installed withac. It also refuses when the platform still manages any other cluster, including imported clusters and clusters that were only partly created. The error names those clusters. You cannot skip either check.- If the run fails or stops after the control plane is down, run the same command again on the same machine, as the same user, and with the same kubeconfig.
destroycontinues from the plan that it saved when you confirmed the deletion. The plan contains the infrastructure credentials. - If the cluster responds but rejects the kubeconfig with
401,403, or an untrusted certificate,destroystops without deleting anything. The address may now belong to another cluster. - If anything is left after the run, the error names the saved plan file. Delete the file after you clean up.
- If a cluster never responded, you cannot destroy it with
ac. Clean up such a failed installation on the infrastructure side. destroyleaves the bootstrap node as it is.ac adm alpha cluster destroy --cluster globalis refused. That command is for workload clusters.