@zerry_jin/k8s-doctor-mcp 1.0.0

package/dist/analyzers/log-analyzer.js

@@ -0,0 +1,402 @@
+/**
+ * Log analysis module
+ *
+ * Rather than simply showing logs
+ * finds error patterns and analyzes root causes
+ *
+ * @author zerry
+ */
+/**
+ * Analyze pod logs
+ *
+ * Finds error patterns in logs and suggests solutions
+ * Extracts key information from thousands of log lines
+ */
+export async function analyzeLogs(logApi, namespace, podName, containerName, tailLines = 500) {
+    try {
+        const stream = new (require('stream').Writable)();
+        let logData = '';
+        stream._write = (chunk, encoding, next) => {
+            logData += chunk.toString();
+            next();
+        };
+        // Fetch logs
+        await logApi.log(namespace, podName, containerName || '', stream, {
+            tailLines,
+        });
+        const lines = logData.split('\n').filter(line => line.trim());
+        // 1. Extract error/warning lines
+        const errorLines = extractErrorLines(lines);
+        const warningLines = extractWarningLines(lines);
+        // 2. Detect error patterns
+        const patterns = detectErrorPatterns(lines);
+        // 3. Find repeated errors
+        const repeatedErrors = findRepeatedErrors(errorLines);
+        // 4. Generate summary
+        const summary = generateLogSummary(lines.length, errorLines, patterns);
+        // 5. Generate recommendations
+        const recommendations = generateRecommendations(patterns, repeatedErrors);
+        return {
+            totalLines: lines.length,
+            errorLines,
+            warningLines,
+            patterns,
+            repeatedErrors,
+            summary,
+            recommendations,
+        };
+    }
+    catch (error) {
+        throw new Error(`Log analysis failed: ${error.message}`);
+    }
+}
+/**
+ * Extract error lines
+ *
+ * Finds errors using keywords like ERROR, Exception, Fatal
+ */
+function extractErrorLines(lines) {
+    const errorKeywords = [
+        'error',
+        'exception',
+        'fatal',
+        'panic',
+        'failed',
+        'failure',
+        'err:',
+        'traceback',
+        'stacktrace',
+    ];
+    const errorLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lowerLine = line.toLowerCase();
+        for (const keyword of errorKeywords) {
+            if (lowerLine.includes(keyword)) {
+                errorLines.push({
+                    lineNumber: i + 1,
+                    content: line,
+                    timestamp: extractTimestamp(line),
+                    level: 'ERROR',
+                });
+                break;
+            }
+        }
+    }
+    return errorLines;
+}
+/**
+ * Extract warning lines
+ */
+function extractWarningLines(lines) {
+    const warnKeywords = ['warn', 'warning', 'deprecated'];
+    const warningLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lowerLine = line.toLowerCase();
+        for (const keyword of warnKeywords) {
+            if (lowerLine.includes(keyword)) {
+                warningLines.push({
+                    lineNumber: i + 1,
+                    content: line,
+                    timestamp: extractTimestamp(line),
+                    level: 'WARN',
+                });
+                break;
+            }
+        }
+    }
+    return warningLines;
+}
+/**
+ * Detect error patterns
+ *
+ * Matches patterns of commonly occurring errors with solutions
+ * This is the core functionality!
+ */
+function detectErrorPatterns(lines) {
+    const patterns = [];
+    // Pattern definitions: errors frequently seen in production
+    const knownPatterns = [
+        {
+            name: 'Connection Refused',
+            regex: /connection refused|ECONNREFUSED/i,
+            description: 'Cannot connect to target service',
+            causes: [
+                'Target service not started yet',
+                'Wrong service port',
+                'Blocked by network policy',
+            ],
+            solutions: [
+                'Check if service is running: kubectl get pods',
+                'Verify service port: kubectl get svc',
+                'Check network policy: kubectl get networkpolicy',
+            ],
+            severity: 'high',
+        },
+        {
+            name: 'Database Connection Error',
+            regex: /could not connect to.*database|ETIMEDOUT.*:5432|:3306|:27017/i,
+            description: 'Database connection failed',
+            causes: [
+                'DB service not ready',
+                'Invalid connection string',
+                'DB authentication failed',
+            ],
+            solutions: [
+                'Check DB Pod status',
+                'Verify environment variables (ConfigMap/Secret)',
+                'Check DB service endpoints: kubectl get endpoints',
+            ],
+            severity: 'critical',
+        },
+        {
+            name: 'Out of Memory',
+            regex: /out of memory|OOMKilled|cannot allocate memory/i,
+            description: 'Insufficient memory',
+            causes: [
+                'Memory limit set too low',
+                'Memory leak',
+                'Higher memory usage than expected',
+            ],
+            solutions: [
+                'Increase memory limit: resources.limits.memory',
+                'Profile application memory usage',
+                'Increase pod count with HPA',
+            ],
+            severity: 'critical',
+        },
+        {
+            name: 'File Not Found',
+            regex: /no such file|ENOENT|FileNotFoundError/i,
+            description: 'File or directory not found',
+            causes: [
+                'ConfigMap/Secret not mounted',
+                'Invalid file path',
+                'Volume mount failed',
+            ],
+            solutions: [
+                'Check volumeMounts configuration',
+                'Verify ConfigMap/Secret exists',
+                'Verify file path is correct',
+            ],
+            severity: 'high',
+        },
+        {
+            name: 'Permission Denied',
+            regex: /permission denied|EACCES|access denied/i,
+            description: 'Permission denied',
+            causes: [
+                'SecurityContext runAsUser setting',
+                'Volume fsGroup not set',
+                'File permission issues',
+            ],
+            solutions: [
+                'Configure securityContext:\nfsGroup: 1000\nrunAsUser: 1000',
+                'Check volume permissions',
+                'Set permissions in Dockerfile',
+            ],
+            severity: 'high',
+        },
+        {
+            name: 'DNS Resolution Failed',
+            regex: /dns.*failed|getaddrinfo.*ENOTFOUND|name.*not known/i,
+            description: 'DNS lookup failed',
+            causes: [
+                'CoreDNS issues',
+                'Invalid service name',
+                'ndots configuration problem',
+            ],
+            solutions: [
+                'Check CoreDNS Pod: kubectl get pods -n kube-system',
+                'Service name format: <service>.<namespace>.svc.cluster.local',
+                'Verify dnsPolicy setting',
+            ],
+            severity: 'high',
+        },
+        {
+            name: 'Port Already in Use',
+            regex: /address already in use|EADDRINUSE/i,
+            description: 'Port already in use',
+            causes: [
+                'Multiple processes using same port',
+                'Previous process not terminated properly',
+            ],
+            solutions: [
+                'Change port number',
+                'Implement graceful shutdown',
+                'Configure preStop hook',
+            ],
+            severity: 'medium',
+        },
+        {
+            name: 'Timeout',
+            regex: /timeout|timed out|ETIMEDOUT/i,
+            description: 'Timeout occurred',
+            causes: [
+                'Response time too long',
+                'Network latency',
+                'Target service overloaded',
+            ],
+            solutions: [
+                'Increase timeout value',
+                'Optimize service performance',
+                'Adjust readinessProbe timeout',
+            ],
+            severity: 'medium',
+        },
+        {
+            name: 'Null Pointer / Undefined',
+            regex: /null pointer|undefined is not|cannot read property.*undefined|NullPointerException/i,
+            description: 'Null/Undefined reference',
+            causes: [
+                'Environment variable not set',
+                'Using uninitialized variable',
+            ],
+            solutions: [
+                'Verify ConfigMap/Secret',
+                'Set default value for environment variables',
+                'Fix code',
+            ],
+            severity: 'medium',
+        },
+        {
+            name: 'SSL/TLS Error',
+            regex: /ssl.*error|certificate.*invalid|CERT_/i,
+            description: 'SSL/TLS certificate error',
+            causes: [
+                'Expired certificate',
+                'Self-signed certificate',
+                'CA bundle missing',
+            ],
+            solutions: [
+                'Renew certificate',
+                'Verify tls.crt, tls.key Secret',
+                'NODE_TLS_REJECT_UNAUTHORIZED=0 (development only)',
+            ],
+            severity: 'high',
+        },
+    ];
+    // Match each pattern
+    for (const pattern of knownPatterns) {
+        const matchedLines = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (pattern.regex.test(lines[i])) {
+                matchedLines.push(i + 1);
+            }
+        }
+        if (matchedLines.length > 0) {
+            patterns.push({
+                name: pattern.name,
+                matchedLines,
+                description: pattern.description,
+                possibleCauses: pattern.causes,
+                solutions: pattern.solutions,
+                severity: pattern.severity,
+            });
+        }
+    }
+    return patterns;
+}
+/**
+ * Find repeated errors
+ *
+ * If the same error keeps occurring, there's a pattern
+ */
+function findRepeatedErrors(errorLines) {
+    const errorMap = new Map();
+    for (const entry of errorLines) {
+        // Normalize error message (remove timestamps, numbers, etc.)
+        const normalized = normalizeErrorMessage(entry.content);
+        if (!errorMap.has(normalized)) {
+            errorMap.set(normalized, []);
+        }
+        errorMap.get(normalized).push(entry.lineNumber);
+    }
+    const repeatedErrors = [];
+    for (const [message, lineNumbers] of errorMap.entries()) {
+        if (lineNumbers.length >= 3) { // If repeated 3+ times
+            repeatedErrors.push({
+                message,
+                count: lineNumbers.length,
+                firstLine: lineNumbers[0],
+                lastLine: lineNumbers[lineNumbers.length - 1],
+                isPattern: true,
+            });
+        }
+    }
+    // Sort by occurrence count
+    return repeatedErrors.sort((a, b) => b.count - a.count);
+}
+/**
+ * Normalize error message
+ *
+ * Remove timestamps, IPs, ports, etc. to group similar errors
+ */
+function normalizeErrorMessage(message) {
+    return message
+        .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}.*?Z/g, '<timestamp>') // ISO timestamp
+        .replace(/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/g, '<ip>') // IP address
+        .replace(/:\d{2,5}/g, ':<port>') // Port number
+        .replace(/\d+/g, '<num>') // Other numbers
+        .replace(/0x[0-9a-f]+/gi, '<hex>') // Hex values
+        .toLowerCase()
+        .trim();
+}
+/**
+ * 타임스탬프 추출
+ *
+ * 로그에서 타임스탬프를 파싱 시도
+ */
+function extractTimestamp(line) {
+    // ISO 8601 format
+    const isoMatch = line.match(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?/);
+    if (isoMatch)
+        return isoMatch[0];
+    // RFC 3339
+    const rfcMatch = line.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}/);
+    if (rfcMatch)
+        return rfcMatch[0];
+    return undefined;
+}
+/**
+ * Generate log summary
+ */
+function generateLogSummary(totalLines, errorLines, patterns) {
+    let summary = `Analyzed ${totalLines} lines of logs.\n`;
+    summary += `Errors: ${errorLines.length}\n`;
+    if (patterns.length > 0) {
+        summary += `\nDetected ${patterns.length} error patterns:\n`;
+        for (const pattern of patterns) {
+            summary += `  - ${pattern.name} (${pattern.matchedLines.length} occurrences)\n`;
+        }
+    }
+    else {
+        summary += '\n✅ No known error patterns detected.';
+    }
+    return summary;
+}
+/**
+ * Generate recommendations
+ */
+function generateRecommendations(patterns, repeatedErrors) {
+    const recommendations = [];
+    // Prioritize critical patterns
+    const criticalPatterns = patterns.filter(p => p.severity === 'critical');
+    if (criticalPatterns.length > 0) {
+        recommendations.push(`🔴 Resolve ${criticalPatterns.length} Critical issue(s) as top priority`);
+    }
+    // If there are many repeated errors
+    if (repeatedErrors.length > 0) {
+        const topError = repeatedErrors[0];
+        recommendations.push(`⚠️ "${topError.message}" error is repeating ${topError.count} times. Find the root cause.`);
+    }
+    // Pattern-specific recommendations
+    for (const pattern of patterns.slice(0, 3)) { // Top 3 only
+        recommendations.push(`💡 ${pattern.name}: ${pattern.solutions[0]}`);
+    }
+    if (recommendations.length === 0) {
+        recommendations.push('✅ No special issues found in current logs.');
+    }
+    return recommendations;
+}

