Alauda Container Platform

Installing

This section describes the specific steps for installing the global cluster.

Installation Path

This page documents the traditional operating system installation path. If your environment runs on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see Installing the global Cluster on Immutable Infrastructure instead.

Before starting the installation, please ensure that you have completed the prerequisite checks, installation package download and verification, node preprocessing, and other preparatory work.

TOC

ProcessParameter DescriptionCommon Stalls and Where to LookInstaller CleanupAdditional Resources

Process

Upload and Extract Installation Package

Upload the Core Package installation package to any machine of the global cluster control plane nodes, and extract it according to the following command:

# Assume that the /root/cpaas-install folder already exists on the machine
tar -xvf {Path to Core Package File}/{Core Package File Name} -C /root/cpaas-install
cd /root/cpaas-install/installer || exit 1
INFO
  • This machine will become the first control plane node after the global cluster installation is complete.
  • After the Core Package is extracted, at least 100GB of disk space is required. Please ensure sufficient storage resources.
  • If you have already downloaded extensions, complete the ACP Core installation first, and then follow Extend to upload and install them.

Start the Installer

Execute the following installation script to start the installer. After the installer starts successfully, the command line terminal will output the web console access address.

After waiting for about 5 minutes, you can use a browser on your PC to access the web console provided by the installer.

bash setup.sh
WARNING

Ensure that the IP address and port 8080 of the node where the installer is located can be accessed normally, so that the web console provided by the installer can be accessed smoothly after the installer starts successfully.

IP Family

bash setup.sh --ip-family ipv6

If you plan to create a global cluster with Single-stack Network IPv6, you must explicitly specify --ip-family ipv6 when starting the installer. Without this parameter, the global cluster created by the installer will support Single-stack Network IPv4 and Dual-stack Network by default.

Parameter Configuration

After completing the installation parameter configuration according to the page guide, confirm the installation.

Parameter Description provides detailed descriptions of key parameters. Please read carefully and configure according to actual needs.

Monitor Installation Progress

After you confirm the parameters, the installer runs through several phases. A 3-node global cluster usually completes in 30–60 minutes; total time depends on node hardware, network throughput, and the number of plugins selected.

Phases You Will Observe

PhaseWhat is happeningFirst place to watch
BootstrapThe installer container starts in the temporary minialauda KIND environment on the installation node and brings up the embedded registry.Terminal output of bash setup.sh
Control plane provisioningThe first control plane node is bootstrapped with kubeadm; etcd starts; additional control plane nodes join.Installer Web UI; installer log
Network and core add-onsThe CNI (Kube-OVN by default), CoreDNS, kube-proxy, and other in-cluster networking components come up.Installer Web UI; kubectl get pods -n kube-system on the new cluster
Core platformThe base operator deploys, ClusterModule/global is created, and the platform control plane comes up.Installer Web UI; kubectl get clustermodule global
Aligned pluginsAppReleases for the selected Aligned plugins reconcile.kubectl get apprelease -A
CompletionThe installer posts the platform access URL and stops the bootstrap container after a short grace period.Installer Web UI; /var/cpaas/data/installer.log

Signals During Installation

If the Web UI appears stuck for more than a few minutes, check the backend signals instead — the Web UI polls a backend progress API and can lag, but the underlying state is always available from the installation node.

# Live installer log on the installation node
tail -f /var/cpaas/data/installer.log

# Use the installer kubeconfig until the global cluster takes over
export KUBECONFIG=/var/cpaas/data/alauda.kubeconfig

# Cluster API resources that drive the new global cluster
kubectl get clusters.cluster.x-k8s.io -A
kubectl get kubeadmcontrolplane -A
kubectl get machines -A

# Charts that the installer is reconciling
kubectl get apprelease -A

The installer log records each phase transition and any retryable errors. Most transient errors retry automatically on a 10-second interval; persistent errors stay in the log and surface in the Web UI as a stalled phase.

Verify Successful Installation

After the installation completes, the platform access URL is displayed in the Web UI. Click the Access button to open the platform and confirm that login succeeds.

Next, run the following commands on a control plane node of the new global cluster to confirm the installed state:

# All nodes are Ready
kubectl get nodes

# ClusterModule/global reports the base module as healthy
kubectl get clustermodule global -o jsonpath='{.status.phase}'

# No AppRelease is in a failed state
kubectl get apprelease -A

# No Pod is stuck outside Running or Completed
kubectl get pod --all-namespaces | awk '{if ($4 != "Running" && $4 != "Completed")print}' | awk -F'[/ ]+' '{if ($3 != $4)print}'

The installation is healthy when:

  • All global cluster nodes are Ready.
  • ClusterModule/global reports a healthy phase.
  • Every AppRelease is in a non-failed state.
  • Critical Pods in cpaas-system are Running or Completed.

Install Product Docs Plugin

INFO

The Alauda Container Platform Product Docs plugin provides access to product documentation within the platform. All help links throughout the platform will direct users to this documentation. If this plugin is not installed, clicking help links in the platform will result in 404 access errors.

  1. Navigate to Administrator.

  2. In the left sidebar, click Marketplace > Cluster Plugins and select the global cluster.

  3. Locate the Alauda Container Platform Product Docs plugin and click Install.

