⚓ GitOps Infrastructure: ArgoCD & K3s

🏗 Project Architecture

This repository serves as the Single Source of Truth (SSOT) for my lightweight Kubernetes cluster infrastructure. Hosted on a Virtual Private Server (VPS) running K3s, it strictly adheres to GitOps principles using ArgoCD, ensuring that the cluster state always matches the declarative configurations stored in this repository.

🔗 Open the scheme in the Lucidchart

🧳 The App-of-Apps Pattern

To maintain scalability and clean logical separation, this repository implements the ArgoCD App-of-Apps pattern.

Instead of deploying individual manifests manually, a single root.yaml application is deployed, which recursively discovers and synchronizes all other applications defined in the apps/ directory.

Here is the updated section for your README in professional technical English. I’ve refined the descriptions to highlight your DevOps skills, specifically focusing on the dynamic nature of your pipelines.

📂 Repository Structure

.
├── apps/               # ArgoCD Application Wrappers
│   ├── monitoring.yaml # Kube-Prometheus-Stack definition
│   ├── portfolio.yaml  # Portfolio app definition
│   └── tikceto.yaml    # Tikceto microservices definition
├── bootstrap/          # Cluster Initialization
│   └── root.yaml       # The "App of Apps" entry point
└── manifests/          # Raw Kubernetes Resources
    ├── portfolio/      # Deployment, Ingress, Service
    └── tikceto/        # Backend, Frontend, Minio, Postgres, Ingress

⚙️ Cluster Bootstrapping

To deploy this entire infrastructure to a fresh Kubernetes cluster (assuming ArgoCD is pre-installed):

1. Apply the Root Application:

kubectl apply -f bootstrap/root.yaml

2. Automated Synchronization:

ArgoCD will detect the root application, which will subsequently deploy monitoring, portfolio, and tikceto. All dependencies, persistent volume claims, and ingresses will be provisioned automatically based on the sync policies.

🔐 Security & Connectivity

To ensure the cluster remains isolated from the public internet while remaining accessible for management, the following components are integrated into the GitOps workflow:

🌐 Tailscale: Zero Trust Networking

Instead of exposing the Kubernetes API (6443) or internal services to the world, the cluster utilizes Tailscale for secure, encrypted connectivity.

• Tailscale Kubernetes Operator: Managed via ArgoCD, the operator allows exposing internal services directly to the private Tailnet.
• Subnet Routing: A dedicated pod acts as a Subnet Router, announcing internal service and pod CIDRs (10.43.0.0/16, 10.42.0.0/16) to authorized devices, such as my macOS management environment.
• Management Isolation: This dual-layer approach provides a "Management Plane" for SSH and host-level recovery, while the "Control Plane" remains accessible only via private cluster routes.

🗝️ HashiCorp Vault: Secrets Management

Following GitOps best practices, no sensitive data is stored in plain text within this repository.

• Centralized Secrets: HashiCorp Vault serves as the primary secrets engine, providing a secure, centralized location for database credentials, API keys, and certificates.
• External Secrets Operator (ESO): The cluster utilizes ESO to synchronize secrets from Vault into native Kubernetes Secret resources, ensuring a seamless and secure developer experience.
• Dynamic Injection: Future iterations aim to implement direct sidecar injection for applications, further reducing the attack surface by avoiding persistent secret storage in the cluster etcd.

🚀 CI/CD & Security Pipelines

This repository utilizes GitHub Actions to automate security auditing and manifest validation, ensuring that only "clean" and syntactically correct configurations reach the cluster.

🛡️ Image Security Scan

A scheduled and event-driven vulnerability scanner that maintains an overview of the software supply chain.

• Dynamic Matrix Strategy: The workflow automatically parses all Docker images defined in the manifests/ directory and generates a parallel execution matrix.
• Trivy Analysis: Every extracted image is scanned for CRITICAL and HIGH vulnerabilities.

📋 PR Validation

A robust "Gatekeeper" pipeline that triggers on every Pull Request to the main branch:

• Kube-Linter: Audits Kubernetes manifests against security best practices (e.g., verifying SecurityContext, Resource Limits, and Root FS settings).
• Infrastructure as Code (IaC) Scanning: Uses Trivy to detect misconfigurations in the YAML manifests before they are applied.
• Syntax & Schema Verification: Validates YAML structure using yq and ensures ArgoCD Application manifests contain all required fields to prevent synchronization failures.
• Sanity Checks: Verifies the logical presence of essential resources (like Deployments) within each project subdirectory.

📅 Backlog

• Add external secret manager
• Add the ELK Stack
• Integrate HashiCorp Vault for centralized secret management.
• Configure Tailscale Subnet Router for secure k9s access.
• Add the ELK Stack for advanced log analysis.

---

Made with ❤️ by Yurii Yevtushenko