Merge pull request #106431 from deborahc/dech-cosmos-free-tier-docs

Docs for Cosmos DB free tier

Author: PMEds28

articles/cosmos-db/concepts-limits.md

@@ -182,6 +182,20 @@ The following table lists the limits for the [Try Azure Cosmos DB for Free](http
 
 Try Cosmos DB supports global distribution in only the Central US, North Europe, and Southeast Asia regions. Azure support tickets can't be created for Try Azure Cosmos DB accounts. However, support is provided for subscribers with existing support plans.
 
+## Free tier account limits
+The following table lists the limits for [Azure Cosmos DB free tier accounts.](optimize-dev-test.md#azure-cosmos-db-free-tier)
+
+| Resource | Default limit |
+| --- | --- |
+| Number of free tier accounts per Azure subscription | 1 |
+| Duration of free-tier discount | Lifetime of the account. Must opt-in during account creation. |
+| Maximum RU/s for free | 400 RU/s |
+| Maximum storage for free | 5 GB |
+| Maximum number of shared throughput databases | 5 |
+| Maximum number of containers in a shared throughput database | 25 <br>In free tier accounts, the minimum RU/s for a shared throughput database with up to 25 containers is 400 RU/s. |
+
+  In addition to the above, the [Per-account limits](#per-account-limits) also apply to free tier accounts.
+
 ## Next steps
 
 Read more about Cosmos DB's core concepts [global distribution](distribute-data-globally.md) and [partitioning](partitioning-overview.md) and [provisioned throughput](request-units.md).

articles/cosmos-db/introduction.md

@@ -15,7 +15,7 @@ Today’s applications are required to be highly responsive and always online. T
 
 Azure Cosmos DB is Microsoft's globally distributed, multi-model database service. With a click of a button, Cosmos DB enables you to elastically and independently scale throughput and storage across any number of Azure regions worldwide. You can elastically scale throughput and storage, and take advantage of fast, single-digit-millisecond data access using your favorite API including SQL, MongoDB, Cassandra, Tables, or Gremlin. Cosmos DB provides comprehensive [service level agreements](https://aka.ms/acdbsla) (SLAs) for throughput, latency, availability, and consistency guarantees, something no other database service offers.
 
-You can [Try Azure Cosmos DB for Free](https://azure.microsoft.com/try/cosmosdb/) without an Azure subscription, free of charge and commitments.
+You can [Try Azure Cosmos DB for Free](https://azure.microsoft.com/try/cosmosdb/) without an Azure subscription, free of charge and commitments or use the [Azure Cosmos DB free tier](optimize-dev-test.md#azure-cosmos-db-free-tier) to get an account with the first 400 RU/s and 5 GB of storage free.
 
 > [!div class="nextstepaction"]
 > [Try Azure Cosmos DB for Free](https://azure.microsoft.com/try/cosmosdb/)

articles/cosmos-db/optimize-dev-test.md

@@ -10,20 +10,29 @@ ms.date: 05/21/2019
 
 # Optimize development and testing cost in Azure Cosmos DB
 
-This article describes the different options to use Azure Cosmos DB for development and testing for free of cost.
+This article describes the different options to use Azure Cosmos DB for development and testing for free of cost, as well as techniques to optimize cost in development or test accounts.
 
 ## Azure Cosmos DB emulator (locally downloadable version)
 
 [Azure Cosmos DB emulator](local-emulator.md) is a local downloadable version that mimics the Azure Cosmos DB cloud service. You can write and test code that uses the Azure Cosmos DB APIs even if you have no network connection and without incurring any costs. Azure Cosmos DB emulator provides a local environment for development purposes with high fidelity to the cloud service. You can develop and test your application locally, without creating an Azure subscription. When you're ready to deploy your application to the cloud, update the connection string to connect to the Azure Cosmos DB endpoint in the cloud, no other modifications are needed. You can also [set up a CI/CD pipeline with the Azure Cosmos DB emulator](tutorial-setup-ci-cd.md) build task in Azure DevOps to run tests. You can get started by visiting the [Azure Cosmos DB emulator](local-emulator.md) article.
 
+## Azure Cosmos DB free tier 
+Azure Cosmos DB free tier makes it easy to get started, develop and test your applications, or even run small production workloads for free. When free tier is enabled on an account, you'll get the first 400 RU/s and 5 GB of storage in the account free. You can also create a shared throughput database with 25 containers that share 400 RU/s at the database level, all covered by free tier (limit 5 shared throughput databases in a free tier account). Free tier lasts indefinitely for the lifetime of the account and comes with all the [benefits and features](introduction.md#key-benefits) of a regular Azure Cosmos DB account, including unlimited storage and throughput (RU/s), SLAs, high availability, turnkey global distribution in all Azure regions, and more. You can have up to one free tier account per Azure subscription and must opt-in when creating the account. To get started, [create a new account with free tier enabled](create-cosmosdb-resources-portal.md). See the [pricing page](https://azure.microsoft.com/pricing/details/cosmos-db/) for more details. 
+
 ## Try Azure Cosmos DB for free
 
-[Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) is a free of charge experience that allows you to create database and collections, and experiment with Azure Cosmos DB in the cloud. You don't have to sign-up for Azure or pay any cost. The try Azure Cosmos DB accounts are available for a limited time, currently 30 days. You can renew them at any time. Try Azure Cosmos DB accounts makes it easy to evaluate Azure Cosmos DB, build and test an application by using the Quickstarts or tutorials. You can create a demo or perform unit testing without incurring any costs. By using try Azure Cosmos DB for free accounts, you can evaluate Azure Cosmos DB’s premium capabilities for free, including turnkey global distribution, SLAs, and consistency models. You can create a database with a maximum of 25 Azure Cosmos containers and 10,000 RU/s of throughput. You can run the sample application without subscribing to an Azure account or using your credit card. With Try Azure Cosmos DB for free, you can create a multi-region Azure Cosmos account and run an app on it in just a few minutes. To get started, see [Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) page.
+[Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) is a free of charge experience that allows you to experiment with Azure Cosmos DB in the cloud without signing up for an Azure account or using your credit card. The Try Azure Cosmos DB accounts are available for a limited time, currently 30 days. You can renew them at any time. Try Azure Cosmos DB accounts makes it easy to evaluate Azure Cosmos DB, build and test an application or use the Quickstarts or tutorials. You can also create a demo, perform unit testing, or even create a multi-region account and run an app on it without incurring any costs. In a Try Azure Cosmos DB account, you can have one shared throughput database with a maximum of 25 containers and 20,000 RU/s of throughput, or one container with up to 5000 RU/s. To get started, see [Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) page.
 
-## Azure Free Account
+## Azure free account
 
 Azure Cosmos DB is included in the [Azure free account](https://azure.microsoft.com/free), which offers Azure credits and resources for free for a certain time period. Specifically for Azure Cosmos DB, this free account offers 5-GB storage and 400 RUs of provisioned throughput for the entire year. This experience enables any developer to easily test the features of Azure Cosmos DB or integrate it with other Azure services at zero cost. With Azure free account, you get a $200 credit to spend in the first 30 days. You won’t be charged, even if you start using the services until you choose to upgrade. To get started, visit [Azure free account](https://azure.microsoft.com/free) page.
 
+## Use shared throughput databases
+
+In a [shared throughput database](set-throughput.md#set-throughput-on-a-database), all containers inside the database share the provisioned throughput (RU/s) of the database. For example, if you provision a database with 400 RU/s and have four containers, all four containers will share the 400 RU/s. In a development or testing environment, where each container may be be accessed less frequently and thus require lower than the minimum of 400 RU/s,  putting containers in a shared throughput database can help optimize cost. 
+
+For example, suppose your development or test account has four containers. If you create four containers with dedicated throughput (minimum of 400 RU/s), your total RU/s will be 1600 RU/s. In contrast, if you create a shared throughput database (minimum 400 RU/s) and put your containers there, your total RU/s will be just 400 RU/s. In general, shared throughput databases are great for scenarios where you don't need guaranteed throughput on any individual container.  Learn more about [shared throughput databases.](set-throughput.md#set-throughput-on-a-database)
+
 ## Next steps
 
 You can get started with using the emulator or the free Azure Cosmos DB accounts with the following articles:

articles/cosmos-db/understand-your-bill.md

@@ -194,6 +194,38 @@ The total monthly bill will be (assuming 30 days/720 hours in a month) will be c
 | | |Throughput bill for 2 additional regions: East US, North Europe (all regions are writable)  |`(1 + 1) * (70 K RU/sec /100 * $0.016) * 20 hours = $448`  |$224  |
 || |**Total Monthly Cost**  | |**$38,688**   |
 
+## Billing examples with free tier accounts
+With Azure Cosmos DB free tier, you'll get the first 400 RU/s and 5 GB of storage in your account for free, applied at the account level. Any RU/s and storage beyond 400 RU/s and 5 GB will be billed at the regular pricing rates per the pricing page. On the bill, you will not see a charge or line item for the free 400 Ru/s and 5 GB, only the RU/s and storage beyond what is covered by free tier. 
+The 400 RU/s applies to any type of RU/s - provisioned throughput, autopilot (preview), and multi-master.  
+
+### Billing example - container or database with provisioned throughput
+- Let's suppose we create a database or container in a free tier account with 400 RU/s and 5 GB of storage.
+- Your bill will not show any charge for this resource. Your hourly and monthly cost will be $0.
+- Now, let's suppose in the same account, we add another database or container with 1000 RU/s and 10 GB of storage.
+- Your bill will now show a charge for the 1000 RU/s and 10 GB of storage. 
+
+### Billing example - container or database with autopilot throughput (preview)
+- Let's suppose in a free tier account, we create a database or container with autopilot enabled, with a maximum RU/s of 4000 RU/s. This resource will automatically scale between 400 RU/s - 4000 RU/s. 
+- Suppose in hour 1 through hour 10, the resource is at the minimum of 400 RU/s. During hour 11, the resource scales up to 1000 RU/s and then back down to 400 RU/s within the hour.
+- In hours 1 through 10, you will be billed $0 for throughput, as the 400 RU/s were covered by free tier. 
+- In hour 11, you will be billed for an effective 1000 RU/s - 400 RU/s = 600 RU/s, as this is the highest RU/s in the hour. This will be 6 units of 100 RU/s for the hour, so the total throughput cost for the hour will be 6 units * $0.012 = $0.072. 
+- Any storage beyond the first 5 GB will be billed at normal storage rates. 
+
+### Billing example - multi-region, single write region account
+- Let's suppose in a free tier account, we create a database or container with 1200 RU/s and 10 GB of storage. We replicate the account to 3 regions, and we have a single-master (single write-region) account.
+- In total, without free tier, we would be billed for 3 * 1200 RU/s = 3600 RU/s and 3 * 10 GB = 30 GB of storage.
+- With the free tier discount, after removing 400 RU/s and 5 GB of storage, we will be billed for an effective 3200 RU/s (32 units) of provisioned throughput at the single write region rate and 25 GB of storage.
+- The monthly cost for RU/s would be: 32 units * $0.008 * 24 hours * 31 days = $190.46. The monthly cost for storage would be: 25 GB * 0.25 / GB = $6.25. The total cost would be $190.46 + $6.25 = $196.71.
+- Note: if the unit price for RU/s or storage differs in the regions, the free tier 400 RU/s and 5 GB will reflect the rates of the account the region was created in.
+
+### Billing example - multi-region, multi-master (multiple write region) account
+
+This example reflects [multi-master pricing](https://azure.microsoft.com/pricing/details/cosmos-db/) for accounts created after December 1, 2019. 
+- Let's suppose in a free tier account, we create a database or container with 1200 RU/s and 10 GB of storage. We replicate the account to 3 regions, and we have a multi-master (multiple write region) account. 
+- In total, without free tier, we would be billed for 3 * 1200 RU/s = 3600 RU/s and 3 * 10 GB = 30 GB of storage.
+- With the free tier discount, after removing 400 RU/s and 5 GB of storage, we will be billed for an effective 3200 RU/s (32 units) of provisioned throughput at the multiple write region rate and 25 GB of storage.
+- The monthly cost for RU/s would be: 32 units * $0.016 * 24 hours * 31 days = $380.93. The monthly cost for storage would be: 25 GB * 0.25 / GB = $6.25. The total cost would be $380.93 + $6.25 = $387.18.
+
 ## Proactively estimating your monthly bill  
 
 Let’s consider another example, where you want to proactively estimate your bill before the month’s end. You can estimate your bill as follows:

includes/cosmos-db-create-dbaccount.md

@@ -23,9 +23,15 @@
     |Resource Group|Resource group name|Select a resource group, or select **Create new**, then enter a unique name for the new resource group. |
     |Account Name|A unique name|Enter a name to identify your Azure Cosmos account. Because *documents.azure.com* is appended to the name that you provide to create your URI, use a unique name.<br><br>The name can only contain lowercase letters, numbers, and the hyphen (-) character. It must be between 3-31 characters in length.|
     |API|The type of account to create|Select **Core (SQL)** to create a document database and query by using SQL syntax. <br><br>The API determines the type of account to create. Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Currently, you must create a separate account for each API. <br><br>[Learn more about the SQL API](../articles/cosmos-db/documentdb-introduction.md).|
+    |Apply Free Tier Discount|Apply or Do not apply|With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Learn more about [free tier](https://azure.microsoft.com/pricing/details/cosmos-db/).|
     |Location|The region closest to your users|Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data.|
+    |Account Type|Production or Non-Production|Select **Production** if the account will be used for a production workload. Select **Non-Production** if the account will be used for non-production, e.g. development, testing, QA, or staging. This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. You can change this value anytime.|
 
-   ![The new account page for Azure Cosmos DB](./media/cosmos-db-create-dbaccount/azure-cosmos-db-create-account.png)
+
+> [!NOTE]
+> You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.
+   
+   ![The new account page for Azure Cosmos DB](./media/cosmos-db-create-dbaccount/azure-cosmos-db-create-new-account-detail.png)
 
 1. Select **Review + create**. You can skip the **Network** and **Tags** sections.
 

includes/cosmos-db-emulator-docdb-api.md

@@ -19,4 +19,4 @@ ms.author: sngun
 ms.custom: "include file"
 ---
 
-You can [Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) without an Azure subscription, free of charge and commitments. Or, you can use the [Azure Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator) with a URI of `https://localhost:8081`. For the key to use with the emulator, see [Authenticating requests](../articles/cosmos-db/local-emulator.md#authenticating-requests).
+You can [Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) without an Azure subscription, free of charge and commitments, or create an [Azure Cosmos DB free tier account](../articles/cosmos-db/optimize-dev-test.md#azure-cosmos-db-free-tier), with the first 400 RU/s and 5 GB of storage for free. You can also use the [Azure Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator) with a URI of `https://localhost:8081`. For the key to use with the emulator, see [Authenticating requests](../articles/cosmos-db/local-emulator.md#authenticating-requests).