@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/examples/kagent/k8s-troubleshooter-v1.ossa.yaml

@@ -0,0 +1,269 @@
+# OSSA v1.0 KAgent Example
+# Kubernetes Troubleshooter Agent with KAgent Bridge
+# Fully compatible with kagent.dev/v1alpha2
+
+ossaVersion: "1.0"
+
+agent:
+  id: k8s-troubleshooter
+  name: Kubernetes Troubleshooter
+  version: 1.0.0
+  description: Autonomous Kubernetes cluster troubleshooting agent with diagnostic capabilities
+  role: monitoring
+  tags:
+    - kubernetes
+    - troubleshooting
+    - infrastructure
+    - diagnostics
+
+  runtime:
+    type: k8s
+    image: ossa/k8s-troubleshooter:1.0.0
+    resources:
+      cpu: "500m"
+      memory: "512Mi"
+    health_check:
+      type: http
+      endpoint: /health
+      port: 8080
+      initial_delay_seconds: 30
+      period_seconds: 10
+      timeout_seconds: 5
+      failure_threshold: 3
+
+  capabilities:
+    - name: diagnose_pod_failures
+      description: Diagnose why pods are failing or crashing
+      input_schema:
+        type: object
+        required:
+          - namespace
+          - pod_name
+        properties:
+          namespace:
+            type: string
+            description: Kubernetes namespace
+          pod_name:
+            type: string
+            description: Pod name pattern
+      output_schema:
+        type: object
+        properties:
+          status:
+            type: string
+            enum: [healthy, degraded, failed]
+          issues:
+            type: array
+            items:
+              type: object
+              properties:
+                type:
+                  type: string
+                severity:
+                  type: string
+                  enum: [critical, warning, info]
+                message:
+                  type: string
+                remediation:
+                  type: string
+      timeout_seconds: 120
+      retry_policy:
+        max_attempts: 3
+        backoff: exponential
+
+    - name: analyze_resource_constraints
+      description: Analyze CPU and memory resource constraints
+      input_schema:
+        type: object
+        required:
+          - namespace
+        properties:
+          namespace:
+            type: string
+      output_schema:
+        type: object
+        properties:
+          cpu_pressure:
+            type: boolean
+          memory_pressure:
+            type: boolean
+          recommendations:
+            type: array
+            items:
+              type: string
+      timeout_seconds: 60
+
+    - name: check_network_connectivity
+      description: Verify network connectivity between services
+      input_schema:
+        type: object
+        required:
+          - source_service
+          - target_service
+        properties:
+          source_service:
+            type: string
+          target_service:
+            type: string
+          namespace:
+            type: string
+            default: default
+      output_schema:
+        type: object
+        properties:
+          reachable:
+            type: boolean
+          latency_ms:
+            type: number
+          errors:
+            type: array
+            items:
+              type: string
+
+  policies:
+    compliance:
+      - soc2-type2
+      - iso27001
+    data_residency:
+      - US
+    encryption: true
+    audit: true
+    pii_handling: prohibit
+
+  integration:
+    protocol: http
+    endpoints:
+      base_url: http://k8s-troubleshooter:8080
+      health: /health
+      metrics: /metrics
+      openapi: /api/openapi.json
+    auth:
+      type: jwt
+      config:
+        issuer: https://auth.company.com
+        audience: k8s-troubleshooter
+    rate_limits:
+      requests_per_second: 10
+      requests_per_minute: 500
+      burst: 20
+
+  monitoring:
+    traces: true
+    metrics: true
+    logs: true
+    health_check: http://localhost:8080/health
+    phoenix_arise:
+      enabled: true
+      project: infrastructure-agents
+      export_interval_seconds: 60
+
+  dependencies:
+    required:
+      - agent_id: security-scanner
+        min_version: 1.0.0
+        max_version: 2.0.0
+    optional:
+      - agent_id: cost-optimizer
+        fallback: skip_optimization
+
+  metadata:
+    author: Platform Team
+    maintainer: platform-team@company.com
+    homepage: https://github.com/company/k8s-troubleshooter
+    repository: https://github.com/company/k8s-troubleshooter
+    documentation: https://docs.company.com/agents/k8s-troubleshooter
+    license: Apache-2.0
+    keywords:
+      - kubernetes
+      - troubleshooting
+      - monitoring
+      - diagnostics
+
+  # Multi-framework bridge configuration
+  bridge:
+    # KAgent bridge for Kubernetes-native deployment
+    kagent:
+      enabled: true
+      api_version: kagent.dev/v1alpha2
+      agent_type: declarative
+      deployment:
+        replicas: 2
+        resources:
+          requests:
+            cpu: "250m"
+            memory: "256Mi"
+          limits:
+            cpu: "500m"
+            memory: "512Mi"
+      model_config: gpt-4
+      system_message: |
+        You are an expert Kubernetes troubleshooter. You diagnose pod failures,
+        network issues, resource constraints, and configuration problems.
+        You use kubectl and monitoring tools to identify root causes and suggest remediation steps.
+      a2a_config:
+        skills:
+          - id: diagnose_pod_failures
+            name: Diagnose Pod Failures
+            description: Identify why pods are failing or crashing in Kubernetes
+            examples:
+              - Why is my-app-pod crashing in the production namespace?
+              - Diagnose ImagePullBackOff errors in the staging environment
+            tags:
+              - kubernetes
+              - pods
+              - diagnostics
+          - id: analyze_resource_constraints
+            name: Analyze Resource Constraints
+            description: Check for CPU and memory pressure in namespaces
+            examples:
+              - Are there resource constraints in the production namespace?
+              - Check memory pressure for my-service
+            tags:
+              - kubernetes
+              - resources
+              - performance
+          - id: check_network_connectivity
+            name: Check Network Connectivity
+            description: Verify network connectivity between Kubernetes services
+            examples:
+              - Can frontend-service reach backend-service?
+              - Test network connectivity from app-a to app-b
+            tags:
+              - kubernetes
+              - networking
+              - connectivity
+
+    # MCP bridge for Claude Desktop/Cursor integration
+    mcp:
+      enabled: true
+      server_type: stdio
+      tools:
+        - name: diagnose_pod
+          description: Diagnose Kubernetes pod issues
+          input_schema:
+            type: object
+            properties:
+              namespace:
+                type: string
+              pod_name:
+                type: string
+          output_schema:
+            type: object
+            properties:
+              status:
+                type: string
+              issues:
+                type: array
+          capability: diagnose_pod_failures
+
+    # A2A protocol bridge for agent-to-agent communication
+    a2a:
+      enabled: true
+      card_url: https://company.com/agents/k8s-troubleshooter/card.json
+      schema_version: "1.0"
+
+    # OpenAPI bridge for REST API integration
+    openapi:
+      enabled: true
+      spec_url: http://k8s-troubleshooter:8080/api/openapi.json
+      spec_version: "3.1"

