Getting started

This guide demonstrates how to create a Kubernetes cluster using the rackctl command-line tool.

Prerequisites

rackctl installed (see Installation Guide)
Valid authentication token

Creating a Kubernetes Cluster

Step 1: Authenticate

You can authenticate in one of two ways:

Option A — Log in once with token-login (recommended for CI/CD)

Exchange your API token for a session token; rackctl saves it to ~/.ginger-society/auth.json and picks it up automatically on every subsequent command, this is valid for 20 minutes , same as a recommended pipeline run time:

rackctl token-login <your-api-token>

Option B — Set a session token via environment variable (recommended for local use)

export RACKCTL_SESSION_TOKEN=eyJ0eXAiOi**********QlB0h3hEM

If RACKCTL_SESSION_TOKEN is set, it always takes priority over the saved token-login session. Note that this is not same as the API keys , you can find a temporary session token ( valid for 5 minutes ) on the portal after you login. The token keeps refreshing after every 5 minutes.

Step 2: Create Kubernetes Cluster

Execute the cluster creation command:

rackctl create test-cluster

Expected Output

When successful, you’ll see the following type of output:

Creating cluster with name: test-cluster
✅ Kubeconfig saved to "/Users/userone/.k8/kubeconfig.yml"
📝 Saved resource_id to "/Users/userone/.rackmint/k8"

Please note that the path for kubeconfig is automatically evaluated if you have KUBECONFIG defined, if not it will default to the default KUBECONFIG value which is generally in the user home directory

Kubeconfig Details

The generated kubeconfig contains:

Cluster information with certificate authority data
Context configuration
User credentials with authentication token

Next Steps

After successfully creating your cluster, you can:

Use the generated kubeconfig to interact with your cluster:
```
kubectl get nodes
```
Set up SSL and Ingress and Deploy applications to your cluster following the Deployment Guide

Troubleshooting

If you encounter issues:

Verify your session token is valid and not expired — re-run rackctl token-login <your-api-token> to refresh it
Check network connectivity to the API endpoint
Ensure you have the latest version of rackctl installed