Documentation

• 1: Overview
• 1.1: 1.7 release notes
• 1.2: Features
• 1.3: Roadmap
• 2: Getting started
• 2.1: All-in-One deployment
• 2.2: Offline clusters
• 2.3: Offline component packages
• 3: Deployment docs
• 3.1: High availability
• 3.2: Upgrade checklist
• 4: Tutorials
• 4.1: Create clusters
• 4.2: Cluster hosting
• 4.3: Cluster management
• 4.4: Node management
• 4.5: Access control
• 4.6: Operations and logs
• 4.7: Platform diagnostics
• 4.8: Image registries
• 5: FAQ
• 5.1: Cluster creation troubleshooting
• 6: Contribution Guidelines

1 - Overview

KubeClipper manages the Kubernetes cluster lifecycle, including creation, scaling, upgrades, backup, recovery, and deletion, through a web console, API, and the kcctl CLI.

Architecture in 1.7

• kc-server serves the API and persists clusters, Operations, and Tasks. Controllers advance their state.
• kc-agent runs on managed nodes. It accesses the Server API over mTLS, watches assigned tasks, executes them, and reports results.
• kcctl / Console submit management requests and display platform health, progress, and logs.
• etcd stores platform resources and state. Plan platform etcd separately from the etcd clusters used by managed Kubernetes clusters.

1.7 uses API-driven Operation v2 rather than built-in NATS task delivery. Operations run asynchronously. Confirm results using Operations, cluster state, and the actual nodes. See operations and logs.

Networking

Deployment configuration can change these ports. Check Agent task-log listener configuration against firewall rules as well; older NATS port lists do not apply.

--ip-detect selects the platform management address. --node-ip-detect selects the Kubernetes node address. Check connectivity explicitly on hosts with multiple interfaces. Pod network address detection belongs to the selected CNI configuration.

Start here

• 1.7 release notes and component matrix
• Getting started
• High availability
• Platform diagnostics

1.1 - 1.7 release notes

This documentation targets KubeClipper v1.7.0, released on September 8, 2026. See the official v1.7.0 release.

Main changes

• API-driven Operation v2 manages operations, tasks, and execution state. Agents communicate with Servers over mTLS.
• kcctl operation provides lists, details, logs, retries, and cancellation.
• kcctl status and kcctl doctor report platform health and diagnostic evidence.
• Registry resources select Kubernetes image repositories and configure containerd image pulls.
• Deployment prechecks identify the node, role, and underlying error. Server installation waits for platform etcd health.

Component versions

Kubernetes v1.37.0 is the default. Available selections depend on platform resources; offline installations also need packages for the target CPU architecture. Source: v1.7.0 support matrix.

Release scope

This documentation describes v1.7.0. Review release notes, security advisories, and binary versions before production use. See the upgrade checklist.

The version menu preserves documentation for 1.6 through 1.1. The 1.6 documentation follows the v1.6.0 release tag.

1.2 - Features

Cluster lifecycle

Create, delete, upgrade, back up, and restore Kubernetes clusters. Manage cluster nodes and import existing clusters. Online and offline installation support amd64 and arm64 resources; use the 1.7 component matrix when selecting versions.

Operations and troubleshooting

Operation v2 records asynchronous cluster changes. Inspect execution state and logs, then retry or cancel when appropriate. Operation commands and platform diagnostics help locate failures.

Image and resource management

Registry resources configure image sources and containerd pull settings. Offline packages provide component resources separately.

Platform and access

Deploy a single-node lab or a high-availability platform. Agents use mTLS to access the Server API. RBAC provides user permissions; see access control.

1.3 - Roadmap

This page records development directions, not capabilities guaranteed by v1.7.0. Consult the release notes for shipped functionality and GitHub issues for current discussions.

• OCI-based distribution of installation resources
• Kubernetes workload and monitoring views
• Application and add-on lifecycle management
• Additional managed-cluster deployment modes

