RBAC & permissions¶

The minimum set of Kubernetes API permissions kube-saver needs to operate.

Authentication and connectivity¶

A live scan needs a reachable Kubernetes API and an authenticated identity. Locally, use your kubeconfig (or set KUBECONFIG to its file path). Select a context with KUBE_SAVER_CONTEXT or kubeconfig_context, and check it with kube-saver doctor --context <name>. Kubeconfig exec plugins may contact an identity provider and must be installed where the CLI runs.

Inside a pod, the client loads an available kubeconfig first and otherwise uses the mounted service account token. An explicit KUBECONFIG must refer to an existing file. Authentication does not grant authorization: that identity still needs the Kubernetes RBAC below. Cloud IAM alone is insufficient.

Examples using manifests/ assume you have cloned the repository and are in its root. kubectl apply installs RBAC objects and requires separate administrative permissions; kube-saver scans do not create them. The container guide explains credential mounts and plugins.

Minimum required permissions¶

kube-saver is read-only. It needs list and get on these resources:

API group	Resources	Verbs
`""` (core)	`pods`, `nodes`, `namespaces`	`list`, `get`
`apps`	`deployments`, `replicasets`, `statefulsets`, `daemonsets`	`list`, `get`
`metrics.k8s.io`	`pods`, `nodes`	`list`, `get`

The metrics.k8s.io permission is optional. If metrics-server is unavailable, kube-saver falls back to request-based estimates automatically.

Cluster-scoped deployment¶

Use a ClusterRole when you want a single kube-saver instance to scan the entire cluster.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kube-saver-reader
rules:
  - apiGroups: [""]
    resources: ["pods", "nodes", "namespaces"]
    verbs: ["list", "get"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
    verbs: ["list", "get"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods", "nodes"]
    verbs: ["list", "get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kube-saver-reader
subjects:
  - kind: ServiceAccount
    name: kube-saver
    namespace: kube-saver
roleRef:
  kind: ClusterRole
  name: kube-saver-reader
  apiGroup: rbac.authorization.k8s.io

Apply it:

kubectl apply -f manifests/cluster-scoped-rbac.yaml

Namespace-scoped deployment¶

Use a Role + RoleBinding per namespace when you want to limit kube-saver to specific namespaces. Set namespace_filter in .kube-saver.yaml to those namespace names; this lets kube-saver scan them without cluster-wide permission to list Namespace objects.

namespace_filter:
  - MY-NAMESPACE

apiVersion: v1
kind: Namespace
metadata:
  name: kube-saver
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kube-saver
  namespace: kube-saver
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kube-saver-reader
  namespace: MY-NAMESPACE
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["list", "get"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
    verbs: ["list", "get"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["list", "get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kube-saver-reader
  namespace: MY-NAMESPACE
subjects:
  - kind: ServiceAccount
    name: kube-saver
    namespace: kube-saver
roleRef:
  kind: Role
  name: kube-saver-reader
  apiGroup: rbac.authorization.k8s.io

Replace MY-NAMESPACE with each target namespace in the manifest and config. Node totals and namespace labels need cluster-wide permissions, so they are unavailable in this mode. doctor checks the selected namespaces when namespace_filter is set.

Verifying permissions¶

Run kube-saver doctor to check whether your current context has the required access:

kube-saver doctor

It runs SelfSubjectAccessReview checks and reports exactly which permissions are missing.