Skip to content

Kubernetes

Connect a Kubernetes cluster so SARA can investigate it, and change it when you approve. There are two ways to connect:

Kubeconfig In-cluster agent
Setup Paste a kubeconfig, or an API server URL and a token Install a Helm chart in the cluster
Network The API server must be reachable from the internet The agent only makes outbound HTTPS calls
What SARA can run kubectl and helm, reads and changes, each through approvals Read-only kubectl
Credentials Your kubeconfig, stored encrypted by SkyPortal An agent token; no kubeconfig leaves the cluster

This page covers the kubeconfig route.

Connect with a kubeconfig

In the web app

  1. In the Hosts sidebar, click New Host, then open the ⎈ Kubernetes cluster tab.
  2. Choose how to provide credentials:
    • Paste kubeconfig: paste it into the Kubeconfig field.
    • Enter details: fill API server URL and Service-account token, and optionally CA certificate. Skip TLS verify is only allowed for Dev hosts.
  3. Fill Server Name, choose the Environment, and optionally a Default namespace. Without one, SARA starts in default; you can change it later from the Scope picker.
  4. Click Test Connection, then Save.

When you save, SkyPortal runs kubectl version against the cluster from its own servers. A cluster it can't reach is not saved.

From a chat

Write "add a kubernetes cluster" and paste the kubeconfig, or let SARA ask for each detail: the name, the API server URL, a kubeconfig or token, the CA, Skip TLS verify, the default namespace and the environment. The credentials go straight to SkyPortal and are never sent to the model.

From the CLI or the SDK

skyportalai kubernetes connect ml-cluster --kubeconfig ~/.kube/config --environment Staging

See CLI commands and the Python SDK.

Kubeconfigs that are refused

SkyPortal runs kubectl on its own servers, so it refuses kubeconfigs that would make those servers run a program, read a local file or reach a private network.

Refused What to do instead
An exec credential plugin (users[].user.exec), the default in EKS, GKE and AKS kubeconfigs Use a token or client-certificate kubeconfig, for example with a service-account token from kubectl create token <service-account>
File references: client-certificate, client-key, certificate-authority Embed the data with kubectl config view --flatten --raw. Treat the output as a secret
A tokenFile reference Replace it with an inline token. --flatten does not embed token files
A cluster proxy-url Remove it and point server at a publicly reachable API endpoint
YAML merge keys (<<) or duplicate keys Export a plain kubeconfig with kubectl config view --flatten --raw
An API server on a private or internal address: loopback, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, link-local, localhost, *.local, *.internal, or a hostname that doesn't resolve Use the in-cluster agent
insecure-skip-tls-verify on a host that isn't labelled Dev Provide the cluster's CA certificate. A CA and Skip TLS verify can't be combined

Inline credentials (token, client-certificate-data, client-key-data and certificate-authority-data) are accepted.

SkyPortal stores the kubeconfig encrypted. For each command, kubectl reads it from a temporary file that is deleted afterwards.

Give SARA only the access you want it to have

SARA uses whatever the kubeconfig allows. Create a service account with just the permissions you're comfortable with, and connect with its token.

How SARA works with the cluster

  • kubectl and helm run on SkyPortal's servers, never inside your cluster.
  • This connection is not read-only. SARA can apply manifests, delete resources and upgrade Helm releases. Each command goes through the approval rules, including the environment policy: on a host labelled Production, destructive commands are blocked.
  • Reading Secrets, touching RBAC objects, kubectl exec, cp, attach and port-forward, and deleting a namespace, PVC or PV always need a new approval, even when a permit list matches.
  • Each step is a single kubectl or helm command. Pipes, &&, redirects and xargs are refused.

Namespaces

Pick the namespaces SARA may use in the chat's Scope picker. It also has All namespaces (cluster-wide).

  • With no namespace selected, only cluster-wide commands such as kubectl get ns, kubectl top nodes and kubectl cluster-info run.
  • Commands aimed at a namespace outside the selection are refused.
  • -A only works when All namespaces is selected.
  • When exactly one namespace is selected, SkyPortal adds -n for you.

In the interactive terminal, use /namespace.

Monitoring

Clusters connected with a kubeconfig appear in the Monitor Dashboard. See Monitoring.