No delivery dates are promised here. Validate experimental features separately before production use.

2 - Getting started

This guide uses KubeClipper v1.7.0. Deploy the platform on an SSH-accessible Linux host with systemd, then create a single-node test cluster. See high availability for production topology.

Prepare the host

• Install curl, tar, and sudo. Enable SSH and give the deployment user sudo privileges.
• Run chrony, ntp, or systemd-timesyncd to keep clocks synchronized.
• Prepare an SSH private key that can log in to the target host and check network connectivity.
• Check the kernel, cgroup, and runtime requirements of the Kubernetes version you select. Operating system lists from older guides do not establish compatibility with newer Kubernetes versions.
• Allow disk space for downloading and extracting packages and loading container images. The complete 1.7.0 deployment package is about 1.2 GiB. The roughly 60 MB binary archives on GitHub Release do not replace it.

Install kcctl

Download the installer from the 1.7.0 release tag before running it. It downloads binaries from the project’s native Alibaba Cloud OSS endpoint rather than the old oss.kubeclipper.io domain.

curl -fL -o get-kubeclipper.sh \
  https://raw.githubusercontent.com/kubeclipper/kubeclipper/v1.7.0/scripts/get-kubeclipper.sh
KC_VERSION=v1.7.0 bash get-kubeclipper.sh
kcctl version

The client supports Linux and macOS on amd64 and arm64. Platform services run on Linux; run the following deployment commands on a Linux deployment host. Clients are also available from the v1.7.0 Release.

Download the complete deployment package

Set ARCH to the target architecture. Use arm64 instead of amd64 for ARM hosts.

ARCH=amd64
curl -fL -o "kc-${ARCH}.tar.gz" \
  "https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/release/v1.7.0/kc-${ARCH}.tar.gz"
tar -tzf "kc-${ARCH}.tar.gz" | head

The complete package includes platform services, the console, and offline resources. Download it on a connected host and transfer it to the deployment host for an air-gapped installation. Before creating a cluster, check that resource versions and architectures are present; see offline clusters.

Deploy All-in-One

Replace the private key path below. SSH access to the target is required even when the target is the deployment host itself.

read -r -s -p 'Set the admin password: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-${ARCH}.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

The initial password must be 8–16 characters and include uppercase letters, lowercase letters, and digits. If prechecks fail, resolve the reported node and check before retrying.

Agents in 1.7 access the Server API over mTLS. Keep TLS enabled during deployment. The default console endpoint is http://SERVER_IP:80; the Server API is https://SERVER_IP:8080. They serve different purposes.

Log in and check the platform

Replace SERVER_IP with your Server address. Login prompts for the admin password you set above.

SERVER_IP=192.168.10.10
kcctl login --host "https://${SERVER_IP}:8080" --username admin
kcctl status
kcctl doctor
kcctl get node
kcctl resource list

Open http://SERVER_IP for the console. Configure HTTPS at the console entry point in production. status reports platform health and doctor provides diagnostic evidence; neither repairs the environment.

Create a cluster

Choose a Ready node from kcctl get node and set NODE to its ID or IP. Offline installation is the default; first confirm that matching resource packages are available.

NODE=192.168.10.10
kcctl create cluster --name demo --master "$NODE" --untaint-master \
  --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5
kcctl operation list -c demo
kcctl get cluster demo -o yaml

--untaint-master lets this test cluster schedule regular workloads on the control-plane node. Installation time depends on hardware, connectivity, and image availability. Successful submission is followed by an asynchronous Operation; inspect its result and the cluster state.

Obtain the cluster kubeconfig from the console, set KUBECONFIG, then check Kubernetes:

kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

Confirm Running cluster state, Ready nodes, system Pod health, and API readiness. See operations and logs and platform diagnostics when a task fails.

Remove the test cluster

This deletes the demo cluster. Confirm that no workloads or data must be retained before running it:

kcctl delete cluster demo
kcctl operation list -c demo
kcctl get cluster

