# mightyshashank/ceph-devstack architecture

> Architecture diagram of the GitHub repository mightyshashank/ceph-devstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mightyshashank/ceph-devstack
- Repository: https://github.com/mightyshashank/ceph-devstack

## Overview

##### Project Purpose & Type
- This project is a command‐line tool written in Python to deploy and manage containerized services – such as teuthology and testnodes – for testing the Ceph distributed storage system locally. It uses nested rootless podman containers for container orchestration and supports configuration for container images and even (in proposed enhancements) multiple storage devices per testnode.

##### Analyzing the File Structure
- ceph_devstack/cli.py, which acts as the main command interface.
- ceph_devstack/exec.py and ceph_devstack/host.py that likely implement the execution engine and system interactions.
- ceph_devstack/config.toml, which forms the default configuration.
- A logging configuration file (logging.conf), requirements management (requirements.py), and type hints (py.typed).
- Within ceph_devstack, there’s also a “resources” subdirectory further defining components (see directory structure below):
- ceph_devstack/resources/
├── __init__.py
├── ceph/
│    ├── __init__.py
│    ├── containers.py
│    ├── requirements.py
├── container.py
├── misc.py
└── test/
├── test_container.py
└── test_podmanresource.py

##### Main Components & Their Directory Structure

- Client Interface / Command-line Entry Point:
- Represents ceph_devstack/cli.py.
- Example substructure:
[ceph_devstack]
├── cli.py
├── config.toml
└── logging.conf

- Core Application Engine:
- Contains the business logic modules:
[ceph_devstack]
├── exec.py
├── host.py
├── requirements.py
└── py.typed
- This node represents how the tool parses configurations, manages container lifecycle commands, and orchestrates test runs.

- Resources & Container Definitions:
- Captures the “resources” directory where container-specific definitions and support modules reside.
- Directory structure snippet:
[ceph_devstack/resources]
├── ceph/
│    ├── containers.py
│    └── requirements.py
├── container.py
├── misc.py
└── test/
├── test_container.py
└── test_podmanresource.py
- This node should indicate how container orchestration (for teuthology, testnodes, paddles, etc.) is defined.

- Configuration Management:
- Reflects the management and extension of default configurations.
- Config files:
- ceph_devstack/config.toml
- Additional config examples in ~/.config/ceph-devstack/config.yml (as referenced in the README)
- You could represent this as a node labeled “Configuration” containing:
[ceph_devstack]
├── config.toml

- Container Operations & Integration with Podman:
- Incorporates external interactions, such as the use of podman for image pulling, building container images (ceph_devstack/Dockerfile.selinux), and starting/stopping containers.
- Reference to the build script:
[build_selinux_module.sh]
- And note the Dockerfile inside ceph_devstack/:
[ceph_devstack/Dockerfile.selinux]

- Testing, Logging, and Management:
- Depicts features such as viewing container logs (e.g., teuthology.log from ~/.local/share/ceph-devstack) and running tests.
- In the node a reference to the test command feature (for instance, the new log-feature command described in the README/GSoC tasks).
- Optionally, add a subnode with:
[ceph_devstack/resources/test]
├── test_container.py
└── test_podmanresource.py

- CI/CD and Quality Assurance:
- Reflects continuous integration and code quality setup using:
- .flake8, .pre-commit-config.yaml, Jenkinsfile, .github/workflows/.
- Node structure:
[Project root]
├── .flake8
├── Jenkinsfile
├── .github/
│    └── workflows/
│         ├── ci.yml
│         └── tox.yml

- Documentation & Auxiliary Files:
- Captures the docs folder, README.md, and configuration for testing/building the project.
[docs]
└── cgroup_v2.md
[Project root]
├── README.md
├── pyproject.toml
├── pytest.ini
└── setup.cfg

