ASP.NET Core Kubernetes Development Boilerplate

Note: Do not forget to uncomment config in .gitignore.

This repository provides a standardized development environment for ASP.NET Core applications integrated with PostgreSQL and Redis, orchestrated via Kubernetes (Kind). The architecture is designed to eliminate the need for local SDKs or toolchains; all dependencies, including the Kubernetes cluster itself, are managed through Docker.

• Runtime: .NET 8.0 (Razor Pages)
• Orchestration: Kubernetes 1.27.x via Kind (Kubernetes-in-Docker)
• Database: PostgreSQL 15 (Alpine)
• Caching: Redis (Alpine)
• Storage: Persistent volume mounting for live code synchronization
• Infrastructure GUIs: Adminer (PostgreSQL) and Redis Commander

• Docker Desktop (or Docker Engine on Linux)
• PowerShell (for Windows users) or Bash (for Linux/macOS users)

├── config/
│   ├── k8s-manifest.yaml    # Kubernetes resource definitions
│   └── kind-config.yaml     # Generated cluster configuration
├── scripts/
│   └── setup.sh             # Cluster provisioning and deployment script
├── Pages/                   # Application Razor Pages and Layouts
├── wwwroot/                 # Static assets (CSS, JS)
├── App.csproj               # Project dependencies
├── Dockerfile.app           # Production build definition
├── Dockerfile.installer     # Infrastructure toolchain container
└── Program.cs               # Application entry point and service configuration

To provision the cluster and deploy all services for the first time, execute the following commands. This process builds the installer toolchain and initializes the Kubernetes nodes.

# Build the infrastructure installer image
docker build -t k8s-installer -f Dockerfile.installer .

# Initialize the cluster and deploy services
docker run -d --name k8s-daemon `
  -v /var/run/docker.sock:/var/run/docker.sock `
  -v ${PWD}:/installer `
  -e HOST_PWD=${PWD} `
  --net host `
  k8s-installer bash scripts/setup.sh

The environment uses a live-mount strategy. Your local directory is synchronized with the Kubernetes pod, and the application uses dotnet watch to recompile on file change.

• Modify Code: Edit any .cs, .cshtml, or .css file in your IDE.
• Automatic Refresh: The pod detects the change via a polling file watcher and restarts the internal process.
• View Logs: Monitor the live compilation and application output:

  docker exec k8s-daemon kubectl logs -f -l app=webapp

Upon successful deployment, the following endpoints are available:

docker exec k8s-daemon kubectl get pods

If you modify config/k8s-manifest.yaml, apply the changes without restarting the daemon:

docker exec k8s-daemon kubectl apply -f config/k8s-manifest.yaml

To destroy the cluster and delete all persistent data:

# Terminate the daemon and the cluster node
docker rm -f k8s-daemon
docker rm -f my-cluster-control-plane

# Clean up local build artifacts
Remove-Item -Recurse -Force bin, obj, config/kubeconfig.yaml

• Cache Busting: Automatic CSS/JS versioning via asp-append-version tag helpers.
• Resilience: Automatic database migration and connection retry logic on startup.
• High Availability: The WebApp deployment can be configured for N replicas behind a Kubernetes Service load balancer.
• Persistent Storage: Data for PostgreSQL and Redis is stored in the ./data directory on the host machine. This ensures data survives cluster restarts or daemon termination.
• Redis Durability: Configured with Append Only File (AOF) mode, ensuring high data durability by logging every write operation to the persistent volume.
• Hot Reloading: Integrated dotnet watch with polling enabled, allowing near-instant application updates across host-to-container volume boundaries.
• Stateful Development: Database migrations are applied automatically, but the underlying data remains intact between development sessions.

Because the system uses persistent storage, a standard cluster reset will not wipe your data. To start with a completely empty database:

1. Stop the daemon: docker rm -f k8s-daemon my-cluster-control-plane
2. Manually delete the contents of the ./data folder in your project directory.
3. Restart the daemon using the initialization command.