infrapuzzle/bootstrap/AGENTS.md

AGENTS.md

[!NOTE] This directory handles the bootstrapping and provisioning of the Haumdaucher Kubernetes cluster using Kubespray.

Project Overview

• Tool: Kubespray (Ansible-based).
• Method: The local inventory/ is the source of truth, which is synced into a checked-out Kubespray repository.
• Idempotency: The process is designed to be repeatable. The kubespray folder is treated as ephemeral and is re-created by init.sh.

Workflow & Scripts

The core workflow is encapsulated in init.sh.

init.sh

Purpose: Prepares the environment and Kubespray for deployment. Actions:

1. Clean Slate: Deletes existing kubespray/ directory.
2. Clone: Clones Kubespray (version defined in variable VERSION, e.g., release-2.27).
3. Environment: Sets up Python virtualenv via pyenv and installs requirements.txt.
4. Sync: Copies local ./inventory/ configurations into ./kubespray/inventory/.

Usage

1. Source the script:

   source init.sh
   

2. Deploy / Upgrade: After sourcing, go to the kubespray directory and run the Ansible playbooks as instructed by the script output.
   • Standard Run:

     cd kubespray
     ansible-playbook -i inventory/prod/inventory.ini cluster.yml
     

   • Forced Upgrade:

     cd kubespray
     ansible-playbook -i inventory/prod/inventory.ini -e upgrade_cluster_setup=true cluster.yml
     

Directory Structure

• init.sh: The entry point script. Source of truth for Kubespray version.
• inventory/: Contains cluster inventory configurations (hosts, variables). Edit this, not the one in kubespray/.
• kubespray/: (Ignored/Ephemeral) The checked-out Kubespray repository. Do not edit files here directly; they will be overwritten.

Configuration Updates

To upgrade Kubespray or change cluster config:

1. Version Upgrade: Update VERSION in init.sh (e.g., to release-2.28).
2. Config Changes: Modify files in ./inventory/.
3. Apply: Run source init.sh then execute the Ansible playbook.