---
title: "Create a Kubernetes cluster"
description: "Plan, apply, open GitOps."
url: https://frazer.ai/docs/quickstarts/kubernetes-cluster
index: https://frazer.ai/docs/llms.txt
tokens: 1706
---

> For agents: this page is indexed at https://frazer.ai/docs/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Create a Kubernetes cluster

At the end of this guide, the project `acme-staging` has its own Kubernetes cluster, `acme-staging-1`: virtual machines on your servers, built from one resource you planned and applied. It arrives with Frazer GitOps, eBPF networking, the certificate manager, the secret sync and the monitoring agents installed, `kubectl` reaches it with your Frazer identity, and its GitOps view is open in your browser.

You need:

-   A project for the cluster. To create one, run `frazer projects create acme-staging --organization acme`.
-   Capacity: servers in a pool with the `substrate-host` role, in your host project (`acme-infra`) and shared with this project. A `small` cluster needs one server; a `production` cluster needs three. Servers joined with the install command keep their own OS and cannot host VMs, so join these through a provider account or the Frazer boot image ([Servers and pools](https://frazer.ai/docs/servers)).
-   Permission to create clusters in the project (`kubernetes.clusters.create`).
-   `kubectl` on your laptop.

> **Tip:** Every `frazer` command that changes something takes `--dry-run`: it prints the plan and changes nothing. Run the same command without it to apply the change.

## Create the cluster

1.  **Install the CLI and sign in.**
    
    ```sh
    curl -fsSL https://get.frazer.ai | sh
    frazer login
    ```
    
2.  **Check the project’s capacity.** List the pools the project can place VMs on, its own and the ones shared with it:
    
    ```sh
    frazer servers server-pools list --project acme-staging --include-shared
    ```
    
    You should see a pool shared from `acme-infra`, with the capacity guaranteed to `acme-staging` and its limit. If the list is empty, someone with `servers.serverPools.share` on the host project shares a pool with it:
    
    ```sh
    frazer servers server-pools share vint-hill-default --project acme-infra --location us-virginia1 \
      --share-type specific-projects \
      --consumer 'acme-staging=guaranteed:vcpus=16,memory-gib=64;limit:vcpus=32,memory-gib=128' --dry-run
    ```
    
    Guaranteed capacity is held for the project and never lent; the limit is how far it may burst into capacity nobody holds. The `--consumer` value is quoted so the shell does not read its `;`. The plan shows the capacity math, the project it adds and any resources affected; run the command again without `--dry-run` to apply it.
    
3.  **Plan the cluster.** The `small` class has one control-plane VM and workers, and suits staging and small projects:
    
    ```sh
    frazer kubernetes clusters create acme-staging-1 --project acme-staging \
      --location us-virginia1 --class small --dry-run
    ```
    
    ```text title="Output"
      Pool       vint-hill-default · shared from acme-infra
      Quota      10 vCPU, 38 GiB of your share · surge VM held
      Servers    the control-plane VM on Atlas
      Objects    + cluster objects · + Application frazer-platform
      Network    a subnet of your project's VPC · pod and service ranges
      Addresses  none yet · from the site's range when you add a gateway
    ```
    
    The plan shows the quota the cluster takes from your share (one spare VM per pool is held for upgrades and repairs), the servers that host the VMs, the network ranges, the monthly cost, and the rendered objects as a diff. Nothing exists yet. In a production project, a second person approves the plan before it applies.
    
4.  **Apply it.** Run the same command without `--dry-run`:
    
    ```sh
    frazer kubernetes clusters create acme-staging-1 --project acme-staging \
      --location us-virginia1 --class small
    ```
    
    The command returns an operation. In the console, open **Compute › Kubernetes clusters** and select `acme-staging-1` to follow its ten phases: Requested, Accepted, Creating machines, Control plane starting, Control plane ready, Nodes joining, Seeding, Platform syncing, Environments syncing and Ready. If a phase times out, the page shows the message of the object that failed.
    
5.  **Connect `kubectl`.**
    
    ```sh
    frazer kubernetes clusters get-credentials acme-staging-1 --project acme-staging
    kubectl get nodes
    ```
    
    The kubeconfig holds no secret. For each call, `kubectl` asks `frazer` for a 10-minute token for this one cluster, and the traffic goes through Frazer Link, so there is no VPN to install. Your Frazer role maps to Kubernetes RBAC groups. You should see the control-plane node and the workers, all `Ready`.
    
6.  **Open GitOps.** On the cluster’s page, click **Open GitOps**. It opens behind Frazer sign-in. The Application `frazer-platform` is the platform set Frazer installed; the cluster’s own Frazer GitOps keeps it synced, even when Frazer is unreachable. **Open dashboards**, on the same page, shows the cluster’s dashboards.
    

## What you have

-   **A cluster of VMs.** Each node is a virtual machine running Ubuntu and Kubernetes on your servers. Your containers never run on the bare host.
-   **The platform set.** The Kubernetes distribution brings the control plane, its datastore, eBPF networking and cluster DNS; a one-time seed installs Frazer GitOps and the secret sync; then the cluster’s Frazer GitOps installs the rest in waves: Frazer Policy, the certificate manager, the cluster’s gateway, local NVMe volumes and the metrics and log agents.
-   **Changes as plans.** Scaling a node pool, upgrading Kubernetes or switching on an add-on is the same plan, then apply. Rolling back is applying an earlier revision. Deleting is soft, with a restore window.
-   **No apps yet.** Workloads come from Git: connect an environment repository and the cluster’s Frazer GitOps deploys what is in it.

## Next steps

[Connect your environment repo](https://frazer.ai/docs/quickstarts/environment-repo) Deploy from Git with the Frazer Reader app.

[Kubernetes](https://frazer.ai/docs/kubernetes) Classes, node pools, upgrades, access and limits.

[Environments and GitOps](https://frazer.ai/docs/gitops) Environments, permission profiles and the pull-request check.

[Kubernetes on frazer.ai](https://frazer.ai/kubernetes) The product page, with the plan screen and the platform set.

## Pages in Get started

- [Docs home](https://frazer.ai/docs.md)
- [Bring your first server](https://frazer.ai/docs/quickstarts/first-server.md)
- [Create a Kubernetes cluster](https://frazer.ai/docs/quickstarts/kubernetes-cluster.md) (this page)
- [Deploy serverless with Postgres](https://frazer.ai/docs/quickstarts/serverless-postgres.md)
- [Deploy an open model](https://frazer.ai/docs/quickstarts/open-model.md)
- [Give your team devboxes](https://frazer.ai/docs/quickstarts/devboxes.md)
- [Connect your environment repo](https://frazer.ai/docs/quickstarts/environment-repo.md)