Deploy a Kubernetes Cluster

Overview

Deploying a Kubernetes cluster on Polystack K8SaaS provisions the full control plane and worker node infrastructure from a cluster template. The process creates virtual machine instances for master and worker nodes, configures the Kubernetes API server, installs the selected CNI plugin, and allocates a load balancer VIP for master access. A cluster deployment typically completes in 5–10 minutes depending on node count.

Prerequisites

A cluster template created in your project (see Cluster Templates)
Compute quota to provision master + worker nodes
A project network with external connectivity
A keypair available in your project

Deploy a Cluster

Dashboard
CLI

Navigate to Clusters

Navigate to Container > Clusters.

Create a cluster

Click Create Cluster and complete the form:

Field	Description	Recommended
Cluster Name	Unique name for this cluster	`prod-cluster-01`
Cluster Template	Select a template from your project	`k8s-1.29-prod`
Master Count	Number of control plane nodes	`1` (dev) or `3` (HA)
Node Count	Initial number of worker nodes	`3`
Keypair	SSH key for node access	Your project keypair
Availability Zone	Fault domain for node placement	`nova`

Launch the cluster

Click Create Cluster. The status transitions through:CREATE_IN_PROGRESS → CREATE_COMPLETEProvisioning typically takes 5–10 minutes. Refresh the cluster list to track progress.

For production clusters, use 3 master nodes and ensure the cluster template has Master LB Enabled set to True for control plane high availability.

Verify completion

The cluster shows Status: CREATE_COMPLETE and Health Status: HEALTHY when ready.

Cluster is deployed and all nodes are healthy.

Authenticate

Load credentials

source openrc.sh

Create the cluster

Deploy Kubernetes cluster

openstack coe cluster create prod-cluster-01 \
  --cluster-template k8s-1.29-prod \
  --master-count 3 \
  --node-count 3 \
  --keypair my-keypair

The command returns the cluster UUID immediately. Provisioning continues asynchronously.

Monitor progress

Check cluster status

openstack coe cluster show prod-cluster-01 \
  -f value -c status -c status_reason

Poll until status is CREATE_COMPLETE. If status shows CREATE_FAILED, check status_reason for the error message.

Verify

List all clusters

openstack coe cluster list

Show cluster health

openstack coe cluster show prod-cluster-01 \
  -f value -c health_status -c master_count -c node_count

Status is CREATE_COMPLETE and health_status is HEALTHY.

Cluster Sizing Reference

Cluster Type	Master Count	Worker Count	Use Case
Development	`1`	`2–3`	Single developer or CI/CD pipelines
Staging	`1`	`3–5`	Pre-production testing
Production HA	`3`	`5+`	Customer-facing workloads

A single master node is a single point of failure. For production workloads, always deploy 3 master nodes with the master load balancer enabled in the cluster template.

Monitor Deployment Progress

Dashboard
CLI

Navigate to Container > Clusters. The Status column updates in real time. Click the cluster name to view node-level detail.

Watch cluster status in a loop

watch -n 10 "openstack coe cluster show prod-cluster-01 \
  -f value -c status -c status_reason"

If a failure occurs, the status_reason field contains the error from the underlying Orchestration stack:

Show failure details

openstack coe cluster show prod-cluster-01 \
  -f value -c status_reason

Next Steps

Access Cluster

Download kubeconfig and verify kubectl connectivity to your new cluster.

Scale Cluster

Add or remove worker nodes from the cluster default node group.

Node Groups

Create specialized node pools with different flavors and configurations.

Troubleshooting

Resolve deployment failures and cluster health issues.

Core Services

Other Services

Overview

Deploy a Cluster

Navigate to Clusters

Create a cluster

Launch the cluster

Verify completion

Authenticate

Create the cluster

Monitor progress

Verify

Cluster Sizing Reference

Monitor Deployment Progress

Next Steps

Access Cluster

Scale Cluster

Node Groups

Troubleshooting

​Overview

​Deploy a Cluster

Navigate to Clusters

Create a cluster

Launch the cluster

Verify completion

Authenticate

Create the cluster

Monitor progress

Verify

​Cluster Sizing Reference

​Monitor Deployment Progress

​Next Steps

Access Cluster

Scale Cluster

Node Groups

Troubleshooting

Overview

Deploy a Cluster

Cluster Sizing Reference

Monitor Deployment Progress

Next Steps