Skip to content

AUTHENTICATION.md

Latest commit

 

History

History
252 lines (176 loc) · 7.07 KB

AUTHENTICATION.md

File metadata and controls

252 lines (176 loc) · 7.07 KB
Raw

KubeArchive MCP Server - Authentication Guide

This guide explains how to set up Kubernetes RBAC authentication for the KubeArchive MCP server, based on the official KubeArchive documentation.

Overview

KubeArchive delegates authentication and authorization to the Kubernetes RBAC service. To retrieve resources from KubeArchive, you need to pass a Kubernetes service account token when making requests.

Quick Setup

Option 1: Automated Setup (Recommended)

Use the MCP server's built-in authentication tools:

# Start the MCP server
kubearchive-mcp

# Then in your AI assistant, ask:
"Set up Kubernetes RBAC for kubearchive-view service account in the default namespace"

This will:

  1. Create a service account named kubearchive-view
  2. Create appropriate roles and role bindings
  3. Generate a token and configure the client automatically

Option 2: Manual Setup

Step 1: Port Forward KubeArchive

First, ensure KubeArchive is accessible:

kubectl port-forward -n kubearchive svc/kubearchive-api-server 8081:8081

Step 2: Create Service Account and RBAC

# Create service account
kubectl create serviceaccount kubearchive-view --namespace default

# Create role with permissions for resources you want to archive
kubectl create role kubearchive-view-role \
    --verb=get,list,watch \
    --resource=pods,deployments,jobs,configmaps,secrets \
    --namespace default

# Create role binding
kubectl create rolebinding kubearchive-view-binding \
    --serviceaccount=default:kubearchive-view \
    --role=kubearchive-view-role \
    --namespace default

Step 3: Generate Token

export SA_TOKEN=$(kubectl create token kubearchive-view --namespace default)
echo "Your token: $SA_TOKEN"

Step 4: Configure MCP Server

# Method 1: Environment variable
export KUBEARCHIVE_TOKEN="$SA_TOKEN"
kubearchive-mcp

# Method 2: Runtime configuration (ask your AI assistant)
"Configure authentication with token: $SA_TOKEN"

Authentication Tools

The MCP server provides several tools to help with authentication:

setup_kubearchive_auth

Creates a complete RBAC setup automatically:

  • service_account: Name of service account to create (default: kubearchive-view)
  • namespace: Kubernetes namespace (default: default)
  • resources: Resources to grant access to (default: pods,deployments,jobs,configmaps,secrets)

Example: "Set up authentication for production namespace with access to pods and deployments"

generate_auth_setup_script

Generates a shell script for manual setup:

Example: "Generate an authentication setup script"

verify_kubearchive_permissions

Checks if a service account has required permissions:

Example: "Verify permissions for kubearchive-view service account"

configure_kubearchive_token

Sets the authentication token:

Example: "Configure authentication with token eyJ..."

configure_kubearchive_auth

Sets both endpoint and token:

Example: "Configure KubeArchive with endpoint https://archive.example.com and token eyJ..."

Production Considerations

Multi-Namespace Access

For production environments, you might want cluster-wide access:

# Create cluster role
kubectl create clusterrole kubearchive-cluster-view \
    --verb=get,list,watch \
    --resource=pods,deployments,jobs,configmaps,secrets

# Create cluster role binding
kubectl create clusterrolebinding kubearchive-cluster-view-binding \
    --serviceaccount=default:kubearchive-view \
    --clusterrole=kubearchive-cluster-view

Token Rotation

Service account tokens should be rotated regularly:

# Generate new token
NEW_TOKEN=$(kubectl create token kubearchive-view --namespace default)

# Update MCP server (ask your AI assistant)
"Configure authentication with the new token: $NEW_TOKEN"

Monitoring Access

Verify your setup works:

# Test permissions
kubectl auth can-i list pods \
    --as=system:serviceaccount:default:kubearchive-view \
    --namespace default

# Test API access
curl --insecure \
    -H "Authorization: Bearer ${SA_TOKEN}" \
    https://localhost:8081/api/v1/namespaces/default/pods

Troubleshooting

Common Issues

  1. "Forbidden" errors: Service account lacks required permissions

    • Use verify_kubearchive_permissions to check access
    • Ensure role bindings are correct

  2. "Unauthorized" errors: Token is invalid or expired

    • Generate a new token with kubectl create token
    • Update the MCP server configuration

  3. Connection refused: KubeArchive API is not accessible

    • Check port forwarding: kubectl port-forward -n kubearchive svc/kubearchive-api-server 8081:8081
    • Verify KubeArchive is running: kubectl get pods -n kubearchive

Debugging Commands

# Check service account
kubectl get serviceaccount kubearchive-view --namespace default

# Check role and bindings
kubectl get role kubearchive-view-role --namespace default
kubectl get rolebinding kubearchive-view-binding --namespace default

# Test token
kubectl auth can-i --list \
    --as=system:serviceaccount:default:kubearchive-view \
    --namespace default

Security Best Practices

  1. Principle of Least Privilege: Only grant access to resources that need to be archived
  2. Namespace Isolation: Use separate service accounts for different namespaces
  3. Token Rotation: Regularly rotate service account tokens
  4. Monitoring: Monitor access logs and audit trails
  5. Network Security: Use TLS and secure network policies

Example Configurations

Development Environment

# Simple setup for development
kubectl create serviceaccount kubearchive-dev --namespace default
kubectl create role kubearchive-dev-role \
    --verb=get,list \
    --resource=pods,configmaps \
    --namespace default
kubectl create rolebinding kubearchive-dev-binding \
    --serviceaccount=default:kubearchive-dev \
    --role=kubearchive-dev-role \
    --namespace default

export DEV_TOKEN=$(kubectl create token kubearchive-dev --namespace default)

Production Environment

# Production setup with cluster-wide read access
kubectl create serviceaccount kubearchive-prod --namespace kubearchive-system
kubectl create clusterrole kubearchive-prod-role \
    --verb=get,list,watch \
    --resource=pods,deployments,jobs,configmaps,replicasets,daemonsets,statefulsets
kubectl create clusterrolebinding kubearchive-prod-binding \
    --serviceaccount=kubearchive-system:kubearchive-prod \
    --clusterrole=kubearchive-prod-role

export PROD_TOKEN=$(kubectl create token kubearchive-prod --namespace kubearchive-system)

Integration with CI/CD

For automated deployments, store tokens as secrets:

# Create secret
kubectl create secret generic kubearchive-token \
    --from-literal=token="$SA_TOKEN" \
    --namespace your-app-namespace

# Use in deployment
env:
- name: KUBEARCHIVE_TOKEN
  valueFrom:
    secretKeyRef:
      name: kubearchive-token
      key: token

This ensures secure token management in production environments.