Skip to content

Infrastructure overview

Platform layout

Mintfit uses two Kubernetes environments with different responsibilities:

Environment Role Access model
Mintfit management cluster Runs Rancher and management services Managed through the management kubeconfig/context
Mintfit workload cluster Runs the user-facing platform services Registered and administered by Rancher

The workload cluster is an RKE2 cluster. The management environment provides the Rancher control plane used to register and operate it. Cluster membership and node roles are therefore managed by Rancher and reflected into the Ansible inventory through Kubernetes.

Network path

Operators normally connect through the shared mintfit-jump bastion. Ansible uses the node's private address and a ProxyJump in local mode. Automation running inside the cluster uses the private network directly by selecting the cluster network location.

The intended paths are:

operator workstation
        │
        └── SSH ──> mintfit-jump ──> private node address

in-cluster automation ────────────> private node address

The public ingress path is handled by Traefik, the bundled RKE2 ingress controller. TLS certificates are issued by cert-manager. Public hostnames are routed to the relevant service through Kubernetes Ingress resources.

Node and storage roles

Ansible discovers nodes dynamically from the configured Kubernetes contexts. Each node carries its private address, public address (when available), Kubernetes version, cluster, and detected role. The main groups are:

all
├── bastion
├── cluster_nodes
│   ├── mintfit_cluster_01
│   │   ├── mintfit_cluster_01_controlplane
│   │   └── mintfit_cluster_01_worker
│   └── mintfit_mgmt
└── manual

The workload cluster includes Hetzner Robot bare-metal workers. Those nodes attach to the private vSwitch through VLAN 4000 and use MTU 1400. Longhorn uses a dedicated data disk on workers; disk identity is pinned by hardware serial rather than by an unstable /dev/nvme* name.

Calico supplies the pod network. The vSwitch MTU and Calico MTU must remain compatible; an MTU mismatch can produce silent pod-network packet loss.

Platform services

The cluster repositories deploy services independently through Fleet or their service-specific manifests. The current platform includes:

  • Rancher for cluster lifecycle and registration.
  • RKE2 for the workload Kubernetes distribution.
  • Traefik for ingress and cert-manager for TLS certificates.
  • Longhorn for persistent volumes and node-local data disks.
  • GitLab, its container registry, and supporting object storage.
  • Keycloak for identity and OIDC integrations.
  • Semaphore UI for in-cluster Ansible execution.

Service-specific deployment details belong in the owning repository. This site documents the relationships that matter when operating the underlying nodes and network.

Source repositories

The source of truth is split by responsibility:

Area Repository or path Purpose
Node automation infrastructure/ansbile Inventory, playbooks, roles, and node profiles
Cluster services cluster/services/* Service deployments and Helm values
Keycloak cluster/keycloak Identity service manifests and operations
GitLab cluster/services/gitlab GitLab chart configuration and supporting services

The spelling of the Ansible project path (ansbile) is retained for compatibility with the existing GitLab project.

Operating principles

  1. Use Rancher as the source of truth for Kubernetes membership.
  2. Use Ansible for repeatable host preparation and maintenance.
  3. Scope disruptive playbooks with --limit and use --check --diff first.
  4. Treat private keys, kubeconfigs, Rancher tokens, and service secrets as external configuration; they do not belong in this documentation project.
  5. Refresh the dynamic inventory after a node joins or leaves a cluster.