Wait for deletion to finish and confirm the cluster is gone. Investigate failures before considering state resets or forced deletion.

2.1 - All-in-One deployment

All-in-One runs the Server and Agent on the same Linux host for evaluation and testing.

Follow Getting started to prepare the host, install v1.7.0 kcctl, download the complete package, deploy the platform, and create a test cluster.

For production, plan separate Server and workload nodes and see high availability.

2.2 - Offline clusters

Offline installation needs a platform deployment package and component resources for Kubernetes, the CRI, and the CNI. Registry resources describe image repositories; they do not replace offline packages.

Check resources

After deploying the platform, log in and inspect resources and nodes:

kcctl resource list
kcctl get node

Match package architecture to the target nodes. The 1.7 matrix uses Kubernetes v1.37.0 / v1.36.4 / v1.35.8, containerd 2.2.4, and Calico v3.31.5. See offline component packages when more resources are needed.

Create the cluster

kcctl create cluster defaults to offline installation. This example uses one test node:

kcctl create cluster --name offline-demo --master 192.168.10.21 --untaint-master \
  --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5
kcctl operation list -c offline-demo
kcctl get cluster offline-demo -o yaml

In the Console wizard, select prepared component versions, target nodes, and offline installation. Populate any image repository and configure its Registry resource first. Select storage plugins according to actual requirements; a particular NFS plugin is not a mandatory cluster-creation step.

Confirm installation

Use Operations and node logs to locate failures. After obtaining kubeconfig, check Ready nodes, system Pods, and API readiness. Resolve missing resources, architecture mismatches, and unreachable image paths before retrying. See operations and logs.

2.3 - Offline component packages

The full 1.7.0 deployment package installs the platform. Additional Kubernetes, CRI, and CNI packages provide cluster resources. Deploy the platform using Getting started first.

Choose versions and architecture

Use the 1.7 matrix. This Bash example prepares Kubernetes v1.37.0 for amd64. Prepare arm64 packages for arm64 nodes.

set -e
ARCH=amd64
VERSION=v1.37.0
PKG_DIR="$(mktemp -d)"
COMPONENT_DIR="k8s/${VERSION}/${ARCH}"
mkdir -p "${PKG_DIR}/${COMPONENT_DIR}"
for FILE in manifest.json configs.tar.gz images.tar.gz; do
  curl -fL -o "${PKG_DIR}/${COMPONENT_DIR}/${FILE}" \
    "https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/packages/${COMPONENT_DIR}/${FILE}"
done
tar -czf "k8s-${VERSION}-${ARCH}.tar.gz" -C "$PKG_DIR" k8s
tar -tzf "k8s-${VERSION}-${ARCH}.tar.gz"

Preserve the k8s/version/architecture/ hierarchy. Keep certificate and HTTP verification enabled. The download directory remains at $PKG_DIR for inspection and subsequent cleanup.

Other components use the same hierarchy. Archive the component directory with the following files:

For example, Calico uses packages/calico/v3.31.5/amd64/manifest.json. Packaging existing resources does not imply support for arbitrary custom versions.

Upload in the offline environment

Transfer the archive to a deployment machine that can reach the platform and has the deployment configuration and Server SSH credentials.

kcctl resource push --pkg k8s-v1.37.0-amd64.tar.gz --type k8s
kcctl resource list

Use --type cri for containerd and --type cni for Calico. Confirm the versions and architecture in the resource list before creating an offline cluster. See Registry configuration for image registry settings.

3 - Deployment docs

3.1 - High availability

This guide deploys a highly available KubeClipper control plane. Platform availability and the availability of managed Kubernetes clusters require separate planning.

Prepare nodes and networking

Prepare three Linux Server nodes and the Agent nodes you want to manage. The deployment user needs SSH access to every node with the same private key and sudo privileges. See architecture and networking for clock synchronization and ports.