Parameter Description

ParameterDescription
Kubernetes Version

All optional versions are rigorously tested for stability and compatibility.
Recommendation: Choose the latest version for optimal features and support.

Cluster Network Protocol

Supports three modes: IPv4 single stack, IPv6 single stack, IPv4/IPv6 dual stack.
Note: If you select dual stack mode, ensure all nodes have correctly configured IPv6 addresses; the network protocol cannot be changed after setting.

Cluster Endpoint

    Enter the pre-prepared domain name.
    If no domain name is available, enter the pre-prepared global VIP.
    Self-built VIP is disabled by default, only enable it if you have not provided a LoadBalancer.

    The following conditions must be met when using Self-built VIP :

    • A usable VRID is available;
    • The host network supports the VRRP protocol;
    • All control plane nodes and the VIP must be on the same subnet.

    Tip: For single-node deployments in feature experience scenarios, you can directly enter the node IP. There is no need to enable Self-built VIP or prepare network resources such as global VIP.

Platform Access Address

    If you do not need to distinguish between Cluster Endpoint and Platform Access Address, enter the same address as the Cluster Endpoint.
    If you need to distinguish, for example, if the global cluster is only for internal network access and the platform needs to provide external network access, enter the pre-prepared domain name or External IP.
    The platform uses HTTPS access by default and does not enable HTTP. If you need to enable HTTP access, enable it in Advanced Settings (not recommended).
    Note: A domain name must be entered in the following cases,

    • A disaster recovery plan for the global cluster is planned;
    • The platform needs to support IPv6 access.

    Tip: If you need to configure more platform access addresses, you can add them in Other Settings > Other Platform Access Addresses in the next step. Or, after installation, add them in platform management according to the user manual.

Certificate

The platform provides self-signed certificates to support HTTPS access by default.
If you need to use a custom certificate, you can upload an existing certificate.

Image Repository

The Platform Deployment image repository is used by default, which contains images of all components.
If you need to use an External image repository, please contact technical support to obtain the image synchronization plan before configuring.

Container Network

The default subnet and Service network segment of the cluster cannot overlap.
When using the Kube-OVN Overlay network, ensure that the container network and the host network are not in the same network segment, otherwise it may cause network exceptions.

Node Name

If you select Host Name as Node Name, ensure that the host names of all nodes are unique.

global Cluster Platform Node Isolation

Enable only when you plan to run application workloads in the global cluster.
After enabling:

  • Nodes can be set to Platform Exclusive, i.e., only run platform components, ensuring platform and application workloads are isolated;
  • Workloads of the DaemonSet type are excluded.
Add NodeControl Plane Node:
    • Supports adding 1 or 3 control plane nodes (3 for high availability configuration);
    • If Platform Exclusive is enabled, Deployable Applications is forced to be disabled, and control plane nodes only run platform components;
    • If Platform Exclusive is disabled, you can choose whether to enable Deployable Applications, allowing control plane nodes to run application workloads.
Worker Node:
    • If Platform Exclusive is enabled, Deployable Applications is forced to be disabled;
    • If Platform Exclusive is disabled, Deployable Applications is forced to be enabled.

When using Kube-OVN, you can specify the node network card by entering the gateway name.

If the node availability check fails, please adjust it according to the page prompt and add it again.

Common Stalls and Where to Look

If the installer reports an error or appears to make no progress, start with the symptom in the table below. The signals listed are the first place to look; collect that output before opening a ticket so support can act on the same data.

SymptomFirst place to lookWhat you are looking for
Web UI does not loadTerminal output of setup.sh and nerdctl ps on the installation nodeThe minialauda-control-plane container is Running and port 8080 is reachable from the browser.
Installer log stops advancingtail -f /var/cpaas/data/installer.logThe last log line tells you which phase the installer is in. If the same phase repeats for more than a few minutes, the cause is usually one of the rows below.
Stuck on control plane provisioningkubectl get machines -A and kubectl describe on a machine that is not ReadyBootstrap and Infrastructure conditions on the machine; the node can usually be reached at the IP from status.addresses.
Stuck on network and core add-onskubectl -n kube-system get pods on the new clusterKube-OVN, CoreDNS, and kube-proxy pods are Running. Image-pull failures usually point to a registry reachability problem.
AppRelease shows Failedkubectl describe apprelease <name> -n <namespace>The Status conditions and recent Events describe the underlying chart error.
Pod is ImagePullBackOff or ErrImagePullkubectl describe pod <pod>Confirm the platform image repository is reachable from the failing node.
ClusterModule/global does not reach a healthy phasekubectl describe clustermodule globalThe Status.conditions describe which module is blocking the cluster from completing.

Issues that are not listed here usually point to environment-specific causes. Capture the installer log and the relevant kubectl describe output, then escalate.

Installer Cleanup

Normally, the installer will be automatically deleted after installation. If the installer is not automatically deleted after 30 minutes of installation, please execute the following command on the node where the installer is located to force delete the installer container:

nerdctl rm -f minialauda-control-plane

Additional Resources