kctl CLI reference

kctl is the command-line interface for managing kcore clusters. Global flags: -s / --controller (controller address, repeatable for HA), -k / --insecure (skip TLS verification), -c / --config (path to config file), --node (node address for direct node commands).

You are browsing in YAML mode. This page lists CLI commands; for manifest kinds and fields see the YAML manifest reference.

This page is the kctl reference. Terraform examples are on the task pages, such as VM creation.

create

kctl create is idempotent. Re-running the same command (or re-applying the same manifest with -f) performs a server-side upsert: it creates the resource if missing, updates mutable fields if they drifted, rejects changes to immutable fields with InvalidArgument, or prints unchanged when the stored state already matches. See Idempotency and upsert for the mutable/immutable field tables.

kctl create vm accepts --extra-network (repeatable), --label key=value (repeatable), and --anti-affinity <group>. kctl create network accepts --ipv6-prefix, --ipv6-gateway, and --east-west-firewall. See Networks and VM creation.

get

Filters worth knowing: audit-events takes --limit (default 100), --action for an exact action name, and --since for an RFC 3339 timestamp. vms, networks and disk-layouts take --target-node. crl takes -o to write the CRL to a file. sbom takes --kind crates|iso-closure and -o to write the CycloneDX document.

describe

describe disk-layout <name> shows the current generation, the observed status reported by the node, and the layout body. See Day-2 operations and kcore SAN (Ceph).

delete

vm and network take --target-node when the name exists on more than one node. image and container take --force.

start / stop

set

update

node

pull

ssh-key

operator

Operators are named RBAC identities, each with its own client certificate under CN=kctl:<name>. Every subcommand here needs cluster-admin.

Removing a role is not the same as revoking the certificate. revoke-role changes what an identity is allowed to do; the certificate itself stays valid until you revoke it with kctl revoke cert --subject kctl:<name>. Revocation takes effect on the next RPC the operator makes, not during the TLS handshake. See certificates & encryption.

gpu

drain

migrate

A receive session outlives its migration if the controller dies mid-flight, and every later migration of that VM to that node then fails with ALREADY_EXISTS. Nothing clears it automatically. Inspect first with kctl get migrate-session <vm> (read-only; queries every CephCluster member unless you pass --node), then clear with kctl migrate reset-session <vm> --node <id> --force. Clearing a session whose receive VMM is still alive kills an in-flight migration. See VM migration.

rotate

revoke

kubernetes

kctl kubernetes plans and applies a KubernetesCluster manifest. Needs cluster-admin. The API VIP, Cilium L2, and volumes are on the Kubernetes page.

apply

Apply a NixOS configuration to the controller. Flags: -f (config file), --dry-run (preview without applying).

diff

Show what applying a manifest would change, without changing anything. -f / --filename is required. Only kind: DiskLayout is supported today — any other kind exits with an error rather than guessing. See Day-2 operations.

version

Print the kctl client version. Takes no flags and does not contact a controller.

console

kctl console <vm> attaches to a VM's serial console through the controller. Press Ctrl-] then Enter to detach. Needs vm-admin, and every attach is recorded in the audit log as AttachVmConsole with the actor, the VM and the timestamp.

This is a serial console, so it is the right tool for a CLI login, rescue, or watching an installer. kcore does not provide a hypervisor-level graphical console; if you need a desktop, run a VNC server inside the guest and reach it over the network. The dashboard exposes the same console in a browser.

workload

security-group (alias: sg)