AI Assistant — Kubernetes Tools#

Overview#

The AI Assistant can investigate your Kubernetes clusters directly, on demand, while troubleshooting an alert or answering a question in chat. Once a cluster is connected, the assistant can:

list the contexts (clusters) it has access to,
get and list cluster resources (pods, deployments, nodes, services, events, …),
read pod logs,
read Kubernetes events (e.g. to surface a CrashLoopBackOff or a failed image pull).

These tools are read-only by design. The assistant only issues read requests (get, list, watch, logs, events) — it never creates, modifies, deletes, executes into, or port-forwards to anything in your cluster.

This is distinct from Kubernetes monitoring (topology, metrics, dashboards), which is covered in Kubernetes. The tools here give the assistant live, interactive read access for troubleshooting; they don't ingest or store metrics.

Enabling the tools is two steps: create a read-only ServiceAccount in your cluster, then add a Kubernetes connector in Unryo containing a kubeconfig built from that ServiceAccount. A single connector's kubeconfig can hold several clusters (as separate contexts), and you can add multiple connectors — so this supports many clusters.

How the assistant addresses a cluster#

The assistant selects a cluster by context, namespaced by its connector as <connectorName>/<contextName> — for example prod/us-east. Context names come from the kubeconfig you paste and needn't be unique across connectors; the <connectorName>/ prefix keeps them distinct. Two rules to know:

The kubeconfig's current-context is ignored — the assistant always picks a context explicitly (the list_kubernetes_contexts tool shows the available <connector>/<context> values).
Exception: when exactly one context exists across all connectors, the assistant uses it without being asked.

Step 1 — Create a read-only ServiceAccount in your cluster#

The assistant authenticates with a ServiceAccount token that has read-only access. Apply the following in each cluster you want to reach (it creates a dedicated unryo namespace, a ServiceAccount, a read-only ClusterRole and binding, and a long-lived token):

apiVersion: v1
kind: Namespace
metadata:
  name: unryo
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: unryo-ai-assistant
  namespace: unryo
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: unryo-ai-assistant-readonly
rules:
  - apiGroups: [""]
    resources: [pods, pods/log, services, endpoints, configmaps,
                persistentvolumeclaims, persistentvolumes, nodes, namespaces, events]
    verbs: [get, list]
  - apiGroups: ["apps"]
    resources: [deployments, replicasets, statefulsets, daemonsets]
    verbs: [get, list]
  - apiGroups: ["batch"]
    resources: [jobs, cronjobs]
    verbs: [get, list]
  - apiGroups: ["networking.k8s.io"]
    resources: [ingresses, networkpolicies]
    verbs: [get, list]
  - apiGroups: ["events.k8s.io"]
    resources: [events]
    verbs: [get, list]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: unryo-ai-assistant-readonly
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: unryo-ai-assistant-readonly
subjects:
  - kind: ServiceAccount
    name: unryo-ai-assistant
    namespace: unryo
---
apiVersion: v1
kind: Secret
metadata:
  name: unryo-ai-assistant-token
  namespace: unryo
  annotations:
    kubernetes.io/service-account.name: unryo-ai-assistant
type: kubernetes.io/service-account-token

kubectl apply -f unryo-ai-assistant-rbac.yaml

The Secret of type kubernetes.io/service-account-token yields a long-lived token, which is what a persistent connector needs. This also works on older clusters that don't support kubectl create token.

Restrict the scope as you see fit. The ClusterRole above grants cluster-wide read access to the resources the assistant's tools understand. If you only want the assistant to see specific namespaces, replace the ClusterRole/ClusterRoleBinding with a namespaced Role/RoleBinding — the tools will simply return less.

Step 2 — Build a self-contained kubeconfig#

The connector takes a kubeconfig. We encourage a self-contained one, so nothing has to be read from disk or fetched at query time:

Self-contained means every credential is embedded inline — using the *-data fields (certificate-authority-data, client-*-data) or a token — rather than referenced by file path.
If your kubeconfig does reference anything external (file paths, or an exec: credential plugin — common with cloud-provider CLIs like aws/gcloud/kubelogin), it must be present inside the assistant container: files mounted at the exact paths the kubeconfig names, and exec-plugin binaries on the container's PATH. Unryo does not fetch or provide them. The ServiceAccount-token kubeconfig built below avoids this entirely.

Build one from the ServiceAccount you just created:

SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA=$(kubectl get secret unryo-ai-assistant-token -n unryo -o jsonpath='{.data.ca\.crt}')      # already base64
TOKEN=$(kubectl get secret unryo-ai-assistant-token -n unryo -o jsonpath='{.data.token}' | base64 -d)

cat <<EOF
apiVersion: v1
kind: Config
clusters:
- name: my-cluster
  cluster:
    server: ${SERVER}
    certificate-authority-data: ${CA}
users:
- name: unryo-ai-assistant
  user:
    token: ${TOKEN}
contexts:
- name: my-cluster          # becomes "<connectorName>/my-cluster" — name it meaningfully
  context:
    cluster: my-cluster
    user: unryo-ai-assistant
current-context: my-cluster  # ignored by the assistant; harmless to leave in
EOF

Notes:

The server URL must be reachable from where Unryo runs. If your API server isn't directly reachable (private cluster, network segmentation), expose it through whatever secure path your environment uses (VPN, bastion, jump host) and put that address in server.
The API server presents a TLS certificate valid for a specific set of names/IPs (its Subject Alternative Names). The host in server must match one of them, or TLS verification fails. kubernetes and 127.0.0.1 are commonly present.
To expose several clusters through one connector, add more clusters/users/contexts entries to the same kubeconfig — each context becomes its own <connectorName>/<contextName>.

Step 3 — Add a Kubernetes connector in Unryo#

Go to Configuration Management > Connectors.
Click +.
Select the Kubernetes connector template.
Fill in the settings:
- Name — a short, meaningful connector name (e.g. prod). It prefixes every context from this connector, so contexts appear as prod/<context>. It must not contain /.
- kubeconfig — paste the kubeconfig from Step 2.
Apply.

Unryo stores the configuration and credentials encrypted in the secure on-premise vault in your infrastructure. Within a few seconds the assistant can reach the cluster — ask it to "list the Kubernetes contexts you can access" to confirm your <connector>/<context> appears.

For many clusters, either add multiple contexts to one connector's kubeconfig, or add multiple connectors. When more than one context is available the assistant selects by the fully-qualified <connector>/<context> name (and will ask you to disambiguate if a request is ambiguous).

Security#

Read-only on two levels. The ServiceAccount is bound to a read-only ClusterRole, and the assistant's tools only ever issue read requests — there is no code path that writes, deletes, execs, or port-forwards.
Least privilege. Scope the RBAC down to specific namespaces (or fewer resources) if you don't want cluster-wide read access — see the note in Step 1. Only paste kubeconfig contexts you actually want the assistant to reach.
Credential handling. The kubeconfig (token and CA) is stored encrypted in Unryo's on-premise vault. To revoke access, delete the ServiceAccount (and its binding) in the cluster and remove the connector in Unryo.