# Helm guide
## 📚 **Complete Configuration Files Walkthrough**

Here's a **step-by-step guide** to understand every configuration file and how they interconnect:

### **🏗️ Phase 1: Foundation Files**

#### **Step 1.1: Service Account** (`service-account.yaml`)
```yaml
# Purpose: Defines the IAM identity for all pods
apiVersion: v1
kind: ServiceAccount
metadata:
  name: llm-trace-langfuse-svc  # ← Referenced by all deployments
  annotations:
    iam.gke.io/gcp-service-account: 'xdev-llm-trace-langfuse-svc@xhr-development.iam.gserviceaccount.com'
    argocd.argoproj.io/sync-wave: "-5"  # ← Deploys first
```

**🔗 Connections:**
- **Referenced by**: All deployment files (`spec.serviceAccountName`)
- **Depends on**: GCP IAM service account must exist
- **Purpose**: Provides cloud permissions for database/cache access

#### **Step 1.2: External Secrets** (`external-secret-db.yaml`, `external-secret.yaml`)
```yaml
# Purpose: Pulls secrets from GCP Secret Manager into Kubernetes
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: llm-trace-langfuse-db
spec:
  secretStoreRef:
    name: gcp-secret-manager  # ← References cluster secret store
  target:
    name: llm-trace-langfuse-db  # ← Creates this k8s secret
  data:
  - secretKey: database_url  # ← Maps to GCP secret
    remoteRef:
      key: xdev-llm-trace-langfuse-database-url
```

**🔗 Connections:**
- **Creates**: Kubernetes secrets (`llm-trace-langfuse-db`, `llm-trace-langfuse`)
- **Referenced by**: All deployments via `secretRef` in `envFrom`
- **Depends on**: GCP secrets must exist before deployment

### **🏭 Phase 2: Infrastructure Layer**

#### **Step 2.1: PostgreSQL Infrastructure** (`base/infra/postgres/`)
```yaml
# kustomization.yaml - Defines PostgreSQL deployment
helmCharts:
  - name: postgresql  # ← Deploys Bitnami PostgreSQL
    valuesInline:
      auth:
        existingSecret: llm-trace-langfuse-postgres  # ← References secret above
      primary:
        persistence:
          enabled: false  # ← No persistent disk for dev
```

**🔗 Connections:**
- **Depends on**: `external-secret.yaml` for database credentials
- **Creates**: PostgreSQL deployment, service, and persistent storage
- **Referenced by**: Application deployments for database connections

#### **Step 2.2: Redis Infrastructure** (`base/infra/redis/`)
```yaml
# kustomization.yaml - Defines Redis deployment  
helmCharts:
  - name: redis  # ← Deploys Bitnami Redis
    valuesInline:
      auth:
        existingSecret: llm-trace-langfuse-redis  # ← References secret above
```

**🔗 Connections:**
- **Depends on**: `external-secret.yaml` for Redis credentials
- **Creates**: Redis deployment and service for caching
- **Referenced by**: Application for session storage and caching

### **🎯 Phase 3: Application Layer**

#### **Step 3.1: ConfigMap** (`configmap.yaml`)
```yaml
# Purpose: Application configuration via environment variables
apiVersion: v1
kind: ConfigMap
metadata:
  name: config-map-llm-trace-langfuse
data:
  LANGFUSE_HOST: "0.0.0.0"  # ← Application binding
  OTEL_SERVICE_NAME: "llm-trace-langfuse"  # ← Monitoring service name
  REDIS_HOST: "redis-service"  # ← References Redis service
```

**🔗 Connections:**
- **Referenced by**: All deployments via `configMapRef` in `envFrom`
- **References**: Redis service name for connection
- **Purpose**: Non-sensitive configuration that can be version controlled

#### **Step 3.2: Service Definition** (`rest-service.yaml`)
```yaml
# Purpose: Defines network service for load balancing
apiVersion: v1
kind: Service
metadata:
  name: llm-trace-langfuse
spec:
  selector:
    app: llm-trace-langfuse  # ← Matches deployment labels
  ports:
    - port: 8080  # ← Service port
      targetPort: 8080  # ← Container port
```

**🔗 Connections:**
- **Referenced by**: Istio VirtualService for routing
- **References**: Deployment pod labels for pod selection
- **Purpose**: Provides stable network endpoint for the application

#### **Step 3.3: Main Deployment** (`rest-deployment.yaml`)
```yaml
# Purpose: Defines the main application pods
apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-trace-langfuse
spec:
  selector:
    matchLabels:
      app: llm-trace-langfuse  # ← Must match service selector
  template:
    spec:
      serviceAccountName: llm-trace-langfuse-svc  # ← References service account
      containers:
        - name: llm-trace-langfuse-container
          image: llm-trace-langfuse:latest  # ← Your Docker image
          envFrom:  # ← References all config sources
            - configMapRef:
                name: config-map-llm-trace-langfuse
            - secretRef:
                name: llm-trace-langfuse
            - secretRef:
                name: llm-trace-langfuse-db
```

**🔗 Connections:**
- **References**: ServiceAccount, ConfigMap, Secrets, Services
- **Referenced by**: Service (via labels), KEDA ScaledObject, Istio
- **Purpose**: Defines how application pods are created and configured

