RGW management API

[arttor]

Support api endpoints to manage rados-gateway.

Links:

• openapi of existing dashboard api mgr module
• rgw admin-ops api https://docs.ceph.com/en/latest/radosgw/adminops/

TODOs:

• @ubi2go add requirements
• discuss with @shutstart & @arttor
• implement

[fa-at-pulsit]

From the start, it’s best to organize all APIs into logical groups, creating a maintainable and future-proof structure, similar to how Kubernetes structures its API. This approach not only improves scalability and clarity but also makes it easier to manage access rights for different API groups.
e.g.

• Use /api/ for core Ceph functionality.
• Use /apis/{group}/ for subsystems (e.g., RGW, CephFS, Security).

API Group	Prefix	Description
Cluster API	/api/v1/cluster	Health, quorum, PG status, and general cluster operations.
Config API	/api/v1/config	Manage dynamic Ceph settings, tuning, and configurations.
Storage API	/api/v1/storage	Manage OSDs, pools, quotas, and storage-related operations.
Logging API	/api/v1/logs	Query audit logs, event streams, and debugging tools.
RADOS Gateway API	/apis/rgw/v1/	Manage object storage (buckets, users, and access policies).
CephFS API	/apis/cephfs/v1/	Manage CephFS filesystems, mounts, and snapshots.
Security API	/apis/security/v1/	Manage authentication, RBAC, and API tokens.
Event API	/apis/events/v1/	Manage webhook subscriptions and alert notifications.

---

To enhance security and accessibility, APIs should be categorized into public, private, and admin-only endpoints, ensuring fine-grained control over what is exposed. This can be dynamically configured using an API exposure control mechanism, allowing administrators to define which endpoints are publicly accessible and which are restricted to internal users.
e.g.

• Ability to configure which APIs are public vs. private.
• Separate Ingress controllers for:
  • Public APIs (e.g., /apis/rgw/ for object storage).
  • Private APIs (e.g., /api/v1/storage/ for internal operations).
• Admin APIs (e.g., /api/v1/config/ restricted to Ceph admins).
• ConfigMap-driven API exposure control to enable/disable endpoints dynamically.

---

Cool feature can be, implementing a webhook registration system allows external services to subscribe to real-time events, such as OSD failures, bucket creation, permission changes, and storage thresholds. This event-driven approach enables automated responses, reducing the need for manual intervention in cluster operations.
e.g.

• Webhook registration: Subscribe to Ceph events (e.g., OSD failure, bucket creation).
• Event-driven API: Expose real-time Ceph alerts and notifications.
  Webhook triggers for:
• Cluster health changes (HEALTH_WARN, HEALTH_ERR).
• Storage issues (pool reaching quota, PG imbalance).
• Security events (new user, permission changes).
• RADOS Gateway events (bucket created, deleted, access modified).

---

For efficient cluster management, the API should provide real-time health status, quorum state, self-healing triggers, placement group monitoring, and performance metrics. This ensures that administrators can proactively detect and resolve issues while maintaining high availability.
e.g.

• Real-time health status (GET /api/v1/cluster/health).
• Detailed cluster status (GET /api/v1/cluster/status).
• Quorum & MON status (GET /api/v1/cluster/quorum).
• Self-healing trigger (POST /api/v1/cluster/heal).
• Placement Group (PG) monitoring (GET /api/v1/cluster/pgs).
• Performance metrics (GET /api/v1/cluster/metrics).

---

Storage management capabilities should include OSD lifecycle operations, pool creation and deletion, quota enforcement, and erasure coding profile management. Automatic PG balancing and storage optimization should be incorporated to prevent bottlenecks and performance degradation.
e.g.

• OSD lifecycle management (mark in/out, reweight, replace dead OSDs).
• Pool management (create/delete pools, adjust replication/EC settings).
• Quota enforcement (per-user, per-bucket, per-pool limits).
• Automatic PG balancing (detect & redistribute uneven PGs).
• Erasure Coding profile management.

---

For RGW, the API should enable user management, bucket lifecycle control, detailed per-user and per-bucket statistics, and real-time event streaming. Advanced object operations such as tagging, metadata search, and replication management can enhance flexibility for object storage users.

