# 🚀 Deployment en GKE — Klaus-proxy
Guía completa para desplegar Klaus-proxy en Google Kubernetes Engine (cliente MM/MO con >40 clusters).
## 🤔 ¿Qué hago? ¿Cómo lo hago? ¿Y para qué lo hago?
**¿Qué hago?** Configuro Klaus-proxy para ejecutarse de forma automática y segura en clusters GKE de Kyndryl MM/MO.
**¿Cómo lo hago?** Usando Helm chart + GitHub Actions CI/CD + Google Cloud Container Registry.
**¿Por qué?** Para tener control de versiones, deployments reproducibles, security scanning automático y rollbacks rápidos.
---
## 📋 Requisitos previos
- GKE cluster running (Kubernetes 1.21+)
- `gcloud` CLI configurado
- `kubectl` instalado
- `helm` 3.0+
- Acceso a GitHub Actions (repo settings)
- GCP Service Account con permisos Container Registry
## 🔧 Setup inicial — GitHub Secrets
### 1. Crear GCP Service Account
```bash
# En GCP Console o vía gcloud
gcloud iam service-accounts create github-cd-klaus \
--display-name="Klaus-proxy CD"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:github-cd-klaus@$PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/container.developer"
# Crear y descargar JSON key
gcloud iam service-accounts keys create /tmp/github-cd.json \
--iam-account=github-cd-klaus@$PROJECT_ID.iam.gserviceaccount.com
```
### 2. Agregar secrets a GitHub
```bash
# En GitHub: Settings → Secrets and variables → Actions
# GCP_PROJECT_ID
GCP_PROJECT_ID="your-gcp-project"
# GCP_SA_KEY (todo el contenido de github-cd.json)
cat /tmp/github-cd.json | base64 -w0
# SLACK_WEBHOOK_URL (opcional, para notificaciones)
https://hooks.slack.com/services/YOUR/WEBHOOK/URL
```
### 3. Verificar secrets
```bash
# En GitHub CLI
gh secret list --repo Ka0s-Klaus/Klaus-proxy-global
```
## 🐳 Pipeline CI/CD — Cómo funciona
### Trigger
Cuando mergeas a `main` y hay cambios en:
- `proxy/**`
- `Dockerfile`
- `helm/**`
- `.github/workflows/cd.yml`
### Pasos
```mermaid
graph LR
A["✅ Merge a main"] → B["🔨 Build image"]
B → C["🔒 Trivy scan"]
C → D{CRITICAL?}
D → |Sí| E["❌ Fail"]
D → |No| F["📦 Push a GCR"]
F → G["🏷️ GitHub Release"]
G → H["💬 Slack notify"]
```
**Salidas:**
- ✅ Image en GCR: `gcr.io/PROJECT_ID/klaus-proxy:1.2.0-abc123def`
- ✅ Tags automáticos: `:latest`, `:1.2.0`
- ✅ Security report (Trivy SARIF)
- ✅ GitHub Release con changelog
## 📦 Desplegar en GKE
### Opción A — Helm chart directo
```bash
# 1. Crear namespace
kubectl create namespace klaus-proxy
# 2. Crear secrets
kubectl create secret generic klaus-proxy-secrets \
--from-literal=api-key=$ANTHROPIC_API_KEY \
-n klaus-proxy
# 3. Desplegar con Helm
helm install klaus-proxy ./helm \
--namespace klaus-proxy \
--set image.repository=gcr.io/PROJECT_ID/klaus-proxy \
--set image.tag=1.2.0-abc123def \
--set replicaCount=5
# 4. Verificar
kubectl get pods -n klaus-proxy
```
### Opción B — Kustomize (para múltiples clusters)
```bash
# Estructura:
# kustomize/
# base/
# deployment.yaml
# kustomization.yaml
# overlays/
# dev/
# kustomization.yaml
# prod/
# kustomization.yaml
kubectl apply -k ./kustomize/overlays/prod -n klaus-proxy
```
## 🔍 Verificación y monitoreo
```bash
# Ver pods
kubectl get pods -n klaus-proxy -o wide
# Ver logs
kubectl logs -n klaus-proxy -l app=klaus-proxy --tail=100
# Health check
kubectl exec -it -n klaus-proxy pods/klaus-proxy-xxx \
-- curl http://localhost:8080/health
# Port-forward (debugging)
kubectl port-forward -n klaus-proxy svc/klaus-proxy 8080:8080
curl http://localhost:8080/dashboard
# Eventos de deployment
kubectl describe deployment -n klaus-proxy klaus-proxy
```
## 🆘 Troubleshooting
| Problema | Solución |
| --- | --- |
| `ImagePullBackOff` | Verificar GCP SA permisos; `kubectl auth can-i` |
| `CrashLoopBackOff` | Revisar logs; `kubectl logs ...` |
| `Pending` | PVC no bound; revisar `kubectl get pvc` |
| High CPU/Memory | Ajustar `resources` en values.yaml |
| Slow startup | Aumentar `initialDelaySeconds` en livenessProbe |
## 🔐 Security
- ✅ No hardcodear secrets en YAML
- ✅ Usar `kubectl create secret` o Sealed Secrets
- ✅ Trivy scan automático en CI/CD (falla si CRITICAL)
- ✅ Network policies (recomendado)
- ✅ RBAC por namespace
## 📊 SLOs recomendados
| Métrica | Target |
| --- | --- |
| Availability | 99.9% |
| P95 latency | <200ms |
| Error rate | <0.1% |
| CD lead time | <5 min (merge → prod) |
## 🔗 Referencias
- [helm/README.md](../helm/README.md) — Helm chart docs
- [docs/proxy.md](./proxy.md) — Proxy API + config
- [GKE best practices](https://cloud.google.com/kubernetes-engine/docs/best-practices)
- [GitHub Actions docs](https://docs.github.com/en/actions)