readme.md

README.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a **Kubernetes cluster bootstrapping and GitOps configuration repository** using ArgoCD. It defines the infrastructure-as-code for deploying and managing applications, services, and policies on Kubernetes clusters.
+
+## Repository Structure
+
+```
+.
+├── bootstrap.sh              # Main bootstrap script to initialize ArgoCD and cluster
+├── argocd/                   # ArgoCD configuration (primary entrypoint)
+│   ├── _app-of-apps.yaml    # App-of-apps pattern: parent Application that manages all child apps
+│   ├── apps/                 # Individual ArgoCD Application resources
+│   │   ├── application.yaml       # Main application deployment (music-man from scaling-parakeet repo)
+│   │   ├── traefik-application.yaml    # Ingress controller (Traefik)
+│   │   ├── cert-manager-application.yaml   # TLS certificate management
+│   │   ├── kyverno.yaml              # Policy engine for security
+│   │   ├── prometheus.yaml           # Metrics & monitoring
+│   │   ├── grafana.yaml              # Monitoring visualization
+│   │   ├── loki.yaml                 # Log aggregation
+│   │   ├── fluent-bit.yaml           # Log shipping
+│   │   ├── trivy.yaml                # Container scanning
+│   │   ├── sealedsecrets.yaml        # Secret encryption
+│   │   └── cluster-resources-application.yaml   # Cluster-wide resources
+│   └── values/               # Helm value overrides for ArgoCD and services
+│       ├── argocd-values.yaml        # ArgoCD server configuration
+│       ├── prometheus-values.yaml
+│       ├── grafana-values.yaml
+│       └── loki-values.yaml
+└── cluster-resources/        # Cluster-level configurations
+    ├── cert-manager-namespace.yaml
+    ├── letsencrypt-issuer.yaml       # TLS certificate issuer
+    └── kyverno-config.yaml           # Security policies and secret syncing
+```
+
+## Architecture & Key Concepts
+
+### GitOps Model
+- **App-of-Apps Pattern**: `argocd/_app-of-apps.yaml` is the root Application that manages all child applications
+- **Source of Truth**: GitHub repository (`https://github.com/snothub/scaling-parakeet.git`) is the single source of truth
+- **Auto-sync**: All Applications have automated sync enabled with auto-pruning and self-healing
+- **Namespace Creation**: `CreateNamespace=true` allows ArgoCD to create namespaces as needed
+
+### Key Components
+
+1. **Traefik** - Kubernetes Ingress controller for routing external traffic with HTTP/HTTPS redirect
+2. **Cert-Manager** - Automates TLS certificate management with Let's Encrypt (see `letsencrypt-issuer.yaml`)
+3. **Kyverno** - Policy engine that enforces security rules and syncs secrets across namespaces (via `sync-secret-with-multi-clone` policy)
+4. **Monitoring Stack** - Prometheus (metrics) + Grafana (visualization) + Loki (logs) + Fluent-Bit (log shipping)
+5. **Trivy** - Container vulnerability scanning
+6. **Sealed Secrets** - Encrypts secrets for safe storage in Git
+
+### Secret Management
+- **Kyverno ClusterPolicy**: Automatically clones secrets from the `secrets` namespace to new namespaces when they're created
+- Only secrets labeled `allowedToBeCloned: "true"` are cloned
+- Syncing happens automatically via `synchronize: true` in the policy
+
+### Istio Integration
+- Cert-Manager and webhooks disable Istio sidecar injection (`sidecar.istio.io/inject: "false"`) to avoid mTLS conflicts
+- Indicates the cluster likely has Istio installed for service mesh capabilities
+
+### Network Configuration
+- ArgoCD UI: `argocd.127.0.0.1.nip.io` (local development)
+- Server runs in insecure mode (`--insecure`, `--disable-auth`) - suitable for local/dev clusters
+- Traefik routes to multiple services via Kubernetes Ingress
+
+## Common Commands
+
+### Bootstrap the Cluster
+```bash
+./bootstrap.sh
+```
+This runs the `Bootstrap()` function which calls `ArgoCd()` to install ArgoCD using Helm.
+
+### Monitor ArgoCD Applications
+```bash
+# View all ArgoCD applications
+kubectl get applications -n argocd
+
+# Watch sync status
+kubectl get applications -n argocd -w
+
+# Describe a specific application
+kubectl describe app <app-name> -n argocd
+```
+
+### Manage ArgoCD
+```bash
+# Port forward to access UI
+kubectl port-forward svc/argocd-server -n argocd 8080:443
+
+# Access at: https://localhost:8080 (admin auth disabled in dev)
+```
+
+### Check Secret Syncing
+```bash
+# Verify Kyverno policy is applied
+kubectl get clusterpolicy sync-secret-with-multi-clone
+
+# Check if secrets are synced to a namespace
+kubectl get secrets -n <namespace>
+```
+
+### Deploy Changes
+- Changes to YAML files in `argocd/` or `cluster-resources/` are automatically synced by ArgoCD
+- Push changes to the GitHub repository for them to be reflected
+- ArgoCD reconciliation happens every 60s (`timeout.reconciliation: 60s`)
+
+### Review Helm Values
+Application-specific Helm value overrides are in `argocd/values/` and referenced within each Application's `values` field.
+
+## Important Notes
+
+- **No admin auth in development**: ArgoCD has `admin.enabled: "false"` - suitable for local/dev only
+- **Insecure server mode**: `--insecure` and `--disable-auth` flags are set - not for production
+- **Database password**: The music-man app has `change-me-in-production` placeholder in `application.yaml`
+- **Replica counts**: Traefik runs 2 replicas; other services run 1 replica
+- **Retry policy**: All applications retry up to 5 times with exponential backoff (max 3m)
+- **Ignore replica scaling**: Deployments ignore replica count differences to allow HPA/manual scaling
+
+## Development Tips
+
+- **Check ArgoCD logs**: `kubectl logs -n argocd deployment/argocd-application-controller`
+- **Validate YAML**: Files are validated server-side (`Validate=true`) before applying
+- **Resource tracking**: Uses annotation-based method (`application.resourceTrackingMethod: annotation`)
+- **Modify applications**: Edit the corresponding YAML in `argocd/apps/` and push to trigger sync
+- **Add new services**: Create a new Application YAML following the pattern of existing ones, then reference it from `_app-of-apps.yaml`