Skip to content

Integrate with Kubernetes

This guide covers how to integrate muster with Kubernetes clusters, enabling AI agents to interact with Kubernetes resources.

Overview

muster can connect to Kubernetes clusters through an MCP server, providing AI agents with tools to:

  • List and inspect Kubernetes resources (pods, deployments, services, etc.)
  • Monitor cluster health and status
  • Execute kubectl-like operations through natural language

Prerequisites

  • muster installed and running
  • Access to a Kubernetes cluster with valid credentials
  • The mcp-kubernetes server binary (or a compatible Kubernetes MCP server)

Quick Start

1. Create the Kubernetes MCP Server

Create an MCP server configuration for Kubernetes:

type: stdio below runs mcp-kubernetes as a subprocess of muster, which is what the local CLI is for. A muster deployed into Kubernetes rejects stdio MCPServers — there, run the Kubernetes MCP server as its own workload and register it with type: streamable-http. See MCPServer CRD reference.

# kubernetes-mcp.yaml
apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: kubernetes
  namespace: default
spec:
  type: stdio
  autoStart: true
  command: ["mcp-kubernetes"]
  description: "Kubernetes cluster management MCP server"

2. Register the Server

muster create mcpserver kubernetes-mcp.yaml

3. Verify the Integration

# Check server status
muster get mcpserver kubernetes

# Test tool availability
muster agent --repl
# In REPL:
filter tools k8s

Using Kubernetes Tools

Once configured, AI agents can access Kubernetes tools through the aggregator. The exact tool names depend on the Kubernetes MCP server implementation and any configured toolPrefix. Common examples include:

  • x_kubernetes_list_pods - List pods in a namespace
  • x_kubernetes_get_pod - Get details of a specific pod
  • x_kubernetes_list_deployments - List deployments
  • x_kubernetes_apply - Apply Kubernetes manifests
  • x_kubernetes_logs - Get pod logs

Note: Tool names are prefixed with x_<server-name>_ by default. If you set a toolPrefix in the MCPServer spec, that prefix is used instead of the server name.

Example: List Pods

Ask your AI agent: 

List all pods in the default namespace

The agent will use the Kubernetes tools to retrieve and display pod information.

SSO Authentication with Kubernetes

For production environments, muster supports Single Sign-On with Kubernetes OIDC authentication. This allows users to authenticate once and access Kubernetes clusters without separate authentication flows.

Configure Token Forwarding

Enable SSO for the Kubernetes MCP server:

apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: mcp-kubernetes
spec:
  description: "Kubernetes MCP with SSO"
  toolPrefix: "k8s"
  type: streamable-http
  url: "https://mcp-kubernetes.example.com/mcp"
  auth:
    type: oauth
    forwardToken: true
    requiredAudiences:
      - "dex-k8s-authenticator"

How it works:

  1. User authenticates to muster via muster auth login
  2. muster requests tokens with Kubernetes OIDC audiences
  3. On MCP requests, muster forwards the token to the Kubernetes server
  4. Users can immediately access Kubernetes without additional authentication

For detailed SSO configuration, see the MCP Server Management Guide.

Multi-Cluster Configuration

To connect to multiple Kubernetes clusters, create separate MCP server configurations:

Production cluster (production-cluster.yaml):

apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: k8s-production
spec:
  type: stdio
  autoStart: true
  command: ["mcp-kubernetes"]
  toolPrefix: "k8s-prod"
  description: "Production Kubernetes cluster"
  env:
    KUBECONFIG: "/path/to/production-kubeconfig"

Staging cluster (staging-cluster.yaml):

apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: k8s-staging
spec:
  type: stdio
  autoStart: true
  command: ["mcp-kubernetes"]
  toolPrefix: "k8s-staging"
  description: "Staging Kubernetes cluster"
  env:
    KUBECONFIG: "/path/to/staging-kubeconfig"

Using different tool prefixes (k8s-prod, k8s-staging) allows AI agents to distinguish between clusters.

Troubleshooting

Server Not Starting

# Check if the command is available
which mcp-kubernetes

# Verify server status
muster get mcpserver kubernetes

# Check for errors in server output
muster check mcpserver kubernetes

Authentication Errors

  • Verify your kubeconfig is valid: kubectl cluster-info
  • Check KUBECONFIG environment variable is set correctly
  • For SSO, ensure the IdP supports cross-client authentication

Tools Not Appearing

# Verify server is running
muster list mcpserver

# Test tool discovery
muster agent --repl
# In REPL:
list tools
filter tools kubernetes