SkillAgentSearch skills...

Kogaro

Kogaro - Kubernetes Configuration Hygiene Agent

GenerateConvertImprove

Install / Use

/learn @topiaruss/Kogaro
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

Kogaro - Stop Kubernetes Silent Failures

CI Go Report Card codecov Production Ready Validation Types License: Apache 2.0 GitHub release

The operational intelligence system that catches configuration issues before they cause outages.

Kogaro transforms Kubernetes cluster hygiene from reactive debugging to proactive intelligence. While other tools generate compliance noise, Kogaro delivers actionable signals that production teams actually trust and act upon.

Project Components

  • Core Kubernetes validator/agent: repository root (main.go, internal/, charts/)
  • Desktop app (Wails + Svelte): ui/
  • Public website (deployed separately): website/

🚨 The Problem We Solve

Production Kubernetes clusters suffer from silent configuration failures:

  • Dangling references cause mysterious service outages
  • Security misconfigurations slip through CI/CD
  • Resource issues manifest as performance problems
  • Network policies have gaps that compromise security

These issues are invisible until they cause incidents.

⚡ How Kogaro Helps

Kogaro provides operational vigilance through:

  • 60+ validation types across Reference, Security, Resource, Image, and Networking categories
  • CI/CD Integration with scoped validation for pre-deployment validation
  • Structured error codes (KOGARO-XXX-YYY) for automated processing
  • Real-time detection of configuration drift and dangerous changes
  • Prometheus integration for monitoring and alerting
  • Production-ready architecture with leader election and HA support

Result: Issues caught in minutes, not hours. Admins who trust alerts instead of ignoring noise.

🎯 Why Choose Kogaro Over Alternatives?

| Category | Traditional Tools | Kogaro Advantage | |----------|------------------|------------------| | Policy Engines | Complex rule languages | Simple, focused validations | | Security Scanners | Point-in-time reports | Continuous operational monitoring | | Monitoring Tools | Runtime metrics only | Configuration hygiene focus | | Compliance Tools | Audit checklists | Actionable operational intelligence |

Unique Value: Kogaro is the only tool specifically designed for operational configuration hygiene - catching the silent failures that other tools miss.

Features

Comprehensive Kubernetes Validation (60+ validation types)

Kogaro provides five comprehensive validation categories covering all critical aspects of Kubernetes cluster hygiene:

1. Reference Validation (11 validation types)

Detects dangling references to non-existent resources:

  • Ingress References (--enable-ingress-validation)

    • dangling_ingress_class: Missing IngressClass references
    • dangling_service_reference: Missing Service references in ingress rules
    • dangling_tls_secret: Missing TLS Secrets in ingress

  • ConfigMap References (--enable-configmap-validation)

    • dangling_configmap_volume: Missing ConfigMap volume references
    • dangling_configmap_envfrom: Missing ConfigMap envFrom references

  • Secret References (--enable-secret-validation)

    • dangling_secret_volume: Missing Secret volume references
    • dangling_secret_envfrom: Missing Secret envFrom references
    • dangling_secret_env: Missing Secret env var references

  • Storage References (--enable-pvc-validation)

    • dangling_pvc_reference: Missing PVC references
    • dangling_storage_class: Missing StorageClass references

  • ServiceAccount References (--enable-serviceaccount-validation)

    • dangling_service_account: Missing ServiceAccount references

2. Resource Limits Validation (10 validation types)

Ensures proper resource management and QoS:

  • Resource Constraints (--enable-resource-limits-validation)
    • missing_resource_requests: Containers without CPU/memory requests
    • missing_resource_limits: Containers without CPU/memory limits
    • insufficient_cpu_request: CPU requests below minimum thresholds
    • insufficient_memory_request: Memory requests below minimum thresholds
    • qos_class_issue (BestEffort): Containers with no resource constraints
    • qos_class_issue (Burstable): Containers where requests ≠ limits

3. Security Validation (12 validation types)

