Helm guide

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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

snippet.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

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

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)

snippet.yaml

# Services find pods by labels
Service selector: app: llm-trace-langfuse
Deployment labels: app: llm-trace-langfuse  # ← Must match!

snippet.yaml

# Auth proxy finds application service
BACKEND_HOST: "llm-trace-langfuse"  # ← Kubernetes service name

snippet.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.