micro-cloud

micro-cloud is a self-hosted home infrastructure organized into trust zones, designed to test and validate cloud-native solutions in a real-world environment.

This project supports a technical article series on Kubernetes, Proxmox, MicroCloud, OpenStack, and more.

Objectives

• Design a modular and secure cloud platform
• Separate a stable management zone (ring0) from an experimental hosting zone (ring1)
• Test orchestration, virtualization, containerization, and access control solutions

C4Context
title Micro Cloud 2-ring principle


System_Ext(mesh, "Tailscale Mesh VPN", "Network Mesh VPN / SDN.")
Person(admin, "Micro Cloud Administrator", "You")
Enterprise_Boundary(mdc, "Micro Cloud") {
    System(ring0, "Undercloud - Management<br>Ring0")
    System(ring1, "Cloud<br>Ring1")
}

Rel(ring0, ring1, "Creates<br>and manages")
Rel(ring0, mesh, "Is connected")
Rel(ring1, mesh, "Is connected")
Rel(admin, mesh, "Is connected")

UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")

Loading

C4Context
title Micro Cloud 2-ring principle

System_Ext(mesh, "Tailscale Mesh VPN", "Network Mesh VPN / SDN.")
Person(admin, "Micro Cloud Administrator", "You")

Enterprise_Boundary(mdc, "Micro Cloud") {

    System_Boundary(ring0, "Ring 0 - Management") {
        System(pki, "PKI", "Certificates management")
        System(bootstrap, "Bootstrap", "Pets deployment")
        System(id, "ID Provider", "Managing people")
        System(deployment, "Platform deployer", "Managing Ring 1 resources", "Bare Metal as a Service")
        System(dcim, "CMDB", "Managing resources", "DCIM, IPAM")
    }

    System_Boundary(ring1, "Ring 1 - Workload Hosting") {
        System(cluster, "Cluster", "A system used to <br>host business workloads.")
    }
}

Rel(deployment, cluster, "Installs the machines")

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Loading

Repository Structure

micro-cloud/
├── ring0/         # Low dependency services and core infrastructure (PKI, Netboot, Management)
│   ├── core-services/   # Manifests and templates for ring0 Kubernetes workloads
│   ├── flux/            # FluxCD Operator manifests (HelmRepositories, HelmReleases, Kustomizations)
│   └── scripts/         # Bootstrap and day-2 shell scripts
├── ring1/         # Experimental environments (Kubernetes clusters, etc.)
├── docs/          # Schematics, documentation, examples
├── .github/       # GitHub Actions workflows (OCI artifact release + GitHub Release)
├── cliff.toml     # git-cliff config (changelog generation)
├── renovate.json  # Renovate config (automated dependency updates)
├── CHANGELOG.md   # Keep a Changelog, generated from Conventional Commits
├── RELEASING.md   # Release process
├── LICENSE        # Project license (Apache 2.0)
└── README.md      # This file

Physical Architecture

The project relies on a home server rack composed of:

• 1x Deskpi RackMate T2
• 1x Ubiquity Gateway (NAT, SDN, VPN)
• 1x Ubiquity Flex 2.5G Switch
• 1x NUCBox G5 N97 for ring0 (management services)
• 1x NUCBox G5 N97 for ring1 (hosting environments)
• 4x NUCBox G3 Plus for ring1 (hosting environments)

Technology Stack

• Network / VPN: Tailscale
• Containerization: Incus (LXC / KVM)
• PKI: cfssl, cert-manager, OpenBao
• Bootstrapping: kea, matchbox, Talos
• GitOps: FluxCD Operator (OCI artifact releases via GitHub Actions)
• Orchestration: Kubernetes, Kamaji, Tinkerbell, Cluster API
• Middleware: Netbox, Authentik, External Secrets Operator, Zot

Releases

Releases follow Conventional Commits + Semantic Versioning, with a Keep a Changelog CHANGELOG.md generated by git-cliff. Pushing a signed vX.Y.Z tag publishes the ring0 Flux manifests as an OCI artifact and creates the matching GitHub Release. See RELEASING.md for the full process.

Dependencies (Flux Helm charts, container images in manifests, GitHub Actions, pre-commit hooks and a few version pins in the bootstrap scripts) are kept up to date by Renovate (renovate.json).

Getting Started

1. Initialize the headnode (ring0)

On the physical machine with KVM access:

wget https://raw.githubusercontent.com/mgrzybek/micro-cloud/refs/heads/main/ring0/scripts/init-headnode.sh
chmod +x init-headnode.sh
./init-headnode.sh

2. Register the headnode as an Incus remote

From your workstation:

incus remote add headnode-0 headnode-0
incus remote switch headnode-0

3. Bootstrap sequence

Refer to ring0/README.md for the full step-by-step sequence.

Contributions

Contributions are welcome: bug fixes, documentation, extensions to other rings or orchestration tools.

License

This project is licensed under Apache 2.0.