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.

Installation 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.yaml in it before you run ac. ac does not create either of them. If one is missing, ac stops with an error.
  • Use a separate directory for each global installation. In a disaster recovery pair, each side has its own directory on its own bootstrap node.
  • Use the same directory for every ac command of that installation, including when you run create again.

You write install-config.yaml. ac writes everything else in the directory.

<install-dir>/
  install-config.yaml       written by you; ac never changes it
  manifests/                the rendered cluster objects
  output/kubeconfig         kubeconfig of the global cluster; it is not renewed automatically
  logs/ac.log               log of every ac run in this directory
  logs/cpaas-installer.log  copy of the platform installer log
  • 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/kubeconfig and logs/ 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 controlPlane and computes.

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.

install-config.yaml (common structure)
global:
  registry:
    address: <host>:<port>
    username: <user>
    password: <password>
  platform:
    address: <platform-domain-or-ip>
    username: admin@cpaas.io
    password: <password>
    extraAddresses: [] 
    cert:
      certificateFile: <console-cert-file>
      privateKeyFile: <console-key-file>
      # pkcs12CertificateFile: <console-pkcs12-file>
      # pkcs12Password: <password>

cluster:
  sshKeys:
    - <ssh-public-key>
  encryptionProviderConfig: <encryption-key>
  ntpServers: [] 
  network:
    podCIDR: 10.199.0.0/16
    serviceCIDR: 10.96.0.0/12
    kubeOVN:
      joinCIDR: 100.64.0.0/16

provider:
  <provider-name>: {} 

controlPlane:
  replicas: 3
  deployMode: normal
  <provider-name>: {} 

computes:
  - name: worker
    replicas: 3
    deployMode: normal
    <provider-name>: {}
#FieldDescription
global.registryRequired · objectThe image registry of the installation.
1global.registry.addressRequired · stringThe address of the external registry that holds all installation artifacts, which you prepared in Prepare the Core Package and the Registry. Write it as <host>[:<port>], without a scheme or /v2/. <host> is a domain name or an IPv4 address. If the registry uses IPv6, use a domain name.
2global.registry.usernameOptional · string · Default: none (anonymous access)Set it together with password, or delete both for anonymous access. Do not set only one of them.
3global.registry.passwordOptional · string · Default: none (anonymous access)The password of username.
global.platformRequired · objectHow users reach the platform: its access address, administrator, extra addresses, and certificate.
4global.platform.addressRequired · stringThe platform access address: a domain name or an IP address, without a scheme or port. Disaster recovery requires a domain name.
5global.platform.usernameOptional · string · Default: admin@cpaas.ioThe platform administrator, lowercased.
6global.platform.passwordRequired · string8 to 32 characters, containing a letter, a digit, and a symbol from !#$%&()*+=?@^_~-. If the value starts with a YAML special character, such as !, *, or &, quote it.
7global.platform.extraAddressesOptional · []string · Default: []Other addresses for the console, without a port. ac does not add the control plane VIP. To open the console on the VIP, list the VIP here. For disaster recovery, this field is required on both sides, and each side lists its own control plane VIP.
8global.platform.certOptional · object · Default: a self-signed certificateThe user-provided certificate of the platform access address; see Common Prerequisites. Set certificateFile and privateKeyFile (PEM), or pkcs12CertificateFile and pkcs12Password (a bundle of one certificate and its key). Put the files on the bootstrap node and refer to them by absolute paths. A bundle with a CA chain is rejected. The certificate covers address, which is a domain name or an IP address, and the domain names in extraAddresses. It has an RSA or ECDSA key. To use a self-signed certificate, delete this field. Disaster recovery does not allow a self-signed certificate and needs the same certificate on both sides.
clusterRequired · objectCluster-wide settings that do not depend on the provider.
9cluster.sshKeysRequired · []stringThe SSH public keys of the boot user on every node, for logging in to the nodes.
10cluster.encryptionProviderConfigOptional · string · Default: generatedThe base64 encoding of a 16, 24, or 32 byte aescbc key that encrypts Secrets at rest. It is not a configuration file. Delete this field to have a key generated. For disaster recovery, generate it once and set the same value on both sides.
11cluster.ntpServersOptional · []string · Default: []The NTP servers for the nodes. They are written into the chronyd configuration and take precedence over the time sources of the image. When the list is empty, the time configuration of the image applies.
cluster.networkConditional · objectThe cluster network. Required on VMware vSphere, Huawei DCS, and Bare Metal, which need loadBalancer. On Huawei Cloud Stack, loadBalancer is not allowed and the three CIDRs have defaults, so you can leave the section out.
12cluster.network.podCIDROptional · string · Default: 10.199.0.0/16The Pod CIDR. It must not overlap the Service CIDR or the join CIDR.
13cluster.network.serviceCIDROptional · string · Default: 10.96.0.0/12The Service CIDR. It must not overlap the Pod CIDR or the join CIDR.
14cluster.network.kubeOVN.joinCIDROptional · string · Default: 100.64.0.0/16The Kube-OVN join CIDR. It must not overlap the Pod CIDR or the Service CIDR.
providerRequired · objectThe provider settings, under a key named after the provider.
15provider.<provider-name>Required · objectThe infrastructure of the provider: vsphere, dcs, hcs, or baremetal; see the provider's installation page.
controlPlaneRequired · objectThe control plane node group.
16controlPlane.replicasRequired · integer1, or an odd number of 3 or more, as the stacked etcd requires. A single node is for testing and cannot be upgraded.
17controlPlane.deployModeOptional · string · Default: normalnormal or base. The field also exists in computes[]. base dedicates the node group to the platform; see Platform Node Groups.
18controlPlane.<provider-name>Conditional · objectThe node group fields of the provider. The field also exists in computes[]. Whether it is required depends on the provider; see the template of the provider.
computes[]Optional · []object · Default: []The worker node groups, one entry per group.
19computes[].nameRequired · stringA DNS-1123 label, unique across the groups. control-plane is reserved.
20computes[].replicasOptional · integer · Default: 0The number of nodes in the group. It cannot be negative.

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.