Platform etcd runs on Server nodes. Plan membership and failure tolerance around etcd quorum requirements. Keep platform Servers separate from Kubernetes workload nodes in production.

Install and download

Follow Getting started to install v1.7.0 kcctl and download the complete kc-amd64.tar.gz or kc-arm64.tar.gz package for your targets. GitHub Release client archives are not deployment packages for --pkg.

Deploy Servers and Agents

Replace the IP addresses, private key, and package path. --server accepts comma-separated addresses; --agent can include a region.

read -r -s -p 'Set the admin password: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy \
  --server 192.168.10.11,192.168.10.12,192.168.10.13 \
  --agent default:192.168.10.21,192.168.10.22 \
  --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-amd64.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

Keep TLS enabled. On hosts with multiple interfaces, select reachable addresses using --ip-detect and --node-ip-detect; consult kcctl deploy -h. Platform etcd ports default to 12379, 12380, and 12381.

Verify the platform

kcctl login --host https://192.168.10.11:8080 --username admin
kcctl status
kcctl doctor
kcctl get node

Check services on all three Servers, platform etcd membership, and Agent health. Repeat API connectivity checks against the other Servers. Configure a load balancer and certificates separately if you need a common hostname or VIP; deploying three Servers does not provision an entry-point VIP.

Browsers use each Server’s default HTTP port 80 console entry point; the CLI uses the HTTPS port 8080 API. Configure HTTPS at the production console entry point and restrict management ports to the intended networks.

Add and remove Agents

kcctl join --agent default:192.168.10.23
kcctl get node

After confirming the node has no clusters or workloads to retain, remove it:

kcctl drain --agent 192.168.10.23

Investigate a normal drain failure before choosing further actions. Do not use force options by default. See the upgrade checklist before changing versions.

3.2 - Upgrade checklist

Platform upgrades and managed Kubernetes upgrades are separate procedures. This page covers platform checks; it does not promise a direct upgrade from every older release to 1.7.

Before upgrading

1. Record Server, Agent, kcctl, and Console versions and node topology. Confirm package architecture.
2. Review release notes, security advisories, and configuration changes. 1.7 introduces Operation v2; inspect old operation records and task state in a test environment.
3. Choose a window with no running installation, upgrade, or backup operations. Resolve unfinished work first.
4. Back up platform etcd, Server and Agent configuration, certificates, and persistent authentication keys. Verify recovery. Back up managed-cluster data separately.
5. Rehearse the target upgrade path in a recoverable test environment and record interruption and recovery steps.

kcctl version
kcctl status
kcctl doctor
kcctl operation list
kcctl upgrade -h

Upgrade

kcctl upgrade supports platform and component upgrades. Use a package with the structure described in command help that you have validated in a test environment. Client archives are not platform upgrade packages.

UPGRADE_PACKAGE=/path/to/validated-upgrade-package.tar.gz
kcctl upgrade all --pkg "$UPGRADE_PACKAGE"

Use online upgrades or individual component replacement only when the release or your validated deployment procedure supports them. Replacing one binary does not establish that the whole platform upgrade succeeded.

After upgrading

Repeat kcctl status and kcctl doctor and verify versions running on every node. Check login, node data, operation details and logs, managed-cluster access, and basic Console flows. Exercise a controlled lifecycle operation and compare the Operation result with actual cluster state.

Preserve errors and logs on failure and follow the recovery procedure tested beforehand. Check data and configuration compatibility before restoring old binaries; do not repeatedly overwrite services in an unknown state.

4 - Tutorials

4.1 - Create clusters

Before creating a cluster, confirm the platform is healthy, nodes are registered and ready, and resource versions match node architecture. Complete Getting started to validate the deployment path.

Create in the Console

Create a cluster from the cluster page. Set a name, control-plane and worker nodes, component versions, and Pod / Service CIDRs that fit your network. Plan control-plane availability, API access, and storage for production deployments; a single-node lab configuration is insufficient.

