🚀 K8s GitOps Template

Production-ready Kubernetes GitOps template with automated local clusters, full observability stack, and security policies

Explore the docs »

View Demo · Report Bug · Request Feature

📋 Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Project Structure
5. Architecture
6. CI/CD
7. Contributing
8. License
9. Contact
10. 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:

• 
• 
• 
• 
• 
• 

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+)

  # Verify installation
  docker --version

• kubectl (1.28+)

  # Verify installation
  kubectl version --client

• k3d (5.6+)

  # Verify installation
  k3d version

• Helm (3.12+)

  # Verify installation
  helm version

� Installation

1. Clone the repository

   git clone https://github.com/Kobeep/k8s-gitops-template.git
   cd k8s-gitops-template

2. Install prerequisites (if needed)

   ./scripts/install-prerequisites.sh

3. Bootstrap both clusters

   ./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

4. Verify cluster status

   ./scripts/status.sh

5. Get ArgoCD credentials

   The bootstrap script will output the ArgoCD admin passwords for both clusters. You can also retrieve them manually:

   # DEV cluster
   kubectl config use-context k3d-k8s-dev
   kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
   
   # 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:

# Bootstrap both dev and prod clusters
./scripts/bootstrap.sh

Switch Between Clusters:

# Switch to dev cluster
kubectl config use-context k3d-k8s-dev

# Switch to prod cluster
kubectl config use-context k3d-k8s-prod

Check Cluster Status:

./scripts/status.sh

Destroy Clusters:

./scripts/destroy.sh

Accessing Services

ArgoCD:

# Dev cluster - http://localhost:8080
kubectl port-forward -n argocd svc/argocd-server 8080:443 --context k3d-k8s-dev

# Prod cluster - http://localhost:9080
kubectl port-forward -n argocd svc/argocd-server 9080:443 --context k3d-k8s-prod

Grafana:

# Access via Prometheus Stack service
kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80

Prometheus:

# Access Prometheus UI
kubectl port-forward -n monitoring svc/kube-prometheus-stack-prometheus 9090:9090

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:

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

(back to top)

📁 Project Structure

k8s-gitops-template/
├── clusters/                         # Cluster-specific configurations
│   ├── dev/
│   │   ├── 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/
│       ├── 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
│   └── install-prerequisites.sh     # Install required tools
│
├── CONTRIBUTING.md                   # Contribution guidelines
├── LICENSE                          # MIT License
└── README.md                        # This file

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

(back to top)

🏗 Architecture

Cluster Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         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     │
    └────────────────────┘        └───────────────────┘

Platform Components per Cluster

┌─────────────────────────────────────────────────────────────┐
│                    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                              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
└─────────────────────────────────────────────────────────────┘

GitOps Flow

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

(back to top)

🤝 Contributing

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.

(back to top)

📄 License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

📧 Contact

Jakub Pospieszny - @Kobeep

Project Link: https://github.com/Kobeep/k8s-gitops-template

(back to top)

🙏 Acknowledgments

This project was built using these amazing open-source tools:

• k3d - Lightweight Kubernetes in Docker
• ArgoCD - GitOps continuous delivery tool
• Prometheus - Monitoring and alerting toolkit
• Grafana - Analytics and monitoring platform
• Loki - Log aggregation system
• Kyverno - Kubernetes native policy management
• NGINX Ingress Controller - Ingress controller for Kubernetes
• Helm - The package manager for Kubernetes
• Best-README-Template - README template inspiration

(back to top)

---

Made with ❤️ for the DevOps community
_{If you find this project helpful, please consider giving it a ⭐}