package/examples/kagent/k8s-troubleshooter-v1.v0.2.2.ossa.yaml

@@ -0,0 +1,106 @@
+apiVersion: ossa/v1
+kind: Agent
+metadata:
+  name: k8s-troubleshooter
+  version: 1.0.0
+  description: Autonomous Kubernetes cluster troubleshooting agent with diagnostic capabilities
+  labels:
+    kubernetes: "true"
+    troubleshooting: "true"
+    infrastructure: "true"
+    diagnostics: "true"
+  annotations:
+    ossa.io/migration: v1.0 to v0.2.2
+    ossa.io/migrated-date: 2025-10-29
+spec:
+  role: monitoring
+  taxonomy:
+    domain: infrastructure
+    subdomain: kubernetes
+    capability: troubleshooting
+  tools:
+    - type: mcp
+      name: diagnose_pod_failures
+      server: k8s-troubleshooter
+      capabilities:
+        - with_input_schema
+    - type: mcp
+      name: analyze_resource_constraints
+      server: k8s-troubleshooter
+      capabilities:
+        - with_input_schema
+    - type: mcp
+      name: check_network_connectivity
+      server: k8s-troubleshooter
+      capabilities:
+        - with_input_schema
+  observability:
+    tracing:
+      enabled: true
+    metrics:
+      enabled: true
+    logging:
+      level: info
+      format: json
+  extensions:
+    mcp:
+      enabled: true
+      server_type: stdio
+      tools:
+        - name: diagnose_pod_failures
+          description: Diagnose why pods are failing or crashing
+        - name: analyze_resource_constraints
+          description: Analyze CPU and memory resource constraints
+        - name: check_network_connectivity
+          description: Verify network connectivity between services
+    buildkit:
+      deployment:
+        replicas:
+          min: 1
+          max: 4
+        health_check:
+          path: /health
+          port: 8080
+      container:
+        image: ossa/k8s-troubleshooter:1.0.0
+        runtime: k8s
+        resources: &a1
+          cpu: 500m
+          memory: 512Mi
+    kagent:
+      kubernetes:
+        namespace: default
+        labels:
+          app: k8s-troubleshooter
+        resourceLimits: *a1
+      deployment:
+        replicas: 2
+        strategy: rolling-update
+    runtime:
+      type: k8s
+      image: ossa/k8s-troubleshooter:1.0.0
+      resources: *a1
+      health_check:
+        type: http
+        endpoint: /health
+        port: 8080
+        initial_delay_seconds: 30
+        period_seconds: 10
+        timeout_seconds: 5
+        failure_threshold: 3
+    integration:
+      protocol: http
+      endpoints:
+        base_url: http://k8s-troubleshooter:8080
+        health: /health
+        metrics: /metrics
+        openapi: /api/openapi.json
+      auth:
+        type: jwt
+        config:
+          issuer: https://auth.company.com
+          audience: k8s-troubleshooter
+      rate_limits:
+        requests_per_second: 10
+        requests_per_minute: 500
+        burst: 20

