English | EN 
When integrating Azure Cosmos DB with microservices, choosing the right connectivity mode is crucial for performance, security, and stability. However, many teams face challenges when configuring connectivity, particularly with firewall restrictions and port requirements. In this blog, we will explore the key issues encountered while connecting a Spring Boot microservice to Cosmos DB and discuss the resolution approach.
Architecture Overview
Below is a snapshot of the components deployed:
- Azure API Management (APIM): A platform that enables publishing and securely orchestrating APIs to backends.
- Azure Web App: Hosts the GraphQL APIs, deployed as a Spring Boot microservice.
- Azure Cosmos DB: A fully managed NoSQL and relational database for modern application development. Various programming languages offer SDKs to establish connectivity with Cosmos DB.
Issues Observed
- The Spring Boot microservice deployed as a web app failed to establish connectivity with Cosmos DB.
- Direct mode connectivity uses random ports to establish a connection between the web app and Cosmos DB.
- According to Microsoft’s documentation, direct mode communication requires firewall access to ports 0-65535, posing a security risk.
- Given the wide range of ports required, the network team identified this as a critical security concern.
Microsoft Guidance on Connectivity Modes
Microsoft offers two modes of connectivity: Direct Mode and Gateway Mode. While direct mode is recommended for its lower latency, it requires opening a large range of ports, which may not be feasible in secure environments. Gateway mode introduces an additional hop but provides a more controlled and firewall-friendly approach.
| Mode | Port Requirement | Hardware Requirement | Latency | Pricing |
| Direct | 0 through 65535 | NA | Low | No additional charge |
| Gateway (standard) | 443 | NA(hardware for gateway is shared) | High | No additional charge |
| Gateway (dedicated) | 443 | Additional hardware for gateway provisioning | High | Additional charge for hardware |
Resolution Approach
Lower Environments:
- Given that Gateway Mode (Standard) only requires port 443, it was selected for lower environments to ensure easier firewall whitelisting.
- This approach avoids additional infrastructure costs while ensuring stable connectivity.
Higher Environments:
- Gateway Mode (Dedicated) was chosen for production and higher environments since it provides dedicated hardware for traffic handling.
- As port 443 is a standard port with a high probability of firewall approval, this ensures a secure and reliable connection.
Pricing and Infrastructure Provisioning
The dedicated gateway mode incurs additional costs based on the number of vCores provisioned. It is recommended to refer to the Azure Pricing Portal for the latest pricing details.
Terraform Provisioning for Dedicated Gateway
Terraform provides a resource to provision dedicated hardware for Cosmos DB. This can be integrated into the Cosmos account provisioning workflow to ensure seamless deployment.
Configuration Updates
With the dedicated gateway provisioned, the connection string must be updated to use the revised gateway connection keys instead of the primary key used in direct mode.
By implementing these changes, we successfully established a stable and secure connection to Cosmos DB while ensuring minimal impact on latency and performance.
Conclusion
Choosing the right connectivity mode for Cosmos DB is key to balancing security, performance, and cost. Direct Mode offers low latency but has extensive port requirements, while Gateway Mode (Dedicated) provides a more secure and manageable alternative for production. Organizations should assess their infrastructure and security needs to make an informed decision, keeping Microsoft’s guidance and pricing updates in mind.