K8sMed

K8sMed: AI-Powered Kubernetes First Responder

K8sMed Logo

K8sMed is an open-source, AI-powered troubleshooting assistant designed to act as a first responder for Kubernetes clusters. By analyzing cluster logs, events, and metrics, K8sMed leverages Large Language Models (LLMs) to diagnose issues, provide natural language explanations, and generate actionable remediation commands—all through a simple kubectl plugin.

License Go Report Card

Table of Contents

Project Overview

K8sMed helps Kubernetes administrators and developers troubleshoot issues faster by acting as a “first responder” for cluster problems. The tool analyzes Kubernetes resources, interprets error messages, and generates clear explanations and remediation steps using AI.

Why K8sMed?

Kubernetes environments are complex, and troubleshooting issues often requires deep expertise. K8sMed reduces mean time to resolution (MTTR) by:

Goals

Key Features

Architecture

K8sMed follows a modular architecture with these key components:

  1. Resource Collection: Gathers information about Kubernetes resources
  2. Problem Analysis: Examines resources for potential issues
  3. AI Processing: Sends anonymized data to AI for interpretation
  4. Remediation Generation: Creates actionable commands to fix issues

The tool runs as a kubectl plugin, requiring only kubectl access to your cluster.

Installation

Prerequisites

Quick Install

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

# Build the binary
make build

# Install the kubectl plugin
make install

Verify Installation

kubectl k8smed version

Usage

Basic Analysis

# Analyze a pod with issues
kubectl k8smed analyze pod my-pod-name --namespace default

# Analyze with a specific question
kubectl k8smed query "Why is my pod in CrashLoopBackOff state?"

# Get remediation suggestions
kubectl k8smed suggest pod my-pod-name

Anonymization

# Enable anonymization to protect sensitive data
kubectl k8smed analyze pod my-pod-name --anonymize

Using Different AI Providers

# Use OpenAI
export OPENAI_API_KEY=your_api_key
kubectl k8smed analyze pod my-pod-name

# Use LocalAI
export K8SMED_AI_PROVIDER=localai
export K8SMED_AI_ENDPOINT=http://localhost:8080
kubectl k8smed analyze pod my-pod-name

Configuration

K8sMed can be configured using environment variables:

Variable Description Default
K8SMED_AI_PROVIDER AI provider (openai, localai) openai
K8SMED_AI_MODEL Model name to use gpt-3.5-turbo
K8SMED_AI_ENDPOINT API endpoint for LocalAI -
K8SMED_ANONYMIZE_DEFAULT Enable anonymization by default false
K8SMED_OUTPUT_FORMAT Output format (text, json) text
OPENAI_API_KEY OpenAI API key -

Examples

Diagnosing a Pod in CrashLoopBackOff

kubectl k8smed analyze pod nginx-deployment-665d87f687-abcde

Output:

📋 K8sMed Analysis:
🔍 Pod nginx-deployment-665d87f687-abcde is in CrashLoopBackOff state

📝 Description:
The container is repeatedly crashing after startup. The exit code 1 suggests
the application is exiting with an error.

✅ Remediation:
1. Check container logs: kubectl logs nginx-deployment-665d87f687-abcde
2. Verify environment variables are set correctly
3. Check if the application can connect to required services
4. Inspect the startup command for errors

💻 Remediation Commands:
kubectl logs nginx-deployment-665d87f687-abcde
kubectl describe pod nginx-deployment-665d87f687-abcde

More Examples

Check out our examples directory for more use cases, including:

Documentation

Detailed documentation is available in the docs directory:

Privacy & Security

K8sMed takes privacy seriously:

For sensitive environments, we recommend:

  1. Using the --anonymize flag
  2. Setting up a local AI model
  3. Reviewing prompts sent to the AI

Contributing

We welcome contributions to K8sMed! Please see our Contributing Guide for details on:

For technical details about the codebase, architecture, and development workflows, check out our Developer Guide.

Roadmap

Current Focus (Q2-Q3 2025)

Next Steps (Q3-Q4 2025)

Future Plans (2024+)

Getting Involved

We’re actively seeking contributors in the following areas:

  1. Analyzer Development: Help build analyzers for specific Kubernetes resources
  2. AI Integration: Assist with implementing new AI provider integrations
  3. Documentation: Improve guides, examples, and tutorials
  4. Testing: Create test cases and validation frameworks

If you’re interested in contributing, check out our open issues labeled with “good first issue” or “help wanted”, or reach out through our contact channels.

License

K8sMed is licensed under the Apache License 2.0.

Contact

K8sMed aims to revolutionize Kubernetes troubleshooting with an AI-powered approach that delivers fast, accurate, and actionable insights. We invite you to try it out, provide feedback, and join our community of contributors!

This site is open source. Improve this page.