Skip to content
Beta
Sahabti

Get started with Kubernetes

A Kubernetes cluster runs your containers on workers inside your workspace's private network. The platform runs the control plane, watches the workers and replaces one that stops working; you get a kubeconfig and use kubectl, Helm or any tool you already know. Every cluster comes with a managed gateway that serves your websites and APIs over HTTPS, on the cluster's own hostname or on your own domain. This guide takes you from no cluster to a first app on your own domain.

Before you start

  • A workspace role of Owner, Admin or Developer. Viewers can look, not create.
  • The workspace's private network must be ready. It is created the first time you launch something, and the form waits for it on its own.
  • kubectl on your computer.

The Free plan allows one cluster with one Free worker. Paid plans allow more clusters, bigger workers and high availability: see Plans and limits.

1. Create a cluster

Open Kubernetes in your workspace and choose New cluster. The form has four steps on one page, each already filled in with a sensible default, and a Summary beside them.

  1. Basics: the cluster's Name, 3 to 40 lowercase letters, digits and dashes, such as shop. It names the cluster's nodes and its hostname, and cannot change later. Keep the Version marked Recommended, the Location its nodes run in, and the Network, your workspace's private network.
  2. Availability: Standard, for development and most workloads, or Highly available, so the cluster's API keeps answering through a host failure. High availability comes with a paid plan.
  3. Node pools: the cluster's first pool, named default, with its Worker size and its number of Workers. Labels and taints are optional. Choose Add another pool for workloads that need machines of their own.
  4. Add-ons: leave the Managed gateway on. It serves the cluster's HTTP routes over HTTPS with a free hostname and certificates, and uses no load balancer.

The Summary shows your workers, how many of them and how many clusters your plan allows, and the Pay-as-you-go estimate. Select Create cluster.

The cluster goes from Queued to Creating to Ready in a few minutes, and its Overview shows each step as it happens.

2. Connect with kubectl

Open the cluster, go to Access and choose Download kubeconfig:

bash
export KUBECONFIG=~/Downloads/shop.kubeconfig
kubectl auth whoami
kubectl get nodes

The kubeconfig carries your own role in the cluster and renews its credentials with sh and curl. On a machine without them, choose 12-hour kubeconfig instead. Listing nodes takes the cluster's Admin role: as an editor or a viewer, run kubectl get pods. See Cluster access.

3. Deploy a first app

Save this as hello.yaml: a small web server, its Service, and a route to it on the managed gateway.

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: hello
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  selector:
    app: hello
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: hello
spec:
  parentRefs:
    - name: sahabti
      namespace: sahabti-gateway
  rules:
    - backendRefs:
        - name: hello
          port: 80
bash
kubectl apply -f hello.yaml

Open the cluster's Services & routes. Under Managed gateway, the cluster's own hostname, its name with a short suffix of its own such as shop-k3x9mq.sahabti.app, shows Live once it is served. Open it with the hostname your cluster shows:

bash
curl https://shop-k3x9mq.sahabti.app/

The cluster's Workloads shows the pods and their logs. For databases and other TCP or UDP services, use a Service of type LoadBalancer instead: see Expose it.

4. Add your own domain

A cluster serves your own hostname, such as shop.example.com, with a CNAME record and nothing to verify on the Domains page.

  1. In Services & routes, under Managed gateway → Use your own domain, enter shop.example.com and select Add hostname.
  2. At your DNS provider, create the record the console shows, with your cluster's hostname filled in:
TypeNameValue
CNAMEshop.example.comshop-k3x9mq.sahabti.app
  1. Name the hostname in your route: add hostnames: [shop.example.com] under the HTTPRoute's spec, and apply it again.

The hostname moves from Waiting for DNS to Issuing certificate to Live, usually within a few minutes. Keep the record in place, and keep it DNS only if your provider offers to proxy it. A root domain such as example.com cannot hold a CNAME record: serve www.example.com instead. See Your own domain.

5. Turn on Security

Open the cluster's Security to decide what the managed gateway lets through to your sites, before a request reaches your pods:

  1. Under Security profile, choose Standard. It blocks requests for secret files and common admin consoles, oversized bodies and slow clients. Strict suits an API or an admin tool.
  2. Add what you need: firewall rules, rate limits, password sign-in, CORS or managed rules, for every hostname or only some.
  3. Select Review and save, check the list of changes, and confirm. Each rule shows Applying, then Applied about a minute later.

See Kubernetes gateway security for every setting, with examples.

6. Add workers and node pools

Open the cluster's Nodes:

  • Edit a pool to change its number of Workers, or its labels and taints. Removed workers are drained first.
  • Add node pool for workers of another size or zone, with labels and taints of their own.

Every pool's workers count against your plan's workers per cluster. The cluster shows Updating while it changes and keeps serving. See Kubernetes node pools.

With PromptOps

In a workspace with PromptOps on, ask in the chat. It asks before it creates or changes anything:

  • "Create a Kubernetes cluster called shop with two Small workers."
  • "Scale the default pool of the shop cluster to 3 workers."
  • "Add shop.example.com to the shop cluster's gateway."
  • "Why does the hello pod in the shop cluster keep restarting?"

With the API or MCP

Create an API token with the kubernetes actions, then find your network's id with GET /v1/networks:

bash
curl "https://api.sahabti.com/v1/networks?orgId=$WORKSPACE_ID" \
  -H "x-api-key: $SAHABTI_TOKEN"

Save the cluster as cluster.json, with your workspace's id and your network's id:

json
{
  "orgId": "<workspace id>",
  "name": "shop",
  "networkId": "<network id>",
  "pools": [{ "name": "default", "size": "small", "count": 2 }]
}
bash
curl -X POST https://api.sahabti.com/v1/kubernetes/clusters \
  -H "x-api-key: $SAHABTI_TOKEN" \
  -H "Content-Type: application/json" \
  -d @cluster.json

The Example on the API tokens page has your workspace's id filled in. Over MCP, the create_kubernetes_cluster tool takes the same fields; add_kubernetes_gateway_cname adds your own hostname and apply_kubernetes_resources applies a manifest. A token never gets a kubeconfig: download one in the console.

What it costs

The Free worker costs nothing. Workers of a paid size, high availability and volumes are metered by the hour, and the Summary shows the estimate before you create. Paid workers don't use your quota once usage billing is on for your workspace; until then, they count against it. See Kubernetes pricing and usage, Plans and pay as you go and the pricing page.

First checks

  • The cluster shows Ready, and kubectl get nodes lists every worker as Ready.
  • kubectl auth whoami shows your email address and your role's group.
  • In Services & routes, each hostname shows Live.
  • In Security, every rule shows Applied.
  • Insights lists what to fix before the next upgrade.

Next steps

PreviousGet started with databases and managed services
NextGet started with virtual machines