Read-Only Access

Set up secure, read-only access to your Kubernetes clusters for Kubey.

When Do You Need This?

Recommended for shared deployments

If you're deploying Kubey for your team or organization where multiple users will access the dashboard, you should use read-only credentials. This ensures users can view cluster data without the ability to modify resources, delete pods, or change configurations.

Optional for personal/local use

If you're running Kubey locally for personal use (e.g., on your laptop with Docker Desktop or minikube), and it's only accessible to you, using your existing kubeconfig with full access is fine. The security boundary is your local machine.

Required if exposed to the internet

If Kubey will be accessible from the public internet, read-only credentials are essential. See our Network Security guide for additional recommendations on securing your deployment.

Why Read-Only Access?

Kubey is a monitoring and visualization tool. It does not need write access to your clusters. Using read-only credentials provides several benefits:

Security: Even if credentials are compromised, attackers cannot modify your clusters
Compliance: Satisfies principle of least privilege for audit requirements
Peace of mind: Team members can explore clusters freely without risk of accidental changes
Separation of concerns: Keep monitoring access separate from operational access

Quick Setup Script

We provide a script that automatically creates read-only ServiceAccounts across all your kubectl contexts. Download and run it to set up access for all clusters at once.

Download and run the setup scriptbash

# Download the script
curl -sL https://kubey.app/scripts/setup-readonly-access.sh -o setup-readonly-access.sh

# Review the script (always a good practice!)
less setup-readonly-access.sh

# Make it executable and run
chmod +x setup-readonly-access.sh
./setup-readonly-access.sh

The script will iterate through all contexts in your kubeconfig and create:

A kubey-reader ServiceAccount in the kubey namespace
A kubey-reader ClusterRole with read-only permissions
A ClusterRoleBinding connecting the ServiceAccount to the ClusterRole
A long-lived token for authentication

Manual Setup

If you prefer to set up access manually, or want to customize the permissions, follow these steps for each cluster.

1. Create the Namespace and ServiceAccount

kubey-reader-sa.yamlyaml

apiVersion: v1
kind: Namespace
metadata:
  name: kubey
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kubey-reader
  namespace: kubey

2. Create the Read-Only ClusterRole

This ClusterRole grants read-only access to the resources Kubey needs to display cluster information.

kubey-reader-role.yamlyaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubey-reader
rules:
  # Core resources
  - apiGroups: [""]
    resources:
      - pods
      - pods/log
      - services
      - nodes
      - namespaces
      - configmaps
      - secrets
      - persistentvolumeclaims
      - persistentvolumes
      - events
    verbs: ["get", "list", "watch"]
  # Apps resources
  - apiGroups: ["apps"]
    resources:
      - deployments
      - replicasets
      - statefulsets
      - daemonsets
    verbs: ["get", "list", "watch"]
  # Batch resources
  - apiGroups: ["batch"]
    resources:
      - jobs
      - cronjobs
    verbs: ["get", "list", "watch"]
  # Networking
  - apiGroups: ["networking.k8s.io"]
    resources:
      - ingresses
      - networkpolicies
    verbs: ["get", "list", "watch"]
  # Storage
  - apiGroups: ["storage.k8s.io"]
    resources:
      - storageclasses
    verbs: ["get", "list", "watch"]
  # Metrics (if metrics-server is installed)
  - apiGroups: ["metrics.k8s.io"]
    resources:
      - pods
      - nodes
    verbs: ["get", "list"]

3. Bind the Role to the ServiceAccount

kubey-reader-binding.yamlyaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kubey-reader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubey-reader
subjects:
  - kind: ServiceAccount
    name: kubey-reader
    namespace: kubey

4. Create a Long-Lived Token

Kubernetes 1.24+ requires explicitly creating a token Secret for ServiceAccounts.

kubey-reader-token.yamlyaml

apiVersion: v1
kind: Secret
metadata:
  name: kubey-reader-token
  namespace: kubey
  annotations:
    kubernetes.io/service-account.name: kubey-reader
type: kubernetes.io/service-account-token

5. Apply the Configuration

kubectl apply -f kubey-reader-sa.yaml
kubectl apply -f kubey-reader-role.yaml
kubectl apply -f kubey-reader-binding.yaml
kubectl apply -f kubey-reader-token.yaml

6. Retrieve the Token and Cluster Info

Get credentials for Kubeybash

# Get the token
TOKEN=$(kubectl get secret kubey-reader-token -n kubey -o jsonpath='{.data.token}' | base64 -d)

# Get the cluster CA certificate
CA_CERT=$(kubectl get secret kubey-reader-token -n kubey -o jsonpath='{.data.ca\.crt}')

# Get the cluster server URL
SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')

# Display the values
echo "Server: $SERVER"
echo "Token: $TOKEN"
echo "CA Cert (base64): $CA_CERT"

Generate a Kubeconfig File

To use the read-only credentials with Kubey, generate a kubeconfig file:

Generate kubeconfig for Kubeybash

CLUSTER_NAME="my-cluster"  # Change this to your cluster name

# Create the kubeconfig
kubectl config set-cluster $CLUSTER_NAME \
  --server=$SERVER \
  --certificate-authority=<(echo $CA_CERT | base64 -d) \
  --embed-certs=true \
  --kubeconfig=kubey-reader.kubeconfig

kubectl config set-credentials kubey-reader \
  --token=$TOKEN \
  --kubeconfig=kubey-reader.kubeconfig

kubectl config set-context kubey-reader@$CLUSTER_NAME \
  --cluster=$CLUSTER_NAME \
  --user=kubey-reader \
  --kubeconfig=kubey-reader.kubeconfig

kubectl config use-context kubey-reader@$CLUSTER_NAME \
  --kubeconfig=kubey-reader.kubeconfig

echo "Kubeconfig saved to kubey-reader.kubeconfig"

Verify the Setup

Test that the read-only credentials work correctly and cannot modify resources:

Test read-only accessbash

# This should succeed (read operations)
kubectl --kubeconfig=kubey-reader.kubeconfig get pods -A
kubectl --kubeconfig=kubey-reader.kubeconfig get nodes
kubectl --kubeconfig=kubey-reader.kubeconfig get deployments -A

# This should fail (write operations)
kubectl --kubeconfig=kubey-reader.kubeconfig delete pod some-pod -n default
# Error: pods "some-pod" is forbidden: User "system:serviceaccount:kubey:kubey-reader"
# cannot delete resource "pods" in API group "" in the namespace "default"

Cloud Provider Managed Clusters

For managed Kubernetes services, you can also use cloud IAM roles with read-only permissions.

Amazon EKS

Create an IAM role with the AmazonEKSClusterPolicy and map it to the kubey-reader ClusterRole using aws-auth ConfigMap.

Google GKE

Assign the roles/container.viewer IAM role for basic read access, or use the RBAC approach above for more granular control.

Azure AKS

Use Azure RBAC with the Azure Kubernetes Service Cluster User Role combined with Kubernetes RBAC for read-only access.

Best Practices

Use dedicated credentials: Create separate read-only credentials specifically for Kubey rather than reusing admin credentials
Rotate tokens periodically: While the tokens don't expire, it's good practice to rotate them during regular security audits
Audit access: Enable Kubernetes audit logging to track what Kubey accesses
Restrict Secrets access: If you don't need to view Secrets in Kubey, remove secrets from the ClusterRole
Use network policies: If running Kubey in-cluster, restrict its network access to only the API server