Choose a connectivity mode (gateway versus direct)

When developing native applications using Microsoft Azure Cosmos DB, one important decision to make is choosing the connectivity mode between gateway and direct. Both modes have their advantages and considerations, and selecting the appropriate mode depends on your specific application requirements and use cases.

1. Gateway Mode

Gateway mode is the default connectivity mode and is recommended for most scenarios, including web and mobile applications. In this mode, the Azure Cosmos DB SDK communicates with the Azure Cosmos DB service via a gateway managed by Microsoft.

When using gateway mode, the SDK communicates over HTTPS (port 443) with the gateway. The gateway handles essential functionalities like authentication, load balancing, and routing requests to the appropriate data partitions.

To configure your application to use gateway mode, you need to provide the URI and key to connect to the gateway endpoint. Here’s an example of connecting to Azure Cosmos DB in gateway mode using the .NET SDK:

using Microsoft.Azure.Cosmos;

Gateway mode provides the following benefits:

• Firewall-friendly: Since gateway communication happens over the standard HTTPS port, it simplifies firewall configuration.
• Encryption: All traffic between the SDK and the gateway is encrypted using SSL/TLS protocols.
• Client SDK version independence: You can upgrade the client SDK version without any changes to your application code.

2. Direct Mode

Direct mode provides direct connectivity to the Azure Cosmos DB service without requiring interaction through the gateway. It is designed for specific scenarios where you need more control over network connectivity, request routing, or advanced features of Azure Cosmos DB.

In direct mode, the SDK communicates directly with the Azure Cosmos DB service’s internal network endpoints over TCP/IP. This mode allows for low-latency and more efficient communication compared to gateway mode.

To utilize direct mode, you need to specify the TCP endpoint in addition to the authentication key. Here’s an example of connecting to Azure Cosmos DB in direct mode using the .NET SDK:

using Microsoft.Azure.Cosmos;

var cosmosClient = new CosmosClient("your-endpoint-uri", "your-authentication-key", connectionPolicy);

Direct mode offers the following advantages:

• Low-latency: Direct mode provides a more direct and faster connection to the Azure Cosmos DB service.
• Control over networking: With direct mode, you have control over network-level features like DNS resolution and proxy configuration.
• Access to advanced features: Direct mode enables features like TCP-only transport and custom endpoint routing.

While direct mode offers certain benefits, it also introduces additional considerations:

• Network configuration: Using direct mode requires careful network configuration, including allowing outbound access on specific ports and enabling connectivity to the necessary Azure Cosmos DB internal endpoints.
• SDK compatibility: Direct mode requires SDK-specific support and version compatibility. Ensure that your chosen SDK supports direct mode and use the appropriate version.

In summary, when choosing a connectivity mode for your native applications using Azure Cosmos DB, consider your specific requirements in terms of performance, control, and features. Gateway mode is recommended for most scenarios, providing simplicity, security, and ease of use. Direct mode offers more control but requires additional setup and considerations. Finally, consult the official Azure Cosmos DB documentation and SDK documentation for detailed guidance on choosing and configuring the appropriate connectivity mode for your application.