Documentation

• 1: 1.6 release guide
• 2: Getting started
• 3: Tutorials
• 3.1: Operations and logs
• 3.2: Image registries
• 3.3: Diagnostics and upgrade checks

1 - 1.6 release guide

KubeClipper v1.6.0 was released on June 2, 2026 as a stable release. Release · Full changelog.

Included changes

• containerd 2 and Calico v3.31.5 support, with an updated Kubernetes matrix.
• Improved Operation commands and logs, including a cluster-wide TUI.
• kcctl set cluster for external cluster access configuration.
• Persistent registry configuration and fixes that preserve existing containerd configuration when updating registry authentication.

Component matrix

Source: v1.6.0 README. Available resources also depend on the uploaded versions and architecture.

Architecture and default ports

1.6 consists of kc-server, kc-agent, kcctl, Console, and platform etcd. It distributes tasks using built-in or external NATS. This differs from the API-driven Operation v2 architecture in 1.7.

Restrict management access and check your actual deployment configuration. Sources: v1.6.0 deployment options.

Command differences from 1.7

• 1.6 uses kcctl operation terminate; 1.7 uses cancel.
• 1.6 does not provide kcctl status or kcctl doctor; inspect node services and logs instead.
• Use the 1.6 matrix, NATS configuration, and task model with 1.6 binaries.

2 - Getting started

Run this example in Bash on a Linux amd64 deployment machine, using v1.6.0 binaries and the full deployment package. Prepare Linux nodes with systemd, SSH access, sudo permissions, and synchronized clocks. Check Kubernetes kernel, cgroup, and disk requirements.

Install the client

The old installer at the 1.6 tag uses oss.kubeclipper.io, whose certificate has expired. Download directly from GitHub Release while keeping certificate verification enabled.

curl -fL -o kc-linux-amd64-v1.6.0.tar.gz \
  https://github.com/kubeclipper/kubeclipper/releases/download/v1.6.0/kc-linux-amd64.tar.gz
mkdir -p kc-client-v1.6.0
tar -xzf kc-linux-amd64-v1.6.0.tar.gz -C kc-client-v1.6.0
sudo install -m 0755 kc-client-v1.6.0/kcctl /usr/local/bin/kcctl
kcctl version

Select other client architectures from the 1.6 Release. arm64 archives contain an architecture subdirectory; inspect paths with tar -tzf before installing.

Download the full package and deploy

The client archive is not the deployment package. Use the native OSS endpoint below. Full packages are available for amd64 and arm64.

curl -fL -o kc-amd64-v1.6.0.tar.gz \
  https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/release/v1.6.0/kc-amd64.tar.gz
read -r -s -p 'Set admin password: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy --user root --pk-file "$HOME/.ssh/id_rsa" \
  --pkg "$PWD/kc-amd64-v1.6.0.tar.gz" \
  --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

Use an SSH private key that can access the nodes. The password must contain 8–16 characters, including uppercase and lowercase letters and digits. Consult kcctl deploy -h for multi-node options. Keep API and NATS TLS enabled.

Log in and create a cluster

Replace Server and node addresses. Login prompts for the admin password. The Console uses http://SERVER_IP; the CLI uses the HTTPS API.

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

Confirm resource versions and architecture before creating a single-node lab cluster:

NODE=192.168.10.10
kcctl create cluster --name demo --master "$NODE" --untaint-master \
  --k8s-version v1.36.1 --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

Obtain kubeconfig from cluster details. Verify kubectl get nodes -o wide, kubectl get pods -A, and kubectl get --raw='/readyz?verbose'. See operations and logs for troubleshooting.

3 - Tutorials

Operations, registries, and maintenance for 1.6.

3.1 - Operations and logs

1.6 Operations use the older task model and NATS. List operations, then copy the actual ID to inspect details and logs:

kcctl operation list
kcctl operation list -c demo
OPERATION_ID='<actual operation ID>'
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow
kcctl operation logs "$OPERATION_ID" --summary

Open the cluster-wide TUI in an interactive terminal:

kcctl operation logs --cluster demo

Preserve failed-step and node logs and resolve the cause before retrying. 1.6 only retries operations in failed status:

kcctl operation retry "$OPERATION_ID"

Use terminate for running operations, rather than the 1.7 cancel command:

kcctl operation terminate "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"

A termination request does not roll back node changes. Inspect task, cluster, and node state before cleanup. Source: v1.6.0 Operation CLI.

3.2 - Image registries

Registry resources describe Kubernetes image sources or containerd pull settings. Registering a registry does not copy images into it. Offline component packages are prepared separately.

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

This example uses an HTTP registry on a management network. Configure HTTPS, CA trust, and authentication for production. 1.6 also persists node and SSH configuration for kcctl registry; check existing configuration before subsequent operations.

During cluster creation, --image-registry internal selects the Kubernetes image source, and --cri-registry internal configures containerd pulls. Populate images first and verify node connectivity, certificates, and authentication. Source: v1.6.0 Registry CLI.

3.3 - Diagnostics and upgrade checks

1.6 does not include the 1.7 kcctl status and kcctl doctor commands. Start with versions, API access, node services, and operation logs.

kcctl version
kcctl get node
kcctl get cluster
kcctl operation list
kcctl resource list

Inspect services according to each Linux node’s role. Diagnose NATS, platform etcd, and Server failures separately.

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

Agent nodes may not run Server, etcd, or NATS. External NATS deployments have no local kc-nats service. Check actual roles and deployment configuration.

Before upgrading to 1.7

Back up platform etcd, configuration, certificates, authentication keys, and managed-cluster data. Rehearse the upgrade in a recoverable test environment, checking the NATS to Operation v2 transition, active tasks, and old operation records. Consult the 1.7 upgrade checklist and verify versions running across all components.

This page does not guarantee an in-place upgrade for every 1.6 deployment. Preserve errors and follow the recovery steps you rehearsed.