Detects security misconfigurations and vulnerabilities:

  • Pod & Container Security (--enable-security-validation)

    • pod_running_as_root: Pod SecurityContext specifies runAsUser: 0
    • pod_allows_root_user: Pod SecurityContext missing runAsNonRoot: true
    • container_running_as_root: Container SecurityContext specifies runAsUser: 0
    • container_allows_privilege_escalation: Container allows privilege escalation
    • container_privileged_mode: Container running in privileged mode
    • container_writable_root_filesystem: Container has writable root filesystem
    • container_additional_capabilities: Container adds Linux capabilities
    • missing_pod_security_context: Pod has no SecurityContext defined
    • missing_container_security_context: Container has no SecurityContext defined

  • ServiceAccount & RBAC Security (--enable-security-serviceaccount-validation)

    • serviceaccount_cluster_role_binding: ServiceAccount with ClusterRoleBinding
    • serviceaccount_excessive_permissions: ServiceAccount with dangerous RoleBinding

4. Image Validation (5 validation types)

Validates container images and registry accessibility:

  • Image Registry & Architecture (--enable-image-validation)
    • invalid_image_reference: Containers with malformed image references
    • missing_image: Images that don't exist in the registry
    • missing_image_warning: Missing images (when --allow-missing-images is enabled)
    • architecture_mismatch: Image architecture incompatible with cluster nodes
    • architecture_mismatch_warning: Architecture mismatches (when --allow-architecture-mismatch is enabled)

5. Networking Validation (9 validation types)

Validates service connectivity and network policies:

  • Service Connectivity (--enable-networking-validation)

    • service_selector_mismatch: Service selectors that don't match any pods
    • service_no_endpoints: Services with no ready endpoints despite matching pods
    • service_port_mismatch: Service ports that don't match container ports
    • pod_no_service: Pods not exposed by any Service (warning when enabled)

  • NetworkPolicy Coverage (--networking-policy-validation)

    • network_policy_orphaned: NetworkPolicy selectors that don't match any pods
    • missing_network_policy_default_deny: Namespaces with policies but no default deny
    • missing_network_policy_required: Required namespaces missing NetworkPolicies

  • Ingress Connectivity (--enable-networking-validation)

    • ingress_service_missing: Ingress references to non-existent services
    • ingress_service_port_mismatch: Ingress references to non-existent service ports
    • ingress_no_backend_pods: Ingress services with no ready backend pods

Observability

  • Prometheus Metrics: Exports validation error counts and run statistics
  • Structured Logging: Detailed logs of all validation issues found
  • Health Checks: Kubernetes-native health and readiness probes

Structured Error Codes

Kogaro assigns structured error codes to all validation issues for easy categorization, filtering, and automated processing. Each error follows the format KOGARO-CCC-XXX:

  • Reference Validation: KOGARO-REF-001 through KOGARO-REF-011
  • Resource Limits: KOGARO-RES-001 through KOGARO-RES-010
  • Security Validation: KOGARO-SEC-001 through KOGARO-SEC-012
  • Image Validation: KOGARO-IMG-001 through KOGARO-IMG-005
  • Networking Validation: KOGARO-NET-001 through KOGARO-NET-009

Benefits:

  • Automated Processing: Filter and process errors by type or category
  • Metrics & Alerting: Create dashboards and alerts based on error patterns
  • Tool Integration: External tools can understand and act on specific error types
  • Trend Analysis: Track which issues are most common over time

📖 See the complete Error Codes Reference for detailed mappings

Example usage:

# Show only security issues
kubectl logs kogaro-pod | grep "KOGARO-SEC-"

# Count reference validation errors
kubectl logs kogaro-pod | grep "KOGARO-REF-" | wc -l

# Check for image-related issues
kubectl logs kogaro-pod | grep "KOGARO-IMG-"

Quick Start

Deploy in 5 minutes, start catching silent failures immediately.

For detailed deployment instructions, see the Deployment Guide.

Prerequisites

  • Go 1.21 or later
  • Kubernetes cluster access
  • kubectl configured

Installation

Option 1: Helm Repository (Recommended)

# Add the Kogaro Helm repository
helm repo add kogaro https://topiaruss.github.io/kogaro
helm repo update

# Install Kogaro with default settings
helm install kogaro kogaro/kogaro \
  --namespace kogaro-system \
  --create-namespace

# Or install with custom configuration including image validation
helm install kogaro kog

topiaruss

View profile

View on GitHub
GitHub Stars39
CategoryDevelopment
Updated1d ago
Forks0
topiaruss/kogaro

Languages

Go

Security Score

75/100

Audited on Mar 29, 2026

No findings