CLI Reference

Complete reference for the kubectl-unbounded plugin commands.

Overview

kubectl-unbounded is a kubectl plugin that extends kubectl with commands for managing Unbounded sites. Once installed, commands are available as:

kubectl unbounded <command>

The plugin binary can also be invoked directly as kubectl-unbounded.

Installation

Download the plugin binary from the GitHub releases page and place it on your PATH. kubectl automatically discovers plugins named kubectl-<name>.

You can also install via Krew:

kubectl krew install unbounded

Global Behavior

All commands that interact with the cluster accept a --kubeconfig flag. If omitted, the plugin falls back to the KUBECONFIG environment variable. If neither is set, the default kubeconfig location (~/.kube/config) is used.

Commands

kubectl unbounded site

Manage Unbounded sites.

This is a command group with no action of its own. Use one of the subcommands below.

kubectl unbounded install

Bootstrap a cluster with the Unbounded CRDs and unbounded-operator. This command applies the operator manifests and waits for the operator to roll out. The operator itself installs and upgrades the machina and net CRDs at startup, so install no longer applies CRDs directly. It does not deploy component workloads directly; the operator reconciles those from Site.spec.components after Sites are created or updated.

kubectl unbounded install

Optional flags:

Breaking change: the --skip-crds flag has been removed. CRDs are now owned and installed by the operator at startup (operator.BootstrapCRDs), so there is nothing for install to skip. Automation passing --skip-crds must drop it.

--operator-image overrides the operator image. --image-registry configures the registry for components; their image tag always matches the operator’s compiled version.

kubectl unbounded site init

Initialize a new Unbounded site. This command:

1. Validates inputs and kubeconfig access.
2. Bootstraps CRDs and unbounded-operator unless --skip-install is set.
3. Creates a cluster Site, a remote Site, and related net GatewayPool resources.
4. Records component choices in Site.spec.components for unbounded-operator.
5. Creates a bootstrap token for the remote site.

Global components (unbounded-net, machina, and unbounded-storage) are enabled on the cluster Site. metalman is per-site and is enabled on the remote Site when --enable-metalman is set.

Required Flags

Optional Flags

Validation

• All CIDR values must be valid IPv4 CIDR notation.
• The kubeconfig must be readable.

Example

kubectl unbounded site init \
  --name my-edge-site \
  --cluster-node-cidr 10.224.0.0/16 \
  --cluster-pod-cidr 10.244.0.0/16 \
  --node-cidr 10.100.0.0/24 \
  --pod-cidr 10.101.0.0/24

With optional components:

kubectl unbounded site init \
  --name dc2 \
  --cluster-node-cidr 10.224.0.0/16 \
  --cluster-pod-cidr 10.244.0.0/16 \
  --node-cidr 10.200.0.0/24 \
  --pod-cidr 10.201.0.0/24 \
  --enable-metalman \
  --enable-storage \
  --kubeconfig ~/.kube/config

kubectl unbounded machine

Manage Unbounded machines.

This is a command group with no action of its own. Use one of the subcommands below.

kubectl unbounded machine register

Register a machine to an existing site. This command:

1. Creates a Kubernetes Secret containing the SSH private key.
2. Optionally creates a separate Secret for bastion SSH credentials.
3. Resolves the bootstrap token created by site init.
4. Detects the cluster’s Kubernetes version.
5. Creates a Machine custom resource with SSH and Kubernetes configuration.

Required Flags

Optional Flags

Default Derivation

• Machine name: If --name is omitted, it is derived from --host by replacing dots and colons with hyphens, then prefixed with the site name. For example, --site dc1 --host 10.0.0.5:2222 produces the machine name dc1-10-0-0-5-2222.
• Bastion credentials: Bastion SSH username, key, and secret name all default to the corresponding non-bastion values.

Validation

• --site, --host, and --ssh-username must be non-empty.
• --ssh-private-key is required when no bastion flags are specified.
• Key files (both --ssh-private-key and --bastion-ssh-private-key) must be readable if provided.

Examples

Direct SSH:

kubectl unbounded machine register \
  --site dc1 \
  --host 10.0.0.5 \
  --ssh-username admin \
  --ssh-private-key ~/.ssh/id_ed25519

With explicit machine name:

kubectl unbounded machine register \
  --site dc1 \
  --name worker-1 \
  --host 10.0.0.5 \
  --ssh-username admin \
  --ssh-private-key ~/.ssh/id_ed25519

With bastion (shared credentials):

kubectl unbounded machine register \
  --site dc1 \
  --host 10.0.0.5:2222 \
  --ssh-username admin \
  --ssh-private-key ~/.ssh/id_ed25519 \
  --bastion-host 5.6.7.8

With bastion (separate credentials):

kubectl unbounded machine register \
  --site dc1 \
  --host 10.0.0.5 \
  --ssh-username admin \
  --ssh-private-key ~/.ssh/host_key \
  --bastion-host 5.6.7.8 \
  --bastion-ssh-username bastion-user \
  --bastion-ssh-private-key ~/.ssh/bastion_key \
  --bastion-ssh-secret-name bastion-ssh

kubectl unbounded machine operation

Create and watch MachineOperation resources.

This command group is the resource-oriented surface for day-2 machine operations. It creates the same MachineOperation CRD you can manage directly with kubectl get mop, kubectl describe mop, and kubectl delete mop.

kubectl unbounded machine operation create

Create a MachineOperation.

Required Arguments and Flags

AgentUpgrade also requires --param downloadURL=<url>.

Optional Flags

--wait streams progress output and can only be used with the default -o name output.

Examples

Create a host reboot operation:

kubectl unbounded machine operation create reboot-worker-01 \
  --kind HostReboot \
  --machine worker-01

Create and wait for a node reboot operation selected by labels:

kubectl unbounded machine operation create reboot-gpu \
  --kind NodeReboot \
  --selector role=gpu \
  --wait

Generate YAML without creating the operation:

kubectl unbounded machine operation create poweroff-worker-01 \
  --kind HostPowerOff \
  --machine worker-01 \
  --dry-run=client \
  -o yaml

Upgrade the agent:

kubectl unbounded machine operation create upgrade-worker-01 \
  --kind AgentUpgrade \
  --machine worker-01 \
  --param downloadURL=https://example.com/unbounded-agent-linux-amd64.tar.gz

Selector support is implemented at the CRD level. Agent operations support selectors. Metalman bare-metal host operations support selectors when the selector includes unbounded-cloud.io/site=<site>. Cloud VM host operations currently require one operation per Machine.

kubectl unbounded machine operation wait

Wait for an existing MachineOperation to reach Complete or Failed.

kubectl unbounded machine operation wait reboot-worker-01 --timeout 5m

Use native kubectl commands for listing and inspection:

kubectl get mop
kubectl describe mop reboot-worker-01
kubectl get mop reboot-worker-01 -o yaml

Machine Operation Convenience Commands

Convenience commands create a MachineOperation with a generated operation name, default --ttl 300, and --wait=true.

Common flags:

Legacy Machine Operation Commands

The older counter-backed commands remain available for compatibility:

These commands do not create MachineOperation resources.

Environment Variables

See Also

• Getting Started – Walks through site init and machine register step by step.
• SSH Guide – Detailed SSH provisioning walkthrough with examples.
• CRD Reference – Full Machine and Image API specification.