Vapora/kubernetes/kagent/README.md

# Kagent Kubernetes Integration

Kubernetes manifests for deploying Google Kagent with VAPORA A2A protocol integration.

## Directory Structure

```
kagent/
├── base/                 # Base configuration (environment-agnostic)
│   ├── namespace.yaml    # Kagent namespace
│   ├── rbac.yaml         # ServiceAccount, ClusterRole, ResourceQuota
│   ├── configmap.yaml    # Kagent configuration
│   ├── statefulset.yaml  # Kagent StatefulSet (3 replicas)
│   ├── service.yaml      # Kubernetes services
│   └── kustomization.yaml
├── overlays/
│   ├── dev/              # Development environment
│   │   ├── kustomization.yaml
│   │   └── statefulset-patch.yaml
│   └── prod/             # Production environment
│       ├── kustomization.yaml
│       └── statefulset-patch.yaml
└── README.md
```

## Deployment

### Prerequisites

- Kubernetes 1.24+
- kubectl configured
- Kustomize 4.0+
- VAPORA A2A server running

### Deploy to Development

```bash
kubectl apply -k kubernetes/kagent/overlays/dev
```

### Deploy to Production

```bash
kubectl apply -k kubernetes/kagent/overlays/prod
```

## Features

### StatefulSet Configuration

- **Replicas**: 3 (base), 1 (dev), 5 (prod)
- **Image**: `google-kagent:latest`
- **Service Type**: ClusterIP (Headless)
- **Pod Anti-Affinity**: Distributed across nodes

### A2A Integration

Kagent is configured to discover and integrate with VAPORA A2A server:

```yaml
a2a:
  enabled: true
  vapora_server: "http://vapora-a2a:8003"
  discover_interval: 30s (dev), 60s (prod)
  timeout: 30s
```

### Ports

- **8080/http** - REST API
- **50051/grpc** - gRPC endpoint
- **9090/metrics** - Prometheus metrics

### Resource Limits

**Development:**
- CPU: 100m req, 500m limit
- Memory: 128Mi req, 512Mi limit

**Production:**
- CPU: 1000m req, 4000m limit
- Memory: 1Gi req, 4Gi limit

## RBAC

Kagent service account has permissions to:
- List/watch pods, services
- Read configmaps
- Create/delete batch jobs
- Create events

## Health Checks

- **Liveness Probe**: `/health` on port 8080 (30s initial, 10s interval)
- **Readiness Probe**: `/ready` on port 8080 (10s initial, 5s interval)

## Environment Variables

- `KAGENT_CONFIG` - Config file path
- `KAGENT_POD_NAME` - Pod name (auto-filled)
- `KAGENT_NAMESPACE` - Pod namespace (auto-filled)
- `A2A_SERVER_URL` - VAPORA A2A server URL
- `LOG_LEVEL` - Logging level (debug/info/warn/error)

## Storage

- **ConfigMap Volume** - Kagent configuration
- **EmptyDir** - Cache (1Gi) and tmp (500Mi)
- **PersistentVolume** - Data (10Gi per pod)

## Networking

All services use internal cluster DNS:
- `kagent.kagent.svc.cluster.local` - Headless service
- `kagent-api.kagent.svc.cluster.local` - REST API
- `kagent-grpc.kagent.svc.cluster.local` - gRPC

## Monitoring

Prometheus metrics exposed at `/metrics:9090`

Enable scraping with annotation:
```yaml
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
```

## Troubleshooting

### Check pod status

```bash
kubectl get pods -n kagent
kubectl describe pod -n kagent <pod-name>
kubectl logs -n kagent <pod-name>
```

### Test A2A connectivity

```bash
kubectl exec -it -n kagent kagent-0 -- /bin/sh
curl http://vapora-a2a:8003/health
```

### View events

```bash
kubectl get events -n kagent --sort-by='.lastTimestamp'
```

## Cleanup

```bash
kubectl delete -k kubernetes/kagent/overlays/dev
kubectl delete -k kubernetes/kagent/overlays/prod
```