Skip to main content

Set up your first cluster

You’ll connect or create a cluster so apps and databases have somewhere to run.

Before you start​

  • Permission to administer the cluster (or the servers you will turn into one)
  • A connection file for existing clusters (YAML)
  • Network access so Xooshe can reach your cluster API — see the Network management guide

Choose a path​

GoalPath
You already have a clusterConnect an existing cluster
You need a new clusterCreate a new cluster

Connect an existing cluster​

Get your connection file​

Self-managed clusters (example using a local kubectl context):

kubectl config view --raw > config.yaml

Cloud-managed clusters (AKS, EKS, GKE, …): download the connection file from your cloud console.

Add the cluster in Xooshe​

  1. Go to Select Cluster → + Add Cluster.
  2. Choose Add an Existing Kube Config (upload your connection file).1 Add an Existing Kube Config option
  3. Enter a clear cluster name.
  4. Upload the .yaml connection file.
  5. Click Confirm.
Network requirements

Your cluster must accept connections from Xooshe. Details: Network management guide.

After connection​

Select the cluster from the side menu. On the home dashboard you see:

  • Environments — isolated places for apps
  • Shared variables — reusable configuration values
  • Nodes — servers in the cluster

Xooshe cluster home

For node-level operations, grant SSH access:

  1. Open the Nodes tab.
  2. Open a node’s settings.
  3. Copy the SSH command from the SSH Access Required warning.
  4. Run it on each node as root.

Nodes setting SSH token

This installs what Xooshe needs for fuller management. Without it, you can still run many app workflows, but adding nodes and some monitoring tasks may be limited.

Production safety

Back up production clusters before major changes.

Create a new cluster​

Bare metal​

Minimum idea: one control-plane node + one or more worker nodes, Ubuntu 22.04 LTS or newer.

Typical minimum sizes (production needs more):

RoleRAMCPUDisk
Control plane4 GB (8 GB better)2 vCPU (4 better)40 GB SSD+
Worker4 GB (8–16 GB better)2 vCPU (4–8 better)50 GB+ SSD
  1. Give nodes static IPs, working SSH, and clear hostnames.
  2. In Xooshe: Select Cluster → + Add Cluster → Create A New Cluster from Scratch.
  3. Run the shown SSH setup command on the control-plane node.
  4. Enter the cluster name and control-plane hostname/IP, then confirm.
  5. When the cluster exists, open Nodes → + Add Node, run the SSH command on each worker, and join them.

Optional check on the control plane (advanced):

kubectl get nodes

Cloud providers​

  1. Connect cloud credentials under Cloud Providers.
  2. Create a cluster for that provider (region, sizes, scaling).
  3. Follow the provider steps for AWS, GCP, or DigitalOcean.

You’re done when​

  • The cluster appears in the cluster selector.
  • Environments, Shared variables, and Nodes are visible for that cluster.
  • Nodes move to a healthy / Ready state.

If it fails​

SymptomFix
Cluster will not connectCheck network access, then re-upload a valid connection file
Nodes never become ReadyEnable full management (SSH) on those nodes
Upload rejectedConfirm the file is valid YAML and includes the expected cluster, user, and context

Footnotes​

  1. The UI label is Add an Existing Kube Config. Docs call the file a connection file. See Terms we use. ↩