Create a Cluster on Huawei Cloud Stack

ACP CLI (ac) renders the Cluster API and HCS objects from one install-config.yaml, applies them to the global cluster, and reports the creation stages. Every object lives in the cpaas-system namespace of the global cluster.

Prerequisites

  • You meet the Huawei Cloud Stack prerequisites.
  • ac is logged in to the platform as a platform administrator (ac login https://<platform-address> --name <session-name>).

Procedure

1. Write install-config.yaml

Create an installation directory for the cluster and write install-config.yaml in it. ac writes manifests/ and logs/ac.log next to it.

Copy the following template and fill in the placeholders. The table below the template describes the numbered lines, which are specific to Huawei Cloud Stack. For the other fields, see Common install-config.yaml Fields. For the objects that ac renders from this file, see Parameters.

install-config.yaml
cluster:
  clusterName: <cluster-name>
  sshKeys:
    - <ssh-public-key>
  # registrySecretRef:
  #   name: <registry-secret-name>
  #   namespace: cpaas-system
  # 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:
  hcs:
    imageName: <image-name>
    flavorName: <flavor-name>
    # availabilityZone: <az>
    network:
      vpcName: <vpc-name>
      securityGroupName: <security-group>
      subnetName: <primary-subnet>
    elb:
      vipAddress: <control-plane-vip>
      # vipSubnetName: <vip-subnet-name>
      l4:
        # subnetName: <subnet-name>
        ips: [<l4-ip-1>, <l4-ip-2>]
      l7:
        # subnetName: <subnet-name>
        ips: [<l7-ip-1>, <l7-ip-2>]
    rootDisk:
      type: SSD
      sizeGiB: <root-disk-gib>
    diskType: SSD
    # controlPlaneHA:
    #   enabled: true
    #   policy: soft-anti-affinity

controlPlane:
  replicas: 3
  # hcs:
  #   flavorName: <flavor-name>
  #   availabilityZone: <az>
  #   subnetName: <subnet-name>
  #   rootDisk:
  #     type: SSD
  #     sizeGiB: <root-disk-gib>
  network:
    additions: []
    # additions:
    #   - hcs:
    #       subnetName: <additional-subnet>
  disks:
    ephemeral:
      - name: var-lib-containerd
        sizeGiB: 100
      - name: var-lib-kubelet
        sizeGiB: 100
      - name: var-lib-etcd
        sizeGiB: 20
    persistent:
      - name: var-cpaas
        sizeGiB: 100
    rawDisks: [] 
    # rawDisks:
    #   - name: data-001
    #     sizeGiB: 50
    # hcs:
    #   type: SSD
  hosts:
    - hostname: <cp-0-hostname>
      ip: <cp-0-ip>
      additionalIps: []
    - hostname: <cp-1-hostname>
      ip: <cp-1-ip>
      additionalIps: []
    - hostname: <cp-2-hostname>
      ip: <cp-2-ip>
      additionalIps: []

computes:
  - name: worker
    replicas: 3
    # hcs:
    #   flavorName: <flavor-name>
    #   availabilityZone: <az>
    #   subnetName: <subnet-name>
    #   rootDisk:
    #     type: SSD
    #     sizeGiB: <root-disk-gib>
    network:
      additions: []
      # additions:
      #   - hcs:
      #       subnetName: <additional-subnet>
    disks:
      ephemeral:
        - name: var-lib-containerd
          sizeGiB: 100
        - name: var-lib-kubelet
          sizeGiB: 100
      persistent:
        - name: var-cpaas
          sizeGiB: 100
      rawDisks: []
      # rawDisks:
      #   - name: data-001
      #     sizeGiB: 50
      # hcs:
      #   type: SSD
    hosts:
      - hostname: <worker-0-hostname>
        ip: <worker-0-ip>
        additionalIps: []
      - hostname: <worker-1-hostname>
        ip: <worker-1-ip>
        additionalIps: []
      - hostname: <worker-2-hostname>
        ip: <worker-2-ip>
        additionalIps: []

credentialRef:
  name: <credential-secret-name>
  namespace: cpaas-system
#FieldDescription
provider.hcsRequired · objectThe Huawei Cloud Stack settings.
1provider.hcs.imageNameRequired · stringThe Alauda OS image, uploaded to HCS, that every node is created from. It must carry the Kubernetes version that ac installs; see Kubernetes Version. Its Alauda OS version matches the platform version; see Version Mapping.
2provider.hcs.flavorNameConditional · stringThe default ECS flavor, by its API name. Required unless every node group sets hcs.flavorName. The flavor sets the CPU and memory, so cpuCore and memoryGiB are rejected on every node group.
3provider.hcs.availabilityZoneOptional · string · Default: the first available zone that HCS reportsThe default availability zone; a node group can override it. See Availability Zone Placement.
4provider.hcs.networkRequired · objectThe node network. vpcName and securityGroupName apply to every node, and a node group cannot change them. subnetName is the default subnet of the primary NIC, an existing subnet of the VPC; a node group can override it. Every subnet named in the file must be in this VPC. ac collects all of them into the HCSCluster.
5provider.hcs.elbRequired · objectThe control plane ELB, which the provider creates; see Control Plane Endpoint. vipAddress is the control plane VIP, an IPv4 address in the VIP subnet. vipSubnetName is optional and defaults to network.subnetName. l4.ips and l7.ips are the L4 and L7 Hybrid Load Balancing addresses: exactly two distinct IPv4 addresses for each. Their optional subnetName defaults to network.subnetName.
6provider.hcs.rootDiskConditional · objectThe system disk of all nodes. Required unless every node group sets hcs.rootDisk. type is the EVS type: SSD, SAS, or SATA. type defaults to SSD. sizeGiB is required and must be greater than 0.
7provider.hcs.diskTypeOptional · string · Default: SSDThe EVS type of the data and persistent disks: SSD, SAS, or SATA. disks.hcs.type overrides it for one node group.
8provider.hcs.controlPlaneHAOptional · object · Default: enabled, soft-anti-affinityThe server group policy of the control plane instances. enabled defaults to true, which spreads the control plane across physical hosts, and false lets HCS place the control plane freely. policy is soft-anti-affinity (the default) or anti-affinity. See Control Plane HA Placement.
controlPlaneRequired · objectThe control plane node group.
9controlPlane.hcsOptional · object · Default: the values of provider.hcsFor this group, overrides flavorName, availabilityZone, and rootDisk of provider.hcs, and subnetName of provider.hcs.network. Uncomment the block and keep only the fields that differ. A group's rootDisk replaces provider.hcs.rootDisk, so set both type and sizeGiB. See Place Node Groups Separately.
10controlPlane.networkOptional · object · Default: no additional NICsTakes only additions, the optional additional NICs, which are matched in order to hosts[].additionalIps. Use the commented block. gateway, dns, and mask are rejected, on an addition as well, because the subnet supplies them. See Add a Second NIC.
11controlPlane.network.additions[].hcsOptional · object · Default: the node group's subnetsubnetName: the subnet of the additional NIC.
12controlPlane.disks.ephemeralRequired · []objectThe disks var-lib-containerd, var-lib-kubelet, and var-lib-etcd, which are recreated with the instance. Keep the names and change only sizeGiB.
13controlPlane.disks.persistentRequired · []objectThe disk var-cpaas, which is kept when the instance is replaced. Keep the name and change only sizeGiB.
14controlPlane.disks.rawDisksOptional · []object · Default: []Raw block volumes for TopoLVM. Each has a name of your choice and a sizeGiB from 10 to 32768. Use the commented block. Other disk names are rejected, so add extra volumes here. See Add Raw Disks.
15controlPlane.disks.hcsOptional · object · Default: the value of provider.hcs.diskTypetype overrides provider.hcs.diskType for this group.
16controlPlane.hostsRequired · []objectOne entry per node, and at least replicas entries. For hostname, see Hostname Behavior on the Node. ip is the IPv4 address of the primary NIC. additionalIps lists one IPv4 address per network.additions entry, in order; the default is [].
computes[]Optional · []object · Default: []The worker node groups, one entry per group. The controlPlane fields above also apply to each entry. The rows below describe the fields whose rules differ for worker node groups.
17computes[].disks.ephemeralRequired · []objectA worker node group has no var-lib-etcd. Keep var-lib-containerd and var-lib-kubelet, and change only sizeGiB.

cluster.network.loadBalancer is rejected, because the control plane endpoint is the ELB under provider.hcs.elb. For cluster.registrySecretRef, see Workload Cluster Image Registry.

2. Create the Cluster

Run the following command from a machine where ac is logged in to the platform:

ac config use-cluster global
ac adm alpha cluster create --dir <install-dir> --provider hcs

ac first checks the platform's Kubernetes and Kube-OVN versions, the providers, the registry, and the credential Secret and its IAM endpoint. If a check fails, nothing is changed and the error names the item. Before you run create, make sure that the credential is correct, and that the names of the image, flavor, availability zone, VPC, subnet, and security group are correct.

create returns once the objects are applied, and the cluster keeps building. To wait until all stages are ready, add --wait. --timeout (default 2h) limits only the wait. To render without applying, run ac adm alpha cluster manifests with the same --dir and --provider.

3. Monitor the Creation

ac config use-cluster global
ac adm alpha cluster status --cluster <cluster-name>                      # prints the four stages once
ac adm alpha cluster wait-for install-complete --cluster <cluster-name>   # waits until all four are ready

Continue when all four stages are ready; otherwise see Troubleshooting.

4. Verify the Cluster

Run the following commands from a machine where ac is logged in to the platform:

ac config sync
ac config use-cluster <cluster-name>
ac get nodes
ac config use-cluster global

Continue when every node is Ready; otherwise see Troubleshooting.

Control Plane HA

Applies to: provider.hcs.controlPlaneHA.enabled: true, the default. Skip it when it is false.

ac config use-cluster global
ac -n cpaas-system get hcscluster <cluster-name> \
  -o jsonpath='{range .status.conditions[?(@.type=="ControlPlaneHAReady")]}{.status}{" "}{.reason}{" "}{.message}{"\n"}{end}'

Continue when the status is True; otherwise see Control Plane HA in Troubleshooting.

Run create Again

create only creates the cluster. Do not run it on a cluster that already exists. To change a running cluster, see Manage Nodes.

If create stops before the cluster is created, run the same command again. Completed work is skipped. When you run create again on the same directory:

  • It recreates objects that were deleted. The exception is a Secret: ac creates Secrets once and then leaves them as they are.
  • It does not overwrite a field that you changed with another tool. When the rendered value differs, create reports that the fields are owned by another manager and stops. Do not delete the object that the error names.
  • It does not change the subnet list of the HCSCluster (spec.network.subnets) once the HCSCluster exists. A subnet that you add to or change in install-config.yaml after that has no effect.
  • When manifests/ already exists, create asks whether to reuse it. Press Enter to reuse it, or answer n to render again after you change install-config.yaml. When standard input is not a terminal, pass --reuse-manifests=true or --reuse-manifests=false instead.
  • Reusing manifests/ ignores install-config.yaml and skips every check.

Do not edit the files in manifests/.

WARNING

Keep <install-dir>/manifests/, or set cluster.encryptionProviderConfig. A generated encryption key is kept on disk only in manifests/. If you render again without doing either, a new key is generated, and manifests/ then no longer records the key that the cluster uses.

Next Steps