package/dist/diagnostics/cluster-health.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cluster-wide health diagnostics
+ *
+ * @author zerry
+ */
+import * as k8s from '@kubernetes/client-node';
+import type { ClusterHealth } from '../types.js';
+/**
+ * Diagnose overall cluster health
+ *
+ * Comprehensively analyzes nodes, pods, and resource utilization
+ */
+export declare function diagnoseClusterHealth(coreApi: k8s.CoreV1Api, namespace?: string): Promise<ClusterHealth>;

package/dist/diagnostics/cluster-health.js

@@ -0,0 +1,176 @@
+/**
+ * Cluster-wide health diagnostics
+ *
+ * @author zerry
+ */
+/**
+ * Diagnose overall cluster health
+ *
+ * Comprehensively analyzes nodes, pods, and resource utilization
+ */
+export async function diagnoseClusterHealth(coreApi, namespace) {
+    const issues = [];
+    // 1. Node health
+    const nodesResponse = await coreApi.listNode();
+    const nodes = nodesResponse.items;
+    const readyNodes = nodes.filter((n) => n.status?.conditions?.some((c) => c.type === 'Ready' && c.status === 'True'));
+    const notReadyNodes = nodes.filter((n) => !n.status?.conditions?.some((c) => c.type === 'Ready' && c.status === 'True'));
+    // Not Ready node issues
+    for (const node of notReadyNodes) {
+        issues.push({
+            type: 'Node Not Ready',
+            severity: 'critical',
+            message: `Node "${node.metadata?.name}" is not in Ready state`,
+            rootCause: 'Node has encountered a problem',
+            solution: 'Check detailed cause with: kubectl describe node <node-name>',
+            resource: {
+                kind: 'Node',
+                name: node.metadata?.name || 'unknown',
+                namespace: '',
+            },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // 2. Pod health
+    const podsResponse = namespace
+        ? await coreApi.listNamespacedPod({ namespace })
+        : await coreApi.listPodForAllNamespaces();
+    const pods = podsResponse.items;
+    const podStats = {
+        total: pods.length,
+        running: pods.filter((p) => p.status?.phase === 'Running').length,
+        pending: pods.filter((p) => p.status?.phase === 'Pending').length,
+        failed: pods.filter((p) => p.status?.phase === 'Failed').length,
+        crashLooping: pods.filter((p) => p.status?.containerStatuses?.some((c) => c.state?.waiting?.reason === 'CrashLoopBackOff' || (c.restartCount || 0) > 5)).length,
+    };
+    // Pending pod issues
+    const pendingPods = pods.filter((p) => p.status?.phase === 'Pending');
+    for (const pod of pendingPods.slice(0, 5)) { // Max 5 pods
+        issues.push({
+            type: 'Pod Pending',
+            severity: 'high',
+            message: `Pod "${pod.metadata?.name}" is in Pending state`,
+            rootCause: 'Cannot be scheduled or image cannot be pulled',
+            solution: `kubectl describe pod ${pod.metadata?.name} -n ${pod.metadata?.namespace}`,
+            resource: {
+                kind: 'Pod',
+                name: pod.metadata?.name || 'unknown',
+                namespace: pod.metadata?.namespace || 'default',
+            },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // CrashLoop pod issues
+    const crashLoopPods = pods.filter((p) => p.status?.containerStatuses?.some((c) => c.state?.waiting?.reason === 'CrashLoopBackOff' || (c.restartCount || 0) > 5));
+    for (const pod of crashLoopPods.slice(0, 5)) {
+        issues.push({
+            type: 'CrashLoopBackOff',
+            severity: 'critical',
+            message: `Pod "${pod.metadata?.name}" is in CrashLoop state`,
+            rootCause: 'Container is repeatedly failing',
+            solution: `kubectl logs ${pod.metadata?.name} -n ${pod.metadata?.namespace} --previous`,
+            resource: {
+                kind: 'Pod',
+                name: pod.metadata?.name || 'unknown',
+                namespace: pod.metadata?.namespace || 'default',
+            },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // 3. Resource utilization (basic calculation)
+    const resourceUtilization = {
+        cpu: 0,
+        memory: 0,
+        storage: 0,
+    };
+    // 4. Overall health score
+    const overallScore = calculateOverallScore(nodes.length, readyNodes.length, podStats, issues);
+    // 5. Filter critical issues only
+    const criticalIssues = issues.filter(i => i.severity === 'critical');
+    // 6. Recommendations
+    const recommendations = generateClusterRecommendations(issues, podStats, nodes.length);
+    // 7. Summary
+    const summary = generateClusterSummary(nodes.length, readyNodes.length, podStats, overallScore);
+    return {
+        overallScore,
+        nodeHealth: {
+            total: nodes.length,
+            ready: readyNodes.length,
+            notReady: notReadyNodes.length,
+            issues: issues.filter(i => i.resource?.kind === 'Node'),
+        },
+        podHealth: {
+            ...podStats,
+            issues: issues.filter(i => i.resource?.kind === 'Pod'),
+        },
+        resourceUtilization,
+        criticalIssues,
+        recommendations,
+        summary,
+    };
+}
+/**
+ * Calculate overall health score
+ */
+function calculateOverallScore(totalNodes, readyNodes, podStats, issues) {
+    let score = 100;
+    // Deduct for node status
+    const nodeHealthPercent = (readyNodes / totalNodes) * 100;
+    score -= (100 - nodeHealthPercent) * 0.5;
+    // Deduct for pod status
+    const healthyPodPercent = (podStats.running / podStats.total) * 100;
+    score -= (100 - healthyPodPercent) * 0.3;
+    // CrashLoop is severe
+    score -= podStats.crashLooping * 5;
+    // Deduct for issues
+    for (const issue of issues) {
+        if (issue.severity === 'critical')
+            score -= 10;
+        else if (issue.severity === 'high')
+            score -= 5;
+        else if (issue.severity === 'medium')
+            score -= 2;
+    }
+    return Math.max(0, Math.min(100, score));
+}
+/**
+ * Generate cluster recommendations
+ */
+function generateClusterRecommendations(issues, podStats, totalNodes) {
+    const recommendations = [];
+    const critical = issues.filter(i => i.severity === 'critical');
+    if (critical.length > 0) {
+        recommendations.push(`🔴 Resolve ${critical.length} Critical issue(s) as top priority`);
+    }
+    if (podStats.crashLooping > 0) {
+        recommendations.push(`⚠️ ${podStats.crashLooping} pod(s) in CrashLoop state. Check logs immediately`);
+    }
+    if (podStats.pending > 5) {
+        recommendations.push(`⚠️ ${podStats.pending} pod(s) in Pending state. Check for resource insufficiency`);
+    }
+    if (totalNodes < 3) {
+        recommendations.push('💡 For high availability, running at least 3 nodes is recommended');
+    }
+    if (recommendations.length === 0) {
+        recommendations.push('✅ Cluster is healthy!');
+    }
+    return recommendations;
+}
+/**
+ * Generate cluster summary
+ */
+function generateClusterSummary(totalNodes, readyNodes, podStats, score) {
+    let summary = `Cluster Health Score: ${score.toFixed(1)}/100\n\n`;
+    summary += `Nodes: ${readyNodes}/${totalNodes} Ready\n`;
+    summary += `Pods: ${podStats.running}/${podStats.total} Running\n`;
+    if (podStats.crashLooping > 0) {
+        summary += `⚠️ CrashLoop: ${podStats.crashLooping}\n`;
+    }
+    if (podStats.pending > 0) {
+        summary += `⚠️ Pending: ${podStats.pending}\n`;
+    }
+    if (podStats.failed > 0) {
+        summary += `⚠️ Failed: ${podStats.failed}\n`;
+    }
+    return summary;
+}

package/dist/diagnostics/pod-diagnostics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pod diagnostics module
+ *
+ * Comprehensively analyzes pod status, containers, and events
+ * to identify the root cause of problems
+ *
+ * @author zerry
+ */
+import * as k8s from '@kubernetes/client-node';
+import type { PodDiagnostics, DiagnosticIssue } from '../types.js';
+/**
+ * Comprehensive pod diagnostics
+ *
+ * This is the core feature. Analyzes all pod states
+ * to clearly explain "why it's not working"
+ */
+export declare function diagnosePod(coreApi: k8s.CoreV1Api, namespace: string, podName: string, metricsApi?: k8s.Metrics): Promise<PodDiagnostics>;
+/**
+ * Specialized CrashLoopBackOff diagnostics
+ *
+ * CrashLoop is really tricky, this function accurately identifies the cause
+ */
+export declare function diagnoseCrashLoop(coreApi: k8s.CoreV1Api, logApi: k8s.Log, namespace: string, podName: string, containerName?: string): Promise<DiagnosticIssue[]>;