Installation

This guide will help you install KubeStellar A2A on your system with all required dependencies.

System Requirements

Minimum Requirements

Python: 3.11 or higher
Memory: 512MB available RAM
Storage: 100MB free disk space
Network: Internet access for package downloads

Recommended Requirements

Python: 3.12 or higher
Memory: 2GB available RAM
Storage: 1GB free disk space
kubectl: Configured with at least one Kubernetes cluster
Helm: Version 3.x for advanced deployment features

Installation Methods

Method 1: Using uv (Recommended)

uv is the fastest Python package installer and project manager.

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/kubestellar/a2a.git
cd a2a

# Install KubeStellar A2A with all dependencies
uv pip install -e ".[dev]"

Method 2: Using pip

# Clone the repository
git clone https://github.com/kubestellar/a2a.git
cd a2a

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install KubeStellar A2A
pip install -e .

Method 3: Development Installation

For contributors and developers:

# Clone the repository
git clone https://github.com/kubestellar/a2a.git
cd a2a

# Install with development dependencies
uv pip install -e ".[dev,test]"

# Install pre-commit hooks (optional)
pre-commit install

Verify Installation

Test your installation to ensure everything is working correctly:

# Check CLI installation
uv run kubestellar --help

# List available functions
uv run kubestellar list-functions

# Test basic functionality
uv run kubestellar execute get_kubeconfig

CLI Commands Overview

Main Commands

# Show help
uv run kubestellar --help

# List all available functions
uv run kubestellar list-functions

# Execute a function with parameters
uv run kubestellar execute <function_name> [parameters]

# Get detailed function description and schema
uv run kubestellar describe <function_name>

# Start interactive agent mode
uv run kubestellar agent

Function Execution Examples

# Using --param flag
uv run kubestellar execute get_kubeconfig --param context=production --param detail_level=full

# Using -P shorthand (recommended)
uv run kubestellar execute get_kubeconfig -P context=staging -P detail_level=contexts

# Using JSON parameters
uv run kubestellar execute get_kubeconfig --params '{"context": "production", "detail_level": "full"}'

# Complex array parameters
uv run kubestellar execute namespace_utils -P target_namespaces='["prod","staging"]' -P all_namespaces=true

Available Functions

- kubestellar_management
  Description: Advanced KubeStellar multi-cluster resource management with deep search capabilities
  
- get_kubeconfig
  Description: Get details from kubeconfig file including contexts, clusters, and users
  
- helm_deploy
  Description: Deploy Helm charts across clusters with KubeStellar binding policy integration
  
- namespace_utils  
  Description: List and count pods, services, deployments and other resources across namespaces
  
- gvrc_discovery
  Description: Discover and inventory all available Kubernetes API resources across clusters
  
- multicluster_create
  Description: Create Kubernetes resources across multiple clusters
  
- multicluster_logs
  Description: Aggregate and stream logs from multiple clusters
  
- deploy_to
  Description: Deploy resources to specific clusters with advanced targeting

Optional Components

AI Features Setup

For AI-powered automation and natural language interfaces:

OpenAI Integration

# Set your OpenAI API key
export OPENAI_API_KEY="your-openai-api-key"

# Test agent mode
uv run kubestellar agent

Agent Mode Interface

╭─────────────────────────────────────────────────────────────────────────────────────────────╮
│  ██╗  ██╗██╗   ██╗██████╗ ███████╗███████╗████████╗███████╗██╗     ██╗      █████╗ ██████╗  │
│  ██║ ██╔╝██║   ██║██╔══██╗██╔════╝██╔════╝╚══██╔══╝██╔════╝██║     ██║     ██╔══██╗██╔══██╗ │
│  █████╔╝ ██║   ██║██████╔╝█████╗  ███████╗   ██║   █████╗  ██║     ██║     ███████║██████╔╝ │
│  ██╔═██╗ ██║   ██║██╔══██╗██╔══╝  ╚════██║   ██║   ██╔══╝  ██║     ██║     ██╔══██║██╔══██╗ │
│  ██║  ██╗╚██████╔╝██████╔╝███████╗███████║   ██║   ███████╗███████╗███████╗██║  ██║██║  ██║ │
│  ╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚══════╝   ╚═╝   ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ │
│                       Multi-Cluster Kubernetes Management Agent                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯

Provider: openai
Model: gpt-4o

Type 'help' for available commands
Type 'exit' or Ctrl+D to quit

[openai] ▶ 

Agent Commands

# Natural language queries
[openai] ▶ how many pods are running?
[openai] ▶ show me kubestellar topology
[openai] ▶ deploy nginx using helm to production clusters
[openai] ▶ check binding policy status

# Built-in commands
help          # Show available commands
clear         # Clear conversation history
provider <name>  # Switch AI provider
exit          # Exit the agent

Claude MCP Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kubestellar": {
      "command": "uv",
      "args": ["run", "kubestellar-mcp"],
      "cwd": "/path/to/a2a"
    }
  }
}

KubeStellar Integration

For full KubeStellar 2024 architecture support:

# Ensure you have KubeStellar installed
# Follow the official KubeStellar installation guide
# https://docs.kubestellar.io/

# Verify KubeStellar is accessible
kubectl get wds --all-namespaces
kubectl get its --all-namespaces

Configuration

Environment Variables

Set up common environment variables for seamless operation:

# Add to your shell profile (.bashrc, .zshrc, etc.)

# Kubernetes configuration
export KUBECONFIG="$HOME/.kube/config"

# AI provider - OpenAI (currently only supported provider)
export OPENAI_API_KEY="your-openai-key"

# Logging level
export LOG_LEVEL="INFO"

Configuration File

Create a configuration file at ~/.kube/a2a-config.yaml:

# AI Provider Configuration (OpenAI only currently supported)
providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    temperature: 0.7
    
default_provider: "openai"

# UI Configuration
ui:
  show_thinking: true
  show_token_usage: true
  
# Cluster Configuration
clusters:
  default_timeout: "5m"
  auto_discovery: true

Note: Additional AI providers (Claude, Gemini, etc.) will be added in future releases.

Troubleshooting Installation

Common Issues

Python Version Issues

# Check Python version
python --version

# If using pyenv, set local version
pyenv local 3.12

Permission Issues

# On macOS/Linux, you might need to use sudo for system-wide installation
sudo uv pip install -e .

# Or install to user directory
uv pip install --user -e .

Network Issues

# If behind corporate proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Install with proxy settings
uv pip install -e . --proxy http://proxy.company.com:8080

Kubernetes Configuration Issues

# Verify kubectl is working
kubectl cluster-info

# List available contexts
kubectl config get-contexts

# Test kubeconfig access
uv run kubestellar execute get_kubeconfig --param detail_level=full

Getting Help

If you encounter issues:

Check the logs: Set LOG_LEVEL=DEBUG for detailed output
Verify prerequisites: Ensure all requirements are met
Update dependencies: Run uv pip install --upgrade -e .
Report issues: GitHub Issues

Next Steps

Once installation is complete:

Quick Start Guide → - Get up and running in 5 minutes
Troubleshooting Guide → - Resolve common issues
GitHub Repository → - Source code and issues

Installation complete! Ready to revolutionize your Kubernetes management? 🚀

System Requirements​

Minimum Requirements​

Recommended Requirements​

Installation Methods​

Method 1: Using uv (Recommended)​

Method 2: Using pip​

Method 3: Development Installation​

Verify Installation​

CLI Commands Overview​

Main Commands​

Function Execution Examples​

Available Functions​

Optional Components​

AI Features Setup​

OpenAI Integration​

Agent Mode Interface​

Agent Commands​

Claude MCP Integration​

KubeStellar Integration​

Configuration​

Environment Variables​

Configuration File​

Troubleshooting Installation​

Common Issues​

Python Version Issues​

Permission Issues​

Network Issues​

Kubernetes Configuration Issues​

Getting Help​

Next Steps​