Deploy your first app on Kubernetes

Stand up a Magnum Kubernetes cluster on Quake AI and deploy an Nginx app reachable from the public internet through a LoadBalancer service. The Kubernetes service (OpenStack Magnum) provisions the control plane, worker nodes, and cluster networking; you drive the cluster with kubectl once it reaches CREATE_COMPLETE.

Prerequisites#

You need:

• A Quake AI account with a Developer tier project
• An SSH key pair uploaded to your account

• kubectl installed on your local machine. See the Kubernetes install docs for your operating system.
• A cluster template in your project. Step 1 covers how to confirm you have one. To build your own, follow How to create a cluster template first, then return here.

Use the Console to create the cluster and download credentials; use your local terminal for kubectl steps.

Step 1: Confirm you have a cluster template#

A cluster template defines the Kubernetes version, the network driver, and the default node flavors that the cluster inherits. You select a template when you create the cluster.

1. In the Console, go to Kubernetes > Cluster Templates.
2. Look for a platform-provided template in the list. Platform templates include the Kubernetes version in the name, for example Standard-v2.0-k8s-calico-fc38_v1.24.16.

If the list is empty, create a template before continuing: follow How to create a cluster template, then come back to Step 2. That guide also documents the labels a template needs (including boot_volume_size, which Quake AI requires because every flavor family ships with a zero-size root disk).

Step 2: Create the cluster#

Create a one-master, one-worker cluster from the template. The Console renders the Create Cluster wizard as five numbered steps.

1. Go to Kubernetes > Clusters and select Create Cluster.
2. Step 1: Cluster Info. Set Cluster Name to tutorial-k8s. Under Cluster Template, select the platform template you found in Step 1. Select Next: Node Spec.
3. Step 2: Node Spec. Select your SSH Keypair. Leave Number of Master Nodes at 1 and Number of Nodes at 1 for this walkthrough. Pick master and worker flavors from the families listed in the dropdown (for example, m2a.xlarge for the master and m2a.large for the worker). Available families vary by project; choose any flavor that fits your quota. Select Next: Network Setting.
4. Step 3: Network Setting. Under Enable Load Balancer, check Enabled Load Balancer for Master Nodes so the cluster API gets a load balancer. Under Enabled Network, leave Create New Network checked so the wizard provisions a dedicated cluster network. Select Next: Management.
5. Step 4: Management. Leave the defaults. Select Next: Additional Labels.
6. Step 5: Additional Labels. Confirm the template carries boot_volume_size=40. If the label is missing, add it with + Add Label (key boot_volume_size, value 40). Without it, the cluster fails within about a minute because the flavors have a zero-size root disk.
7. Select Confirm.

The cluster appears in the Clusters list with status CREATE_IN_PROGRESS. Provisioning a small cluster takes 5 to 15 minutes. Wait until the status reads CREATE_COMPLETE before continuing.

Step 3: Connect with kubectl#

Download the cluster's kubeconfig from the Console and point kubectl at it.

1. Go to Kubernetes > Clusters.
2. On the tutorial-k8s row, open the Settings gear icon and select Get kube.config. The browser downloads a plain-text YAML file immediately.
3. Move the file to a known location and export it as KUBECONFIG in your terminal:

export KUBECONFIG=/path/to/downloaded/kube.config

1. Confirm kubectl reaches the cluster:

kubectl get nodes

Expected output for a one-master, one-worker cluster:

NAME                                   STATUS   ROLES    AGE   VERSION
tutorial-k8s-<token>-master-0          Ready    master   9m    v1.24.16
tutorial-k8s-<token>-node-0            Ready    <none>   7m    v1.24.16

Both nodes show Ready. The Kubernetes service injects a random token into the node names to keep them unique across cluster re-creates, so your exact names differ.

Step 4: Deploy the app#

Define an Nginx Deployment and apply it with kubectl. Save the following manifest as app.yaml on your local machine:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello-nginx
  template:
    metadata:
      labels:
        app: hello-nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80

Apply it:

kubectl apply -f app.yaml

Expected output:

deployment.apps/hello-nginx created

Watch the pods until both reach Running:

kubectl get pods

Expected output:

NAME                           READY   STATUS    RESTARTS   AGE
hello-nginx-7c8b5d9f4b-5n2hq   1/1     Running   0          40s
hello-nginx-7c8b5d9f4b-pq7xz   1/1     Running   0          40s

The first run pulls the nginx:1.27 image, so the pods may sit in ContainerCreating for a few seconds before they reach Running.

Step 5: Expose the app to the internet#

A LoadBalancer service tells the cluster to publish the selected pods through a public IP. Add the service to app.yaml below the Deployment, separated by a --- document break:

---
apiVersion: v1
kind: Service
metadata:
  name: hello-nginx
spec:
  type: LoadBalancer
  selector:
    app: hello-nginx
  ports:
    - port: 80
      targetPort: 80

Apply the file again. kubectl creates the service and leaves the Deployment unchanged:

kubectl apply -f app.yaml

Expected output:

deployment.apps/hello-nginx unchanged
service/hello-nginx created

Watch the service until the EXTERNAL-IP column changes from <pending> to an address:

kubectl get service hello-nginx --watch

Expected output once the public service finishes provisioning:

NAME          TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)        AGE
hello-nginx   LoadBalancer   10.254.12.118   203.0.113.42    80:31840/TCP   2m

The address in EXTERNAL-IP is the public IP the cluster allocated for the service. Provisioning the service and assigning the IP takes 2 to 4 minutes. Press Ctrl+C to stop watching once the IP appears.

Step 6: Reach the app#

Send a request to the public IP from your local machine. Replace 203.0.113.42 with the EXTERNAL-IP from Step 5:

curl http://203.0.113.42

Expected output (the start of the default Nginx welcome page):

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>

The request travels from your machine to the service's public IP and then to one of the two Nginx pods on the worker node.

Next steps#

• How to deploy to a Quake AI Kubernetes cluster from CI: automate deploys after you outgrow manual kubectl apply
• How to use a container registry with Quake AI: private images for production workloads
• How to manage a Kubernetes cluster: scale workers, resize, and delete clusters
• How to create a cluster template: define the version, network driver, and node defaults a cluster inherits
• Kubernetes on Quake AI: the cluster architecture and resource planning behind the Kubernetes service
• Kubernetes CLI reference: the openstack coe commands for clusters and templates
• All deployments: the full catalog of hands-on guides across compute, networking, storage, and AI

Clean up#

To stop using project resources, delete the app and the cluster.

1. Delete the app. Remove the Deployment and the LoadBalancer service, which releases its public IP:

kubectl delete -f app.yaml

1. Delete the cluster. Go to Kubernetes > Clusters, open the Settings gear icon on the tutorial-k8s row, and select Delete. Confirm in the dialog. Read the cluster name in the dialog body first; the Console deletes on a single confirmation without asking you to type the name.

Deleting the cluster removes its VMs, network, router, and cluster networking resources. The cluster leaves the list once deletion finishes.