README.md

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

Traefik - Kubernetes Ingress controller for routing external traffic with HTTP/HTTPS redirect
Cert-Manager - Automates TLS certificate management with Let's Encrypt (see letsencrypt-issuer.yaml)
Kyverno - Policy engine that enforces security rules and syncs secrets across namespaces (via sync-secret-with-multi-clone policy)
Monitoring Stack - Prometheus (metrics) + Grafana (visualization) + Loki (logs) + Fluent-Bit (log shipping)
Trivy - Container vulnerability scanning
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

./bootstrap.sh

This runs the Bootstrap() function which calls ArgoCd() to install ArgoCD using Helm.

Monitor ArgoCD Applications

# 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

# 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

# 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

6.1 KiB Raw Blame History