Skip to content

Commit ad8eea1

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #211632 from GinSiuCheng/terraform-samples-cosmosdb
Terraform samples for Cosmos DB SQL API
2 parents dcec4b7 + b9b0fa7 commit ad8eea1

File tree

4 files changed

+277
-0
lines changed

4 files changed

+277
-0
lines changed

‎articles/cosmos-db/sql/TOC.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424
- name: Create resources - JSON template
2525
displayName: ARM, Resource Manager, Template, JSON
2626
href: quick-create-template.md
27+
- name: Create resources - Terraform template
28+
displayName: ARM, Resource Manager, Template, Terraform
29+
href: quick-create-terraform.md
2730
- name: Tutorials
2831
items:
2932
- name: Create and manage data
@@ -137,6 +140,8 @@
137140
displayName: ARM
138141
- name: Bicep syntax templates
139142
href: bicep-samples.md
143+
- name: Terraform syntax templates
144+
href: terraform-samples.md
140145
- name: Azure Resource Graph queries
141146
href: ../resource-graph-samples.md
142147
- name: Concepts
@@ -1038,6 +1043,9 @@
10381043
- name: Using Resource Manager templates
10391044
href: manage-with-templates.md
10401045
displayName: ARM
1046+
- name: Using Terraform
1047+
href: manage-with-terraform.md
1048+
displayName: Terraform
10411049
- name: Move between regions
10421050
href: ../how-to-move-regions.md
10431051
- name: Prevent changes or deletion

