If your models run on EKS, GKE or AKS, the kubeconfig on your laptop probably doesn't hold a credential at all. The one aws eks update-kubeconfig writes runs aws eks get-token every time you call kubectl. GKE's calls gke-gcloud-auth-plugin, and AKS clusters that sign in with Microsoft Entra ID call kubelogin.
Skyportal runs kubectl on its own servers and won't run those programs there, so it refuses kubeconfigs with an exec plugin. What it takes instead is a service account token. Setting one up takes a handful of kubectl commands, and you decide what the token is allowed to touch.
A read-only service account
Create a namespace and a service account for Skyportal, and give it the built-in view role:
kubectl create namespace skyportal
kubectl create serviceaccount skyportal -n skyportal
kubectl create clusterrolebinding skyportal-view \
--clusterrole=view --serviceaccount=skyportal:skyportalview reads pods, logs, events, deployments and most other namespaced objects. It can't read Secrets or RBAC objects, and it can't change anything.
It also can't read nodes, and Skyportal needs that: it only counts the cluster as reachable when kubectl get nodes works. Add a small role for nodes:
kubectl create clusterrole skyportal-nodes --verb=get,list,watch --resource=nodes
kubectl create clusterrolebinding skyportal-nodes \
--clusterrole=skyportal-nodes --serviceaccount=skyportal:skyportalIf you run the NVIDIA DCGM exporter (the GPU Operator installs it), Skyportal can chart GPU utilization and memory too. It reads the exporter through the API server proxy, so the token needs get on pods/proxy and services/proxy. Proxy access reaches any pod's HTTP port, not only the exporter's, so add it only if you want the GPU charts:
kubectl create clusterrole skyportal-gpu-metrics --verb=get \
--resource=pods/proxy,services/proxy
kubectl create clusterrolebinding skyportal-gpu-metrics \
--clusterrole=skyportal-gpu-metrics --serviceaccount=skyportal:skyportalA token that doesn't expire this afternoon
kubectl create token skyportal -n skyportal works, but that token expires, usually after an hour, and the connection stops with it. For a connection that keeps working, create a token Secret for the service account and read the token from it:
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: skyportal-token
namespace: skyportal
annotations:
kubernetes.io/service-account.name: skyportal
type: kubernetes.io/service-account-token
EOF
kubectl get secret skyportal-token -n skyportal \
-o jsonpath='{.data.token}' | base64 -dDeleting that Secret revokes the token. It's also your off switch if you ever want Skyportal out of the cluster.
The API server URL and CA
Your current kubeconfig already has both. With the cluster's context selected:
kubectl config view --minify --raw \
-o jsonpath='{.clusters[0].cluster.server}'
kubectl config view --minify --raw \
-o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crtAll three clouds give the API server a public endpoint by default, and Skyportal has to reach it from the internet. If you limited who can reach it (public access CIDRs on EKS, authorized networks on GKE, authorized IP ranges on AKS) or made the endpoint private, Skyportal can't connect. For a private endpoint, use the in-cluster agent instead.
Adding the cluster
In the app, open Hosts, click New Host and pick the Kubernetes cluster tab. Choose Enter details and fill in:
- The API server URL from the first command.
- The service account token.
- The CA certificate as PEM, which is the contents of
ca.crt. - A name, an environment and, if you like, a default namespace.
Test Connection runs kubectl version against the cluster from Skyportal's servers, and Save runs it again before storing anything. The credentials are stored encrypted, and each kubectl run reads them from a temporary file that's deleted afterwards. Put a cluster that serves users under Production, where SARA can't run destructive commands at all.
From the terminal, build a small kubeconfig with the same three values and hand it to the CLI. Keep --embed-certs: without it the file points at ca.crt on disk, and Skyportal refuses file references.
kubectl config --kubeconfig=skyportal.kubeconfig set-cluster my-eks \
--server="$SERVER" --certificate-authority=ca.crt --embed-certs=true
kubectl config --kubeconfig=skyportal.kubeconfig set-credentials skyportal \
--token="$TOKEN"
kubectl config --kubeconfig=skyportal.kubeconfig set-context skyportal \
--cluster=my-eks --user=skyportal
kubectl config --kubeconfig=skyportal.kubeconfig use-context skyportal
skyportalai kubernetes connect my-eks \
--kubeconfig skyportal.kubeconfig --environment StagingTreat that file like a password, since it holds the token.
What Skyportal reads on its own
Every 20 seconds, Skyportal reads the cluster's nodes, namespaces, pods, warning events, deployments and statefulsets. If metrics-server runs in the cluster, it adds CPU and memory from kubectl top. GKE and AKS run metrics-server by default. On EKS it's an add-on you install.
When a pod is in CrashLoopBackOff, ImagePullBackOff, Error or Pending, or keeps restarting, Skyportal also pulls the logs of its previous container, for up to five pods at a time. So when a container crashes, the last lines it printed are already saved by the time you go looking.
The Monitor Dashboard shows all of this in an Infrastructure view and a Workloads view, plus the warning events. With the GPU role above and a DCGM exporter running, it shows GPU utilization and memory too.
Asking SARA about the cluster
Select the cluster in the chat and pick the namespaces SARA may use in the scope picker. Until you do, only cluster-wide commands run, such as kubectl get nodes. With one namespace in scope, SARA adds -n for you.
Then ask the way you'd ask a teammate who has kubectl open:
- "Why is the inference pod in CrashLoopBackOff?"
- "Which pods restarted today, and why?"
- "The training job has been Pending for 20 minutes. What is it waiting for?"
Each step is a single kubectl or helm command, run from Skyportal's servers with the token you gave it. You see it before it runs, and it waits for your approval unless you've already allowed that command. With the read-only token above, anything that changes the cluster fails with Forbidden, so SARA can tell you the fix and you apply it yourself. If you later want SARA to apply fixes, give the service account more rights on a Dev or Staging cluster first.
Get started
The Free plan is enough to connect one cluster. Sign up, create the service account, and ask SARA about the pod that's been restarting all week. The Kubernetes guide lists every kubeconfig field Skyportal accepts.