# AGENTS.md

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

## Project Overview
*   **Tool**: [Kubespray](https://github.com/kubernetes-sigs/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**:
    ```bash
    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**:
        ```bash
        cd kubespray
        ansible-playbook -i inventory/prod/inventory.ini cluster.yml
        ```
    *   **Forced Upgrade**:
        ```bash
        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.