Meshery requires specific kubeconfig permissions to connect to and manage Kubernetes clusters, but these requirements were undocumented. At minimum, read access to kube-system namespace is required for cluster identification.

Changes

New Infrastructure Management Guide

• kubernetes-cluster-permissions.md: Comprehensive guide covering minimum and full management permissions, complete RBAC examples, permission levels for different use cases, security considerations, and troubleshooting guide
• Location: Placed in guides/infrastructure-management/ as a grandchild under "Managing Connections" for better discoverability

Key Content Areas

• Minimum permissions: Read access to kube-system namespace (Meshery uses the namespace UID as unique cluster identifier)
• Full management permissions: Namespace management, Operator/MeshSync/Broker deployment, RBAC setup, resource discovery
• Complete RBAC examples: ClusterRole, ServiceAccount, and kubeconfig generation
• Permission levels: Read-only monitoring, standard management, namespace-scoped access
• Troubleshooting: Common permission issues and resolution steps

Integration Points

• Updated quick-start.md with permissions alert in cluster connection section
• Updated kubernetes.md prerequisites to reference permissions documentation
• Updated lifecycle-management.md with Kubernetes permissions notice
• Added navigation entry in toc.yml under Infrastructure Management → Managing Connections

Technical Basis

Analysis of connection handling code confirmed:

• server/models/k8s_context.go: Queries kube-system namespace UID for cluster identification
• server/models/meshery_controllers.go: Deploys Operator to meshery namespace by default
• MeshSync requires broad read access for cluster-wide resource discovery

# Minimum required for cluster connection
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: meshery-minimum-access
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  resourceNames: ["kube-system"]
  verbs: ["get"]

Custom agent used: Meshery Docs Contributor
Expert-level documentation agent specialized in contributing to Meshery's Jekyll-based documentation site with deep knowledge of technical writing, information architecture, and the Meshery ecosystem.

• Fixes [Docs] Add docs for specfying the permissions that the kubeconfig needs to connect to meshery #16648

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.