Metadata-Version: 2.4
Name: fabric_ceph_client
Version: 1.2.0
Summary: FABRIC Ceph Manager Client API
Author-email: Komal Thareja <kthare10@renci.org>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Project-URL: Home, https://fabric-testbed.net/
Project-URL: Sources, https://github.com/fabric-testbed/fabric_ceph

# fabric_ceph_client

Python client for the [FABRIC](https://fabric-testbed.net/) Ceph Manager service,
which brokers access to FABRIC's distributed Ceph clusters: CephFS subvolumes and
CephX users for POSIX storage, and RGW users, keys and buckets for S3.

Its only dependency is `requests`.

## Install

```bash
pip install fabric_ceph_client
```

## Usage

Authenticate with a FABRIC token, either inline or from a token file:

```python
from fabric_ceph_client.fabric_ceph_client import CephManagerClient

client = CephManagerClient(
    base_url="https://ceph-mgr.fabric-testbed.net",
    token_file="~/work/fabric_config/id_token.json",
)
```

Every call targets a single cluster, passed as `cluster`. Each cluster is an
independent Ceph deployment, so the same identity in two clusters is two
separate accounts.

### Cluster info

```python
info = client.list_cluster_info()
for c in info["data"]:
    print(c["cluster"], c["mon_host"], c.get("s3_endpoints"))
```

### CephFS

```python
client.create_or_resize_subvolume(
    "east", "CEPH-FS-01", "alice", size=10 * 1024**3
)
client.get_subvolume_info("east", "CEPH-FS-01", "alice")
client.list_subvolumes("east", "CEPH-FS-01")
client.delete_subvolume("east", "CEPH-FS-01", "alice")
```

### S3 (RGW)

An S3 user id is the user's FABRIC bastion login, the same identity used to name
their CephFS subvolume.

```python
# Users and access keys
client.list_s3_users("east")
client.get_s3_user("east", "alice_0000123456")

# Secrets are withheld from listings unless asked for explicitly
client.list_s3_user_keys("east", "alice_0000123456", include_secret=True)

# Creating a key also provisions the S3 user on first use
key = client.create_s3_user_key("east", "alice_0000123456")
print(key["access_key"], key["secret_key"])

# Buckets
client.list_s3_buckets("east", uid="alice_0000123456")
client.get_s3_bucket("east", "my-bucket")
client.set_s3_bucket_quota("east", "my-bucket", enabled=True, max_size_kb=1024**2)
```

RGW capabilities cannot be granted through this API — a user with admin caps
could bypass every restriction the service enforces. Grant them out of band with
`radosgw-admin` if genuinely required.

Creating and deleting buckets is restricted to FABRIC facility administrators
and owners of the FABRIC Ceph service project. Regular users can read and write
objects in the buckets they own, using the credentials above with any S3 client
(`aws-cli`, `s3cmd`, `boto3`, `rclone`). Object data goes directly to the Ceph
RGW gateway and never passes through the Ceph Manager service.

## Errors

Failed requests raise `ApiError`, which carries the HTTP status, the URL, and
the parsed response body:

```python
from fabric_ceph_client.fabric_ceph_client import ApiError

try:
    client.get_s3_bucket("east", "nope")
except ApiError as e:
    print(e.status, e.message, e.payload)
```

## Links

- Service source: <https://github.com/fabric-testbed/fabric_ceph>
- FABRIC: <https://fabric-testbed.net/>

## License

Apache-2.0

