📌 Kubernetes Infrastructure with Helm: Local Deployment

This repository provides a modular, reproducible Kubernetes setup for running InfluxDB locally using Helm charts. It is optimized for Mac laptops with Homebrew as the package manager and uv as the Python environment/runtime manager.

🌐 What is Kubernetes?

Kubernetes (K8s) is an open-source system for automating deployment, scaling, and management of containerized applications.

It acts as the operating system for your containers by abstracting infrastructure and providing:

• Self-healing (restarts crashed pods)
• Scalability (easy horizontal scaling with replicas)
• Service discovery & networking (DNS + load balancing)
• Storage orchestration (PVCs, dynamic provisioning)
• Declarative configuration (GitOps-friendly YAML)
• Rolling upgrades & rollbacks (safe updates)

👉 In simple words: Kubernetes ensures your apps are always running, healthy, and scalable without manual babysitting.

Official Documentation:

• Kubernetes Basics
• Concepts Overview
• kubectl Cheat Sheet

🔑 Why Helm Charts?

Instead of maintaining raw YAML manifests, this repo uses Helm because:

• Templating → Avoids repetitive YAML across environments
• Environment overrides → values.yaml, values-staging.yaml, values-prod.yaml
• Release management → Upgrade, rollback, history tracking
• Scalability → Easily adjust replicas, resources, and storage
• Reusability → Same chart works for local dev → staging → production

📂 Repository Structure

.
├── charts/
│   └── influxdb/                  # Helm chart for InfluxDB
│       ├── Chart.yaml              # Chart metadata
│       ├── README.md               # Chart-specific documentation
│       ├── scripts/                # Automation helpers
│       │   ├── dev_install_local.sh   # Install script (Mac + Brew + uv)
│       │   └── setuppod.py           # Pod setup + validation
│       ├── templates/              # Templated Kubernetes YAMLs
│       │   ├── _helpers.tpl         # Template helpers
│       │   ├── _validation.tpl      # Template validations
│       │   ├── data-pvc.yaml        # Persistent volume for DB data
│       │   ├── deployment.yaml      # Deployment definition
│       │   ├── plugin-pvc.yaml      # Optional plugin persistence
│       │   ├── secret.yaml          # Secrets (auth tokens, credentials)
│       │   └── service.yaml         # Service (expose InfluxDB)
│       ├── values.yaml              # Default config (local dev)
│       ├── values-staging.yaml      # Staging overrides
│       ├── values-prod.yaml         # Production overrides
├── namespace.yaml                  # Kubernetes namespace definition
├── main.py                         # Python orchestration entrypoint
├── pyproject.toml                  # Python project metadata
├── uv.lock                         # Python lockfile (reproducibility)
└── README.md                       # (this file) Root documentation

⚙️ Local Development Flow (Mac)

1. Install Dependencies

brew install kubectl
brew install helm
brew install minikube
brew install uv

2. Start Kubernetes Cluster

minikube start --driver=docker
kubectl get nodes

3. Create Namespace

kubectl apply -f namespace.yaml

4. Install InfluxDB Chart

./charts/influxdb/scripts/dev_install_local.sh

This script:

• Loads namespace + values
• Installs InfluxDB chart via Helm
• Runs setuppod.py for validation

5. Verify Deployment

kubectl get pods -n monitoring kubectl get svc -n monitoring

Expected: Pods are Running and service is available internally.

🔄 Flow of How Things Work

         ┌───────────────┐
         │  Helm Chart   │  (charts/influxdb)
         └───────┬───────┘
                 │ Templates + Values
                 ▼
        ┌─────────────────────┐
        │ Kubernetes API      │
        └─────────┬───────────┘
                  │ Applies manifests
                  ▼
        ┌─────────────────────┐
        │ Deployment + PVC    │
        └─────────┬───────────┘
                  │ Scheduler
                  ▼
        ┌─────────────────────┐
        │ Pod (InfluxDB)      │
        │ + Liveness/Readiness│
        └─────────┬───────────┘
                  │ Internal service
                  ▼
        ┌─────────────────────┐
        │ InfluxDB Available  │
        └─────────────────────┘

🚑 Troubleshooting

Pod stuck in CrashLoopBackOff

kubectl logs <pod-name> -n monitoring

• Check misconfiguration in values.yaml
• Validate readiness/liveness probe paths

PVC not binding

kubectl describe pvc -n monitoring

• Ensure Minikube has storage class enabled

Helm release issues

helm list -n monitoring
helm rollback <release-name> <revision>

📌 Next Steps

• Add Grafana/Prometheus integration
• Support multiple storage backends
• Expand main.py into orchestration logic