#### **Step 3.4: Auth Proxy Deployments** (`*-authproxyworkload.yaml`)
```yaml
# Purpose: Security layer in front of each component
apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-trace-langfuse-rest-auth-proxy
spec:
  template:
    spec:
      containers:
        - name: auth-proxy
          env:
            - name: BACKEND_HOST
              value: "llm-trace-langfuse"  # ← Routes to main deployment
            - name: BACKEND_PORT
              value: "8080"
```

**🔗 Connections:**
- **References**: Main deployment service name for routing
- **Referenced by**: Istio VirtualService as entry point
- **Purpose**: Provides authentication and request validation

#### **Step 3.5: Consumer & Migration** (`consumer-deployment.yaml`, `migration-deployment.yaml`)
```yaml
# Purpose: Background processing and database migrations
spec:
  template:
    spec:
      containers:
        - name: consumer-container
          command: ["python", "-m", "app.consumer"]  # ← Different entry point
          env:
            - name: CONSUMER_MODE
              value: "true"  # ← Enables consumer-specific logic
```

**🔗 Connections:**
- **Similar to**: Main deployment but with different configurations
- **References**: Same ConfigMaps and Secrets as main deployment
- **Purpose**: Handle background jobs and database schema updates

### **🌐 Phase 4: Traffic Management**

#### **Step 4.1: Virtual Service** (`virtual-service.yaml`)
```yaml
# Purpose: Defines Istio traffic routing rules
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: llm-trace-langfuse
spec:
  hosts:
    - llm-trace-langfuse  # ← Service discovery name
  http:
    - route:
        - destination:
            host: llm-trace-langfuse-rest-auth-proxy  # ← Routes to auth proxy first
```

**🔗 Connections:**
- **References**: Auth proxy deployment for routing
- **Referenced by**: Istio Gateway for external access
- **Purpose**: Controls how external traffic reaches the service

#### **Step 4.2: Auto-scaling** (`rest-scaled-object.yaml`)
```yaml
# Purpose: KEDA configuration for automatic scaling
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: llm-trace-langfuse-scaled-object
spec:
  scaleTargetRef:
    name: llm-trace-langfuse  # ← Scales main deployment
  triggers:
    - type: prometheus  # ← Uses Prometheus metrics
      metadata:
        serverAddress: http://victoria-metrics-k8s-stack:8428  # ← Metrics source
```

**🔗 Connections:**
- **References**: Main deployment for scaling target
- **Depends on**: Victoria Metrics for scaling decisions
- **Purpose**: Automatically adjusts replica count based on load

### **🎛️ Phase 5: Environment Customization**

#### **Step 5.1: Environment Kustomization** (`envs/dev/app/kustomization.yaml`)
```yaml
# Purpose: Environment-specific customizations
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../../base/app  # ← Includes all base configurations
patchesStrategicMerge:
  - configmap.yaml  # ← Overrides base config for dev
  - rest-deployment.yaml  # ← Dev-specific resource limits
```

**🔗 Connections:**
- **Includes**: All base configurations as foundation
- **Overrides**: Base settings with environment-specific values
- **Purpose**: Customizes the service for development environment

#### **Step 5.2: Environment Patches** (`envs/dev/app/*.yaml`)
```yaml
# Purpose: Environment-specific modifications
apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-trace-langfuse  # ← Patches base deployment
spec:
  replicas: 1  # ← Dev-specific: single replica
  template:
    spec:
      containers:
        - resources:
            requests:
              cpu: "100m"  # ← Dev-specific: lower resources
              memory: "512Mi"
```

**🔗 Connections:**
- **Patches**: Base deployment with dev-optimized settings
- **Strategic Merge**: Only overrides specified sections
- **Purpose**: Optimizes resource usage for development

### **🔗 Complete Dependency Chain**

#### **Deployment Order:**
```
1. Service Account (sync-wave: -5)
2. External Secrets (sync-wave: -5) 
3. Infrastructure (PostgreSQL + Redis)
4. ConfigMaps and Services
5. Application Deployments
6. Auth Proxy Deployments
7. Virtual Services and Scaling
```

#### **Runtime Dependencies:**
```
Application Pods ──→ Service Account (IAM permissions)
                 ├─→ External Secrets (database credentials)
                 ├─→ ConfigMap (application config)
                 ├─→ PostgreSQL Service (database connection)
                 └─→ Redis Service (cache connection)

Auth Proxy Pods ──→ Application Services (request routing)
Virtual Services ──→ Auth Proxy Services (traffic routing)
Scaled Objects ──→ Application Deployments (auto-scaling)
```

### **🔍 Key Reference Patterns**

#### **Label Matching:**
```yaml
# Services find pods by labels
Service selector: app: llm-trace-langfuse
Deployment labels: app: llm-trace-langfuse  # ← Must match!
```

#### **Service Discovery:**
```yaml
# Auth proxy finds application service
BACKEND_HOST: "llm-trace-langfuse"  # ← Kubernetes service name
```

#### **Secret Injection:**
```yaml
# Pods get secrets as environment variables
secretRef:
  name: llm-trace-langfuse-db  # ← Created by external-secret
```

This **interconnected web** of configuration files creates a **robust, scalable, and secure** microservice architecture where each component has a clear purpose and well-defined relationships with other components.