# Kubernetes

Source: https://docs.quake.ai/docs/kubernetes
Markdown: https://docs.quake.ai/docs/kubernetes.md
> Provision Kubernetes clusters on Quake AI from reusable templates: the platform creates master nodes, worker nodes, and networking with Magnum.

---

# Kubernetes

The Kubernetes service automates cluster provisioning on Quake AI. You define the node sizes, network driver, and Kubernetes version through a reusable template, and the platform provisions master nodes, worker nodes, and the networking between them using existing Compute, Network, and Storage infrastructure.

[OpenStack Magnum](https://docs.openstack.org/magnum/latest/) backs Kubernetes. For details on how Quake AI implements OpenStack, see [How Quake AI uses OpenStack](/docs/platform/migration/openstack).



The Kubernetes service provisions clusters from a reusable template. It creates the VMs, the networking between them, and a stable control-plane endpoint you point `kubectl` at.

Master nodes run inside your project as Compute instances, so you can see the control-plane resources, spread them across hosts with anti-affinity server groups, take your own etcd backups, and choose when to upgrade. Your team operates the control plane.



## Start here

First follow [Create a cluster template](/docs/kubernetes/how-to/create-cluster-template) to record the Kubernetes version, node flavors, and drivers you want. Then follow [Create a Kubernetes cluster](/docs/kubernetes/how-to/create-cluster) to provision masters and workers from that template.

## Choose a pattern

| Pattern | Use it when |
| --- | --- |
| [Create a cluster template](/docs/kubernetes/how-to/create-cluster-template) | You need a reusable blueprint for version, flavors, and network driver. |
| [Create a Kubernetes cluster](/docs/kubernetes/how-to/create-cluster) | The template exists and you are ready to provision masters and workers. |
| [Kubernetes cluster template](/build/iac-templates/k8s-cluster) | You want to create the same cluster from an OpenTofu configuration you keep in git. |

## How it works

<Figure size="md" caption="Kubernetes architecture: a cluster template provisions a control plane and worker plane on Compute, with Network and Storage attached.">

```d2
template: Cluster Template {
  spec: "Image\nFlavor\nK8s version\nNetwork driver\nVolume driver"
}

cluster: Kubernetes Cluster {
  control: Control Plane {
    api: API server
    sched: Scheduler
    cm: Controller manager
    etcd: etcd
  }
  workers: Worker Plane {
    w1: "Worker node\nkubelet + runtime"
    w2: "Worker node\nkubelet + runtime"
  }
  control.api -> workers.w1
  control.api -> workers.w2
}

infra: Quake AI Infrastructure {
  compute: Compute (VMs)
  net: Network (CNI, LB, FIP)
  store: Storage (volumes)
}

user: Operator {
  shape: person
}

template -> cluster: provisions
cluster.control -> infra.compute: runs on
cluster.workers -> infra.compute: runs on
cluster.workers -> infra.net: pod + service network
cluster.workers -> infra.store: persistent volumes
user -> cluster.control.api: kubectl
```

</Figure>

A **cluster template** defines the blueprint: which Kubernetes version to run, the compute flavor for master and worker nodes, the network driver, volume driver for persistent storage, and optional settings like auto-scaling and TLS. You create the template once and reuse it for multiple clusters.

When you create a **cluster** from a template, the platform provisions the underlying infrastructure: master VMs running the Kubernetes API server, scheduler, and controller manager; worker VMs running the kubelet and container runtime; and the networking that connects them. The cluster integrates with Quake AI's Compute service for VM provisioning, Network service for pod and service networking, and Storage service for persistent volumes.

Once the cluster is running, you interact with it through standard Kubernetes tools. Use `kubectl` to deploy workloads, manage pods, and configure services. The Quake AI console, CLI, and API handle cluster-level operations: scaling the node pool, upgrading Kubernetes versions, and deleting clusters when no longer needed.



Kubernetes clusters require a minimum of two VMs (one master, one worker). Production deployments typically use three master nodes with 8 vCPU / 16 GB RAM each plus additional workers. Verify that your project's vCPU quota supports your planned cluster size before creating.



## Concepts

<DocsSectionLinks section="kubernetes/concepts" grouping="concepts" />

## How-to

<DocsSectionLinks section="kubernetes/how-to" />

## Related builds

<RelatedBuilds service="kubernetes" />

## Reference and operations

<ReferenceServiceLinks service="kubernetes" />

<ReferenceConsoleLinks service="kubernetes" />

When cluster creation stalls, a Heat stack reports a failure, or `kubectl` cannot reach the API server, work through the [Kubernetes cluster runbooks](/docs/operations/runbooks/kubernetes-troubleshooting).

Clusters run on [Compute](/docs/compute) instances and use [Network](/docs/network) for pod and service connectivity. Persistent volume claims allocate [block storage](/docs/block) volumes. To provision a cluster from code, see [Automation](/docs/automation).