Skip to content

Commit 3d7596f

Browse files
jcocchibadrishc
jcocchi
and
badrishc
authored
Add Azure Cosmos DB Garnet Cache docs (#1439)
* add azure cosmos db garnet cache docs * update azure cosmos db garnet cache docs * update quickstart * add Azure Cosmos DB Garnet Cache to README --------- Co-authored-by: Badrish Chandramouli <[email protected]>
1 parent 4331fa3 commit 3d7596f

21 files changed

+1182
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Garnet is a new remote cache-store from Microsoft Research, that offers several
1717

1818
This repo contains the code to build and run Garnet. For more information and documentation, check out our website at [https://microsoft.github.io/garnet](https://microsoft.github.io/garnet).
1919

20+
**Looking for a fully managed service?** [Azure Cosmos DB Garnet Cache](https://microsoft.github.io/garnet/docs/azure/overview) provides Garnet as a fully managed, enterprise-ready caching solution with built-in high availability, performance guarantees and zero infrastructure management.
21+
2022
## Feature Summary
2123

2224
Garnet implements a wide range of APIs including raw strings (e.g., gets, sets, and key expiration), analytical (e.g., HyperLogLog and Bitmap), and object (e.g., sorted sets and lists)

‎website/docs/azure/api-compatibility.md‎

Lines changed: 286 additions & 0 deletions
Large diffs are not rendered by default.

‎website/docs/azure/cluster-configuration.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
id: cluster-configuration
3+
sidebar_label: Cluster Configuration
4+
title: Cluster Configuration for Azure Cosmos DB Garnet Cache
5+
---
6+
7+
# Cluster Configuration for Azure Cosmos DB Garnet Cache
8+
9+
## Available Tiers
10+
11+
Azure Cosmos DB Garnet Cache lets you choose the underlying [Azure Virtual Machine](https://learn.microsoft.com/azure/virtual-machines/sizes/overview) that your cache nodes will be provisioned on. The specs offered by cache nodes mirror the Azure virtual machine itself. Garnet doesn't limit the number of client connections that can be made on any node for any SKU. When choosing the right tier and SKU for your workload, consider that roughly 30% of memory on each node will be reserved for metadata and processing requests. Smaller SKUs in each tier are classified as [dev/test](#dev-test) while larger SKUs are designed for [production](#production) workloads.
12+
13+
Every node also has a [Premium SSD Managed Disk](https://learn.microsoft.com/azure/virtual-machines/disks-types#premium-ssds) provisioned for [data persistence](./resiliency.md#data-persistence). The disk size is not configurable and represents 2x the total memory of each node. The Managed Disk SKU provisioned for each option is in the table below, and is priced at the [Azure Managed Disk price](https://azure.microsoft.com/pricing/details/managed-disks).
14+
15+
The pricing model for cache nodes is instance-based and there are no licensing fees. For information about pricing for specific SKUs, reach out to [[email protected]](mailto:[email protected]).
16+
17+
### General Purpose
18+
19+
Balanced performance tier suitable for most caching workloads with a good balance of compute, memory, and network resources.
20+
21+
- **Use Cases**: Balanced workloads, general caching, development and testing
22+
23+
|SKU |vCPUs |Memory (GB) |Network bandwidth (MB/s) |Premium SSD Managed Disk |Cluster Type |
24+
|----|------|------------|-------------------------|-------------------------|-------------|
25+
|Standard_B2ls_v2 |2 |4 |6250 |P2 |Dev/ Test |
26+
|Standard_B2als_v2|2 |4 |6250 |P2 |Dev/ Test |
27+
|Standard_D2s_v5 |2 |8 |12500 |P3 |Dev/ Test |
28+
|Standard_D4s_v5 |4 |16 |12500 |P4 |Dev/ Test |
29+
|Standard_D8s_v5 |8 |32 |12500 |P6 |Production |
30+
|Standard_D16s_v5 |16 |64 |12500 |P10 |Production |
31+
|Standard_D32s_v5 |32 |128 |16000 |P15 |Production |
32+
|Standard_D2as_v5 |2 |8 |12500 |P3 |Dev/ Test |
33+
|Standard_D4as_v5 |4 |16 |12500 |P4 |Dev/ Test |
34+
|Standard_D8as_v5 |8 |32 |12500 |P6 |Production |
35+
|Standard_D16as_v5|16 |64 |12500 |P10 |Production |
36+
|Standard_D32as_v5|32 |128 |16000 |P15 |Production |
37+
|Standard_D2s_v4 |2 |8 |5000 |P3 |Dev/ Test |
38+
|Standard_D4s_v4 |4 |16 |10000 |P4 |Dev/ Test |
39+
|Standard_D8s_v4 |8 |32 |12500 |P6 |Production |
40+
|Standard_D16s_v4 |16 |64 |12500 |P10 |Production |
41+
|Standard_D32s_v4 |32 |128 |16000 |P15 |Production |
42+
43+
### Memory Optimized
44+
45+
High-memory tier designed for workloads requiring large in-memory datasets with optimized memory-to-CPU ratios.
46+
47+
- **Use Cases**: Large datasets, gaming leaderboards, vector search workloads
48+
49+
|SKU |vCPUs |Memory (GB) |Network bandwidth (MB/s) |Premium SSD Managed Disk |
50+
|----|------|------------|-------------------------|-------------------------|
51+
|Standard_E2s_v5 |2 |16 |12500 |P4 |Dev/ Test |
52+
|Standard_E4s_v5 |4 |32 |12500 |P6 |Dev/ Test |
53+
|Standard_E8s_v5 |8 |64 |12500 |P10 |Production |
54+
|Standard_E16s_v5 |16 |128 |12500 |P15 |Production |
55+
|Standard_E20s_v5 |20 |160 |12500 |P20 |Production |
56+
|Standard_E32s_v5 |32 |256 |16000 |P20 |Production |
57+
|Standard_E2as_v5 |2 |16 |12500 |P4 |Dev/ Test |
58+
|Standard_E4as_v5 |4 |32 |12500 |P6 |Dev/ Test |
59+
|Standard_E8as_v5 |8 |64 |12500 |P10 |Production |
60+
|Standard_E16as_v5|16 |128 |12500 |P15 |Production |
61+
|Standard_E20as_v5|20 |160 |12500 |P20 |Production |
62+
|Standard_E32as_v5|32 |256 |16000 |P20 |Production |
63+
|Standard_E2s_v4 |2 |16 |5000 |P4 |Dev/ Test |
64+
|Standard_E4s_v4 |4 |32 |10000 |P6 |Dev/ Test |
65+
|Standard_E8s_v4 |8 |64 |12500 |P10 |Production |
66+
|Standard_E16s_v4 |16 |128 |12500 |P50 |Production |
67+
|Standard_E20s_v4 |20 |160 |10000 |P20 |Production |
68+
|Standard_E32s_v4 |32 |256 |16000 |P20 |Production |
69+
70+
71+
### Cluster Types
72+
73+
There are two cluster types to choose from which determine the SKUs available and the performance guarantees offered.
74+
75+
#### Dev/ Test
76+
77+
Development and testing SKUs are designed for non-production workloads with cost optimization and flexibility in mind. They are a good fit for feature testing and integration validation and are offered without SLAs. You may see lower throughput and higher latencies when using these SKUs. All features, including scaling out across shards, are available on Dev/ Test SKUs.
78+
79+
#### Production
80+
81+
Production SKUs are configured for high availability, performance, and reliability. They are a good fit for mission critical applications that need high throughput and consistent low latency.
82+
83+
84+
## Scaling Options
85+
86+
Azure Cosmos DB Garnet Cache provides flexible scaling options to meet your application's changing demands. Understanding when and how to scale your cache cluster is essential for maintaining optimal performance while controlling costs.
87+
88+
### Choosing Your Scaling Strategy
89+
90+
The decision between vertical and horizontal scaling depends on your specific workload characteristics and performance requirements. Vertical scaling offers simplicity and is ideal when you need more resources per node, while horizontal scaling provides better distribution and resilience for high-throughput scenarios.
91+
92+
#### Vertical Scaling (Scale Up/Down)
93+
94+
Vertical scaling involves changing the SKU of your existing cache nodes to increase or decrease their individual capacity. This approach maintains your current cluster topology while providing more or fewer resources per node. You can scale up SKU size in place within the same tier and generation.
95+
96+
**When to Scale Up:**
97+
Vertical scaling is most effective when your workload benefits from having more resources concentrated on fewer nodes. This approach reduces network overhead between nodes and simplifies data management. Consider scaling up when you need increased memory capacity for larger datasets or higher CPU performance for complex operations.
98+
99+
Vector search workloads are particularly well-suited for vertical scaling because they benefit significantly from having the entire dataset available on a single node. Vector similarity searches require access to large portions of the dataset to compute accurate results, and distributing vectors across multiple nodes can introduce latency and complexity. By scaling up to larger SKUs, vector search applications can maintain all vectors in memory on a single node, enabling faster index traversal and more efficient similarity computations.
100+
101+
**Benefits of Vertical Scaling:**
102+
The primary advantage of vertical scaling is operational simplicity, as it maintains your existing cluster topology while providing enhanced performance.
103+
104+
#### Horizontal Scaling (Scale Out/In)
105+
106+
Horizontal scaling involves adding or removing nodes from your cluster to distribute load across more instances. You can scale horizontally by adding more shards to increase memory footprint and write throughput, or by increasing the replication factor to improve read throughput and availability.
107+
108+
**When to Scale Out:**
109+
Horizontal scaling becomes essential when your workload exceeds the capacity limits of individual nodes or when you need to distribute load for better performance. This approach is particularly effective for applications with high concurrent user loads or when you need to improve read performance through additional replica.
110+
111+
**Scaling with Shards vs Replicas:**
112+
Adding shards increases your total memory capacity and write throughput by distributing data across multiple primary nodes. Each shard handles a portion of your keyspace, allowing for parallel processing of operations. Alternatively, adding replicas primarily improves read throughput and provides better availability, as read operations can be distributed across multiple copies of your data. The [replication factor](./resiliency.md#replication) you choose directly impacts both performance and resiliency characteristics of your cluster.
113+
114+
**Benefits of Horizontal Scaling:**
115+
Horizontal scaling provides superior fault tolerance since the failure of individual nodes has less impact on overall system availability. This approach also offers better resource utilization efficiency and can handle virtually unlimited growth by continuously adding nodes.
116+
117+
### How to Scale
118+
119+
The **Settings > Cluster Explorer** page of the [Azure portal](https://aka.ms/garnet-portal) allows you to scale your cluster both vertically and horizontally. The Azure Cosmos DB Garnet Cache is in an expanded Private Preview and you must access the Azure portal through this link to manage your caches.
120+
121+
![Cluster Explorer](../../static/img/azure/cluster-explorer.png)
122+
123+
You can increase the shard count to scale in/ out, or change the SKU size to scale down/ up. Replication factor can only be configured during cluster provisioning and cannot be updated in place on existing clusters.
124+
125+
![Scale Cluster](../../static/img/azure/scale-cluster.png)
126+
127+
### Right-Sizing Your Deployment
128+
129+
You can optimize the size of your Azure Cosmos DB Garnet Cache by monitoring and adjusting based on actual usage patterns. Starting with conservative estimates and scaling based on observed metrics typically provides the most cost-effective approach while ensuring performance requirements are met.
130+
131+
We recommend beginning your deployment with a smaller tier that meets your initial requirements, then monitor key metrics such as memory utilization, CPU usage, and command processing rates. Regular review of these metrics allows you to make informed decisions about when and how to scale your deployment. Watch for sustained high memory utilization that might indicate a need for additional capacity, increased latency that could benefit from more processing power, or uneven load distribution that might be addressed through horizontal scaling. The key is to identify trends before they impact user experience, allowing for proactive scaling rather than reactive responses to performance issues.
132+
133+
134+
## Regional availability
135+
136+
Each Azure Cosmos DB Garnet Cache can be provisioned in a single region. It is available in multiple Azure regions worldwide, with ongoing expansion to additional regions. The availability of each SKU in a given region depends on the Azure Virtual Machine regional availability. You can verify which SKUs are available in each region [here](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/table).
137+
138+
Additionally, you can configure availability zones during provisioning in supported Azure regions where there is capacity for your chosen SKU. See the list of [Azure regions with availability zone support](https://learn.microsoft.com/azure/reliability/regions-list).
139+
140+
| Geography | Region | Region Name |
141+
|-----------|--------|-------------|
142+
| **Americas** | canadacentral | Canada Central |
143+
| | canadaeast | Canada East |
144+
| | centralus | Central US |
145+
| | eastus | East US |
146+
| | eastus2 | East US 2 |
147+
| | northcentralus | North Central US |
148+
| | southcentralus | South Central US |
149+
| | westcentralus | West Central US |
150+
| | westus | West US |
151+
| | westus2 | West US 2 |
152+
| | westus3 | West US 3 |
153+
| | brazilsouth | Brazil South |
154+
| | brazilsoutheast | Brazil Southeast |
155+
| **Europe** | northeurope | North Europe |
156+
| | westeurope | West Europe |
157+
| | francecentral | France Central |
158+
| | germanynorth | Germany North |
159+
| | germanywestcentral | Germany West Central |
160+
| | italynorth | Italy North |
161+
| | norwayeast | Norway East |
162+
| | norwaywest | Norway West |
163+
| | swedencentral | Sweden Central |
164+
| | swedensouth | Sweden South |
165+
| | switzerlandnorth | Switzerland North |
166+
| | switzerlandwest | Switzerland West |
167+
| | uksouth | UK South |
168+
| | ukwest | UK West |
169+
| **Africa** | southafricanorth | South Africa North |
170+
| | southafricawest | South Africa West |
171+
| **Middle East** | uaecentral | UAE Central |
172+
| | uaenorth | UAE North |
173+
| **Asia Pacific** | australiaeast | Australia East |
174+
| | australiasoutheast | Australia Southeast |
175+
| | centralindia | Central India |
176+
| | southindia | South India |
177+
| | westindia | West India |
178+
| | eastasia | East Asia |
179+
| | southeastasia | Southeast Asia |
180+
| | japaneast | Japan East |
181+
| | japanwest | Japan West |
182+
| | koreacentral | Korea Central |
183+
| | koreasouth | Korea South |
184+
185+
186+
## Learn More
187+
188+
- [Getting Started](./quickstart.md)
189+
- [Resiliency](./resiliency.md)
190+
- [Security](./security.md)
191+
- [Monitoring](./monitoring.md)

‎website/docs/azure/faq.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
id: faq
3+
sidebar_label: FAQ
4+
title: Frequently Asked Questions
5+
---
6+
7+
# Frequently Asked Questions
8+
9+
## General Questions
10+
11+
### What is Azure Cosmos DB Garnet Cache?
12+
Azure Cosmos DB Garnet Cache is a fully managed, high-performance caching service built on the Garnet remote cache-store from Microsoft Research. It provides Redis protocol compatibility with ultra-low latency and enterprise-grade security, scalability, and reliability.
13+
14+
### How can I access the Preview?
15+
Azure Cosmos DB Garnet Cache is currently in an expanded Private Preview. Please [sign up](https://aka.ms/cosmos-db-garnet-preview) to join the preview.
16+
17+
### How is it different from self-hosted Garnet?
18+
As a fully managed service, Azure Cosmos DB Garnet Cache handles infrastructure provisioning, scaling, patching, and monitoring automatically. Self-hosted Garnet requires you to manage the infrastructure, updates, and operations yourself.
19+
20+
### Does it only work with Azure Cosmos DB?
21+
No, Azure Cosmos DB Garnet Cache can be used to accelerate data access for any application, including but not limited to use with Azure Cosmos DB. It doesn't use the Azure Cosmos DB SDKs or have any automatic syncing.
22+
23+
### Is it compatible with Redis clients?
24+
Yes, Azure Cosmos DB Garnet Cache uses the Redis RESP protocol, making it compatible with existing Redis clients in all major programming languages without code changes.
25+
26+
### What Redis version is supported?
27+
Azure Cosmos DB Garnet Cache supports the RESP protocol and doesn't have full support for any specific Redis version. Visit the list of [supported Redis commands](./api-compatibility.md).
28+
29+
### How is Azure Cosmos DB Garnet Cache priced?
30+
Azure Cosmos DB Garnet Cache clusters are billed per instance per hour with no licensing fees. Each node will be billed for the chosen SKU plus an attached disk, used for [data persistence](./resiliency.md#data-persistence), with 4x the storage available for the SKU. Pricing per SKU is set at different rates than the underlying Azure VM and is subject to change between our extended Private Preview and Public Preview.
31+
32+
For information about pricing for specific SKUs, reach out to [[email protected]](mailto:[email protected]).
33+
34+
35+
## Performance and Scalability
36+
37+
### What performance can I expect?
38+
Latency is typically sub-millisecond and is around 3ms the 99th percentile. Performance and throughput varies by tier, key/ value size, and number of concurrent requests, among other factors.
39+
40+
### Can I scale my cache?
41+
Yes, you can [scale out](./cluster-configuration.md#horizontal-scaling-scale-outin) by adding shards, or [scale up](./cluster-configuration.md#vertical-scaling-scale-updown) by changing SKU size within a VM family and generation with no downtime.
42+
43+
### How many connections are supported?
44+
Garnet doesn't limit the number of client connections that can be made on any node for any SKU. In practice, connection limits vary by SKU. See the [virtual machine limits](https://learn.microsoft.com/azure/virtual-machines/sizes/overview#list-of-vm-size-families-by-type) corresponding to the [Azure Cosmos DB Garnet Cache SKU](./api-compatibility.md) you choose.
45+
46+
47+
## Development and Integration
48+
49+
### Which client libraries are supported?
50+
All Redis client libraries are supported. Ensure you visit the list of [supported commands](./api-compatibility.md). Popular libraries by language include:
51+
- **C#**: [StackExchange.Redis](https://github.com/StackExchange/StackExchange.Redis)
52+
- **Java**: [Jedis](https://github.com/redis/jedis), [Redisson](https://github.com/redisson/redisson)
53+
- **Python**: [redis-py](https://github.com/redis/redis-py)
54+
- **Node.js**: [node_redis](https://github.com/redis/node-redis)
55+
- **Go**: [go-redis](https://github.com/redis/go-redis)
56+
57+
### Can I test it locally?
58+
For local development, you can use the self-hosted Garnet server.
59+
60+
61+
## Regional Availability
62+
63+
### Which regions is it available in?
64+
Azure Cosmos DB Garnet Cache is available in many Azure regions. Check our [supported regions list](./cluster-configuration.md#regional-availability).
65+
66+
### Which regions support Availability Zones?
67+
Azure Cosmos DB Garnet Cache can be configured with availability zones during provisioning in supported Azure regions where there is capacity for your chosen SKU. See the list of [Azure regions with availability zone support](https://learn.microsoft.com/azure/reliability/regions-list).
68+
69+
70+
## Troubleshooting
71+
72+
### My application can't connect to the cache
73+
Check these common issues:
74+
1. **VNet configuration**: Verify your client application is in the [same virtual network](./security.md#network-security) as your cache
75+
2. **Authentication**: Verify you've configured [role based access control](./security.md#authentication-and-access-control), which is required for data plane access
76+
3. **SSL/TLS**: Ensure your client supports [TLS](./security.md#data-encryption)
77+
78+
### Cache performance is slower than expected
79+
Common causes and solutions:
80+
1. **Connection pooling**: Ensure proper connection pool configuration
81+
2. **Hot keys**: Check for key access patterns causing bottlenecks
82+
3. **Memory pressure**: [Monitor memory usage](./monitoring.md#high-memory-usage) and consider scaling up
83+
4. **Network latency**: Test from the same region as your cache
84+
85+
### I'm getting timeout errors
86+
Troubleshooting steps:
87+
1. **Check timeout settings**: Verify client timeout configuration
88+
2. **Monitor CPU/memory**: [High resource usage](./monitoring.md#high-cpu-usage) can cause timeouts
89+
4. **Network issues**: Test network connectivity between client and cache
90+
91+
92+
## Getting Help
93+
94+
### Where can I get technical support?
95+
- [**Documentation**](./overview.md): For conceptual guidance and tutorials
96+
- **Azure Support**: Create support tickets for technical issues
97+
- **Community**: Stack Overflow and Azure forums
98+
99+
### How do I report bugs or request features?
100+
- **Azure Support** for bugs and critical issues
101+
- [**Feedback Form**](https://aka.ms/garnet-feedback) for feature requests or suggestions
102+
103+
104+
## Next Steps
105+
106+
- [Garnet Overview](./overview.md)
107+
- [Getting Started](./quickstart.md)

0 commit comments

Comments
 (0)