Installation

The installation is performed in two phases:

1. Infrastructure deployment with Ansible for gateway and K3s cluster setup
2. Applications deployment with ArgoCD following a GitOps approach

Prerequisites

Following tools need to be installed on the computer running the deployment:

• ansible - infrastructure as code software tools.
• age - simple, modern and secure encryption tool.
• helm - Kubernetes package manager.
• kubectl - Kubernetes command-line tool.
• sops - simple and flexible tool for managing secrets.
• sshpass - non-interactive ssh password auth.
• yq - portable command-line YAML, JSON, XML, CSV, TOML and properties processor.

# Clone the repository
git clone --depth 1 https://github.com/this-is-tobi/homelab.git && cd ./homelab && rm -rf ./.git

# Copy inventory example to inventory
cp -R ./ansible/inventory-example ./ansible/inventory

Notes:

PiHole and Wireguard installation can be ignored by setting enabled: false in gateway group_vars.

Settings

Infrastructure

Update the hosts file and group_vars files to provide the appropriate infrastructure settings.

To create admin access to the machines, it is required to provide their informations in the group_vars/all.yml file:

• Put user ssh public key in the inventory file, this will grant admin access to the infrastructure by adding authorized_keys.

Applications (GitOps)

Applications are managed via ArgoCD ApplicationSets. Configuration is done through:

1. Instance configuration - Enable/disable apps in JSON files:

   • Core services: ./argo-cd/core/instances/homelab/production.json
   • Platform services: ./argo-cd/platforms/instances/homelab/production.json

2. Values configuration - Customize app values in YAML files:

   • Core values: ./argo-cd/core/values/homelab/
   • Platform values: ./argo-cd/platforms/values/homelab/

Secrets Management

Sops is used to encrypt sensitive values. These secrets are managed (encrypted/decrypted) using the wrapper script run.sh following the keys provided in .sops.yaml.

Notes:

Update Sops keys with your own but leave the first age key blank as it is used by the cluster's automated key management system.

Decrypt secrets by running ./run.sh -d and encrypt secrets by running ./run.sh -e, do not forget to re-encrypt secrets when changes are made.

Notes:

During setup, every password, token and so on are randomly generated and stored into Vault secrets.

Deploy

Infrastructure

Deploy gateway and K3s cluster using the Ansible playbook:

# Update Ansible collections and deploy infrastructure
./run.sh -p ./ansible/install.yml -u -k

# Or with specific tags
./run.sh -p ./ansible/install.yml -t gateway   # Deploy gateway only
./run.sh -p ./ansible/install.yml -t k3s       # Deploy K3s cluster only

The -k flag fetches the kubeconfig from the master node and merges it into your local kubeconfig.

Applications (GitOps)

Once the infrastructure is ready, bootstrap ArgoCD and deploy services:

# Set kubectl context
kubectl config use-context homelab

# Bootstrap ArgoCD
./run.sh -b

# Apply core services (Longhorn, Vault, Cert-Manager, etc.)
./run.sh -c homelab

# Apply platform services (Keycloak, Gitea, Harbor, etc.)
./run.sh -s homelab

Notes:

Multiple tags can be passed as follows: ./run.sh -p ./ansible/install.yml -t gateway,k3s

First gateway init can take a long time to run because of OpenVPN key generation (5-10min).

Destroy

It is possible to cleanly destroy the K3s cluster by running:

# Destroy cluster
./run.sh -p ./ansible/install.yml -t k3s-destroy

Architecture

Core Services

Core services provide the foundation for the platform:

• Longhorn - storage management in the cluster.
• Ingress-NGINX - ingress controller to expose services.
• Cert-Manager - certificate management for TLS.
• Vault Operator - secret management for services deployments.
• ArgoCD - deployment management following GitOps.
• CloudNative-PG - PostgreSQL operator for databases.

Platform Services

Platform services are deployed on top of core services:

• Keycloak - identity and access management (SSO).
• Gitea - self-hosted Git service.
• Harbor - container registry.
• Mattermost - team communication.
• *And more...

GitOps Workflow

Services follow the GitOps workflow with ArgoCD ApplicationSets:

1. ApplicationSet reads instance configuration from JSON files
2. Application is created for each enabled service
3. Helm chart is deployed with values from the values directory
4. Vault provides secrets via Vault Secrets Operator (VSO)

The next step would be to deploy each platform environment to a dedicated cluster as described in the following schema.

Known issues

At the moment, mattermost and outline images are not arm64 compatible so their deployment are using custom mirror image with compatibility (see. this repo and associated ArgoCD applications).

The official Harbor helm chart cannot be used due to arm64 incompatibility, the Bitnami distribution is used instead.