Using kubectl

You manage your production cluster with kubectl, just like any other Kubernetes cluster. The only TrueFullstaq-specific part is how you get your kubeconfig and how you log in: the kubeconfig comes from your dashboard, and authentication happens through TrueFullstaq Single Sign-On (SSO), with no static credentials to copy around.

# Prerequisites

Install these once on your machine:

1. kubectl: the Kubernetes CLI. Installation guide.

2. kubelogin (the oidc-login kubectl plugin): this is what performs the SSO login. The kubeconfig you download invokes it automatically.

   # Recommended: install via krew (the kubectl plugin manager)
   kubectl krew install oidc-login
   
   # macOS (Homebrew)
   brew install int128/kubelogin/kubelogin
   
   # Or download a release binary from:
   # https://github.com/int128/kubelogin/releases
   

   Verify it is discoverable on your PATH:

   kubectl oidc-login --version
   

# Step 1: Download your kubeconfig from the dashboard

1. Open your dashboard at https://dash.<CUSTOMER_ID>.truefullstaq.cloud and sign in with SSO. (<CUSTOMER_ID> is your 5-digit customer ID, e.g. 01234.)
2. In the Clusters section you will see each production cluster, e.g. cid01234-cl02.
3. Click Download kubeconfig for the cluster you want. You get a file named like kubeconf-cid01234-cl02.

The downloaded file already contains your cluster’s API URL, its CA certificate, and the SSO login configuration, so you do not edit it.

# Step 2: Point kubectl at it

You can either drop it into the default location or load it per-shell.

# Option A: use it as your default config
mkdir -p ~/.kube
cp ~/Downloads/kubeconf-cid01234-cl02 ~/.kube/config

# Option B: keep it separate and select it with KUBECONFIG
export KUBECONFIG=~/Downloads/kubeconf-cid01234-cl02

Tip (multiple clusters): keep each kubeconfig as its own file and merge them so you can switch contexts:

export KUBECONFIG=~/.kube/config:~/Downloads/kubeconf-cid01234-cl02
kubectl config get-contexts          # list contexts
kubectl config use-context "you@example.com - cid01234-cl02"

# Step 3: Log in

The first command that talks to the cluster triggers an SSO login: your browser opens, you authenticate with TrueFullstaq SSO, and a short-lived token is cached locally. You will not be asked again until that token expires.

kubectl get nodes

If the browser does not open automatically, copy the URL printed in the terminal. To clear a cached session (e.g. to switch accounts):

kubectl oidc-login clean

How it works: your kubeconfig runs kubectl oidc-login as an exec credential plugin against https://login.truefullstaq.com/realms/truefullstaq with client ID kubernetes. What you are allowed to do in the cluster is decided by your SSO group membership and the cluster’s RBAC; see Access Control.

# Everyday commands

Once you are logged in, it is standard Kubernetes from here on.

# Inspecting workloads

# List your namespaces
kubectl get namespaces

# Pods in a namespace
kubectl get pods -n <namespace>

# Wide output (node, IP)
kubectl get pods -n <namespace> -o wide

# Describe a pod (events at the bottom are gold for debugging)
kubectl describe pod <pod-name> -n <namespace>

# Everything in a namespace at a glance
kubectl get all -n <namespace>

# Logs

# Stream logs
kubectl logs -f <pod-name> -n <namespace>

# A specific container in a multi-container pod
kubectl logs -f <pod-name> -c <container-name> -n <namespace>

# Logs from the previous (crashed) container instance
kubectl logs <pod-name> -n <namespace> --previous

# All pods behind a deployment, by label
kubectl logs -f -l app=my-app -n <namespace> --all-containers

# Rollouts

Your deployments are normally driven by ArgoCD (see CI/CD with ArgoCD), so prefer changing Git over kubectl edit. For a quick restart (e.g. to re-read a rotated secret):

kubectl rollout restart deployment/<name> -n <namespace>
kubectl rollout status  deployment/<name> -n <namespace>
kubectl rollout undo    deployment/<name> -n <namespace>   # roll back one revision

# Debugging

# Exec into a running container
kubectl exec -it <pod-name> -n <namespace> -- sh

# Throwaway debug pod on the same network
kubectl run debug --image=alpine --rm -it --restart=Never -n <namespace> -- sh

# Port-forward a service to your laptop
kubectl port-forward svc/<service-name> 8080:80 -n <namespace>

# Resource usage
kubectl top pods  -n <namespace>
kubectl top nodes

# Events, newest last (catches scheduling / image-pull / probe failures)
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# Troubleshooting access