49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# 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. |