Use the 1.7 component matrix. Upload missing resources first. See Registry for private image settings; image registries and component packages serve different purposes.

CLI and verification

Offline cluster creation includes a CLI example with explicit versions. After submitting the request, inspect the Operation and confirm cluster state, Ready nodes, system Pods, and Kubernetes API health. Preserve logs when troubleshooting; resetting state does not resolve failed installation steps.

4.2 - Cluster hosting

Kubeadm cluster hosting

For a host cluster created and managed by kubeadm, kubeclipper gets the cluster and node information from the kubeconfig file and imports it into the kubeclipper platform.

Click “Cluster Management” > “Cluster Hosting” button to enter the cluster hosting page. Click “Add” button at the upper left corner. In the pop-up window of Add Provider, fill in the provider name (such as kubeadm-demo) and description, and then fill in the following information:

• Region: The region of the cluster and node in the kubeclipper platform.

• Provider type: Select kubeadm.

• SSH: Specifies the connection method of cluster nodes. Private Key or Password can be selected. Ensure that all cluster nodes can be connected through the selected method.

  • Private Key: enter the node user name and private key information.
  • Password: enter the node user name and password.

• Cluster name: Specifies the display name on the platform and cannot be the same as any other clusters.

• KubeConfig: The KubeConfig file of the host cluster.

Click the “OK” button to import the cluster and node into the platform. Click the provider name (kubeadm-demo) to enter the Provider detail page, where you can view the cluster under the provider and perform the following operations on the provider:

• Synchronization: Kubeclipper synchronizes cluster information every four hours. You can also click “Synchronize” to manually perform the operation.
• Edit: Edit the provider’s name, description, access information, and node connection method.
• Remove: Detach platform management while preserving Kubernetes itself. Cleanup also removes imported kc-agent installations and platform-created ServiceAccount, ClusterRoleBinding, and kubectl terminal resources. Previously managed nodes follow separate preservation rules. Check node ownership and retain kubeconfig before removal.

Managed cluster management

You can choose “Cluster Management” > “Cluster” to go to the cluster list page and view the list of all clusters, including hosted clusters and local clusters. The following table lists the operations supported by different clusters:

Image sources for plug-ins and external storage depend on the selected component package and configuration. Prepare images before offline installation and confirm that every node can pull them. Configure the CRI registry first when authentication or a private CA is required.

4.3 - Cluster management

KubeClipper 1.7 executes cluster lifecycle work through Operation v2. Inspect the cluster object, then confirm outcomes using operation details and actual nodes.

kcctl get cluster
kcctl get cluster demo -o yaml
kcctl operation list -c demo

Logs, retries, and cancellation

See operations and logs for commands. Resolve the cause of a failure before retrying. Resetting cluster state does not repair nodes or undo completed work.

Access a cluster

Obtain kubeconfig from the Console cluster details page, set KUBECONFIG, and run:

kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

Healthy platform status does not establish the health of every managed cluster. After upgrades, scaling, backup, or recovery, inspect the relevant nodes, system Pods, and application data.

Scaling and registries

Use kcctl join to register new machines with the platform. Confirm that nodes are Ready and in the cluster’s region before adding them from the cluster details page. Evacuate workloads and check remaining capacity before removing cluster nodes. Platform kcctl drain removes an Agent; it is a separate operation from shrinking a cluster. See node management.

Configure Kubernetes image repositories and containerd pull registries separately. See registries and verify actual image pulls after changes.

Backup and restore

1. Configure a backup space and associate it with the cluster through the edit action. For directory backup spaces, create and mount the agreed path on the relevant nodes and confirm write access.
2. Start a backup, or configure a scheduled backup with its execution time and retention count. Confirm successful backup status and readable files.
3. Select a backup belonging to the cluster for restoration. Follow its Operation, then check the API, nodes, system Pods, and application state.

Cluster backups center on Kubernetes etcd snapshots. They do not include application files in persistent volumes; back up those separately. Restoration changes cluster state. Rehearse in an isolated environment: the existence of a backup record alone does not establish recoverability.