• User management (create, delete, update RGW users).
• Bucket lifecycle & quota controls.
• Per-user / per-bucket statistics API (current throughput, object count).
• Live event streaming for bucket operations (WebSocket support).
• Object tagging & metadata search API.
• Object replication & versioning API.

CephFS should be managed through dedicated APIs for filesystem creation, mount control, permission management, and snapshot operations. Providing multi-user access control will allow administrators to configure granular permissions at the filesystem level.

• Filesystem creation, deletion, and mounts.
• CephFS snapshot & rollback API.
• Multi-user permission control for CephFS.

---

Security and access control must be a top priority, with RBAC enforcement, short-lived API tokens, dynamic user permission updates, and audit logging. A dedicated logging and audit API should allow administrators to track user actions, monitor system changes, and integrate with external security platforms.

• RBAC for Ceph APIs (granular role-based access control).

• Short-lived scoped API tokens (POST /apis/security/v1/tokens).

• Audit log & admin action tracking (GET /api/v1/logs/audit).

• Dynamic permission updates (PATCH /apis/security/v1/users/{userID}/permissions).

• Cluster-wide log search & filtering (GET /api/v1/logs).

• Admin action logging (GET /api/v1/logs/audit).

• Real-time event stream API for external monitoring.

---

And the coolest one can be, an official CLI tool similar to kubectl can be developed for Ceph. This would provide a command-line interface to interact with the API without needing to use a Ceph toolbox container or direct ceph/radosgw-admin commands.

It would be cool to run something like that without having access to a kubernetes cluster.

cephctl cluster health

cephctl osd list

cephctl osd out 5

cephctl rgw user create --name=john --access=read-write

cephctl rgw bucket stats --name=my-bucket

cephctl cluster watch

cephctl cluster slow-requests

cephctl osd migrate 10 15
...

---

There are many powerful ideas for Day-2 operations, from real-time monitoring and self-healing to automated scaling and disaster recovery. The API should provide intelligent mechanisms to minimize manual intervention and keep the cluster optimized.

For example:

• Live health monitoring & metrics to detect slow OSDs, PG imbalances, and high-latency operations.
• Automated self-healing & recovery to trigger rebalancing, failover, or reweighting when needed.
• Dynamic scaling & storage optimization to adjust replication, quotas, and erasure coding based on workload.
• Security & access control automation with RBAC enforcement, token rotation, and audit logging.
• Webhook-driven responses to trigger alerts or auto-remediation for failures and policy violations.
• A kubectl-like CLI with WebSocket streaming for real-time status updates and cluster actions.

---

If we take this approach, there’s certainly a lot to do, but it lays the foundation for a future-oriented, scalable, and automation-friendly solution. By building it module by module, we can create a powerful, modern API for Ceph administration—one that simplifies operations, enhances observability, and aligns with the best practices of cloud-native infrastructure. Step by step, this can evolve into a truly next-generation storage management API.

[arttor]

@fa-at-pulsit thank you for the feedback. I think taht we can use this info to create other tasks from it for the future work.

Our goal for this issue was to identify which endpoints are needed to be implemented to manage rados-gateway with ceph api.
There are exising:

• admin-ops http api hosted by rgw
• rgw-related endpoints in mgr dashboard api
• radosgw-admin CLI.

All these tools have intersections and quite huge so i think that it will be not productive just port all endpoints from them. So it would be useful to identify the most useful endpoints, or most frequent operation tasks to implement in our ceph-api as MVP so users can start using it as a single solution to manage their rgw instances.

At the end of our discussion we should have a list of endpoits to be impelented for rgw mvp.
But we can start from identifying rgw operational tasks and use-cases or probably from struggles and pain-points of rgw management if you can help with that. Then we can define endpoints based on it.
What do you think?

[arttor]

@ubi2go i've created 3 issues which may be useful and relevant for RGW and Ceph operations in general.

• First one Index ceph config options #21 - create indexed database of all ceph configs from ceph config help command. So it will be easy to lookup if daemon restart is needed for config change or see full list of commands in one place.
• Second Manage ceph daemons #22 should list all running ceph daemons
• And finally, we can use manage ceph daemon configs #23 to apply config to daemon

It would be cool to combine all 3 APIs to manage daemons configs on UI in convenient way.

CC @shutstart @jecluis @aprvsh