Skip to content

fleet

Metadata

Field Value
Service fleet
Purpose Bootstrap and reconcile cluster workloads from the GitOps repository into all managed clusters
Criticality Tier 0
Owner Platform / GitOps owner
Clusters homelab, local, jls, ozirke01 via the ozilab GitRepo
Namespace fleet-default for all clusters
Exposure Internal admin workflows through Rancher and kubectl
Stateful no
Backup class Git-backed; cluster backup only for controller state
RPO / RTO Git state authoritative, 30 to 60 minutes to recreate bootstrap and re-establish reconciliation
Last reviewed 2026-04-22

1. Service Overview

Fleet is the primary GitOps bootstrap layer for this repository. Each cluster receives a dedicated GitRepo custom resource that points at explicit application overlay paths on the main branch. If Fleet is unhealthy, the platform loses its standard deployment and reconciliation path.

Summary

Fleet turns repository state into per-cluster bundles and applies them to homelab, local, jls, and the ozilab downstream cluster. The bootstrap manifests live in the fleet directory and are intentionally applied once with kubectl instead of being managed by another GitRepo.

Dependencies

Dependency Type Why it matters
Rancher and Fleet CRDs control plane GitRepo objects only reconcile when Rancher Fleet is running and the CRDs are healthy
gitrepo-auth secret secret Fleet uses this secret to authenticate to the Git repository
Git repository on git.mutana.fr source All workloads are sourced from the main branch of the repository
Registered downstream clusters runtime target GitRepo targets must match cluster names visible in Fleet

2. Architecture Diagram

[Git main branch]
  -> [GitRepo bootstrap manifests in fleet/*/gitrepo.yaml]
  -> [Fleet controller in Rancher]
  -> [Bundles and BundleDeployments]
  -> [Target clusters: homelab, local, jls]
  -> [Per-service overlays and Helm bundles]

The important split is namespace-based:

  • fleet-default hosts all GitRepo objects for all downstream clusters (homelab, local, jls, ozirke01).

3. Deployment Specifications

Item Value
Source path fleet/layer7/gitrepo-main.yaml, fleet/layer7/gitrepo-ozilab.yaml
Deployment model Raw bootstrap manifests applied with kubectl
Namespace fleet-default for all clusters
Workload kind GitRepo custom resources
Chart or image version Controller lifecycle is owned by Rancher Fleet, not by this repository
Config files gitrepo.yaml, optional git-auth-secret.yaml placeholders

Cluster mapping

Cluster Bootstrap path Notes
homelab fleet/layer7/gitrepo-main.yaml Targeted by clusterName homelab in the main GitRepo in namespace fleet-default
local fleet/layer7/gitrepo-main.yaml Targeted by clusterName local; merges former layer7, oci, and oci-free nodes into one k3s cluster
jls fleet/layer7/gitrepo-main.yaml Targeted by clusterName jls in the main GitRepo
ozirke01 fleet/layer7/gitrepo-ozilab.yaml Uses fleet-default from the management cluster, tracks branch dev, and currently deploys traefik plus tailscale-operator to ozilab

4. Configuration Guide

Fleet bootstrap is configured per GitRepo resource rather than with a shared ConfigMap.

Environment variables

Variable Source Purpose Secret?
N/A N/A GitRepo resources store configuration in spec fields instead of container env vars in this repository no

ConfigMaps

Resource Path Purpose
None in this repository N/A Fleet bootstrap is defined directly in GitRepo manifests

Secrets management

  • Secret names: gitrepo-auth
  • Source of truth: manually created gitrepo-auth secret in fleet-default before applying the GitRepo objects
  • Rotation trigger: rotate when Git credentials change or access to git.mutana.fr is revoked
  • Recovery note: if the secret is missing or invalid, GitRepo objects remain unhealthy even though their manifests still exist in Git

Important GitRepo settings shared across clusters:

  • most GitRepo resources point at https://git.mutana.fr/kardudu/k8s.git on branch main
  • the ozilab GitRepo is an explicit exception and currently points at https://github.com/arnaudmut/k8s.git on branch dev
  • correctDrift is disabled in the bootstrap manifests currently committed
  • pollingInterval is 3 minutes for most clusters and 60 seconds for ozilab

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Kubernetes API access to GitRepo, Bundle, and BundleDeployment resources Operators kubeconfig and cluster RBAC Kubernetes API server
External Rancher Continuous Delivery interface for Git Repos and Bundles Platform operators Rancher authentication Rancher ingress

6. Operations and Observability

  • Primary health indicators: GitRepo Ready state, Bundle counts, BundleDeployment status, and absence of authentication or path errors in GitRepo conditions.
  • Dashboards or alerts: Rancher Continuous Delivery views plus controller logs in the Fleet controller namespace.
  • Log locations: Fleet controller logs and GitRepo object status conditions.
  • Known failure modes: invalid gitrepo-auth or clientSecretName reference, wrong target cluster name, path pointing to a missing overlay, wrong branch or repository for a special bootstrap like ozilab, or bundle generation failures after repository layout changes.

7. Backup and Recovery Notes

  • Backup method: Git is the source of truth for GitRepo manifests.
  • Restore prerequisites: Rancher Fleet must be installed, downstream clusters must be registered, and gitrepo-auth must exist in the correct namespace.
  • Related runbook: ../runbooks/fleet.md

8. Release and Change Notes

  • Current deployed app version: Rancher Fleet controller lifecycle is external to this repository.
  • Current chart version: N/A in this repository.
  • Last significant change: consolidated the per-cluster GitRepo bootstrap (former homelab, layer7, oci, oci-free, jls) into a single gitrepo-main.yaml targeting homelab, local, and jls; the unified local cluster merges the former layer7, oci, and oci-free nodes into one k3s cluster with flannel WireGuard backend; ozilab bootstrap split into its own GitRepo on branch dev and switched from cloudflared to tailscale-operator plus Traefik.
  • Rollback reference: reapply the previous GitRepo manifest revision and restore the previous gitrepo-auth secret if credentials changed.