> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Management plane

> Run your own control layer for Kubernetes clusters, inside your boundary.

A management plane builds your clusters and keeps track of them. It is what [`kubox cluster create`](/reference/cli/kubox_cluster_create) talks to.

You do not need your own to start — the managed console runs one for you. Run your own when the control layer has to sit inside your boundary. That is one less vendor for a security team to sign off.

## Who runs one

One plane, many independent clusters. Two kinds of team want that shape:

<CardGroup cols={2}>
  <Card title="SaaS providers" icon="building">
    Run your software in a customer's own AWS account when they ask. Each customer gets their own cluster, isolated from the rest.
  </Card>

  <Card title="Platform teams" icon="users">
    Hand clusters to internal teams without becoming the bottleneck.
  </Card>
</CardGroup>

<Note>
  Your workloads keep running if the plane is unavailable. It builds and tracks clusters; it is not in their traffic path.
</Note>

## Sizing one

A plane runs two pools of machines, and they grow for different reasons:

| Pool | Grows with |
| - | - |
| **System** | How many clusters you are watching |
| **Runner** | How many builds are running at once |

Keeping them separate is what stops a busy build queue from resizing everything.

```bash theme={null}
kubox plane profiles
```

Shows the sizes you can choose and what each one asks for. See [`kubox plane profiles`](/reference/cli/kubox_plane_profiles).

## Where it runs

Install a plane into any Kubernetes cluster you can reach — EKS, GKE, kind, or one Kubox built. You need nothing installed but the `kubox` binary.

<Note>
  The plane can run anywhere, but it builds in AWS. Run [`kubox admin aws bootstrap`](/reference/cli/kubox_admin_aws_bootstrap) in the AWS account it builds from, wherever the plane itself lives.
</Note>

## Building one

One document describes a plane. One command builds it.

```bash theme={null}
kubox plane create -f plane.yaml
```

The command checks your account, DNS zone, image, bucket, and keys **before** it builds anything. If a check fails, nothing is created.

<Tip>
  Add `--plan` to see what it would build, without building it.
</Tip>

If the install step fails after the cluster is built, you do not start over. The command prints a file path; pass that file to [`kubox admin install`](/reference/cli/kubox_admin_install) to finish the job.

## Changing one

Two commands, and the difference matters.

<CardGroup cols={2}>
  <Card title="Upgrade" icon="arrow-up" href="/reference/cli/kubox_plane_upgrade">
    Moves the plane to a new release. Your clusters, state, keys, and connected accounts are untouched.
  </Card>

  <Card title="Rebuild" icon="arrows-rotate" href="/reference/cli/kubox_plane_rebuild">
    Replaces the plane. Everything it manages keeps running.
  </Card>
</CardGroup>

`kubox plane upgrade` refuses if the cluster underneath would have to change. It tells you what differs and sends you to `rebuild`. An upgrade never turns into a rebuild without asking you.

## Checking one

Two commands answer different questions.

```bash theme={null}
kubox plane status   # what the plane says about itself
kubox plane verify   # whether that is still true
```

`status` repeats what the plane last recorded. [`verify`](/reference/cli/kubox_plane_verify) checks it against the real world. It asks three questions:

* Can the plane reach its state?
* Are its two keys actually separate?
* Does each identity hold the access it should, **and nothing more**?

The last one matters most. An identity that has quietly gained extra access passes every other test.

```bash theme={null}
kubox plane capacity
```

Shows how loaded each pool is, so you know when to resize. See [`kubox plane capacity`](/reference/cli/kubox_plane_capacity).

## Deleting one

```bash theme={null}
kubox plane delete -f plane.yaml
```

Deletes the plane only. Clusters it built keep running — they just stop being tracked.

## Related

<CardGroup cols={3}>
  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    How planes, accounts, and clusters fit together.
  </Card>

  <Card title="Cloud accounts" icon="shield-halved" href="/concepts/cloud-accounts">
    What the plane may do in your AWS account.
  </Card>

  <Card title="Plane documents" icon="file-code" href="/reference/config/plane">
    Every field of `plane.yaml`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.