Upgrade Kubernetes

Kubernetes upgrades are separate from KubeClipper platform upgrades. Back up the cluster, validate restoration, and check target component resources, images, and workload compatibility before selecting a target in the cluster upgrade action. This action is unavailable for hosted kubeadm clusters.

Inspect the CLI parameters with:

kcctl cluster upgrade --help

Use --cluster-name and --version to select the cluster and target. Offline mode is the default; --online selects online mode and --image-registry selects a configured Registry resource. The target must exist in platform resources. The support matrix does not guarantee successful upgrades between every listed version. Follow the resulting Operation and repeat the cluster health checks above.

Delete a cluster

Back up workloads and data before deletion, then follow the Operation:

kcctl delete cluster demo
kcctl operation list -c demo
kcctl get cluster

Confirm deletion has finished before reusing nodes. Preserve errors and node state for diagnostics; forced deletion does not establish that cleanup completed.

4.4 - Node management

Region management

KubeClipper supports multi-region management. That is, all nodes and clusters managed by the platform are divided into physical or logical regions. On the Region Management page, you can view all regions in the platform. Click a region name to enter the region detail page, and you can view the clusters and nodes in the region.

Node management

The platform supports multi-region management, that is, the owning region of all nodes managed by the platform. On the Region Management page, you can view all regions managed by the platform. Click a region name to go to the region details page, where you can view the list of all clusters and nodes in the region.

On the “Node Info” page, you can view the list of all nodes managed in the platform, node specifications, status and other information. Click the node name to enter the node detail page, you can view detailed node basic information and system information.

The node status in KubeClipper represents the management status of the node by kc-agent. Under normal circumstances, the node status is displayed as “Ready”. The default monitoring grace period is 4 minutes, checked every 10 seconds. After the grace period, the status changes to “Unknown”; scheduling or communication delays can affect when the change becomes visible. Investigate the Agent, network, and Server connectivity before scheduling new cluster installation or expansion on an unknown node.

Add node

When deploying KubeClipper, you can add the initial server nodes which are used to deploy KubeClipper's own services, and agent nodes which are used to deploy kubernetes clusters. In a KubeClipper environment for experimentation or development, you can add a server node as an agent node at the same time. However, if it is used for a production environment, it is recommended not to reuse the server node as an agent node.

You can also use the kcctl join command to add agent nodes to KubeClipper, and mark a region for each agent node. The region can be a physical or logical location. You can use nodes in the same region to create a kubernetes cluster, but cannot use nodes across regions to create a cluster. Nodes in unmarked regions belong to the default region.

Command line example:

kcctl join --agent beijing:1.2.3.4 --agent shanghai:2.3.4.5

Remove node

When you no longer need some nodes, you can use the kcctl drain command to remove nodes from the platform.

Command line example:

kcctl drain --agent 192.168.10.19

Connect Terminal

On the node list page, you can click the “Connect Terminal” button on the right side of the target node, enter the node port and username password information in the pop-up window, access the node SSH console and execute command tasks.

Enable/disable a node

You can click the Disable button on the right side of the node to temporarily disable the node. The node in the disabled state cannot be created or added to the cluster.

4.5 - Access control

Create user

After installing KubeClipper, you need to create a user of a desired role. Initially, there is only one user, admin, by default, with the platform administrator role.

Click “Access Control” > “Users” to enter the user management page, click the “Create User” button in the upper left corner, fill in the user name, password, alias name and other information in the pop-up window, specify the user role, and click the “OK” button. The four initial roles in the system are as follows:

• platform-admin: Platform administrator, with the authority to set platform, cluster management, user management, audit, etc.

• cluster-manager: Cluster administrator, with all cluster management permissions.

• iam-manager: User administrator, with all user management permissions.

• platform-view: Platform read-only user, with all platform viewing permissions.

After the user is created, you can view the user details and login logs on the user detail page and perform the following operations:

