Azure Cosmos DB Garnet Cache 快速入门从零创建并连接你的首个托管缓存集群【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet本指南以 website/docs/azure/quickstart.md 为骨架完整走通 Azure Cosmos DB Garnet Cache预览版的创建、RBAC 数据访问配置、虚拟网络接入与 Redis 客户端连接测试全流程并结合当前仓库的源码与配套文档overview / security / cluster-configuration / resiliency / api-compatibility补充底层原理。读完本文你将掌握如何正确填写集群创建参数、如何用门户或 Azure CLI 分配 Entra ID 数据面角色、如何打通虚拟网络以及如何用redis-cli通过 TLS 与 Entra ID 令牌连接集群并执行基础命令。背景Azure Cosmos DB Garnet Cache 是什么Azure Cosmos DB Garnet Cache 是基于微软研究院开源的 Garnet 远程缓存存储即当前仓库 README.md 所描述的项目构建的完全托管缓存服务。与自托管 Garnet 一样它使用 Redis RESP 协议对外提供服务因此现有 Redis 客户端与工具无需改造即可接入支持 String、Hash、Set、Sorted Set、Pub/Sub、Lua 脚本及 VectorSet 等数据结构完整命令清单见 website/docs/azure/api-compatibility.md。Garnet 采用节点内共享一切shared-everything的多线程架构——节点内所有线程直接访问同一共享内存空间这与传统单线程缓存或节点内哈希分区的方案不同也是其在数千并发连接下仍能保持亚毫秒级延迟的关键。Azure 托管版将其包装为 PaaS 服务提供 99.99%*估算值可用性、可选 AOFRDB 持久化、虚拟网络隔离与 Entra ID RBAC 认证详细特性对比可参考 website/docs/azure/overview.md。注意该服务目前处于expanded Private Preview扩展私有预览阶段需先完成订阅注册注册非自动生效处理周期最长可达一周。前置条件Prerequisites在开始创建集群前请确认以下条件全部满足有效的 Azure 订阅且已注册到扩展私有预览。若尚未注册请按 注册订阅 的步骤申请。Azure 门户与 Azure CLI可用CLI 用于 RBAC 分配与令牌获取。集群创建权限执行操作的身份需要同时具备Microsoft.DocumentDB/garnetClusters/write——创建/更新 Garnet 集群资源Microsoft.Network/virtualNetworks/subnets/join/action——作用于集群所部署的子网。内置Owner与Contributor角色同时包含以上两项权限而 Cosmos DB 专属角色如 Cosmos DB Operator、DocumentDB Account Contributor不包含这些权限无法创建或扩缩容 Garnet 集群。详见 创建与管理集群的权限。角色分配权限Microsoft.Authorization/roleAssignments/write作用域为订阅或资源组级别。内置角色 Owner 与 User Access Administrator 均包含该权限也可使用自定义角色。提示为什么需要如此多的权限从源码角度看Garnet 集群是一个独立资源类型Microsoft.DocumentDB/garnetClusters并且会被部署到你的虚拟网络中的委派子网上——控制面操作要同时作用于 DocumentDB 资源与网络子网这正是上述两个数据操作writejoin/action缺一不可的原因。Step 1在 Azure 门户创建 Azure Cosmos DB Garnet CacheGarnet Cache 没有公网 IP 与公网 DNS所有应用访问必须来自缓存所在的虚拟网络VNet内部。因此创建时必须新建一个虚拟网络或选用已有的虚拟网络。创建步骤登录 Azure 门户。点击Create a resource创建资源搜索Azure Cosmos DB Garnet Cache。选择Azure Cosmos DB Garnet Cache点击Create。填写必填信息各字段的详细解读见下文表格Subscription订阅必须选择已注册私有预览的订阅。Resource Group资源组新建或选择现有资源组。Region区域选择离应用最近的区域可用区域列表见 区域可用性。Cluster Name集群名称为缓存选择一个全局唯一的名称。Virtual Network虚拟网络选择Create a new virtual network后输入网络名称可选自定义地址空间与子网。若使用已有 VNet须确保已配置正确的 必需出站网络规则且你的身份对所选子网具备Microsoft.Network/virtualNetworks/subnets/join/action权限。Enable outbound access启用出站访问仅在新建 VNet 时出现。新建 VNet 需要出站访问能力才能使预配流程到达必需目的地未勾选则预配失败仅当你打算自行配置显式出站方式如 NAT 网关时才取消勾选。详见 出站访问。Assign Roles分配角色保持勾选以保证预配成功。该选项会把Azure Cosmos DB服务主体在虚拟网络与子网上授予Network Contributor角色使托管服务能在你的网络中部署和管理缓存节点。你需在订阅或资源组作用域具备Microsoft.Authorization/roleAssignments/write权限角色分配才能成功。这是授予服务的权限与你的个人权限相互独立——你的身份仍需Microsoft.DocumentDB/garnetClusters/write与Microsoft.Network/virtualNetworks/subnets/join/action才能创建集群。Availability Zone可用区可选。勾选后节点将跨可用区分布详见 多可用区部署。Cluster Type集群类型Dev/Test或Production决定了可用的 SKU 与预期性能特征。Dev/Test 面向非生产负载、不提供 SLAProduction 面向高可用与低延迟的生产关键应用。详见 集群类型。SKU SizeSKU 大小选定集群类型后选择 SKU集群中所有节点将预配为该 SKU 对应的虚拟机规格。SKU 细目见 可用层级。Shard Count分片数集群中的分片数量即主节点数量。缓存的内存占用由所有主节点总内存决定。何时水平扩容 vs 垂直扩容见 选择扩容策略。Replication Factor复制因子每个分片内的节点数。1x表示仅主节点、无副本高可用场景使用2x或更高。复制因子在预配后不可更改。详见 复制。Total Node Count总节点数不可直接修改由Shard Count × Replication Factor计算得出。可选填写Advanced高级页签信息Persistence mode持久化模式可选No Persistence仅内存或Append Only File (AOF) and Redis Database (RDB)AOF 操作日志 RDB 快照组合实现数据持久化。持久化模式只能在预配时配置之后不可更改。Disk SKU磁盘 SKU不可配置。启用持久化后磁盘大小会根据所选计算 SKU 自动选择。点击Review Create复核再点击Create提交。关键参数速查表参数可选值/说明变更时机集群类型Dev/Test无 SLA或 Production决定可用 SKU 范围SKU 大小对应具体 VM 规格如 Standard_D16s_v6垂直扩容需重建集群分片数主节点数量决定总内存可在线水平扩缩容复制因子1x无副本/ 2x / 3x-6x最大 6x1 主 5 从仅预配时可设置持久化模式No Persistence 或 AOFRDB仅预配时可设置可用区可选节点跨可用区分布仅预配时可设置背后的分片模型从集群层面看Garnet 将键空间划分为16,384 个哈希槽hash slots每个槽由唯一的主节点拥有任一键精确映射到唯一槽位保证可预测的数据放置。当前仓库源码 libs/cluster/Server/ClusterConfig.cs 中定义MAX_HASH_SLOT_VALUE 16384与 Azure 托管版的槽位模型一致。多分片时槽位均匀分布在所有主节点上副本节点对主节点槽位对应的键提供只读服务实现读扩展与负载均衡主节点故障时仅影响其槽位内的键其余集群继续工作。这也是判断横向扩容加分片提升内存与写入吞吐、提高复制因子提升读吞吐与可用性的底层依据详见 数据分布与分片。Step 2使用 RBAC 配置数据访问Azure Cosmos DB Garnet Cache 使用Azure RBAC基于角色的访问控制来授权受支持的 Redis 命令。分配 Microsoft Entra ID RBAC 角色是使用数据面操作的前提且默认不会给任何人包括资源创建者分配任何角色。内置角色清单见 数据面内置角色。注意角色分配生效需要5-10 分钟。角色可以在多个作用域分配以下两个示例均在Azure Cosmos DB Garnet Cache 资源作用域上分配Garnet Data Contributor角色。进行角色分配需具备Microsoft.Authorization/roleAssignments/write权限如 Owner 或 User Access Administrator。方式一Azure 门户操作登录 Azure 门户。进入你的 Azure Cosmos DB Garnet Cache 资源的Access control (IAM)页面选择Add Add role assignment在Add role assignment页面搜索框中输入garnet。选择要分配的角色点击Next。本例分配Garnet Data Contributor角色全部内置角色见 内置角色在Members页面选择User, group or service principal可将角色分配给一个或多个 Microsoft Entra 用户、组或服务主体应用程序选择Managed identity则分配给一个或多个托管身份点击Select members搜索并选择用户、组、服务主体或托管身份。添加完所有安全主体后点击Review assign。内置角色一览节选自 security.mdGarnet Data Reader只读应用/监控、Garnet Data Contributor大多数应用String/Hash/Set/Sorted Set 读写、Garnet Data Owner管理/全控制、Garnet Script Data Contributor脚本执行与管理、Garnet PubSub Data Reader/Garnet PubSub Data ContributorPub/Sub 读与发布订阅。方式二Azure CLI 操作登录 Azure CLIaz login获取你的用户 Object ID或他人的# 获取自己的 Object ID az ad signed-in-user show --query id -o tsv # 或获取其他用户的 Object ID az ad user show --id usercompany.com --query id -o tsv分配 RBAC 角色本例使用Garnet Data Contributor# 设置你的参数 userObjectIdyour-object-id-from-step-1 subscriptionIdyour-subscription-id resourceGroupyour-garnet-cache-resource-group cacheNameyour-garnet-cache-name # 将 Garnet Data Contributor 分配给自己 az role assignment create \ --assignee $userObjectId \ --role Garnet Data Contributor \ --scope /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/garnetClusters/$cacheName控制面与数据面的区分理解这一步前要清楚 Garnet Cache 的访问分两个平面详见 security.md控制面通过 Azure Resource Manager 创建、扩缩容、管理集群资源与数据面对既有集群执行 Redis 命令。上文 Step 1 涉及的权限作用于控制面Step 2 分配的角色则决定数据面上你可以执行哪些 Redis 命令——例如Garnet Data Reader仅允许 GET、EXISTS 等只读命令Garnet Data Owner则允许包括破坏性操作在内的全部命令。每个角色的详细允许命令可在资源的Access control (IAM) Roles页签中按Permissions DataActions查看。Step 3设置网络访问Azure Cosmos DB Garnet Cache不提供公网 IP 或公网 DNS无法从公共互联网访问。缓存节点预配在创建集群时提供的虚拟网络上仅通过内网 IP 可从同一虚拟网络访问客户端机器必须与缓存处于同一网络。方案一创建新的虚拟机在缓存同一虚拟网络中新建一台虚拟机即可作为客户端创建 Linux VM创建 Windows VM方案二使用现有基础设施使用与缓存同 VNet 的现有 VM 或宿主机。若你的 VM 在不同虚拟网络中可设置虚拟网络对等peering前提是两个 VNet 的 IP 地址空间不重叠。对等建立成功后一个 VNet 内的客户端应用即可通过本地 IP 地址访问另一网络中的缓存端点。网络隔离的运维要点若你自带虚拟网络并使用 Azure 防火墙限制出站必须放行下表所列的服务标签service tags及地址前缀否则集群预配或运行将失败完整说明见 必需出站网络规则目标服务标签协议端口用途StorageHTTPS443节点与 Azure Storage 之间的控制面通信与配置AzureKeyVaultHTTPS443与 Azure Key Vault 的安全通信证书与密钥EventHubHTTPS443转发日志到 AzureAzureMonitorHTTPS443转发指标到 AzureAzureActiveDirectoryHTTPS443Microsoft Entra 认证AzureResourceManagerHTTPS443收集与管控 Garnet 节点信息AzureFrontDoor.FirstpartyHTTPS443日志记录操作GuestAndHybridManagementHTTPS443收集与管控 Garnet 节点信息ApiManagementHTTPS443收集与管控 Garnet 节点信息此外还需添加以下无对应服务标签的地址前缀104.40.0.0/13、13.104.0.0/14、40.64.0.0/10。Step 4连接并测试缓存现在可以连接你的 Azure Cosmos DB Garnet Cache 了。1. 获取用户 Object IDaz login az ad signed-in-user show --query id -o tsv2. 获取访问令牌Access Token访问令牌有过期时间窗口过期后需重新生成。令牌生命周期可参考 Microsoft 访问令牌文档az account get-access-token --scope https://cosmos.azure.com/.default --query accessToken -o tsv3. 查找缓存节点的 IP 地址Redis 客户端连接任一节点 IP 后会自动获取所有副本节点及端口的列表这正是 RESP 协议簇集群命令的能力。查找方式登录 Azure 门户。进入资源的Settings Cluster Explorer页面。找到集群中所有节点的 IP 地址并保存备用4. 使用 Redis 客户端连接可以使用任意 Redis 客户端连接集群。这里用Redis CLI快速验证数据访问可选# Linux 下安装 Redis CLI sudo apt-get install redis-tools连接集群替换为你的实际值# 替换为实际值 export USER_OBJECT_IDyour-object-id-from-step-1 export ACCESS_TOKENyour-access-token-from-step-2 export GARNET_HOST10.0.0.5 # 步骤 3 中的任意节点 IP export GARNET_PORT6379 # 连接启用 TLS、以集群模式连接使用 Entra ID 用户与令牌认证 redis-cli -h $GARNET_HOST -p $GARNET_PORT --tls -c --user $USER_OBJECT_ID --pass $ACCESS_TOKEN关于这条连接命令的几点说明--tlsAzure Cosmos DB Garnet Cache 强制 TLS 1.2 及以上并启用节点间加密传输中的数据全程加密见 security.md因此客户端必须开启 TLS。-c以集群模式连接客户端会自动跟随MOVED/ASK重定向并感知槽位映射。--user/--pass分别填入 Entra ID 用户的 Object ID 与 OAuth2 访问令牌作为数据面认证凭据。6379即 Garnet 的默认服务端口——仓库配置 libs/host/defaults.conf 中Port : 6379且 libs/server/Servers/ServerOptions.cs 的默认端点同样监听6379与 Redis 生态默认端口一致。5. 测试基础操作连接成功后可执行以下命令验证数据面是否工作正常更多受支持命令见 命令兼容性列表# 测试连接 PING # 设置与读取值 SET mykey Hello Garnet Cache! GET mykey # 查看集群拓扑 CLUSTER NODES CLUSTER INFO # 测试数据类型 HSET user:1 name John age 30 HGET user:1 name以上命令对应的实现事实PING、SET/GET、HSET/HGET均在 Azure 托管版的受支持命令清单中标记为已实现➕CLUSTER NODES、CLUSTER INFO也由集群命令族提供详见 api-compatibility.md 的 CONNECTION、STRING、HASH、CLUSTER 分类。在自托管 Garnet 中这些命令分别由 libs/server/Resp/BasicCommands.cs 与 libs/server/Resp/Objects/Hash 等模块实现RESP 协议层保证了两者命令语义的一致性。连接后的运维与故障排查速览成功连接只是开始几个与快速入门直接相关的后续事项监控集群会自动把指标如 Command Process Rate、Query Latency P99/Mean、Connected Clients、Main Store Size、CPU/内存/网络指标发送到 Azure Monitor多数指标可按Node拆分用于定位热点节点与扩容决策详见 website/docs/azure/monitoring.md。故障排查常见的四类问题高 CPU、高内存、连接异常、性能下降在监控文档中均有症状 → 解决步骤的对照其中集群创建或扩容失败通常是权限问题——请核对你的身份是否具备Microsoft.DocumentDB/garnetClusters/write与Microsoft.Network/virtualNetworks/subnets/join/action并注意新分配的角色需等待数分钟生效监控文档的 Cluster Creation or Scaling Fails 一节。数据持久化行为若开启了 AOFRDB 模式节点重启含自动故障转移后会从最新 RDB 快照恢复并重放 AOF未复制且未被快照/AOF 捕获的数据可能丢失这是设计上的取舍详见 resiliency.md。更多学习资源监控 Monitoring安全 Security集群配置 Cluster Configuration弹性与持久化 Resiliency命令兼容性 API Compatibility想体验自托管版本仓库根目录的 README.md 与 libs/host/GarnetServer.cs 提供了本地构建与运行的完整指引你可以在本地用同样的 RESP 协议与 Redis 客户端先行验证命令行为。【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Azure Cosmos DB Garnet Cache 快速入门：从零创建并连接你的首个托管缓存集群
Azure Cosmos DB Garnet Cache 快速入门从零创建并连接你的首个托管缓存集群【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet本指南以 website/docs/azure/quickstart.md 为骨架完整走通 Azure Cosmos DB Garnet Cache预览版的创建、RBAC 数据访问配置、虚拟网络接入与 Redis 客户端连接测试全流程并结合当前仓库的源码与配套文档overview / security / cluster-configuration / resiliency / api-compatibility补充底层原理。读完本文你将掌握如何正确填写集群创建参数、如何用门户或 Azure CLI 分配 Entra ID 数据面角色、如何打通虚拟网络以及如何用redis-cli通过 TLS 与 Entra ID 令牌连接集群并执行基础命令。背景Azure Cosmos DB Garnet Cache 是什么Azure Cosmos DB Garnet Cache 是基于微软研究院开源的 Garnet 远程缓存存储即当前仓库 README.md 所描述的项目构建的完全托管缓存服务。与自托管 Garnet 一样它使用 Redis RESP 协议对外提供服务因此现有 Redis 客户端与工具无需改造即可接入支持 String、Hash、Set、Sorted Set、Pub/Sub、Lua 脚本及 VectorSet 等数据结构完整命令清单见 website/docs/azure/api-compatibility.md。Garnet 采用节点内共享一切shared-everything的多线程架构——节点内所有线程直接访问同一共享内存空间这与传统单线程缓存或节点内哈希分区的方案不同也是其在数千并发连接下仍能保持亚毫秒级延迟的关键。Azure 托管版将其包装为 PaaS 服务提供 99.99%*估算值可用性、可选 AOFRDB 持久化、虚拟网络隔离与 Entra ID RBAC 认证详细特性对比可参考 website/docs/azure/overview.md。注意该服务目前处于expanded Private Preview扩展私有预览阶段需先完成订阅注册注册非自动生效处理周期最长可达一周。前置条件Prerequisites在开始创建集群前请确认以下条件全部满足有效的 Azure 订阅且已注册到扩展私有预览。若尚未注册请按 注册订阅 的步骤申请。Azure 门户与 Azure CLI可用CLI 用于 RBAC 分配与令牌获取。集群创建权限执行操作的身份需要同时具备Microsoft.DocumentDB/garnetClusters/write——创建/更新 Garnet 集群资源Microsoft.Network/virtualNetworks/subnets/join/action——作用于集群所部署的子网。内置Owner与Contributor角色同时包含以上两项权限而 Cosmos DB 专属角色如 Cosmos DB Operator、DocumentDB Account Contributor不包含这些权限无法创建或扩缩容 Garnet 集群。详见 创建与管理集群的权限。角色分配权限Microsoft.Authorization/roleAssignments/write作用域为订阅或资源组级别。内置角色 Owner 与 User Access Administrator 均包含该权限也可使用自定义角色。提示为什么需要如此多的权限从源码角度看Garnet 集群是一个独立资源类型Microsoft.DocumentDB/garnetClusters并且会被部署到你的虚拟网络中的委派子网上——控制面操作要同时作用于 DocumentDB 资源与网络子网这正是上述两个数据操作writejoin/action缺一不可的原因。Step 1在 Azure 门户创建 Azure Cosmos DB Garnet CacheGarnet Cache 没有公网 IP 与公网 DNS所有应用访问必须来自缓存所在的虚拟网络VNet内部。因此创建时必须新建一个虚拟网络或选用已有的虚拟网络。创建步骤登录 Azure 门户。点击Create a resource创建资源搜索Azure Cosmos DB Garnet Cache。选择Azure Cosmos DB Garnet Cache点击Create。填写必填信息各字段的详细解读见下文表格Subscription订阅必须选择已注册私有预览的订阅。Resource Group资源组新建或选择现有资源组。Region区域选择离应用最近的区域可用区域列表见 区域可用性。Cluster Name集群名称为缓存选择一个全局唯一的名称。Virtual Network虚拟网络选择Create a new virtual network后输入网络名称可选自定义地址空间与子网。若使用已有 VNet须确保已配置正确的 必需出站网络规则且你的身份对所选子网具备Microsoft.Network/virtualNetworks/subnets/join/action权限。Enable outbound access启用出站访问仅在新建 VNet 时出现。新建 VNet 需要出站访问能力才能使预配流程到达必需目的地未勾选则预配失败仅当你打算自行配置显式出站方式如 NAT 网关时才取消勾选。详见 出站访问。Assign Roles分配角色保持勾选以保证预配成功。该选项会把Azure Cosmos DB服务主体在虚拟网络与子网上授予Network Contributor角色使托管服务能在你的网络中部署和管理缓存节点。你需在订阅或资源组作用域具备Microsoft.Authorization/roleAssignments/write权限角色分配才能成功。这是授予服务的权限与你的个人权限相互独立——你的身份仍需Microsoft.DocumentDB/garnetClusters/write与Microsoft.Network/virtualNetworks/subnets/join/action才能创建集群。Availability Zone可用区可选。勾选后节点将跨可用区分布详见 多可用区部署。Cluster Type集群类型Dev/Test或Production决定了可用的 SKU 与预期性能特征。Dev/Test 面向非生产负载、不提供 SLAProduction 面向高可用与低延迟的生产关键应用。详见 集群类型。SKU SizeSKU 大小选定集群类型后选择 SKU集群中所有节点将预配为该 SKU 对应的虚拟机规格。SKU 细目见 可用层级。Shard Count分片数集群中的分片数量即主节点数量。缓存的内存占用由所有主节点总内存决定。何时水平扩容 vs 垂直扩容见 选择扩容策略。Replication Factor复制因子每个分片内的节点数。1x表示仅主节点、无副本高可用场景使用2x或更高。复制因子在预配后不可更改。详见 复制。Total Node Count总节点数不可直接修改由Shard Count × Replication Factor计算得出。可选填写Advanced高级页签信息Persistence mode持久化模式可选No Persistence仅内存或Append Only File (AOF) and Redis Database (RDB)AOF 操作日志 RDB 快照组合实现数据持久化。持久化模式只能在预配时配置之后不可更改。Disk SKU磁盘 SKU不可配置。启用持久化后磁盘大小会根据所选计算 SKU 自动选择。点击Review Create复核再点击Create提交。关键参数速查表参数可选值/说明变更时机集群类型Dev/Test无 SLA或 Production决定可用 SKU 范围SKU 大小对应具体 VM 规格如 Standard_D16s_v6垂直扩容需重建集群分片数主节点数量决定总内存可在线水平扩缩容复制因子1x无副本/ 2x / 3x-6x最大 6x1 主 5 从仅预配时可设置持久化模式No Persistence 或 AOFRDB仅预配时可设置可用区可选节点跨可用区分布仅预配时可设置背后的分片模型从集群层面看Garnet 将键空间划分为16,384 个哈希槽hash slots每个槽由唯一的主节点拥有任一键精确映射到唯一槽位保证可预测的数据放置。当前仓库源码 libs/cluster/Server/ClusterConfig.cs 中定义MAX_HASH_SLOT_VALUE 16384与 Azure 托管版的槽位模型一致。多分片时槽位均匀分布在所有主节点上副本节点对主节点槽位对应的键提供只读服务实现读扩展与负载均衡主节点故障时仅影响其槽位内的键其余集群继续工作。这也是判断横向扩容加分片提升内存与写入吞吐、提高复制因子提升读吞吐与可用性的底层依据详见 数据分布与分片。Step 2使用 RBAC 配置数据访问Azure Cosmos DB Garnet Cache 使用Azure RBAC基于角色的访问控制来授权受支持的 Redis 命令。分配 Microsoft Entra ID RBAC 角色是使用数据面操作的前提且默认不会给任何人包括资源创建者分配任何角色。内置角色清单见 数据面内置角色。注意角色分配生效需要5-10 分钟。角色可以在多个作用域分配以下两个示例均在Azure Cosmos DB Garnet Cache 资源作用域上分配Garnet Data Contributor角色。进行角色分配需具备Microsoft.Authorization/roleAssignments/write权限如 Owner 或 User Access Administrator。方式一Azure 门户操作登录 Azure 门户。进入你的 Azure Cosmos DB Garnet Cache 资源的Access control (IAM)页面选择Add Add role assignment在Add role assignment页面搜索框中输入garnet。选择要分配的角色点击Next。本例分配Garnet Data Contributor角色全部内置角色见 内置角色在Members页面选择User, group or service principal可将角色分配给一个或多个 Microsoft Entra 用户、组或服务主体应用程序选择Managed identity则分配给一个或多个托管身份点击Select members搜索并选择用户、组、服务主体或托管身份。添加完所有安全主体后点击Review assign。内置角色一览节选自 security.mdGarnet Data Reader只读应用/监控、Garnet Data Contributor大多数应用String/Hash/Set/Sorted Set 读写、Garnet Data Owner管理/全控制、Garnet Script Data Contributor脚本执行与管理、Garnet PubSub Data Reader/Garnet PubSub Data ContributorPub/Sub 读与发布订阅。方式二Azure CLI 操作登录 Azure CLIaz login获取你的用户 Object ID或他人的# 获取自己的 Object ID az ad signed-in-user show --query id -o tsv # 或获取其他用户的 Object ID az ad user show --id usercompany.com --query id -o tsv分配 RBAC 角色本例使用Garnet Data Contributor# 设置你的参数 userObjectIdyour-object-id-from-step-1 subscriptionIdyour-subscription-id resourceGroupyour-garnet-cache-resource-group cacheNameyour-garnet-cache-name # 将 Garnet Data Contributor 分配给自己 az role assignment create \ --assignee $userObjectId \ --role Garnet Data Contributor \ --scope /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/garnetClusters/$cacheName控制面与数据面的区分理解这一步前要清楚 Garnet Cache 的访问分两个平面详见 security.md控制面通过 Azure Resource Manager 创建、扩缩容、管理集群资源与数据面对既有集群执行 Redis 命令。上文 Step 1 涉及的权限作用于控制面Step 2 分配的角色则决定数据面上你可以执行哪些 Redis 命令——例如Garnet Data Reader仅允许 GET、EXISTS 等只读命令Garnet Data Owner则允许包括破坏性操作在内的全部命令。每个角色的详细允许命令可在资源的Access control (IAM) Roles页签中按Permissions DataActions查看。Step 3设置网络访问Azure Cosmos DB Garnet Cache不提供公网 IP 或公网 DNS无法从公共互联网访问。缓存节点预配在创建集群时提供的虚拟网络上仅通过内网 IP 可从同一虚拟网络访问客户端机器必须与缓存处于同一网络。方案一创建新的虚拟机在缓存同一虚拟网络中新建一台虚拟机即可作为客户端创建 Linux VM创建 Windows VM方案二使用现有基础设施使用与缓存同 VNet 的现有 VM 或宿主机。若你的 VM 在不同虚拟网络中可设置虚拟网络对等peering前提是两个 VNet 的 IP 地址空间不重叠。对等建立成功后一个 VNet 内的客户端应用即可通过本地 IP 地址访问另一网络中的缓存端点。网络隔离的运维要点若你自带虚拟网络并使用 Azure 防火墙限制出站必须放行下表所列的服务标签service tags及地址前缀否则集群预配或运行将失败完整说明见 必需出站网络规则目标服务标签协议端口用途StorageHTTPS443节点与 Azure Storage 之间的控制面通信与配置AzureKeyVaultHTTPS443与 Azure Key Vault 的安全通信证书与密钥EventHubHTTPS443转发日志到 AzureAzureMonitorHTTPS443转发指标到 AzureAzureActiveDirectoryHTTPS443Microsoft Entra 认证AzureResourceManagerHTTPS443收集与管控 Garnet 节点信息AzureFrontDoor.FirstpartyHTTPS443日志记录操作GuestAndHybridManagementHTTPS443收集与管控 Garnet 节点信息ApiManagementHTTPS443收集与管控 Garnet 节点信息此外还需添加以下无对应服务标签的地址前缀104.40.0.0/13、13.104.0.0/14、40.64.0.0/10。Step 4连接并测试缓存现在可以连接你的 Azure Cosmos DB Garnet Cache 了。1. 获取用户 Object IDaz login az ad signed-in-user show --query id -o tsv2. 获取访问令牌Access Token访问令牌有过期时间窗口过期后需重新生成。令牌生命周期可参考 Microsoft 访问令牌文档az account get-access-token --scope https://cosmos.azure.com/.default --query accessToken -o tsv3. 查找缓存节点的 IP 地址Redis 客户端连接任一节点 IP 后会自动获取所有副本节点及端口的列表这正是 RESP 协议簇集群命令的能力。查找方式登录 Azure 门户。进入资源的Settings Cluster Explorer页面。找到集群中所有节点的 IP 地址并保存备用4. 使用 Redis 客户端连接可以使用任意 Redis 客户端连接集群。这里用Redis CLI快速验证数据访问可选# Linux 下安装 Redis CLI sudo apt-get install redis-tools连接集群替换为你的实际值# 替换为实际值 export USER_OBJECT_IDyour-object-id-from-step-1 export ACCESS_TOKENyour-access-token-from-step-2 export GARNET_HOST10.0.0.5 # 步骤 3 中的任意节点 IP export GARNET_PORT6379 # 连接启用 TLS、以集群模式连接使用 Entra ID 用户与令牌认证 redis-cli -h $GARNET_HOST -p $GARNET_PORT --tls -c --user $USER_OBJECT_ID --pass $ACCESS_TOKEN关于这条连接命令的几点说明--tlsAzure Cosmos DB Garnet Cache 强制 TLS 1.2 及以上并启用节点间加密传输中的数据全程加密见 security.md因此客户端必须开启 TLS。-c以集群模式连接客户端会自动跟随MOVED/ASK重定向并感知槽位映射。--user/--pass分别填入 Entra ID 用户的 Object ID 与 OAuth2 访问令牌作为数据面认证凭据。6379即 Garnet 的默认服务端口——仓库配置 libs/host/defaults.conf 中Port : 6379且 libs/server/Servers/ServerOptions.cs 的默认端点同样监听6379与 Redis 生态默认端口一致。5. 测试基础操作连接成功后可执行以下命令验证数据面是否工作正常更多受支持命令见 命令兼容性列表# 测试连接 PING # 设置与读取值 SET mykey Hello Garnet Cache! GET mykey # 查看集群拓扑 CLUSTER NODES CLUSTER INFO # 测试数据类型 HSET user:1 name John age 30 HGET user:1 name以上命令对应的实现事实PING、SET/GET、HSET/HGET均在 Azure 托管版的受支持命令清单中标记为已实现➕CLUSTER NODES、CLUSTER INFO也由集群命令族提供详见 api-compatibility.md 的 CONNECTION、STRING、HASH、CLUSTER 分类。在自托管 Garnet 中这些命令分别由 libs/server/Resp/BasicCommands.cs 与 libs/server/Resp/Objects/Hash 等模块实现RESP 协议层保证了两者命令语义的一致性。连接后的运维与故障排查速览成功连接只是开始几个与快速入门直接相关的后续事项监控集群会自动把指标如 Command Process Rate、Query Latency P99/Mean、Connected Clients、Main Store Size、CPU/内存/网络指标发送到 Azure Monitor多数指标可按Node拆分用于定位热点节点与扩容决策详见 website/docs/azure/monitoring.md。故障排查常见的四类问题高 CPU、高内存、连接异常、性能下降在监控文档中均有症状 → 解决步骤的对照其中集群创建或扩容失败通常是权限问题——请核对你的身份是否具备Microsoft.DocumentDB/garnetClusters/write与Microsoft.Network/virtualNetworks/subnets/join/action并注意新分配的角色需等待数分钟生效监控文档的 Cluster Creation or Scaling Fails 一节。数据持久化行为若开启了 AOFRDB 模式节点重启含自动故障转移后会从最新 RDB 快照恢复并重放 AOF未复制且未被快照/AOF 捕获的数据可能丢失这是设计上的取舍详见 resiliency.md。更多学习资源监控 Monitoring安全 Security集群配置 Cluster Configuration弹性与持久化 Resiliency命令兼容性 API Compatibility想体验自托管版本仓库根目录的 README.md 与 libs/host/GarnetServer.cs 提供了本地构建与运行的完整指引你可以在本地用同样的 RESP 协议与 Redis 客户端先行验证命令行为。【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考