From 3e3c806949383000d9b078552315e78fad59d256 Mon Sep 17 00:00:00 2001 From: Danijel Simeunovic Date: Sat, 7 Feb 2026 21:21:08 +0100 Subject: [PATCH] readme.md --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d7de1a --- /dev/null +++ b/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 -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 +``` + +### 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`