89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
# 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`.
|