package/examples/kagent/k8s-troubleshooter.ossa.yaml

@@ -0,0 +1,257 @@
+# ============================================================================
+# OSSA kAgent Reference Implementation: Kubernetes Troubleshooter Agent
+# ============================================================================
+#
+# This manifest demonstrates OSSA compliance for Kubernetes-native agent
+# deployments with comprehensive diagnostic and troubleshooting capabilities.
+#
+# Key Features:
+#   - K8s runtime integration with pod/node discovery
+#   - RBAC-based permission model for safe cluster operations
+#   - MCP server integration for kubectl command execution
+#   - Supervised autonomy with approval gates
+#   - Service mesh integration (Istio/Ambient)
+#   - Agent-to-Agent (A2A) communication patterns
+#   - Audit logging for compliance and observability
+#
+# Domain: infrastructure.kubernetes.troubleshooting
+# ============================================================================
+
+apiVersion: ossa/v1
+kind: Agent
+metadata:
+  # Basic agent identification metadata
+  name: k8s-troubleshooter
+  version: 1.0.0
+  description: "Autonomous Kubernetes cluster troubleshooting agent with diagnostic capabilities"
+
+spec:
+  # =========================================================================
+  # TAXONOMY: Agent Classification & Capabilities
+  # =========================================================================
+  # Defines the functional domain and specialization of this agent within
+  # the infrastructure ecosystem. Used for discovery, routing, and validation.
+  taxonomy:
+    domain: infrastructure           # Primary domain: infrastructure/devops
+    subdomain: kubernetes           # K8s-specific agent
+    capability: troubleshooting     # Core capability: diagnostics & remediation
+
+  # =========================================================================
+  # ROLE: Agent Behavior & Expertise Profile
+  # =========================================================================
+  # Instructs the LLM on this agent's purpose, expertise areas, and approach.
+  # Guides decision-making for K8s diagnosis and troubleshooting workflows.
+  role: |
+    You are an expert Kubernetes troubleshooter. You diagnose pod failures, network issues,
+    resource constraints, and configuration problems. You use kubectl and monitoring tools
+    to identify root causes and suggest remediation steps.
+
+  # =========================================================================
+  # LLM CONFIGURATION: Model Selection & Behavior
+  # =========================================================================
+  # Configures the Large Language Model backend used for reasoning and
+  # diagnostic recommendations. Temperature kept low (0.2) for consistency.
+  llm:
+    provider: openai                # LLM provider for inference
+    model: gpt-4                    # Model with strong K8s/YAML reasoning
+    temperature: 0.2                # Low temperature: consistent diagnostics
+    maxTokens: 4000                 # Token budget for diagnostic analysis
+
+  # =========================================================================
+  # TOOLS: MCP Server Integration & Capabilities
+  # =========================================================================
+  # Declares MCP (Model Context Protocol) servers that provide K8s API access
+  # and kubectl execution capabilities. MCP enables structured interaction
+  # with Kubernetes cluster resources and diagnostic tools.
+  tools:
+    # ===== Kubernetes MCP Server =====
+    # Provides direct access to Kubernetes API resources and kubectl execution
+    # for pod inspection, log retrieval, and event analysis
+    - type: mcp
+      server: kubernetes-mcp
+      namespace: default            # Default K8s namespace for queries
+      capabilities:
+        - get_pods                  # Query pod status and configuration
+        - get_logs                  # Stream pod container logs
+        - get_events                # Retrieve K8s cluster events
+        - describe_resource         # Get detailed resource descriptions
+        - get_metrics               # Access Prometheus/kubelet metrics
+
+    # ===== BuildKit Agent Protocol Server =====
+    # Provides documentation search and log analysis capabilities
+    # for correlating K8s issues with known patterns and solutions
+    - type: mcp
+      server: buildkit-agent-protocol
+      namespace: default
+      capabilities:
+        - search_documentation      # Search troubleshooting KB/runbooks
+        - analyze_logs              # Pattern matching in aggregated logs
+
+  # =========================================================================
+  # AUTONOMY: Permission Model & Action Gates
+  # =========================================================================
+  # Defines the supervision level, approval requirements, and permitted actions.
+  # Follows principle of least privilege for cluster safety.
+  autonomy:
+    level: supervised               # Requires human approval for actions
+    approval_required: true         # All actions need explicit approval
+
+    # ===== ALLOWED READ-ONLY ACTIONS =====
+    # Safe diagnostic operations that don't modify cluster state
+    allowed_actions:
+      - read_pods                   # Query pod metadata/status
+      - read_logs                   # Access application logs
+      - read_events                 # View cluster events
+      - read_metrics                # Access performance metrics
+
+    # ===== BLOCKED DESTRUCTIVE ACTIONS =====
+    # Dangerous operations explicitly forbidden to prevent cluster damage
+    blocked_actions:
+      - delete_pods                 # Prevent accidental pod termination
+      - scale_deployments           # Prevent replica count changes
+      - modify_configs              # Prevent ConfigMap/Secret changes
+
+  # =========================================================================
+  # CONSTRAINTS: Cost & Performance Limits
+  # =========================================================================
+  # Enforces resource limits to prevent excessive API/LLM usage and costs.
+  # Token limits control diagnostic depth; latency limits ensure responsiveness.
+  constraints:
+    cost:
+      maxTokensPerDay: 50000        # Daily token budget for all operations
+      maxTokensPerRequest: 4000     # Per-request token limit
+      maxCostPerDay: 10.0           # USD cost ceiling per day
+      currency: USD
+
+    performance:
+      maxLatencySeconds: 30         # Max response time for diagnostics
+      maxConcurrentRequests: 5      # Concurrent diagnostic requests
+
+  # =========================================================================
+  # EXTENSIONS: kAgent-Specific Kubernetes Integration
+  # =========================================================================
+  # kAgent extensions provide Kubernetes-native deployment configuration,
+  # RBAC integration, service mesh support, and compliance frameworks.
+  extensions:
+    kagent:
+      # =====================================================================
+      # KUBERNETES RUNTIME CONFIGURATION
+      # =====================================================================
+      # Configures how the agent pod itself runs within the cluster,
+      # including namespace, resource limits, and identification labels.
+      kubernetes:
+        namespace: production        # Production namespace for agent pod
+
+        # ===== POD LABELS =====
+        # Standard Kubernetes labels for discovery, monitoring, and routing
+        labels:
+          app: k8s-troubleshooter   # App identifier for selectors
+          team: platform            # Team ownership
+          environment: production   # Environment classification
+
+        # ===== POD ANNOTATIONS =====
+        # Metadata annotations for observability and contact information
+        annotations:
+          description: "Kubernetes troubleshooting agent"
+          contact: "platform-team@company.com"  # Escalation contact
+
+        # ===== RESOURCE LIMITS =====
+        # Container resource requests/limits to prevent resource starvation
+        # or runaway consumption on cluster nodes
+        resourceLimits:
+          cpu: "500m"               # CPU allocation for agent execution
+          memory: "512Mi"           # Memory allocation for LLM context
+
+      # =====================================================================
+      # GUARDRAILS: RBAC & Approval Framework
+      # =====================================================================
+      # Enforces mandatory approvals, resource consumption limits, and
+      # specific K8s API action permissions through RBAC-style rules.
+      guardrails:
+        requireApproval: true       # Mandatory approval gate before actions
+
+        costLimits:
+          maxTokensPerDay: 50000    # Daily LLM token consumption limit
+          maxCostPerDay: 10.0       # Financial ceiling (USD)
+          currency: USD
+
+        # ===== K8S API PERMISSION MODEL =====
+        # RBAC-style permissions for specific Kubernetes API resources
+        # Format: kubernetes:<verb>:<resource>
+        allowedActions:
+          - kubernetes:get:pods     # Read pod objects (GET /pods)
+          - kubernetes:get:logs     # Stream logs (GET /pods/logs)
+          - kubernetes:get:events   # List events (GET /events)
+
+        # ===== AUDIT LOGGING =====
+        # Records all agent actions for compliance, debugging, and security
+        auditLog:
+          destination: compliance-engine  # Audit destination service
+          retention: 7years               # Compliance data retention
+
+      # =====================================================================
+      # AGENT-TO-AGENT (A2A) COMMUNICATION CONFIG
+      # =====================================================================
+      # Enables this agent to communicate with other agents (security-scanner,
+      # cost-optimizer) for collaborative diagnostics using JSON-RPC protocol.
+      # Supports multi-agent troubleshooting workflows.
+      a2aConfig:
+        enabled: true               # Enable inter-agent communication
+        protocol: json-rpc          # JSON-RPC 2.0 for agent calls
+
+        # ===== A2A ENDPOINT REGISTRY =====
+        # Other agents this troubleshooter can invoke for specialized analysis
+        endpoints:
+          - http://security-scanner:8080/a2a    # Security audit queries
+          - http://cost-optimizer:8080/a2a      # Cost analysis queries
+
+        # ===== AUTHENTICATION =====
+        # mTLS (mutual TLS) ensures encrypted, authenticated agent-to-agent
+        # communication within the service mesh
+        authentication:
+          type: mtls               # Mutual TLS certificates required
+
+      # =====================================================================
+      # SERVICE MESH INTEGRATION
+      # =====================================================================
+      # Integrates with Kubernetes service mesh technologies for:
+      #   - Encrypted inter-pod communication
+      #   - Observability (traces, metrics)
+      #   - Traffic policy enforcement
+      #   - mTLS authentication between agents
+      meshIntegration:
+        enabled: true               # Enable service mesh features
+        istioIntegration: true      # Istio sidecar injection
+        ambientMesh: true           # Ambient mode support (Istio 1.14+)
+
+# ============================================================================
+# OPERATIONAL NOTES
+# ============================================================================
+#
+# DEPLOYMENT:
+#   This manifest deploys an agent pod to the production namespace with
+#   K8s cluster discovery enabled. The agent pod receives an Istio sidecar
+#   for encrypted inter-agent communication and observability.
+#
+# RBAC REQUIREMENTS:
+#   Requires ClusterRole with permissions for:
+#     - pods (get, list, watch)
+#     - pods/logs (get)
+#     - events (get, list, watch)
+#     - nodes (get, list)
+#     - deployments (get, list)
+#
+# SECURITY CONSIDERATIONS:
+#   - All actions require explicit approval via guardrails
+#   - No destructive actions permitted (no delete/modify)
+#   - mTLS required for agent-to-agent communication
+#   - Audit logging for compliance and troubleshooting
+#   - Resource limits prevent denial-of-service
+#
+# MONITORING & OBSERVABILITY:
+#   - Metrics exported to Prometheus via agent instrumentation
+#   - Traces propagated to Jaeger via Istio sidecars
+#   - Pod logs aggregated via standard K8s logging
+#   - Audit events recorded in compliance-engine
+#
+# ============================================================================