Deployment docs

• 1: High availability
• 2: Upgrade checklist

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.

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.