diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..07e198f
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,229 @@
+name: CI Pipeline
+
+on:
+ push:
+ branches: [ main, develop ]
+ pull_request:
+ branches: [ main, develop ]
+
+jobs:
+ validate-yaml:
+ name: Validate YAML Syntax
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+
+ - name: Install yamllint
+ run: pip install yamllint
+
+ - name: Validate YAML files
+ run: |
+ find . -name "*.yaml" -o -name "*.yml" | xargs yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}"
+
+ validate-kubernetes:
+ name: Validate Kubernetes Manifests
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up kubectl
+ uses: azure/setup-kubectl@v3
+ with:
+ version: 'v1.28.0'
+
+ - name: Validate cluster configs
+ run: |
+ echo "Validating k3d cluster configurations..."
+ kubectl version --client
+
+ - name: Validate ArgoCD applications
+ run: |
+ echo "Checking ArgoCD application manifests..."
+ for file in clusters/*/argocd-apps/*.yaml; do
+ if [ -f "$file" ]; then
+ echo "Validating $file"
+ kubectl apply --dry-run=client -f "$file" || exit 1
+ fi
+ done
+
+ validate-helm:
+ name: Validate Helm Charts
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up Helm
+ uses: azure/setup-helm@v3
+ with:
+ version: 'v3.13.0'
+
+ - name: Add Helm repositories
+ run: |
+ helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+ helm repo add grafana https://grafana.github.io/helm-charts
+ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
+ helm repo add kyverno https://kyverno.github.io/kyverno/
+ helm repo update
+
+ - name: Validate Helm charts
+ run: |
+ echo "Validating platform Helm charts..."
+ for chart in platform/*/; do
+ if [ -f "${chart}Chart.yaml" ]; then
+ echo "Linting $(basename $chart)"
+ helm dependency update "$chart"
+ helm lint "$chart" || exit 1
+
+ # Validate with dev values
+ if [ -f "${chart}values-dev.yaml" ]; then
+ helm lint "$chart" -f "${chart}values-dev.yaml" || exit 1
+ fi
+
+ # Validate with prod values
+ if [ -f "${chart}values-prod.yaml" ]; then
+ helm lint "$chart" -f "${chart}values-prod.yaml" || exit 1
+ fi
+ fi
+ done
+
+ test-scripts:
+ name: Test Shell Scripts
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Install shellcheck
+ run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+ - name: Validate shell scripts
+ run: |
+ echo "Checking shell scripts with shellcheck..."
+ find scripts/ -name "*.sh" -type f | xargs shellcheck -x || exit 1
+
+ - name: Check script permissions
+ run: |
+ echo "Verifying script permissions..."
+ for script in scripts/*.sh; do
+ if [ -f "$script" ]; then
+ if [ ! -x "$script" ]; then
+ echo "Warning: $script is not executable"
+ chmod +x "$script"
+ fi
+ fi
+ done
+
+ security-scan:
+ name: Security Scan
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Run Trivy vulnerability scanner
+ uses: aquasecurity/trivy-action@master
+ with:
+ scan-type: 'config'
+ scan-ref: '.'
+ format: 'sarif'
+ output: 'trivy-results.sarif'
+
+ - name: Upload Trivy results to GitHub Security
+ uses: github/codeql-action/upload-sarif@v3
+ if: always()
+ with:
+ sarif_file: 'trivy-results.sarif'
+
+ integration-test:
+ name: Integration Test (Optional)
+ runs-on: ubuntu-latest
+ if: github.event_name == 'pull_request'
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up Docker
+ uses: docker/setup-buildx-action@v3
+
+ - name: Install k3d
+ run: |
+ curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
+
+ - name: Install kubectl
+ uses: azure/setup-kubectl@v3
+ with:
+ version: 'v1.28.0'
+
+ - name: Install Helm
+ uses: azure/setup-helm@v3
+ with:
+ version: 'v3.13.0'
+
+ - name: Create test cluster
+ run: |
+ echo "Creating test k3d cluster..."
+ k3d cluster create test-cluster \
+ --servers 1 \
+ --agents 1 \
+ --wait \
+ --timeout 120s
+
+ - name: Verify cluster
+ run: |
+ kubectl cluster-info
+ kubectl get nodes
+
+ - name: Test ArgoCD installation
+ run: |
+ echo "Testing ArgoCD installation..."
+ kubectl create namespace argocd
+ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+ kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd
+
+ - name: Cleanup
+ if: always()
+ run: |
+ k3d cluster delete test-cluster
+
+ lint-markdown:
+ name: Lint Markdown
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Lint Markdown files
+ uses: DavidAnson/markdownlint-cli2-action@v14
+ with:
+ globs: '**/*.md'
+ config: |
+ {
+ "default": true,
+ "MD013": false,
+ "MD033": false,
+ "MD041": false
+ }
+
+ summary:
+ name: CI Summary
+ runs-on: ubuntu-latest
+ needs: [validate-yaml, validate-kubernetes, validate-helm, test-scripts, security-scan]
+ if: always()
+ steps:
+ - name: Check job results
+ run: |
+ echo "## CI Pipeline Summary" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "✅ YAML Validation: ${{ needs.validate-yaml.result }}" >> $GITHUB_STEP_SUMMARY
+ echo "✅ Kubernetes Validation: ${{ needs.validate-kubernetes.result }}" >> $GITHUB_STEP_SUMMARY
+ echo "✅ Helm Validation: ${{ needs.validate-helm.result }}" >> $GITHUB_STEP_SUMMARY
+ echo "✅ Shell Script Tests: ${{ needs.test-scripts.result }}" >> $GITHUB_STEP_SUMMARY
+ echo "✅ Security Scan: ${{ needs.security-scan.result }}" >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..96c58d7
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,38 @@
+name: Release
+
+on:
+ push:
+ tags:
+ - 'v*.*.*'
+
+jobs:
+ release:
+ name: Create Release
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Get version from tag
+ id: get_version
+ run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+ - name: Generate changelog
+ id: changelog
+ run: |
+ echo "## What's Changed" > CHANGELOG.txt
+ git log $(git describe --tags --abbrev=0 HEAD^)..HEAD --pretty=format:"* %s (%h)" >> CHANGELOG.txt
+
+ - name: Create GitHub Release
+ uses: softprops/action-gh-release@v1
+ with:
+ name: Release ${{ steps.get_version.outputs.VERSION }}
+ body_path: CHANGELOG.txt
+ draft: false
+ prerelease: false
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.yamllint b/.yamllint
new file mode 100644
index 0000000..d031d52
--- /dev/null
+++ b/.yamllint
@@ -0,0 +1,16 @@
+---
+extends: relaxed
+
+rules:
+ line-length:
+ max: 120
+ level: warning
+ indentation:
+ spaces: 2
+ indent-sequences: true
+ comments:
+ min-spaces-from-content: 1
+ comments-indentation: {}
+ document-start: disable
+ truthy:
+ allowed-values: ['true', 'false', 'yes', 'no']
diff --git a/README.md b/README.md
index 58af810..2a663ce 100644
--- a/README.md
+++ b/README.md
@@ -1,320 +1,578 @@
-# 🚀 k8s-gitops-template -> **In-progress**
-
-> **Production-ready Kubernetes DevOps template with automated local clusters (dev/prod), GitOps, monitoring, logging, security policies, and CI/CD pipelines.**
-
-[](https://opensource.org/licenses/MIT)
-[](https://kubernetes.io/)
-[](https://argoproj.github.io/cd/)
-
-## 📋 Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Project Structure](#project-structure)
-- [Usage](#usage)
-- [Contributing](#contributing)
-- [License](#license)
-
-## 🎯 Overview
-
-This project provides a **complete, production-ready Kubernetes template** for DevOps engineers. It includes:
-
-- 🏗️ Automated local Kubernetes clusters (dev & prod) using **k3d**
-- 🔄 **GitOps** workflow with ArgoCD
-- 📊 Full observability stack (Prometheus, Grafana, Loki)
-- 🔒 Security policies (Kyverno, Pod Security, Network Policies)
-- 🔐 RBAC configuration with namespace isolation
-- 🚦 CI/CD pipelines with GitHub Actions
-- 📦 Sample microservices with Helm charts
-- 🔧 One-command setup with `make bootstrap`
-
-## ✨ Features
-
-### Platform Components
-
-- **k3d**: Lightweight Kubernetes clusters in Docker
-- **ArgoCD**: GitOps continuous delivery
-- **Ingress NGINX**: Ingress controller with TLS support
-- **cert-manager**: Automatic TLS certificate management
-- **Prometheus Stack**: Monitoring and alerting
-- **Grafana**: Visualization and dashboards
-- **Loki**: Log aggregation
-- **Kyverno**: Policy engine for Kubernetes
-- **Sealed Secrets**: Encrypted secrets management
-
-### DevOps Features
-
-- ✅ Automated cluster provisioning
-- ✅ Namespace isolation (dev/prod)
-- ✅ RBAC roles and bindings
-- ✅ Network policies
-- ✅ Resource quotas and limits
-- ✅ Pod Security Standards
-- ✅ GitHub Actions CI/CD
-- ✅ Helm charts for apps
-- ✅ GitOps deployment workflow
-
-## 🔧 Prerequisites
-
-Required tools (install scripts provided):
-
-- [Docker](https://docs.docker.com/get-docker/) (20.10+)
-- [kubectl](https://kubernetes.io/docs/tasks/tools/) (1.28+)
-- [k3d](https://k3d.io/) (5.6+)
-- [Helm](https://helm.sh/docs/intro/install/) (3.12+)
-- [ArgoCD CLI](https://argo-cd.readthedocs.io/en/stable/cli_installation/) (2.8+)
-- [make](https://www.gnu.org/software/make/)
-
-### Quick Install
-
-```bash
-# Install all prerequisites (Linux/macOS)
-./scripts/install-prerequisites.sh
-```
+
+
+
+
+ 📋 Table of Contents
+
+ -
+ About The Project
+
+
+ -
+ Getting Started
+
+
+ - Usage
+ - Project Structure
+ - Architecture
+ - CI/CD
+ - Contributing
+ - License
+ - Contact
+ - Acknowledgments
+
+
+
+
+## 🎯 About The Project
+
+This project provides a **complete, production-ready Kubernetes template** designed for DevOps engineers who want to quickly set up a local Kubernetes environment with GitOps principles, comprehensive monitoring, and security best practices.
+
+**Key Highlights:**
+* 🏗️ **Automated Setup**: Two k3d clusters (dev & prod) deployed with a single command
+* 🔄 **GitOps Workflow**: ArgoCD-based continuous deployment with declarative configuration
+* 📊 **Full Observability**: Prometheus, Grafana, and Loki for complete monitoring and logging
+* 🔒 **Security First**: Kyverno policies for automated security enforcement
+* 🚀 **Production-Ready**: Separate dev and prod environments with proper isolation
+* � **Easy to Extend**: Well-structured platform components using Helm charts
+
+This template is perfect for learning Kubernetes, testing applications locally, or as a starting point for your own GitOps infrastructure.
+
+(back to top)
+
+### � Built With
+
+This project leverages the following major frameworks and tools:
+
+* [![Kubernetes][Kubernetes-badge]][Kubernetes-url]
+* [![Docker][Docker-badge]][Docker-url]
+* [![ArgoCD][ArgoCD-badge]][ArgoCD-url]
+* [![Prometheus][Prometheus-badge]][Prometheus-url]
+* [![Grafana][Grafana-badge]][Grafana-url]
+* [![Helm][Helm-badge]][Helm-url]
+
+**Platform Components:**
+- **k3d** - Lightweight Kubernetes clusters in Docker
+- **ArgoCD** - GitOps continuous delivery tool
+- **Ingress NGINX** - Kubernetes Ingress controller
+- **Prometheus Stack** (kube-prometheus-stack v55.5.0) - Monitoring and alerting
+- **Grafana** - Metrics visualization and dashboards
+- **Loki** (v2.9.0) - Log aggregation system
+- **Promtail** - Log collector for Loki
+- **Kyverno** (v1.11.0) - Kubernetes policy engine
+
+(back to top)
+
+
+## 🚀 Getting Started
+
+Follow these steps to get your local Kubernetes clusters up and running with all platform components deployed.
+
+### � Prerequisites
+
+Before you begin, ensure you have the following tools installed on your system:
+
+* **Docker** (20.10+)
+ ```sh
+ # Verify installation
+ docker --version
+ ```
+
+* **kubectl** (1.28+)
+ ```sh
+ # Verify installation
+ kubectl version --client
+ ```
+
+* **k3d** (5.6+)
+ ```sh
+ # Verify installation
+ k3d version
+ ```
+
+* **Helm** (3.12+)
+ ```sh
+ # Verify installation
+ helm version
+ ```
+
+### � Installation
+
+1. **Clone the repository**
+ ```sh
+ git clone https://github.com/Kobeep/k8s-gitops-template.git
+ cd k8s-gitops-template
+ ```
+
+2. **Install prerequisites** (if needed)
+ ```sh
+ ./scripts/install-prerequisites.sh
+ ```
+
+3. **Bootstrap both clusters**
+ ```sh
+ ./scripts/bootstrap.sh
+ ```
+
+ This will:
+ - ✅ Create k3d dev cluster (1 server + 2 agents)
+ - ✅ Create k3d prod cluster (1 server + 3 agents)
+ - ✅ Install ArgoCD on both clusters
+ - ✅ Deploy root applications
+ - ✅ Configure GitOps sync
-## 🚀 Quick Start
+4. **Verify cluster status**
+ ```sh
+ ./scripts/status.sh
+ ```
-### 1. Clone the repository
+5. **Get ArgoCD credentials**
+
+ The bootstrap script will output the ArgoCD admin passwords for both clusters. You can also retrieve them manually:
+
+ ```sh
+ # DEV cluster
+ kubectl config use-context k3d-k8s-dev
+ kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
-```bash
-git clone https://github.com/Kobeep/k8s-devops-template.git
-cd k8s-devops-template
+ # PROD cluster
+ kubectl config use-context k3d-k8s-prod
+ kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
+ ```
+
+(back to top)
+
+
+## 💡 Usage
+
+### Managing Clusters
+
+**Bootstrap Clusters:**
+```sh
+# Bootstrap both dev and prod clusters
+./scripts/bootstrap.sh
```
-### 2. Bootstrap everything
+**Switch Between Clusters:**
+```sh
+# Switch to dev cluster
+kubectl config use-context k3d-k8s-dev
-```bash
-# Create both dev and prod clusters with all components
-make bootstrap
+# Switch to prod cluster
+kubectl config use-context k3d-k8s-prod
```
-This single command will:
-- Create k3d clusters (dev & prod)
-- Install ArgoCD and configure GitOps
-- Deploy monitoring stack (Prometheus, Grafana, Loki)
-- Configure RBAC and security policies
-- Deploy sample applications
-
-### 3. Access services
-
-```bash
-# Get ArgoCD password
-make argocd-password
-
-# Access ArgoCD UI (http://localhost:8080)
-make argocd
-
-# Access Grafana (http://localhost:3000)
-make monitoring
+**Check Cluster Status:**
+```sh
+./scripts/status.sh
+```
-# Access Prometheus (http://localhost:9090)
-make prometheus
+**Destroy Clusters:**
+```sh
+./scripts/destroy.sh
```
-### 4. Check status
+### Accessing Services
-```bash
-# View cluster status
-make status
+**ArgoCD:**
+```sh
+# Dev cluster - http://localhost:8080
+kubectl port-forward -n argocd svc/argocd-server 8080:443 --context k3d-k8s-dev
-# Switch between clusters
-make dev # Switch to dev cluster
-make prod # Switch to prod cluster
+# Prod cluster - http://localhost:9080
+kubectl port-forward -n argocd svc/argocd-server 9080:443 --context k3d-k8s-prod
```
-## 🏗️ Architecture
+**Grafana:**
+```sh
+# Access via Prometheus Stack service
+kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80
+```
+**Prometheus:**
+```sh
+# Access Prometheus UI
+kubectl port-forward -n monitoring svc/kube-prometheus-stack-prometheus 9090:9090
```
-┌─────────────────────────────────────────────────────────────┐
-│ GitHub Repository │
-│ (GitOps Source) │
-└──────────────────────┬──────────────────────────────────────┘
- │
- │ ArgoCD Sync
- │
- ┌──────────────┴──────────────┐
- │ │
-┌───────▼───────┐ ┌────────▼────────┐
-│ Dev Cluster │ │ Prod Cluster │
-│ (k3d) │ │ (k3d) │
-├───────────────┤ ├─────────────────┤
-│ • ArgoCD │ │ • ArgoCD │
-│ • Ingress │ │ • Ingress │
-│ • Prometheus │ │ • Prometheus │
-│ • Grafana │ │ • Grafana │
-│ • Loki │ │ • Loki │
-│ • Kyverno │ │ • Kyverno │
-│ • Sample Apps │ │ • Sample Apps │
-└───────────────┘ └─────────────────┘
+
+### Deploying Applications
+
+ArgoCD automatically syncs applications from the `clusters/{dev,prod}/argocd-apps/` directory. To add new applications:
+
+1. Create an ArgoCD Application manifest in the appropriate cluster directory
+2. Commit and push to the repository
+3. ArgoCD will automatically detect and sync the new application
+
+**Example Application:**
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+ name: my-app-dev
+ namespace: argocd
+spec:
+ project: default
+ source:
+ repoURL: https://github.com/Kobeep/k8s-gitops-template.git
+ targetRevision: main
+ path: apps/my-app
+ destination:
+ server: https://kubernetes.default.svc
+ namespace: dev
+ syncPolicy:
+ automated:
+ prune: true
+ selfHeal: true
```
-See [Architecture Documentation](docs/architecture.md) for detailed diagrams.
+(back to top)
+
## 📁 Project Structure
```
-k8s-devops-template/
-├── Makefile # Main automation commands
-├── README.md # This file
-├── .github/
-│ └── workflows/ # GitHub Actions CI/CD
-│ ├── build-and-push.yml # Build & push Docker images
-│ ├── deploy-dev.yml # Deploy to dev
-│ └── deploy-prod.yml # Deploy to prod
-├── clusters/ # Cluster configurations
-│ ├── dev/
-│ │ ├── cluster-config.yaml # k3d dev cluster config
-│ │ └── argocd-apps/ # ArgoCD app definitions
-│ └── prod/
-│ ├── cluster-config.yaml # k3d prod cluster config
-│ └── argocd-apps/ # ArgoCD app definitions
-├── platform/ # Platform components
-│ ├── argocd/ # ArgoCD installation
-│ ├── ingress-nginx/ # Ingress controller
-│ ├── cert-manager/ # Certificate management
-│ ├── monitoring/ # Prometheus, Grafana
-│ ├── logging/ # Loki, Promtail
-│ ├── security/ # Kyverno, policies
-│ └── sealed-secrets/ # Sealed Secrets controller
-├── apps/ # Sample applications
-│ ├── sample-app/
-│ │ ├── helm/ # Helm chart
-│ │ ├── manifests/ # K8s manifests
-│ │ └── src/ # Application source
-│ └── microservices/
-│ ├── frontend/
-│ ├── backend/
-│ └── database/
-├── rbac/ # RBAC configurations
+k8s-gitops-template/
+├── clusters/ # Cluster-specific configurations
│ ├── dev/
-│ │ ├── namespaces.yaml
-│ │ ├── roles.yaml
-│ │ └── rolebindings.yaml
+│ │ ├── cluster-config.yaml # k3d dev cluster config (1 server + 2 agents)
+│ │ │ # Ports: HTTP:8080, HTTPS:8443, NodePort:30000-30010
+│ │ └── argocd-apps/ # ArgoCD Applications for dev
+│ │ ├── root-app.yaml # Root app of apps pattern
+│ │ ├── platform.yaml # Platform components (monitoring, logging, etc.)
+│ │ └── apps.yaml # Application deployments
│ └── prod/
-│ ├── namespaces.yaml
-│ ├── roles.yaml
-│ └── rolebindings.yaml
-├── policies/ # Kyverno policies
-│ ├── pod-security.yaml
-│ ├── resource-limits.yaml
-│ └── network-policies.yaml
-├── scripts/ # Automation scripts
-│ ├── bootstrap.sh # Main bootstrap script
-│ ├── bootstrap-cluster.sh # Single cluster bootstrap
-│ ├── destroy.sh # Destroy clusters
+│ ├── cluster-config.yaml # k3d prod cluster config (1 server + 3 agents)
+│ │ # Ports: HTTP:9080, HTTPS:9443, NodePort:31000-31010
+│ └── argocd-apps/ # ArgoCD Applications for prod
+│ ├── root-app.yaml
+│ ├── platform.yaml
+│ └── apps.yaml
+│
+├── platform/ # Platform components (Helm umbrella charts)
+│ ├── ingress-nginx/ # Ingress NGINX Controller
+│ │ ├── Chart.yaml # v4.8.3
+│ │ ├── values.yaml # Default values
+│ │ ├── values-dev.yaml # Dev-specific overrides
+│ │ └── values-prod.yaml # Prod-specific overrides
+│ │
+│ ├── monitoring/ # Prometheus + Grafana
+│ │ ├── Chart.yaml # kube-prometheus-stack v55.5.0
+│ │ ├── values.yaml
+│ │ ├── values-dev.yaml
+│ │ └── values-prod.yaml
+│ │
+│ ├── logging/ # Loki + Promtail
+│ │ ├── Chart.yaml # Loki v5.41.4, Promtail v6.15.3
+│ │ ├── values.yaml
+│ │ ├── values-dev.yaml
+│ │ └── values-prod.yaml
+│ │
+│ └── security/ # Kyverno policies
+│ ├── Chart.yaml # Kyverno v3.1.4
+│ ├── values.yaml
+│ ├── values-dev.yaml
+│ └── values-prod.yaml
+│
+├── scripts/ # Automation scripts
+│ ├── bootstrap.sh # Bootstrap both clusters
+│ ├── destroy.sh # Destroy all clusters
│ ├── status.sh # Check cluster status
-│ ├── port-forward.sh # Port forwarding helper
-│ ├── deploy-apps.sh # Deploy applications
-│ ├── validate.sh # Validate manifests
│ └── install-prerequisites.sh # Install required tools
-└── tests/ # Integration tests
- ├── cluster-tests.sh
- ├── app-tests.sh
- └── security-tests.sh
+│
+├── CONTRIBUTING.md # Contribution guidelines
+├── LICENSE # MIT License
+└── README.md # This file
```
-## 📖 Usage
+**Key Design Principles:**
+* **Separation of Concerns**: Platform components are separate from applications
+* **GitOps-Native**: Everything is declarative and stored in Git
+* **Environment Parity**: Dev and prod use the same structure with different values
+* **Helm-Based**: All platform components use Helm for easy customization
+* **App of Apps Pattern**: ArgoCD manages multiple applications through a root app
-### Cluster Management
+(back to top)
-```bash
-# Bootstrap both clusters
-make bootstrap
+
+## 🏗 Architecture
-# Bootstrap only dev
-make bootstrap-dev
+### Cluster Architecture
-# Bootstrap only prod
-make bootstrap-prod
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ GitHub Repository │
+│ (GitOps Source of Truth) │
+└────────────────────────────┬─────────────────────────────────────────┘
+ │
+ │ ArgoCD pulls manifests
+ │ and syncs to clusters
+ │
+ ┌──────────────┴──────────────┐
+ │ │
+ ┌─────────▼──────────┐ ┌────────▼──────────┐
+ │ Dev Cluster │ │ Prod Cluster │
+ │ (k3d) │ │ (k3d) │
+ ├────────────────────┤ ├───────────────────┤
+ │ • 1 server │ │ • 1 server │
+ │ • 2 agents │ │ • 3 agents │
+ │ │ │ │
+ │ Ports: │ │ Ports: │
+ │ • HTTP: 8080 │ │ • HTTP: 9080 │
+ │ • HTTPS: 8443 │ │ • HTTPS: 9443 │
+ │ • NodePort: │ │ • NodePort: │
+ │ 30000-30010 │ │ 31000-31010 │
+ └────────────────────┘ └───────────────────┘
+```
-# Destroy all clusters
-make destroy
+### Platform Components per Cluster
-# Check status
-make status
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Kubernetes Cluster (k3d) │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ argocd namespace │ │
+│ │ • ArgoCD Server │ │
+│ │ • ArgoCD Application Controller │ │
+│ │ • ArgoCD Repo Server │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ ingress-nginx namespace │ │
+│ │ • NGINX Ingress Controller │ │
+│ │ • LoadBalancer Service │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ monitoring namespace │ │
+│ │ • Prometheus (metrics collection) │ │
+│ │ • Grafana (visualization) │ │
+│ │ • AlertManager (alerting) │ │
+│ │ • Node Exporter (node metrics) │ │
+│ │ • Kube State Metrics (k8s metrics) │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ logging namespace │ │
+│ │ • Loki (log aggregation) │ │
+│ │ • Promtail (log collection) │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ security namespace │ │
+│ │ • Kyverno (policy engine) │ │
+│ │ • Admission Controller │ │
+│ │ • Background Controller │ │
+│ │ • Reports Controller │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ dev/prod namespaces │ │
+│ │ • Application workloads │ │
+│ └──────────────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────┘
```
-### Switching Contexts
-
-```bash
-# Switch to dev cluster
-make dev
+### GitOps Flow
-# Switch to prod cluster
-make prod
+```
+1. Developer pushes changes to Git repository
+ ↓
+2. ArgoCD detects changes automatically
+ ↓
+3. ArgoCD pulls updated manifests
+ ↓
+4. ArgoCD applies changes to cluster
+ ↓
+5. Applications are deployed/updated
+ ↓
+6. Monitoring & logging track the deployment
```
-### Accessing Services
+(back to top)
-```bash
-# ArgoCD
-make argocd
-make argocd-password
+
+## 🔄 CI/CD
-# Grafana
-make monitoring
+This project includes automated CI/CD pipelines using **GitHub Actions**.
-# Prometheus
-make prometheus
+### CI Pipeline
-# Alertmanager
-make alertmanager
-```
+The CI pipeline runs automatically on every push and pull request to `main` or `develop` branches.
-### Application Deployment
+**Pipeline Stages:**
-```bash
-# Deploy sample applications
-make deploy-apps
+1. **YAML Validation** - Validates all YAML files using yamllint
+2. **Kubernetes Validation** - Validates Kubernetes manifests with kubectl dry-run
+3. **Helm Validation** - Lints all Helm charts in the platform directory
+4. **Script Testing** - Runs shellcheck on all bash scripts
+5. **Security Scanning** - Scans for vulnerabilities using Trivy
+6. **Integration Testing** - Creates a test k3d cluster (PR only)
+7. **Markdown Linting** - Validates markdown documentation
-# Sync ArgoCD applications
-make sync
+**Status Badge:**
-# View application logs
-make logs
-```
+[](https://github.com/Kobeep/k8s-gitops-template/actions/workflows/ci.yml)
+
+### Running Tests Locally
+
+Before pushing, you can run validations locally:
+
+```sh
+# Install dependencies
+pip install yamllint
+sudo apt-get install shellcheck
-### Validation & Testing
+# Validate YAML
+yamllint -c .yamllint .
-```bash
-# Validate all manifests
-make validate
+# Check shell scripts
+shellcheck scripts/*.sh
-# Run integration tests
-make test
+# Lint Helm charts
+helm lint platform/monitoring/
+helm lint platform/logging/
+helm lint platform/security/
+helm lint platform/ingress-nginx/
+
+# Validate Kubernetes manifests
+kubectl apply --dry-run=client -f clusters/dev/argocd-apps/
+kubectl apply --dry-run=client -f clusters/prod/argocd-apps/
```
-## 🔒 Security
+### Release Process
+
+To create a new release:
-This template includes:
+```sh
+# Create and push a tag
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```
-- **Pod Security Standards**: Enforced at namespace level
-- **Network Policies**: Restrict pod-to-pod communication
-- **RBAC**: Fine-grained access control
-- **Kyverno Policies**: Automated policy enforcement
-- **Sealed Secrets**: Encrypted secrets in Git
+The release workflow will automatically:
+- Create a GitHub release
+- Generate a changelog from commits
+- Tag the release with semantic versioning
-See [Security Documentation](docs/security.md) for details.
+For more details, see [`.github/workflows/README.md`](.github/workflows/README.md).
+(back to top)
+
+
## 🤝 Contributing
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+For more details, please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
+
+(back to top)
+
+
## 📄 License
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+Distributed under the MIT License. See `LICENSE` for more information.
+
+(back to top)
+
+
+## 📧 Contact
+Jakub Pospieszny - [@Kobeep](https://github.com/Kobeep)
+
+Project Link: [https://github.com/Kobeep/k8s-gitops-template](https://github.com/Kobeep/k8s-gitops-template)
+
+(back to top)
+
+
## 🙏 Acknowledgments
-- [k3d](https://k3d.io/) - Lightweight Kubernetes in Docker
-- [ArgoCD](https://argoproj.github.io/cd/) - GitOps continuous delivery
-- [Prometheus](https://prometheus.io/) - Monitoring and alerting
-- [Grafana](https://grafana.com/) - Visualization platform
-- [Kyverno](https://kyverno.io/) - Kubernetes policy engine
+This project was built using these amazing open-source tools:
+
+* [k3d](https://k3d.io/) - Lightweight Kubernetes in Docker
+* [ArgoCD](https://argoproj.github.io/cd/) - GitOps continuous delivery tool
+* [Prometheus](https://prometheus.io/) - Monitoring and alerting toolkit
+* [Grafana](https://grafana.com/) - Analytics and monitoring platform
+* [Loki](https://grafana.com/oss/loki/) - Log aggregation system
+* [Kyverno](https://kyverno.io/) - Kubernetes native policy management
+* [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) - Ingress controller for Kubernetes
+* [Helm](https://helm.sh/) - The package manager for Kubernetes
+* [Best-README-Template](https://github.com/othneildrew/Best-README-Template) - README template inspiration
+
+(back to top)
---
-**Made with ❤️ for the DevOps community**
+
+ Made with ❤️ for the DevOps community
+
+ If you find this project helpful, please consider giving it a ⭐
+
+
+
+[Kubernetes-badge]: https://img.shields.io/badge/Kubernetes-326CE5?style=for-the-badge&logo=kubernetes&logoColor=white
+[Kubernetes-url]: https://kubernetes.io/
+[Docker-badge]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white
+[Docker-url]: https://www.docker.com/
+[ArgoCD-badge]: https://img.shields.io/badge/ArgoCD-EF7B4D?style=for-the-badge&logo=argo&logoColor=white
+[ArgoCD-url]: https://argoproj.github.io/cd/
+[Prometheus-badge]: https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge&logo=prometheus&logoColor=white
+[Prometheus-url]: https://prometheus.io/
+[Grafana-badge]: https://img.shields.io/badge/Grafana-F46800?style=for-the-badge&logo=grafana&logoColor=white
+[Grafana-url]: https://grafana.com/
+[Helm-badge]: https://img.shields.io/badge/Helm-0F1689?style=for-the-badge&logo=helm&logoColor=white
+[Helm-url]: https://helm.sh/
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+