Applied to a base node group
Labelnode-role.kubernetes.io/cpaas-system: "true"
Taint on a worker groupnode-role.kubernetes.io/cpaas-system:NoSchedule
Taints on the control plane groupnode-role.kubernetes.io/control-plane:NoSchedule and node-role.kubernetes.io/cpaas-system:NoSchedule

Rendered Manifests

To render the cluster objects without applying anything, run this command on the bootstrap node:

<extract-dir>/res/<arch>/ac adm alpha global manifests \
  --dir <install-dir> --provider <baremetal|dcs|vsphere|hcs>

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 stops create with an error.

The create Command

Run create on the bootstrap node:

<extract-dir>/res/<arch>/ac adm alpha global create \
  --dir <install-dir> --provider <baremetal|dcs|vsphere|hcs>
FlagDescription
--dirThe installation directory. See Installation Directory. Required.
--providerbaremetal, dcs, vsphere, or hcs. It must match the provider section in install-config.yaml. Required.
--core-packageThe extracted Core Package. Needed only when ac runs from outside it.
--reuse-manifestsWhether to reuse an existing manifests/ directory or render it again. See Rendered Manifests.
--timeoutThe maximum wait for each stage. Each stage is timed separately. Default 2h.

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 ac in 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 correct global.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.

Do not delete the Cluster API objects to clean up

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.

ac adm alpha global destroy --kubeconfig <install-dir>/output/kubeconfig          # lists what will be deleted, then asks you to type the cluster name
ac adm alpha global destroy --kubeconfig <install-dir>/output/kubeconfig --yes    # without a terminal

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:

  • destroy refuses to run when the target is not a global cluster installed with ac. 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. destroy continues 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, destroy stops 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.
  • destroy leaves the bootstrap node as it is.
  • ac adm alpha cluster destroy --cluster global is refused. That command is for workload clusters.