Kubernetes Permissions

This document outlines the required Kubernetes permissions for the Obliq AI SRE Agent to work correctly.

Overview

The Avesha Agents platform requires specific Kubernetes permissions to monitor, collect metrics, and manage resources across your cluster. These permissions are organized into three main categories:

• Cluster-Scoped Permissions - Access to cluster-wide resources
• Namespace-Scoped Permissions - Access to resources within specific namespaces
• Metrics API Permissions - Access to Kubernetes metrics for monitoring

Required Permissions

Cluster-Scoped Permissions

The following permissions allow access to cluster-wide resources:

# ClusterRole permissions
- apiGroups: [""]
  resources: ["nodes", "namespaces"]
  verbs: ["get", "list"]

Resources

Resource	Verbs	Description
nodes	get, list	Access to cluster node information
namespaces	get, list	Access to namespace information across the cluster

Namespace-Scoped Permissions

The following permissions allow access to resources within specific namespaces:

# Namespace-scoped permissions
- apiGroups: [""]
  resources: ["pods", "pods/log", "events", "services"]
  verbs: ["get", "list", "watch"]

- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]

Resources

Resource	Verbs	Description
pods	get, list, watch	Access to pod information and status
pods/log	get	Access to pod logs for troubleshooting
events	get, list, watch	Access to Kubernetes events
services	get, list, watch	Access to service information
deployments	get, list, watch	Access to deployment status
replicasets	get, list, watch	Access to replica set information
statefulsets	get, list, watch	Access to stateful set status
daemonsets	get, list, watch	Access to daemon set information

Metrics API Permissions

The following permissions allow access to Kubernetes metrics for monitoring and alerting:

# Metrics API permissions
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]

Resources

Resource	Verbs	Description
pods.metrics.k8s.io	get, list	Access to pod resource metrics (CPU and memory)
nodes.metrics.k8s.io	get, list	Access to node resource metrics

Create ClusterRole and ClusterRoleBinding

Create custom ClusterRoles or use existing ClusterRoles, and bind them.

Create Custom ClusterRole and ClusterRoleBinding

Use the following YAML file to create a custom ClusterRole and ClusterRoleBinding.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: avesha-agents-monitoring
rules:
# Cluster-scoped permissions
- apiGroups: [""]
  resources: ["nodes", "namespaces"]
  verbs: ["get", "list"]

# Namespace-scoped permissions
- apiGroups: [""]
  resources: ["pods", "pods/log", "events", "services"]
  verbs: ["get", "list", "watch"]

- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]

# Metrics API permissions
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: avesha-agents-monitoring
subjects:
- kind: ServiceAccount
  name: avesha-agents
  namespace: avesha
roleRef:
  kind: ClusterRole
  name: avesha-agents-monitoring
  apiGroup: rbac.authorization.k8s.io

Create ClusterRoleBinding with Existing ClusterRoles

If you prefer to use existing cluster roles, you can bind them using the following YAML file.

# Bind to view cluster role (read-only access)
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: avesha-agents-view
subjects:
- kind: ServiceAccount
  name: avesha-agents
  namespace: avesha
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

note

The view cluster role provides most of the required permissions, but may need additional metrics API permissions.

Service Account Configuration

Ensure your Avesha Agents deployment uses the correct service account as in the following YAML file.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: avesha-agents
  namespace: avesha
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: avesha-agents
spec:
  template:
    spec:
      serviceAccountName: avesha-agents
      # ... other configuration

Verify the Permissions

To verify the permissions, use the following commands:

# Test cluster-scoped access
kubectl auth can-i get nodes --as=system:serviceaccount:avesha:avesha-agents
kubectl auth can-i list namespaces --as=system:serviceaccount:avesha:avesha-agents

# Test namespace-scoped access
kubectl auth can-i get pods --as=system:serviceaccount:avesha:avesha-agents -n avesha
kubectl auth can-i get deployments --as=system:serviceaccount:avesha:avesha-agents -n avesha

# Test metrics API access
kubectl auth can-i get pods.metrics.k8s.io --as=system:serviceaccount:avesha:avesha-agents
kubectl auth can-i get nodes.metrics.k8s.io --as=system:serviceaccount:avesha:avesha-agents

Security Considerations

Best Practice	Description
Principle of Least Privilege	Only grant the minimum necessary permissions.
Namespace Isolation	Consider restricting access to specific namespaces if possible.
Regular Review	Periodically review and audit permissions.
Monitoring	Monitor for any permission-related errors in logs.

Troubleshooting

Common Permission Issues

Issue	Resolution
"Forbidden" errors	Check if the service account has the required permissions.
Metrics API errors	Ensure metrics-server is installed and the service account has metrics API access.
Cross-namespace access	Verify ClusterRoleBindings are properly configured.

Debug Commands

# Check service account permissions
kubectl auth can-i --list --as=system:serviceaccount:avesha:avesha-agents

# Check cluster role bindings
kubectl get clusterrolebindings | grep avesha

# Check cluster roles
kubectl get clusterroles | grep avesha