‎articles/cosmos-db/sql/manage-with-terraform.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Create and manage Azure Cosmos DB with terraform
3+
description: Use terraform to create and configure Azure Cosmos DB for Core (SQL) API
4+
author: ginsiucheng
5+
ms.service: cosmos-db
6+
ms.subservice: cosmosdb-sql
7+
ms.topic: how-to
8+
ms.date: 09/16/2022
9+
ms.author: gicheng
10+
ms.reviewer: mjbrown
11+
---
12+
13+
# Manage Azure Cosmos DB Core (SQL) API resources with terraform
14+
15+
[!INCLUDE[appliesto-sql-api](../includes/appliesto-sql-api.md)]
16+
17+
In this article, you learn how to use terraform to deploy and manage your Azure Cosmos DB accounts, databases, and containers.
18+
19+
This article shows terraform samples for Core (SQL) API accounts.
20+
21+
> [!IMPORTANT]
22+
>
23+
> * Account names are limited to 44 characters, all lowercase.
24+
> * To change the throughput (RU/s) values, redeploy the terraform file with updated RU/s.
25+
> * When you add or remove locations to an Azure Cosmos account, you can't simultaneously modify other properties. These operations must be done separately.
26+
> * To provision throughput at the database level and share across all containers, apply the throughput values to the database options property.
27+
28+
To create any of the Azure Cosmos DB resources below, copy the example into a new terraform file (main.tf) or alternatively, have 2 separate files for resources (main.tf) and variables (variables.tf). Be sure to include the azurerm provider either in the main terraform file or split out to a separate providers file. All examples can be found on the [terraform samples repository](https://github.com/Azure/terraform).
29+
30+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-autoscale/providers.tf":::
31+
32+
<a id="create-autoscale"></a>
33+
34+
## Azure Cosmos account with autoscale throughput
35+
36+
Create an Azure Cosmos account in two regions with options for consistency and failover, with database and container configured for autoscale throughput that has most index policy options enabled.
37+
38+
### main.tf
39+
40+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-autoscale/main.tf":::
41+
42+
### variables.tf
43+
44+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-autoscale/variables.tf":::
45+
46+
<a id="create-analytical-store"></a>
47+
48+
## Azure Cosmos account with analytical store
49+
50+
Create an Azure Cosmos account in one region with a container with Analytical TTL enabled and options for manual or autoscale throughput.
51+
52+
### main.tf
53+
54+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-analyticalstore/main.tf":::
55+
56+
### variables.tf
57+
58+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-analyticalstore/variables.tf":::
59+
60+
<a id="create-manual"></a>
61+
62+
## Azure Cosmos account with standard provisioned throughput
63+
64+
Create an Azure Cosmos account in two regions with options for consistency and failover, with database and container configured for standard throughput that has most policy options enabled.
65+
66+
### main.tf
67+
68+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-manualscale/main.tf":::
69+
70+
### variables.tf
71+
72+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-manualscale/variables.tf":::
73+
74+
<a id="create-sproc"></a>
75+
76+
## Azure Cosmos DB container with server-side functionality
77+
78+
Create an Azure Cosmos account, database and container with a stored procedure, trigger, and user-defined function.
79+
80+
### main.tf
81+
82+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-serverside-functionality/main.tf":::
83+
84+
### variables.tf
85+
86+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-serverside-functionality/variables.tf":::
87+
88+
<a id="create-rbac"></a>
89+
90+
## Azure Cosmos DB account with Azure AD and RBAC
91+
92+
Create an Azure Cosmos account, a natively maintained Role Definition, and a natively maintained Role Assignment for an Azure Active Directory identity.
93+
94+
### main.tf
95+
96+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-aad-rbac/main.tf":::
97+
98+
### variables.tf
99+
100+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-aad-rbac/variables.tf":::
101+
102+
<a id="free-tier"></a>
103+
104+
## Free tier Azure Cosmos DB account
105+
106+
Create a free-tier Azure Cosmos account and a database with shared throughput that can be shared with up to 25 containers.
107+
108+
### main.tf
109+
110+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-free-tier/main.tf":::
111+
112+
### variables.tf
113+
114+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-free-tier/variables.tf":::
115+
116+
## Next steps
117+
118+
Here are some additional resources:
119+
120+
* [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
121+
* [Terraform Azure Tutorial](https://learn.hashicorp.com/collections/terraform/azure-get-started)
122+
* [Terraform tools](https://www.terraform.io/docs/terraform-tools)
123+
* [Azure Provider Terraform documentation](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
124+
* [Terraform documentation](https://www.terraform.io/docs)

‎articles/cosmos-db/sql/quick-create-terraform.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Quickstart - Create an Azure Cosmos DB and a container using Terraform
3+
description: Quickstart showing how to an Azure Cosmos database and a container using Terraform
4+
author: ginsiucheng
5+
ms.author: gicheng
6+
tags: azure-resource-manager, terraform
7+
ms.service: cosmos-db
8+
ms.subservice: cosmosdb-sql
9+
ms.topic: quickstart
10+
ms.date: 09/22/2022
11+
12+
#Customer intent: As a database admin who is new to Azure, I want to use Azure Cosmos DB to store and manage my data.
13+
---
14+
15+
# Quickstart: Create an Azure Cosmos DB and a container using Terraform
16+
17+
[!INCLUDE[appliesto-sql-api](../includes/appliesto-sql-api.md)]
18+
19+
Azure Cosmos DB is Microsoft’s fast NoSQL database with open APIs for any scale. You can use Azure Cosmos DB to quickly create and query key/value databases, document databases, and graph databases. Without a credit card or an Azure subscription, you can set up a free [Try Azure Cosmos DB account](https://aka.ms/trycosmosdb). This quickstart focuses on the process of deployments via Terraform to create an Azure Cosmos database and a container within that database. You can later store data in this container.
20+
21+
## Prerequisites
22+
23+
An Azure subscription or free Azure Cosmos DB trial account
24+
25+
- [!INCLUDE [quickstarts-free-trial-note](../../../includes/quickstarts-free-trial-note.md)]
26+
27+
Terraform should be installed on your local computer. Installation instructions can be found [here](https://learn.hashicorp.com/tutorials/terraform/install-cli).
28+
29+
## Review the Terraform File
30+
31+
The Terraform files used in this quickstart can be found on the [terraform samples repository](https://github.com/Azure/terraform). Please create the below 3 files: providers.tf, main.tf and variables.tf. Variables can be set in command line or alternatively with a terraforms.tfvars file.
32+
33+
### Provider Terraform File
34+
35+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-autoscale/providers.tf":::
36+
37+
### Main Terraform File
38+
39+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-manualscale/main.tf":::
40+
41+
### Variables Terraform File
42+
43+
:::code language="terraform" source="~/terraform_samples/quickstart/101-cosmos-db-manualscale/variables.tf":::
44+
45+
46+
Three Cosmos DB resources are defined in the main terraform file.
47+
48+
- [Microsoft.DocumentDB/databaseAccounts](/azure/templates/microsoft.documentdb/databaseaccounts): Create an Azure Cosmos account.
49+
50+
- [Microsoft.DocumentDB/databaseAccounts/sqlDatabases](/azure/templates/microsoft.documentdb/databaseaccounts/sqldatabases): Create an Azure Cosmos database.
51+
52+
- [Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers](/azure/templates/microsoft.documentdb/databaseaccounts/sqldatabases/containers): Create an Azure Cosmos container.
53+
54+
## Deploy via terraform
55+
56+
1. Save the terraform files as main.tf, variables.tf and providers.tf to your local computer.
57+
2. Login to your terminal via Azure CLI or Powershell
58+
3. Deploy via Terraform commands
59+
- terraform init
60+
- terraform plan
61+
- terraform apply
62+
63+
## Validate the deployment
64+
65+
Use the Azure portal, Azure CLI, or Azure PowerShell to list the deployed resources in the resource group.
66+
67+
# [CLI](#tab/CLI)
68+
69+
```azurecli-interactive
70+
az resource list --resource-group "your resource group name"
71+
```
72+
73+
# [PowerShell](#tab/PowerShell)
74+
75+
```azurepowershell-interactive
76+
Get-AzResource -ResourceGroupName "your resource group name"
77+
```
78+
79+
---
80+
81+
## Clean up resources
82+
83+
If you plan to continue working with subsequent quickstarts and tutorials, you might want to leave these resources in place.
84+
When no longer needed, use the Azure portal, Azure CLI, or Azure PowerShell to delete the resource group and its resources.
85+
86+
# [CLI](#tab/CLI)
87+
88+
```azurecli-interactive
89+
az group delete --name "your resource group name"
90+
```
91+
92+
# [PowerShell](#tab/PowerShell)
93+
94+
```azurepowershell-interactive
95+
Remove-AzResourceGroup -Name "your resource group name"
96+
```
97+
98+
---
99+
100+
## Next steps
101+
102+
In this quickstart, you created an Azure Cosmos account, a database and a container via terraform and validated the deployment. To learn more about Azure Cosmos DB and Terraform, continue on to the articles below.
103+
104+
- Read an [Overview of Azure Cosmos DB](../introduction.md).
105+
- Learn more about [Terraform](https://www.terraform.io/intro).
106+
- Learn more about [Azure Terraform Provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs).
107+
- [Manage Cosmos DB with Terraform](manage-with-terraform.md)
108+
- Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
109+
- If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md).
110+
- If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md).

‎articles/cosmos-db/sql/terraform-samples.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Terraform samples for Azure Cosmos DB Core (SQL API)
3+
description: Use Terraform to create and configure Azure Cosmos DB.
4+
author: ginsiucheng
5+
ms.service: cosmos-db
6+
ms.subservice: cosmosdb-sql
7+
ms.topic: conceptual
8+
ms.date: 09/16/2022
9+
ms.author: gicheng
10+
ms.reviewer: mjbrown
11+
---
12+
13+
# Terraform for Azure Cosmos DB
14+
15+
[!INCLUDE[appliesto-sql-api](../includes/appliesto-sql-api.md)]
16+
17+
This article shows Terraform samples for Core (SQL) API accounts.
18+
19+
## Core (SQL) API
20+
21+
|**Sample**|**Description**|
22+
|---|---|
23+
|[Create an Azure Cosmos account, database, container with autoscale throughput](manage-with-terraform.md#create-autoscale) | Create a Core (SQL) API account in two regions, a database and container with autoscale throughput. |
24+
|[Create an Azure Cosmos account, database, container with analytical store](manage-with-terraform.md#create-analytical-store) | Create a Core (SQL) API account in one region with a container configured with Analytical TTL enabled and option to use manual or autoscale throughput. |
25+
|[Create an Azure Cosmos account, database, container with standard (manual) throughput](manage-with-terraform.md#create-manual) | Create a Core (SQL) API account in two regions, a database and container with standard throughput. |
26+
|[Create an Azure Cosmos account, database and container with a stored procedure, trigger and UDF](manage-with-terraform.md#create-sproc) | Create a Core (SQL) API account in two regions with a stored procedure, trigger and UDF for a container. |
27+
|[Create an Azure Cosmos account with Azure AD identity, Role Definitions and Role Assignment](manage-with-terraform.md#create-rbac) | Create a Core (SQL) API account with Azure AD identity, Role Definitions and Role Assignment on a Service Principal. |
28+
|[Create a free-tier Azure Cosmos account](manage-with-terraform.md#free-tier) | Create an Azure Cosmos DB Core (SQL) API account on free-tier. |
29+
30+
## Next steps
31+
32+
Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.
33+
34+
* If all you know is the number of vcores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)
35+
* If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

0 commit comments

Comments
 (0)