• Edit: Edit user alias, role, mobile phone number, email information.

• Edit Password: Edit the user login password.

• Delete: Delete the user.

Create a custom role

In addition to system initial roles, you can also create customized roles to meet business needs.

Click “Access Control” > “Roles” to enter the role management page. You can click the “Create Role” button in the upper left corner to create a custom role.

On the Create Role page, you need to fill in the role name and description, and check the permissions required. Some permissions depend on other permissions. When these permissions are selected, the dependent permissions will be automatically selected.

After creating a customized role, you can view the basic role information, role permission list, authorized user list on the role detail page, and perform the following operations:

• Edit: Edit the custom role description.

• Edit permissions: Edit permissions of the customized role.

• Delete: To delete a customized role, make sure that no user is using the role to be deleted.

Access to external users

External users can log in to KubeClipper via the OIDC protocol .

First, the platform administrator needs to log in to the platform server node and insert the following information under “authentication” in the kubeclipper-server.yaml file:

oauthOptions:
    identityProviders:
    - name: keycloak
      type: OIDC
      mappingMethod: auto
      provider:
        clientID: kc
        clientSecret: REPLACE_WITH_CLIENT_SECRET
        issuer: https://idp.example.com/realms/kubeclipper
        scopes:
        - openid
        - email
        redirectURL: https://console.example.com/oauth2/redirect/keycloak

Merge this fragment under authentication in the existing configuration. Replace the example domains and REPLACE_WITH_CLIENT_SECRET. Register exactly the same redirectURL with the IdP; its final path component must match the provider name. Update each Server and restart kc-server one node at a time.

Under “provider”, you need to fill in the clientID , clientSecret , and issuer information of your OAuth2 service, taking keycloak as an example, as shown in the figure below.

RedirectURL example: https://console.example.com/oauth2/redirect/keycloak

OAuth2 users can log in to the KubeClipper platform by following these steps:

1. Click the “OAuth2 Login” button on the login page, enter the OAuth2 login page, fill in the username and password to enter the KubeClipper platform. When logging in for the first time, you will not be able to access the platform because you have not been granted any permission.

2. The platform administrator or other user with user management rights log in to KubeClipper, find the target OAuth2 user on the user management page, and set the user role by editing the user information.

3. The OAuth2 user repeats the first step, logs in to KubeClipper, and accesses the platform normally.

4.6 - Operations and logs

KubeClipper 1.7 represents installation, upgrades, backup, and deletion as Operations, with Tasks assigned by step and node. A successful submission means the request was accepted; query its result afterward.

Find an operation

kcctl operation list
kcctl operation list -c demo

Copy an actual operation ID from the list, then inspect details and logs:

OPERATION_ID='<actual operation ID>'
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow

Use logs to identify the failed step and node. In an interactive terminal, open the cluster’s TUI log viewer:

kcctl operation logs --cluster demo

Use the operation-ID commands for plain-text logs in scripts and non-interactive terminals.

Handle a failure

Preserve operation details, failed-node logs, and cluster state. Resolve the missing package, image download, node connectivity, or service problem before retrying:

kcctl operation retry "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow

Check actual cluster and node state after the retry. Its command return value alone does not establish recovery. If parameters are wrong, review the task configuration rather than retrying repeatedly.

Cancel work

kcctl operation cancel "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"

Cancellation does not roll back installation or data changes that have already happened. Confirm tasks have stopped and inspect existing changes on the nodes before cleanup.

Confirm the result

Check the Operation result, kcctl get cluster demo -o yaml, Kubernetes nodes, and system Pods together. After cluster deletion, check the platform list and node residue. See platform diagnostics for platform-level issues.

4.7 - Platform diagnostics

Locate the failing layer first: the platform, Agent, resource downloads, or the Kubernetes cluster.

Platform health

kcctl version
kcctl status
kcctl status -o json
kcctl doctor

