# ceph/go-ceph architecture

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

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

## Overview

##### Project type and purpose
- This is a Go-based library (go-ceph) that provides native Go bindings to Ceph’s C APIs (librados, librbd, libcephfs) and to the RADOSGW admin REST API.
- It is not an application with a frontend/backend split, but a modular SDK used by other Go projects to interact with a Ceph cluster.

##### File structure
- Top-level sub-packages:
- cephfs/           – Go bindings for CephFS
- rados/            – Go bindings for librados (cluster I/O)
- rbd/              – Go bindings for librbd (block device)
- rgw/admin/        – Go client for RADOSGW admin operations (HTTP-REST)
- Cross-cutting “support” packages:
- common/           – shared admin interfaces, command abstractions, logging
- internal/         – cgo helpers (cutil, dlsym), error utilities, callbacks, retry logic, tracing
- Other directories:
- testing/containers/ – Dockerfiles for integration tests
- docs/, .github/, Makefile – CI, docs, release process, formatting, test scripts

##### README for additional insights
- Confirms use of cgo to bridge Go ↔ C.
- Describes build-tags for different Ceph releases (pacific, quincy, etc.).
- Notes that the library dynamically links against Ceph system libraries at runtime.
- Describes integration tests via Docker.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    ClientApp["Client Application"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        radosPkg["rados"]:::api
        rbdPkg["rbd"]:::api
        cephfsPkg["cephfs"]:::api
        rgwAdminPkg["rgw/admin"]:::api
    end

    %% Support Layer
    subgraph "Support Layer"
        commonPkg["common"]:::support
        subgraph "internal"
            internalPkg["internal"]:::support
            cutil["cutil"]:::support
            dlsym["dlsym"]:::support
            errutil["errutil"]:::support
            callbacks["callbacks"]:::support
            retry["retry"]:::support
        end
    end

    %% CGO Boundary
    cgoLayer(("CGO Layer")):::cgo

    %% Native C Libraries
    subgraph "Native C Libraries"
        libradosC["librados"]:::clib
        librbdC["librbd"]:::clib
        libcephfsC["libcephfs"]:::clib
        rgwCAPI["RADOSGW C API"]:::clib
    end

    %% Ceph Cluster
    subgraph "Ceph Cluster"
        MON["MON"]:::external
        OSD["OSD"]:::external
        MGR["MGR"]:::external
        RGW["RADOSGW Gateway"]:::external
    end

    %% Testing Environment
    TestContainer["Docker Test Container"]:::test

    %% Dependencies
    ClientApp -->|imports| radosPkg
    ClientApp -->|imports| rbdPkg
    ClientApp -->|imports| cephfsPkg
    ClientApp -->|imports| rgwAdminPkg

    radosPkg -->|uses| commonPkg
    rbdPkg -->|uses| commonPkg
    cephfsPkg -->|uses| commonPkg
    rgwAdminPkg -->|uses| commonPkg

    commonPkg -->|invokes| internalPkg
    internalPkg -->|calls| cutil
    internalPkg -->|calls| dlsym
    internalPkg -->|calls| errutil
    internalPkg -->|calls| callbacks
    internalPkg -->|calls| retry

    commonPkg -->|calls via cgo| cgoLayer
    internalPkg -->|calls via cgo| cgoLayer

    cgoLayer -->|cgo call| libradosC
    cgoLayer -->|cgo call| librbdC
    cgoLayer -->|cgo call| libcephfsC
    cgoLayer -->|cgo call| rgwCAPI

    libradosC -->|librados protocol| MON
    libradosC -->|librados protocol| OSD
    libradosC -->|librados protocol| MGR

    librbdC -->|block ops| OSD
    libcephfsC -->|fs ops| MGR
    rgwCAPI -->|HTTP REST| RGW

    rgwAdminPkg -->|HTTP REST| RGW

    TestContainer -->|orchestrates| MON
    TestContainer -->|orchestrates| OSD
    TestContainer -->|runs go tests against| radosPkg
    TestContainer -->|runs go tests against| rbdPkg
    TestContainer -->|runs go tests against| cephfsPkg
    TestContainer -->|runs go tests against| rgwAdminPkg

    %% Click Events
    click radosPkg "https://github.com/ceph/go-ceph/tree/master/rados/"
    click rbdPkg "https://github.com/ceph/go-ceph/tree/master/rbd/"
    click cephfsPkg "https://github.com/ceph/go-ceph/tree/master/cephfs/"
    click rgwAdminPkg "https://github.com/ceph/go-ceph/tree/master/rgw/admin/"
    click commonPkg "https://github.com/ceph/go-ceph/tree/master/common/"
    click internalPkg "https://github.com/ceph/go-ceph/tree/master/internal/"
    click cutil "https://github.com/ceph/go-ceph/tree/master/internal/cutil/"
    click dlsym "https://github.com/ceph/go-ceph/tree/master/internal/dlsym/"
    click errutil "https://github.com/ceph/go-ceph/tree/master/internal/errutil/"
    click callbacks "https://github.com/ceph/go-ceph/tree/master/internal/callbacks/"
    click retry "https://github.com/ceph/go-ceph/tree/master/internal/retry/"
    click TestContainer "https://github.com/ceph/go-ceph/tree/master/testing/containers/"
    click CI1 "https://github.com/ceph/go-ceph/blob/master/.github/workflows/main.yml"
    click CI2 "https://github.com/ceph/go-ceph/blob/master/.github/workflows/report-stable.yml"
    click MakefileNode "https://github.com/ceph/go-ceph/tree/master/Makefile"
    click ModuleDef "https://github.com/ceph/go-ceph/blob/master/go.mod"
    click ModuleSum "https://github.com/ceph/go-ceph/blob/master/go.sum"
    click Docs "https://github.com/ceph/go-ceph/tree/master/docs/"
    click README "https://github.com/ceph/go-ceph/blob/master/README.md"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef support fill:#FADBD8,stroke:#C0392B,color:#641E16
    classDef cgo fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef clib fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef external fill:#E8DAEF,stroke:#8E44AD,color:#4A235A
    classDef test fill:#FDEDEC,stroke:#CD6155,color:#892E2F
    class ModuleDef,ModuleSum,CI1,CI2,MakefileNode,Docs,README fill:#FEF9E7,stroke:#B7950B,color:#6E2C00
```
