OKE Homelab

Production-grade Kubernetes cluster running entirely free on OCI Always Free tier — GitOps with ArgoCD, Istio, Vault and Terraform.

Overview

This repository contains the complete infrastructure and application stack for a personal Kubernetes cluster, following GitOps principles with Argo CD. Everything is managed as code — from the underlying OCI infrastructure (Terraform) to the Kubernetes applications (Helm), including secrets management (Vault), SSO (VoidAuth) and distributed storage (Longhorn).

Fork it, set your domain once in gitops/global-values.yaml, populate your own Vault, and run the whole stack on your own OCI tenancy.

Stack

Component	Description
Kubernetes (OKE)	Managed Kubernetes on OCI Always Free tier
Terraform	Infrastructure provisioning (OKE, VCN, budgets)
Argo CD	GitOps continuous delivery
Istio	Service mesh and ingress gateway
HashiCorp Vault	Secrets management with OCI KMS auto-unseal
External Secrets	Sync Vault secrets to Kubernetes
Cert Manager	Automatic TLS certificates via Let's Encrypt
ExternalDNS	Automatic DNS records in Cloudflare
Tailscale Operator	Private access to cluster Services over the tailnet
Longhorn	Distributed block storage
CloudNativePG	PostgreSQL operator
PostgreSQL	PostgreSQL cluster
VoidAuth	Identity and Access Management (SSO)
Vaultwarden	Self-hosted password manager
N8N	Workflow automation
Actual Budget	Local-first personal finance app
Metrics Server	Resource metrics for HPA and kubectl top
Prometheus	Metrics collection with Grafana dashboards

Structure

.
├── terraform/          # OCI infrastructure (OKE, VCN, networking, budgets)
├── gitops/
│   ├── bootstrap/      # ArgoCD install and App of Apps
│   ├── apps/           # ArgoCD Application manifests
│   └── config/         # Helm values and manifests per app
└── scripts/            # Vault bootstrap and helper scripts

Quick Start

Prerequisites

• Terraform >= 1.15
• OCI CLI configured
• kubectl
• Helm >= 3.10
• ArgoCD CLI (optional)

1. Infrastructure Setup

# Clone the repository
git clone https://github.com/guarnz/oke-homelab.git
cd oke-homelab

# Configure OCI credentials
oci setup config

# Create Terraform state bucket
oci os bucket create --name terraform-states --versioning Enabled --compartment-id <your-compartment-id>

# Deploy infrastructure
cd terraform
cp terraform.tfvars.example terraform.tfvars    # Edit with your values

# Optional: configure remote state on OCI Object Storage
cp backend.hcl.example backend.hcl              # Edit with your OCI namespace and region
terraform init -backend-config=backend.hcl      # Or just: terraform init (uses local state)
terraform plan
terraform apply

2. Access the Cluster

# Kubeconfig is generated automatically by Terraform
export KUBECONFIG=$(pwd)/.kube.config
kubectl get nodes

3. Configuration

Update the following to match your environment before proceeding.

Domain — set it once; every app reads it from the shared file and builds its own hostname (<subdomain>.<domain>):

# gitops/global-values.yaml
global:
  domain: your-domain.com
  email: admin@your-domain.com
  issuer: letsencrypt-dns01

Repository — the ArgoCD Applications point back at this repo. The bootstrap script detects your fork from git origin and repoints them automatically, then prompts you to commit — so you only need to push the rewritten manifests before the first sync. (Running from a tarball instead of a clone? Set REPO_URL=https://github.com/<your-user>/<your-repo> when you run it.)

• DNS zone — make sure your domain zone exists in Cloudflare before deploying (External DNS will manage records automatically)
• Vault KMS — update key_id, crypto_endpoint and management_endpoint in gitops/config/vault/values.yaml with your OCI KMS values
• Secrets — populate Vault with the required keys for each app (see each app's README). Where a key holds a public URL, it must match your domain.

4. Install ArgoCD

Run the bootstrap script:

bash scripts/argocd-bootstrap.sh

Or manually (make sure the repoURL in every Application under gitops/ already points at your fork before applying):

helm repo add argo https://argoproj.github.io/argo-helm
helm upgrade --install argocd argo/argo-cd -n argocd --create-namespace \
  -f gitops/bootstrap/argocd/values.yaml --wait

# Apply the App of Apps and the self-managed ArgoCD Application
kubectl apply -f gitops/bootstrap/apps-of-apps.yaml
kubectl apply -f gitops/bootstrap/argocd/application.yaml

5. Install Vault

Run the bootstrap script:

bash scripts/vault-bootstrap.sh

Or manually:

# Initialize Vault (first time only) — save vault-init.json securely, do NOT commit it
kubectl exec -n security vault-0 -- vault operator init \
  -recovery-shares=5 \
  -recovery-threshold=3 \
  -format=json > vault-init.json

# Enable secrets engine and Kubernetes auth
kubectl exec -n security vault-0 -- vault secrets enable -path=secret kv-v2
kubectl exec -n security vault-0 -- vault auth enable kubernetes
kubectl exec -n security vault-0 -- vault write auth/kubernetes/config \
  kubernetes_host="https://kubernetes.default.svc"

# Populate secrets for each app
kubectl exec -n security vault-0 -- vault kv put secret/vaultwarden ADMIN_TOKEN='...'
# See each app README for required secret keys

6. Private Git Repositories (optional)

If any ArgoCD Application points to a private repository, register credentials in Vault at secret/argocd-repo. The ExternalSecret in gitops/bootstrap/argocd/manifests/external-secret.yaml renders a repo-creds-typed Secret that ArgoCD picks up automatically for every repo URL matching the stored prefix.

Required keys in secret/argocd-repo:

Key	Value
type	git
url	URL prefix that matches every private repo (e.g. https://github.com/<user>)
username	Git username
password	Personal Access Token with repo scope

kubectl exec -n security vault-0 -- vault kv put secret/argocd-repo \
  type=git \
  url=https://github.com/<user> \
  username=<user> \
  password=<github-pat>

Contributing

Contributions are welcome. Open an issue using one of the issue templates to report a bug or request a feature, and send pull requests following the pull request template — fill in What/Why, tick the change type, and make sure pre-commit run --all-files passes with no secrets committed.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Oracle Cloud Free Tier
• ArgoCD
• Istio
• HashiCorp Vault
• All the amazing open-source projects that make this possible