Ceph RGW Admin Operations API 解析：入口、授权与请求/响应契约（含未实现接口清单）

Ceph RGW Admin Operations API 解析入口、授权与请求/响应契约含未实现接口清单【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/cephCeph 对象网关RADOS Gateway简称 RGW提供了一组独立的 Admin Operations API用于以 REST 方式管理用户、存储桶、池、垃圾回收和日志等管理面资源。本文以仓库文档 doc/dev/radosgw/admin/adminops_nonimplemented.rst 为骨架结合 RGW 前端路由与驱动层源码src/rgw/rgw_appmain.cc、src/rgw/rgw_rest_admin.h、src/rgw/driver/rados/rgw_sal_rados.cc展开系统讲解 Admin API 的通用约定、每个接口的完整语法/参数/响应/错误契约并说明哪些接口在当前仓库中已实现、哪些仍停留在文档草案TBD阶段。读完本文你将能够依据完整契约构造请求、理解响应结构并正确区分可实现与不可实现的接口边界。Admin API 通用约定任何 Admin API 请求都基于一个可配置的资源入口点configurable admin resource entry point发起即 URI 以该入口点开头。在源码中这一入口点由配置项rgw_admin_entry控制// src/rgw/rgw_appmain.cc:457-466 if (apis_set.contains(admin)) { RGWRESTMgr_Admin *admin_resource new RGWRESTMgr_Admin; admin_resource-register_resource(info, new RGWRESTMgr_Info); admin_resource-register_resource(usage, new RGWRESTMgr_Usage); admin_resource-register_resource(account, new RGWRESTMgr_Account); admin_resource-register_resource(restore, new RGWRESTMgr_Restore); /* Register driver-specific admin APIs */ env.driver-register_admin_apis(admin_resource); rest.register_resource(g_conf()-rgw_admin_entry, admin_resource); }也就是说默认入口点为/admin文档中所有{admin}占位符均指该可配置入口。例如GET /{admin}/bucket?object实际请求路径为GET /admin/bucket?object若修改rgw_admin_entry则相应变化。授权模型Admin API 的授权完全复用 S3 授权机制Authorization for the admin API duplicates the S3 authorization mechanism。请求头中需要携带与 S3 一致的签名信息Access Key / 签名等。此外部分操作要求用户持有特殊的管理能力special administrative capabilities——例如用户被授予admin能力如user:read、user:write、bucket:read、bucket:write等后才有权执行相应管理操作这与通过radosgw-admin caps add授予能力是同一套体系。响应格式响应的实体类型entity type可以是 XML 或 JSON通过在请求中携带format查询参数指定formatjson返回 JSONformatxml返回 XML未指定时默认返回 JSONdefaults to JSON if not specified。因此文档中的每个示例请求几乎都带formatjson。Admin 资源树驱动层注册的子资源Admin 入口下注册的子资源分为两类通用子资源src/rgw/rgw_appmain.ccinfo、usage、account、restore驱动层driver注册的子资源以默认的 RADOS 驱动为例src/rgw/driver/rados/rgw_sal_rados.cc 中的RadosStore::register_admin_apis()注册了mgr-register_resource(user, new RGWRESTMgr_User); mgr-register_resource(bucket, new RGWRESTMgr_Bucket); mgr-register_resource(metadata, new RGWRESTMgr_Metadata); mgr-register_resource(log, new RGWRESTMgr_Log); mgr-register_resource(config, new RGWRESTMgr_Config); mgr-register_resource(realm, new RGWRESTMgr_Realm); mgr-register_resource(ratelimit, new RGWRESTMgr_Ratelimit); mgr-register_resource(dedup, new RGWRESTMgr_Dedup);从源码结构看RGWRESTMgr_Admin定义于 src/rgw/rgw_rest_admin.h是一个空的 REST 管理器基类实际能力全部来自register_resource挂载的子资源。这意味着当前仓库中已实现的 Admin API 子资源为 user、bucket、metadata、log、config、realm、ratelimit、dedup、info、usage、account、restore。而下面文档中列出的zone、pool、garbage等资源在register_resource调用中并未出现可以推断它们属于未实现non-implemented的接口——这正是该文档以adminops_nonimplemented.rst命名的原因。Get Object获取对象获取一个已存在的对象。注意该操作不要求对象所有者处于非挂起non-suspended状态。语法GET /{admin}/bucket?objectformatjson HTTP/1.1 Host {fqdn}请求参数参数类型必需说明示例bucketString是待检索对象所在的存储桶foo_bucketobjectString是待检索的对象foo.txt响应实体成功时返回期望的对象本体objectType: Object对象实体本身即对象的全部数据内容。特殊错误响应NoSuchObject指定的对象不存在HTTP 状态码404 Not Found。Head Object探测对象存在性验证对象是否存在。若对象存在将返回该对象的元数据头metadata headers。语法HEAD /{admin}/bucket?object HTTP/1.1 Host {fqdn}请求参数参数类型必需说明示例bucketString是待检索对象所在的存储桶foo_bucketobjectString是待检索的对象foo.txt响应实体无响应实体None。对象是否存在通过 HTTP 状态码与返回的元数据响应头体现。特殊错误响应NoSuchObject指定的对象不存在HTTP 状态码404 Not Found。从仓库现状看RADOS 驱动的register_admin_apis()中并未注册独立的object子资源但bucket资源已被注册RGWRESTMgr_Bucket。因此实践中获取/探测对象通常走 S3 数据面 APIGET /{bucket}/{object}或通过 bucket 管理接口间接实现本文档中的GET /{admin}/bucket?object语法属于管理面草案规范。Get Zone Info获取 Zone/集群信息获取集群信息cluster information。若成功返回集群的池配置cluster pool configuration。语法GET /{admin}/zoneformatjson HTTP/1.1 Host {fqdn}响应实体实体类型父级说明zoneContainer—当前集群池配置的容器domain_rootStringcluster所有存储桶的根root of all bucketscontrol_poolStringcluster控制池gc_poolStringcluster垃圾回收Garbage Collection池log_poolStringcluster日志池intent_log_poolStringcluster意图日志intent log池usage_log_poolStringcluster用量日志usage log池user_keys_poolStringcluster用户密钥池user_email_poolStringcluster用户邮箱池user_swift_poolStringclusterSwift 用户池特殊错误响应无None。示例响应HTTP/1.1 200 Content-Type: application/json { domain_root: .rgw, control_pool: .rgw.control, gc_pool: .rgw.gc, log_pool: .log, intent_log_pool: .intent-log, usage_log_pool: .usage, user_keys_pool: .users, user_email_pool: .users.email, user_swift_pool: .users.swift, user_uid_pool : .users.uid }说明该示例 JSON 与当前文档原文一致注意最后一个键为user_uid_pool 含尾部空格这属于原文档的笔误。对照响应中其他键的命名习惯.users、.users.email、.users.swift该键实际应为user_uid_pool对应 RADOS 池.users.uid——它保存按 UID 索引的用户信息。从当前仓库的池命名体系看.rgw系列池domain root/control/gc与.users系列池keys/email/swift/uid正是 RGW 在 RADOS 中持久化元数据与用户数据的标准布局。此外当前仓库已注册的realm子资源RGWRESTMgr_Realm承担了 zone/zonegroup/realm 的查询与配置zone资源本身并未单独注册可推断GET /{admin}/zone属于文档化的未实现接口。Add Placement Pool将池加入数据放置候选集使一个池可用于数据放置Make a pool available for data placement。语法PUT /{admin}/pool?formatjson HTTP/1.1 Host {fqdn}请求参数参数类型必需说明示例poolString是要使其可用于数据放置的池foo_poolcreateBoolean否若该数据池不存在则创建它False默认响应实体TBD待定义。特殊错误响应TBD待定义。Remove Placement Pool将池移出数据放置候选集使一个池不可用于数据放置Make a pool unavailable for data placement。语法DELETE /{admin}/pool?formatjson HTTP/1.1 Host {fqdn}请求参数参数类型必需说明示例poolString是要移出数据放置的现有池foo_pooldestroyBoolean否在将池移出活动集合后销毁该池False默认响应实体TBD待定义。特殊错误响应TBD待定义。List Available Data Placement Pools列出可用数据放置池列出当前可用于数据放置的池。语法GET /{admin}/pool?formatjson HTTP/1.1 Host {fqdn}响应实体成功时返回可用于数据放置的池列表poolsContainer包含当前可用于数据放置的池。List Expired Garbage Collection Items列出过期 GC 项列出已调度进行垃圾回收Garbage CollectionGC的对象。语法GET /{admin}/garbage?formatjson HTTP/1.1 Host {fqdn}请求参数无None。响应实体若存在过期的垃圾回收项将返回此类对象的列表实体类型父级说明garbageContainer—过期的垃圾回收项objectContainergarbage单个 GC 对象的信息容器nameStringobject对象的名称expiredStringobject对象过期的时间日期特殊错误响应TBD待定义。Manually Process Garbage Collection Items手动处理 GC 项手动触发垃圾回收列出已调度回收的对象文档措辞与 List 接口一致并返回已删除的对象列表。语法DELETE /{admin}/garbage?formatjson HTTP/1.1 Host {fqdn}请求参数无None。响应实体若存在过期的垃圾回收项将返回已移除对象的列表实体类型父级说明garbageContainer—过期的垃圾回收项objectContainergarbage单个 GC 对象的信息容器nameStringobject对象的名称expiredStringobject对象过期的时间日期特殊错误响应TBD待定义。背景补充RGW 的垃圾回收机制用于清理被覆盖或删除对象遗留在底层 RADOS 池中的陈旧数据分片是防止存储空间泄漏的关键后台任务。虽然文档中的GET/DELETE /{admin}/garbage管理接口标记为未实现RADOS 驱动未注册garbage子资源但 GC 的调度与执行能力在 RGW 中是真实存在的——通常由radosgw-admin gc list/radosgw-admin gc process命令驱动配置项rgw_gc_*系列控制其周期与并发。Show Log Objects查看日志对象展示日志对象Show log objects。语法GET /{admin}/log?formatjson HTTP/1.1 Host {fqdn}请求参数参数类型必需说明示例objectString否要返回的日志对象2012-10-11-09-4165.2-foo_bucket响应实体若未指定object参数返回完整的日志对象列表实体类型父级说明log-objectsContainer—日志对象列表objectStringlog-objects日志对象的名称logContainer—日志对象的内容特殊错误响应无None。源码印证与文档中其他未实现接口不同log资源在当前仓库中已真实注册mgr-register_resource(log, new RGWRESTMgr_Log)见 src/rgw/driver/rados/rgw_sal_rados.cc。请求参数object的示例2012-10-11-09-4165.2-foo_bucket体现了 RGW 日志对象的命名规律{时间戳}-{序号}.{分片}.{桶名}形式即按时间与桶分片组织的 OpsLog 对象。标准错误响应Standard Error Responses所有 Admin API 请求共享以下标准错误响应语义与 S3 一致错误码说明HTTP 状态码AccessDenied访问被拒绝403 ForbiddenInternalError内部服务器错误500 Internal Server ErrorNoSuchUser用户不存在404 Not FoundNoSuchBucket存储桶不存在404 Not FoundNoSuchKey不存在对应的访问密钥404 Not Found这些错误码与实际已实现的 Admin 子资源如user、bucket返回的错误模型一致用户/桶/密钥不存在统一映射为 404权限不足映射为 403服务内部异常映射为 500。总结接口实现状态对照基于本文档adminops_nonimplemented.rst与当前仓库源码的对照可以给出如下接口状态结论接口文档状态当前仓库状态推断依据Get Object / Head Object已定义语法无独立object子资源注册属草案Get Zone Info已定义响应zone未注册由realm资源承担相关职责Add/Remove/List Placement Pool参数已定义响应 TBDpool未注册属草案List/Process GC Items响应已定义错误 TBDgarbage未注册属草案GC 实际能力由radosgw-admin gc提供Show Log Objects完整定义已实现log子资源在 rgw_sal_rados.cc 注册标准错误响应完整定义与 S3 错误模型一致的通用约定使用建议需要查询 zone/zonegroup 信息时优先使用当前仓库已实现的realm管理接口或radosgw-admin命令需要管理放置池时通过radosgw-admin pool add/pool remove/pool list完成而非文档中的/{admin}/pool接口需要查看/触发垃圾回收时使用radosgw-admin gc list/gc process需要查看日志对象时可直接使用已实现的GET /{admin}/log?formatjson配合可选object参数或通过radosgw-admin log list/log show操作。通过阅读本文档与源码的对照读者既能掌握 Admin API 的统一请求/响应契约入口、S3 授权、format 语义、标准错误码也能清楚识别文档中哪些接口已落地、哪些仍处于规划草案状态从而避免在生产环境中调用尚未实现的接口。【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考