# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is **ceph-ansible** — Ansible playbooks, roles, and custom modules for deploying and managing Ceph clusters. The project is in maintenance mode; new deployments are encouraged to use `cephadm` instead. Supports Ceph releases from Dumpling (0.67) through Squid (19), with both containerized (Docker/Podman) and non-containerized deployment modes.

## Common Commands

### Linting
```bash
tox -e flake8
```
Max line length is 160 characters. Scans `./library`, `./module_utils/`, and `./tests/`.

### Unit Tests
```bash
cd tests && py.test library/ module_utils/
```

### Functional Tests (via Tox + Vagrant)
```bash
tox -e centos-container-all_daemons
tox -e ubuntu-non_container-all_daemons
tox -e rocky-container-lvm_osds
```
Pattern: `{os}-{container|non_container}-{scenario}`. See `tox.ini` for all ~100+ environments.

### RPM Building
```bash
make        # builds SRPMs
make rpm    # builds full RPMs
make clean
```

### After changing role defaults
```bash
./generate_group_vars_sample.sh
```
The `group_vars/` sample files are version-controlled and must be regenerated when `roles/ceph-defaults/defaults/main.yml` changes.

## Architecture

### Playbook Entry Points
- `site.yml` — primary orchestration playbook; imports roles in dependency order for all daemon types (mons → osds → mgrs → clients → rgws → mdss → nfs → rbdmirrors → monitoring)
- `infrastructure-playbooks/` — operational playbooks run independently: `purge-cluster.yml`, `rolling_update.yml`, `shrink-*.yml`, `add-*.yml`, `cephadm-adopt.yml`, etc.

### Role Dependency Chain
Most roles follow this pattern:
```
ceph-defaults → ceph-facts → ceph-handler → ceph-validate → ceph-common → ceph-config → <daemon-specific role>
```
`ceph-defaults` is the canonical source for all configurable variables — check there before adding new variables.

### Custom Modules (`library/`)
Python Ansible modules that wrap `ceph` CLI commands or the Ceph Python SDK:
- `ceph_key.py` — CephX authentication key management
- `ceph_pool.py` — pool create/modify/delete
- `ceph_crush.py` / `ceph_crush_rule.py` — CRUSH map management
- `ceph_ec_profile.py` — erasure coding profiles
- `ceph_fs.py` — CephFS filesystem management
- `ceph_config.py` — cluster config (`ceph config set/get`)
- `ceph_osd_flag.py` — OSD flags (noout, noscrub, etc.)
- `ceph_mgr_module.py` — mgr module enable/disable
- `ceph_volume.py` — OSD provisioning via `ceph-volume`
- `ceph_orch_apply.py` — cephadm orchestrator

All modules share common container-execution utilities in `module_utils/ca_common.py`, which handles wrapping commands with `docker exec` or `podman exec` when running in containerized mode.

### Filter Plugins (`plugins/filter/`)
- `dict2dict.py` — dict transformation
- `ipaddrs_in_ranges.py` — IP address filtering for network-aware config

### Variable Precedence
1. `group_vars/all.yml.sample` — user-facing documented defaults (generated from role defaults)
2. `roles/ceph-defaults/defaults/main.yml` — authoritative defaults
3. Host/group vars in inventory — user overrides

### Container vs. Non-Container
The boolean `containerized_deployment` variable (default: `false`) controls execution paths throughout roles and modules. When `true`, commands are prefixed with the container runtime and daemon container name. Both paths must be maintained in module code.

## Key Conventions

- **Commit format**: subject line (imperative mood) + blank line + body wrapped at 80 chars + `Signed-off-by:` line. Scope prefix encouraged (e.g., `ceph-osd: fix ...`). Reference issues with `Fixes: #XXXX`.
- **CI**: Jenkins runs on each PR. Add `[skip ci]` to PR title to bypass. Mergify handles merging (requires approval + CI pass).
- **Python style**: flake8, max 160 chars, no E501/W503.
- **Ansible collections required**: `ansible.utils`, `community.general`, `ansible.posix`, `openstack.ansible-config_template` — install with `ansible-galaxy collection install -r requirements.yml`.