##### Determining Relationships & Data Flow
- User inputs commands via the CLI which are handled by the Core Application Engine.
- The Engine reads from configuration (config.toml and user overrides) and then instructs container operations (via the Resources node).
- The Logging/Testing node collects outputs from running containers and offers commands to query logs.

##### Key Architectural Patterns & Technologies
- The tool applies a modular design that isolates the CLI, the core logic, and container orchestration aspects.
- It follows a layered approach, where configuration management, execution logic, and resource definitions are each in their own modules.
- Technologies: Python, Podman (using nested, rootless containers), SELinux (via build_selinux_module.sh and related Dockerfile), and continuous integration (GitHub Actions, Jenkins).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client Interface\n- ceph_devstack/cli.py\n- ceph_devstack/config.toml\n- ceph_devstack/logging.conf"]:::cli
    B["Core Application Engine\n- ceph_devstack/exec.py\n- ceph_devstack/host.py\n- ceph_devstack/requirements.py\n- ceph_devstack/py.typed"]:::core
    C["Configuration Management\n- ceph_devstack/config.toml\n(User override: ~/.config/ceph-devstack/config.yml)"]:::config
    D["Resources & Container Definitions\n[ceph_devstack/resources]\n├─ ceph/\n│   ├─ containers.py\n│   └─ requirements.py\n├─ container.py\n├─ misc.py\n└─ test/\n    ├─ test_container.py\n    └─ test_podmanresource.py"]:::res
    E["Container Operations & Integration\n- build_selinux_module.sh\n- ceph_devstack/Dockerfile.selinux"]:::ops
    F["Testing, Logging, and Management\n[ceph_devstack/resources/test]\n├─ test_container.py\n├─ test_podmanresource.py\nLogging: ceph_devstack/logging.conf"]:::test
    G["CI/CD and Quality Assurance\n- .flake8\n- Jenkinsfile\n- .pre-commit-config.yaml\n- .github/workflows/\n   ├─ ci.yml\n   └─ tox.yml"]:::ci
    H["Documentation & Auxiliary Files\n[docs]\n- cgroup_v2.md\n[Project Root]\n- README.md\n- pyproject.toml\n- pytest.ini\n- setup.cfg"]:::docs

    %% Relationships
    A -->|"command"| B
    B -->|"reads_config"| C
    B -->|"orchestrates"| D
    D -->|"invokes_podman_API"| E
    E -->|"outputs_logs"| F
    H -->|"guides"| A
    G -->|"CI_feedback"| F

    %% Click Events
    click A "https://github.com/mightyshashank/ceph-devstack/blob/main/ceph_devstack/cli.py"
    click B "https://github.com/mightyshashank/ceph-devstack/blob/main/ceph_devstack/exec.py"
    click C "https://github.com/mightyshashank/ceph-devstack/blob/main/ceph_devstack/config.toml"
    click D "https://github.com/mightyshashank/ceph-devstack/tree/main/ceph_devstack/resources/"
    click E "https://github.com/mightyshashank/ceph-devstack/blob/main/build_selinux_module.sh"
    click F "https://github.com/mightyshashank/ceph-devstack/tree/main/ceph_devstack/resources/test/"
    click G "https://github.com/mightyshashank/ceph-devstack/tree/main/.github/workflows/"
    click H "https://github.com/mightyshashank/ceph-devstack/tree/main/docs/"

    %% Styles
    classDef cli fill:#aee1f9,stroke:#333,stroke-width:2px;
    classDef core fill:#b7e1cd,stroke:#333,stroke-width:2px;
    classDef config fill:#e7f5d1,stroke:#333,stroke-width:2px;
    classDef res fill:#ffddad,stroke:#333,stroke-width:2px;
    classDef ops fill:#f9c0c0,stroke:#333,stroke-width:2px;
    classDef test fill:#fceabb,stroke:#333,stroke-width:2px;
    classDef ci fill:#d0e8f2,stroke:#333,stroke-width:2px;
    classDef docs fill:#e0d7ef,stroke:#333,stroke-width:2px;
```
