https://github.com/idvoretskyi/linode-kubernetes-cluster
Simple, clean OpenTofu template for deploying cost-effective Kubernetes clusters on Linode (LKE) with optional monitoring stack
https://github.com/idvoretskyi/linode-kubernetes-cluster
Last synced: 4 months ago
JSON representation
Simple, clean OpenTofu template for deploying cost-effective Kubernetes clusters on Linode (LKE) with optional monitoring stack
- Host: GitHub
- URL: https://github.com/idvoretskyi/linode-kubernetes-cluster
- Owner: idvoretskyi
- License: mit
- Created: 2025-08-27T11:48:36.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T10:55:23.000Z (5 months ago)
- Last Synced: 2026-01-13T13:44:43.122Z (5 months ago)
- Language: HCL
- Homepage: https://github.com/idvoretskyi/linode-kubernetes-cluster
- Size: 78.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Linode Kubernetes Cluster
A simple, clean OpenTofu template for deploying Kubernetes clusters on Linode (LKE) with optional monitoring.
## Features
- **Simple & Clean**: Flat structure with direct OpenTofu commands
- **Cost Optimized**: Start with ~$24/month for a single-node cluster
- **Secure**: Built-in firewall rules and network policies
- **Production Ready**: Autoscaling, HA control plane options
- **Monitoring Included**: Optional Prometheus, Grafana, and metrics-server
## Prerequisites
- [OpenTofu](https://opentofu.org/) or Terraform 1.6+
- kubectl
- Linode API token
- [Linode CLI](https://www.linode.com/docs/products/tools/cli/get-started/) (optional)
## Quick Start
### 1. Get Your Linode Token
```bash
# Option 1: Configure linode-cli (recommended)
linode-cli configure
# Option 2: Set environment variable
export LINODE_TOKEN='your-token-here'
```
### 2. Configure Your Cluster
```bash
cd infrastructure
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your preferences
```
### 3. Deploy
```bash
cd infrastructure
# Initialize
tofu init
# Review the plan
tofu plan
# Deploy cluster with monitoring
tofu apply
```
### 4. Connect to Your Cluster
```bash
# Extract kubeconfig
tofu output -raw kubeconfig | base64 -d > kubeconfig.yaml
# Set environment variable
export KUBECONFIG=./kubeconfig.yaml
# Test connection
kubectl cluster-info
kubectl get nodes
```
## Monitoring Stack
The template includes an optional monitoring module that deploys:
- **kube-prometheus-stack**: Prometheus + Grafana + Alertmanager + Node Exporter + Kube State Metrics
- **metrics-server**: For `kubectl top` commands and HPA
### Access Grafana
After deployment completes (4-5 minutes), access Grafana:
```bash
# Get any node's IP address
kubectl get nodes -o wide
# Access Grafana via NodePort
# URL: http://:30300
# Default credentials: admin / admin
```
Or use port-forwarding:
```bash
kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80
# Open http://localhost:3000
```
### Monitoring Configuration
Control monitoring via `terraform.tfvars`:
```hcl
# Enable/disable monitoring components
monitoring_enable_prometheus_stack = true
monitoring_enable_metrics_server = true
# Grafana settings
monitoring_grafana_service_type = "NodePort" # or "ClusterIP", "LoadBalancer"
monitoring_grafana_nodeport = 30300
monitoring_grafana_admin_password = "admin" # Change for production!
# metrics-server settings
monitoring_metrics_server_insecure_tls = true # Set false for production
```
Get monitoring information:
```bash
tofu output monitoring_namespace
tofu output monitoring_grafana_nodeport
tofu output monitoring_components
tofu output -raw monitoring_access_instructions
```
## Configuration
All configuration is done through [infrastructure/terraform.tfvars](infrastructure/terraform.tfvars.example).
### Basic Settings
```hcl
project_name = "my-project"
environment = "dev"
cluster_name = "my-cluster"
region = "us-east"
k8s_version = "1.34"
```
### Node Pools
```hcl
node_pools = [
{
type = "g6-standard-1" # ~$24/month per node
count = 3
autoscaler = {
min = 1
max = 3
}
}
]
```
**Available Node Types:**
- `g6-standard-1`: 1 vCPU, 2GB RAM (~$24/month) - Dev/testing
- `g6-standard-2`: 2 vCPU, 4GB RAM (~$36/month) - Small production
- `g6-standard-4`: 4 vCPU, 8GB RAM (~$72/month) - Production
### High Availability
```hcl
control_plane_ha = true # Adds ~$60/month for HA control plane
```
### Firewall
```hcl
firewall_enabled = true
firewall_allowed_ips = ["your.ip.address/32"] # Restrict access
firewall_inbound_policy = "DROP"
```
## Cost Estimate
| Configuration | Monthly Cost |
|--------------|--------------|
| Dev (1 node, g6-standard-1) | ~$24 |
| Small Prod (2 nodes, g6-standard-2) | ~$72 |
| Prod HA (3 nodes, g6-standard-2, HA control plane) | ~$168 |
*LKE control plane (non-HA) is free. Prices subject to change.*
## Commands
```bash
# Initialize and deploy
tofu init
tofu plan
tofu apply
# Get outputs
tofu output
tofu output -raw kubeconfig | base64 -d > kubeconfig.yaml
# Destroy
tofu destroy
```
## Project Structure
```
.
├── README.md
├── CLAUDE.md # Claude Code instructions
├── LICENSE
├── infrastructure/
│ ├── main.tf # Main infrastructure
│ ├── variables.tf # Variable definitions
│ ├── outputs.tf # Output definitions
│ ├── terraform.tfvars.example # Example configuration
│ └── modules/
│ └── monitoring/ # Optional monitoring module
│ ├── main.tf
│ ├── variables.tf
│ └── outputs.tf
└── docs/ # Additional documentation
```
**Design Philosophy:**
- Simple, flat structure with minimal nesting
- Direct OpenTofu commands - no Makefile needed
- Single tfvars.example file
- Optional monitoring module for observability
## Security Notes
1. **Restrict firewall access**: Change `firewall_allowed_ips` from `0.0.0.0/0` to your IP
2. **Token security**: Never commit `LINODE_TOKEN` or `terraform.tfvars` to git
3. **State file**: Contains sensitive data - store securely (consider remote state)
4. **Grafana password**: Change `monitoring_grafana_admin_password` for production
5. **metrics-server TLS**: Set `monitoring_metrics_server_insecure_tls = false` for production
## Documentation
- [Architecture](docs/architecture/) - Design decisions and cluster architecture
- [Cost Analysis](docs/cost/) - Detailed cost breakdown
- [Operations](docs/runbooks/) - Management and troubleshooting
- [Examples](docs/examples/) - Sample workloads
## License
MIT