本文为 SPIRE 官方文档 migrating_registration_api_clients.md 的中文译本,以英文原文为准。 🔗 穿越源码分析:SVID 颁发流程
迁移注册 API 客户端
registration API 已被弃用并移除。新的 API 面(API surface)是原有功能的超集,并提供了一致的语义,以及批量(batch)和分页(paging)支持。
本文档列出了将客户端从旧的 registration API 迁移出去时对应的替代 RPC。
替代 RPC
| Registration RPC | 替代 RPC | 说明 |
|---|---|---|
CreateEntry | Entry.BatchCreateEntry | |
CreateEntryIfNotExists | Entry.BatchCreateEntry | 当条目已存在时,该条目的结果码为 ALREADY_EXISTS。 |
DeleteEntry | Entry.BatchDeleteEntry | |
FetchEntry | Entry.GetEntry | |
FetchEntries | Entry.ListEntries | |
UpdateEntry | Entry.BatchUpdateEntry | |
ListByParentID | Entry.ListEntries | 参见 by_parent_id 过滤器。 |
ListBySelector | Entry.ListEntries | 参见 by_selectors 过滤器。 |
ListBySelectors | Entry.ListEntries | 参见 by_selectors 过滤器。 |
ListBySpiffeID | Entry.ListEntries | 参见 by_spiffe_id 过滤器。 |
ListAllEntriesWithPages | Entry.ListEntries | 参见 page_size / page_token 字段。 |
CreateFederatedBundle | Bundle.BatchCreateFederatedBundle | 此外,也可用 Bundle.BatchSetFederatedBundle 对联邦证书包做"upsert"(不存在则插入,存在则更新)。 |
FetchFederatedBundle | Bundle.GetFederatedBundle | |
ListFederatedBundles | Bundle.ListFederatedBundles | |
UpdateFederatedBundle | Bundle.BatchUpdateFederatedBundle | 此外,也可用 Bundle.BatchSetFederatedBundle 对联邦证书包做"upsert"(不存在则插入,存在则更新)。 |
DeleteFederatedBundle | Bundle.BatchDeleteFederatedBundle | |
CreateJoinToken | Agent.CreateJoinToken | |
FetchBundle | Bundle.GetBundle | |
EvictAgent | Agent.DeleteAgent | 类似但有所区别的操作参见 Agent.BanAgent RPC。 |
ListAgents | Agent.ListAgents | 实现方必须假定该 RPC 可以按 server 认为必要的方式任意分页返回结果。 |
MintX509SVID | SVID.MintX509SVID | |
MintJWTSVID | SVID.MintJWTSVID | |
GetNodeSelectors | Agent.GetAgent | 除非被显式过滤,选择器(selector)会包含在 agent 信息中。 |
列表(List)操作
与 Registration API(ListAllEntriesWithPages 除外)不同,新 API 的所有 List* 操作都支持分页。如果客户端提供了页大小(page size),server 会 对响应分页,并以该页大小作为上限。然而,即便客户端没有提供页大小,server 也可以自行对结果分页。因此,客户端必须始终做好处理分页响应的准备。
批量(Batch)操作结果
需要特别注意的是:除非在单个批量操作的应用之外遇到了问题,否则批量 RPC 不会返回非 OK 状态。相反,各个批量操作的结果是通过每个批量操作的结果分别传达的。迁移者应当谨慎地进行妥当的错误检查,不仅要检查 RPC 结果码,还要检查各个批量操作的结果码。有关批处理语义,请参阅各个 RPC 的文档。