## Introduction This guide walks you through running a Kubernetes cluster on Atlas Cloud. Atlas takes care of the control plane, node provisioning, and the Kubernetes installer; you pick a version and a cluster size, click create, and download a `kubeconfig`. ## Prerequisites - An Atlas Cloud account. [Sign up here](https://runatlas.is/en/signup) if you don't have one yet. - An SSH keypair registered in Atlas — see [[SSH Key Pairs]]. - `kubectl` installed locally (see the [Kubernetes install guide](https://kubernetes.io/docs/tasks/tools/#kubectl)). ## Step 1: Create a Kubernetes cluster 1. Log in to the [Atlas Cloud Platform](https://sky.runatlas.is). 2. In the left menu, go to **Compute → Kubernetes**. 3. Click **Add Kubernetes Cluster** and fill in: - **Name**: something short, like `my-cluster`. - **Zone**: the zone you usually deploy into (defaults to `is1`). - **Kubernetes version**: pick one from the dropdown. Atlas maintains the list of supported versions; newer versions appear as Kubernetes publishes them. - **Service offering**: the compute size for each node. Pick `a5` (2 vCPU / 8 GiB) as a starter, `a6` (4 / 16) for more headroom, or `a7` (8 / 32) for production workloads. `a4` (1 vCPU) is below the 2 vCPU minimum Kubernetes expects. See the [pricing page](https://runatlas.is/en/pricing) for the current list. - **Cluster size**: number of worker nodes. Start with 1 or 2; you can scale later. - **Control nodes**: leave at 1 unless you specifically need a highly-available control plane. - **Network**: choose an existing guest network or leave it blank — Atlas will create an isolated network for the cluster. - **SSH keypair**: the keypair from your prerequisites. This lets you SSH into the cluster nodes if you ever need to. 4. Click **OK** and wait for the cluster to reach the **Running** state. First-time cluster creation takes a few minutes while nodes boot and Kubernetes finishes installing. ## Step 2: Connect with kubectl 1. Open the cluster detail page and switch to the **Access** tab. 2. Click **Download kubeconfig**. The file is named `kube.conf`. 3. Point `kubectl` at it and check your cluster: ```bash export KUBECONFIG=~/Downloads/kube.conf kubectl get nodes ``` You should see one control node and however many workers you asked for, all in the `Ready` state. ## Step 3: Deploy something Any standard Kubernetes manifest works. For a quick smoke test: ```bash kubectl create deployment hello --image=nginx kubectl expose deployment hello --port=80 --type=LoadBalancer kubectl get svc hello -w ``` Wait for the `EXTERNAL-IP` column to fill in — Atlas allocates a public IP and wires it through to the service. ## Managing the cluster From the cluster detail page: - **Scale** — change the worker-node count up or down, or switch to a different service offering. - **Upgrade** — move to a newer supported Kubernetes version. You can only move one minor version at a time (for example 1.33 → 1.34), matching Kubernetes's own support policy. - **Stop / Start** — pause a cluster when you aren't using it; resources are released except for the persistent disks. - **Delete** — tear it all down. ## Troubleshooting - **Cluster stuck in Alert** — at least one node failed to finish provisioning. Atlas's background check will retry; if it stays in Alert after 15 minutes, delete the cluster and recreate it. - **Pods can't pull images** — check the cluster network's egress rules; Kubernetes nodes need outbound access to container registries during install and at image-pull time. - **`kubectl` hangs** — the cluster's control-plane public IP may be blocked by your firewall; try from a different network. ## Related - [[Creating your first cloud service]] - [[Instances]] - [[SSH Key Pairs]]