ansible-ceph/CLAUDE.md

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

tox -e flake8

Max line length is 160 characters. Scans ./library, ./module_utils/, and ./tests/.

Unit Tests

cd tests && py.test library/ module_utils/

Functional Tests (via Tox + Vagrant)

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

make        # builds SRPMs
make rpm    # builds full RPMs
make clean

After changing role defaults

./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.