status summarizes kc-server, kc-etcd, and kc-agent health. doctor checks local access, services, platform etcd, and Agents, with evidence for failed checks. Unhealthy results return a nonzero exit code for scripting. Neither command repairs the environment.

If the API cannot be reached, check that kcctl login points to the HTTPS API endpoint, normally port 8080. Inspect local login and deployment configuration and SSH connectivity from the deployment host.

Node services

Run on the relevant Linux node:

sudo systemctl status kc-server kc-etcd kc-agent --no-pager
sudo journalctl -u kc-server -n 100 --no-pager
sudo journalctl -u kc-agent -n 100 --no-pager

An Agent-only node is not expected to run a Server or platform etcd. Interpret service results according to node roles. Check disk space, clock synchronization, management addresses, and firewall rules.

Deployment failures

Precheck errors identify the check and node. If services already exist, establish whether they belong to an active platform before changing anything. For download failures, verify the URL, certificate, file size, and archive contents. Do not hide certificate failures by disabling verification.

Cluster task failures

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node
kcctl resource list

Use operations and logs to locate the failing step and node. Check package versions and architectures for offline installation. For image pull failures, check the registry address, credentials, and connectivity. Include versions, topology, sanitized errors, and operation IDs in an issue; remove passwords, tokens, private keys, and kubeconfig credentials.

4.8 - Image registries

A Registry resource describes a Kubernetes image source or adds image-pull configuration to containerd. It is separate from platform offline resource packages. Creating a Registry does not copy images into it.

Create a Registry

The following example describes an HTTP registry on a management network. Configure HTTPS, CA trust, and authentication for your actual registry; consult command help for all flags.

kcctl create registry --name internal --host registry.example.com:5000 --scheme http
kcctl get registry
kcctl create registry -h

Authentication uses --auth-username and --auth-password; protect credentials from shell history and terminal logs. For HTTPS, review --ca and --skip-tls-verify instead of reusing the HTTP example unchanged.

Select a registry for a cluster

kcctl create cluster --name demo --master 192.168.10.21 \
  --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
  --cni calico --cni-version v3.31.5 \
  --image-registry internal --cri-registry internal

• --image-registry selects a Registry resource for Kubernetes images.
• --cri-registry adds Registry configuration to containerd; select multiple resources as needed.
• Without an explicit image registry, components use their own defaults and applicable Agent image-mirror settings. Kubernetes and Calico do not necessarily use the same default repository.

Populate the registry with the required images first. Check actual image paths, authentication, certificates, and connectivity from cluster nodes. Offline installation also needs the resource packages.

5 - FAQ

5.1 - Cluster creation troubleshooting

This page applies to 1.7. Older v1.2.1 Calico download workarounds do not apply directly to this release.

Cluster not Ready after submission

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node

Inspect operation details and logs next. Request acceptance, operation completion, and Kubernetes node readiness are separate checks.

Offline package or image errors

Use kcctl resource list to confirm version and architecture. Inspect image paths, authentication, and connectivity using the failed step’s logs. See offline clusters.

Platform or Agent errors

Run kcctl status and kcctl doctor to check API access, services, and SSH connectivity. Supply an SSH private key as deployment credentials, not a public key path.

See platform diagnostics for the investigation sequence and operations and logs for retries and cancellation.

6 - Contribution Guidelines

The documentation lives in kubeclipper.github.io, with Chinese and English content in content/zh-cn and content/en. Update both languages when practical; otherwise, note the translation gap in your pull request.

1. Fork the documentation repository and edit the relevant page. Base version and feature claims on released software.
2. Follow the repository README to install dependencies and preview locally. Run make check to build all versions and check local links.
3. Open a pull request describing the pages changed, evidence for technical claims, and local check results. For a substantial user-facing change, add a short project update.
4. After merge and publication, check the live pages and navigation. A passing build alone does not establish that the site has updated.

If you cannot make a correction yet, open a documentation issue. Report software issues in the project repository.