Previous

Next

Exercise - Define child resources

Completed

Note

The first time you activate a sandbox and accept the terms, your Microsoft account is associated with a new Azure directory named Microsoft Learn Sandbox. You're also added to a special subscription named Concierge Subscription.

You're starting to work on your R&D team's requests, and you decide to start by building an Azure Cosmos DB database for the toy drone's test data. In this exercise, you create the Azure Cosmos DB account and two child resources, one by using the parent property and the other as a nested resource.

During the process, you:

• Create a Bicep file that deploys a Cosmos DB account.
• Add a database and container, which are child resources of the Cosmos DB account.
• Deploy the template and verify the deployment.

This exercise uses the Bicep extension for Visual Studio Code. Be sure to install this extension in Visual Studio Code.

Create a Bicep template that contains an Azure Cosmos DB account

First, you create a new Bicep template with an Azure Cosmos DB account. To do so:

1. Open Visual Studio Code.

2. Create a new file called main.bicep.

3. Save the empty file so that Visual Studio Code loads the Bicep tooling.

   You can either select File > Save As or press Ctrl+S in Windows (⌘+S on macOS). Be sure to remember where you saved the file. For example, you might want to create a scripts folder to save it in.

4. Add the following content to the file. It's a good idea to enter it manually rather than copy and paste it. That way, you can see how the tooling helps you write your Bicep files.

   param cosmosDBAccountName string = 'toyrnd-${uniqueString(resourceGroup().id)}'
   param location string = resourceGroup().location
   
   resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2020-04-01' = {
     name: cosmosDBAccountName
     location: location
     properties: {
       databaseAccountOfferType: 'Standard'
       locations: [
         {
           locationName: location
         }
       ]
     }
   }
   

   Tip

   Bicep is strict about where you put line breaks, so be sure to add line breaks only where shown here.

   This Bicep template deploys an Azure Cosmos DB account that is the parent resource you build upon in the next section.

5. Save the changes to the file.

Add a database

Next, you create the database, which is a child resource of the Azure Cosmos DB account.

1. At the top of the file, between the two existing parameters, add the following parameter:

   param cosmosDBDatabaseThroughput int = 400
   

2. Under the parameter declarations, add the following variable:

   var cosmosDBDatabaseName = 'FlightTests'
   

3. Add the following resource definition at the bottom of the file, below the Azure Cosmos DB account resource definition.

   resource cosmosDBDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2020-04-01' = {
     parent: cosmosDBAccount
     name: cosmosDBDatabaseName
     properties: {
       resource: {
         id: cosmosDBDatabaseName
       }
       options: {
         throughput: cosmosDBDatabaseThroughput
       }
     }
   }
   

   Notice that this code deploys the database, which is a child resource, by using the parent property. Also notice that the code uses the fully qualified resource type, with the API version specified explicitly.

4. Save the changes to the file.

Add a container

Now you add another child resource. This time, you add it as a nested resource instead of using the parent property.

1. Near the top of the file, below the cosmosDBDatabaseName variable definition, add the following variables:

   var cosmosDBContainerName = 'FlightTests'
   var cosmosDBContainerPartitionKey = '/droneId'
   

2. Near the bottom of the file, within the database resource definition and before its closing brace (}), add the following nested resource definition:

   resource container 'containers' = {
     name: cosmosDBContainerName
     properties: {
       resource: {
         id: cosmosDBContainerName
         partitionKey: {
           kind: 'Hash'
           paths: [
             cosmosDBContainerPartitionKey
           ]
         }
       }
       options: {}
     }
   }
   

   Notice that you used a short resource type, containers, because Bicep understands that it belongs under the parent resource type. Bicep knows that the fully qualified resource type is Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers. You didn't't specify an API version, so Bicep uses the version from the parent resource, 2020-04-01.

   After you're finished, your complete Bicep template should look like this example:

   param cosmosDBAccountName string = 'toyrnd-${uniqueString(resourceGroup().id)}'
   param cosmosDBDatabaseThroughput int = 400
   param location string = resourceGroup().location
   
   var cosmosDBDatabaseName = 'FlightTests'
   var cosmosDBContainerName = 'FlightTests'
   var cosmosDBContainerPartitionKey = '/droneId'
   
   resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2020-04-01' = {
     name: cosmosDBAccountName
     location: location
     properties: {
       databaseAccountOfferType: 'Standard'
       locations: [
         {
           locationName: location
         }
       ]
     }
   }
   
   resource cosmosDBDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2020-04-01' = {
     parent: cosmosDBAccount
     name: cosmosDBDatabaseName
     properties: {
       resource: {
         id: cosmosDBDatabaseName
       }
       options: {
         throughput: cosmosDBDatabaseThroughput
       }
     }
   
     resource container 'containers' = {
       name: cosmosDBContainerName
       properties: {
         resource: {
           id: cosmosDBContainerName
           partitionKey: {
             kind: 'Hash'
             paths: [
               cosmosDBContainerPartitionKey
             ]
           }
         }
         options: {}
       }
     }
   }
   

3. Save the changes to the file.

Deploy the template to Azure

To deploy this template to Azure, you need to sign in to your Azure account from the Visual Studio Code terminal. Be sure you've installed the Azure CLI, and remember to sign in with the same account that you used to activate the sandbox.

1. On the Terminal menu, select New Terminal. The terminal window usually opens in the lower half of your screen.

2. If the shell shown on the right side of the terminal window is bash, the correct shell is open and you can skip to the next section.

   

3. If a shell other than bash appears, select the shell dropdown arrow, and then select Git Bash.

   

4. In the list of terminal shells, select bash.

   

5. In the terminal, go to the directory where you saved your template. For example, if you saved your template to the templates folder, you can use this command:

   cd templates
   

Install Bicep

Run the following command to ensure you have the latest version of Bicep:

az bicep install && az bicep upgrade

Sign in to Azure

1. In the Visual Studio Code terminal, sign in to Azure by running the following command:

   az login
   

2. In the browser that opens, sign in to your Azure account.

   The Visual Studio Code terminal displays a list of the subscriptions associated with this account.

3. Set the default subscription for all of the Azure CLI commands that you run in this session.

   az account set --subscription "Concierge Subscription"
   

   Note

   If you've used more than one sandbox recently, the terminal might display more than one instance of Concierge Subscription. In this case, use the next two steps to set one as the default subscription. If the preceding command was successful, and only one Concierge Subscription is listed, skip the next two steps.

4. Get the Concierge Subscription IDs.

    az account list \
      --refresh \
      --query "[?contains(name, 'Concierge Subscription')].id" \
      --output table
   

5. Set the default subscription by using the subscription ID. Replace {your subscription ID} with the latest Concierge Subscription ID.

   az account set --subscription {your subscription ID}
   

Set the default resource group

When you use the Azure CLI, you can set the default resource group and omit the parameter from the rest of the Azure CLI commands in this exercise. Set the default to the resource group that's created for you in the sandbox environment.

az configure --defaults group="<rgn>[sandbox resource group name]</rgn>"

Deploy the template to Azure

Run the following code from the terminal in Visual Studio Code to deploy the Bicep template to Azure. This operation can take a minute or two to complete, before you see a successful deployment.

az deployment group create --template-file main.bicep

To deploy this template to Azure, sign in to your Azure account from the Visual Studio Code terminal. Be sure you've installed Azure PowerShell, and sign in to the same account that activated the sandbox.

1. On the Terminal menu, select New Terminal. The terminal window usually opens in the lower half of your screen.

2. If the shell shown on the right side of the terminal window is powershell or pwsh, the correct shell is open, and you can skip to the next section.

   

3. If a shell other than powershell or pwsh appears, select the shell dropdown arrow, and then select PowerShell.

   

4. In the list of terminal shells, select powershell or pwsh.

   

5. In the terminal, go to the directory where you saved your template. For example, if you saved your template in the templates folder, you can use this command:

   Set-Location -Path templates
   

Install the Bicep CLI

To use Bicep from Azure PowerShell, install the Bicep CLI.

Sign in to Azure by using Azure PowerShell

1. In the Visual Studio Code terminal, run the following command:

   Connect-AzAccount
   

   A browser opens so that you can sign in to your Azure account.

2. After you've signed in to Azure, the terminal displays a list of the subscriptions associated with this account.

   If you've activated the sandbox, a subscription named Concierge Subscription is displayed. Use it for the rest of the exercise.

3. Set the default subscription for all of the Azure PowerShell commands that you run in this session.

   $context = Get-AzSubscription -SubscriptionName 'Concierge Subscription'
   Set-AzContext $context
   

   Note

   If you've used more than one sandbox recently, the terminal might display more than one instance of Concierge Subscription. In this case, use the next two steps to set one as the default subscription. If the preceding command was successful, and only one Concierge Subscription is listed, skip the next two steps.

4. Get the subscription ID. Running the following command lists your subscriptions and their IDs. Look for Concierge Subscription, and then copy the ID from the second column. It looks something like cf49fbbc-217c-4eb6-9eb5-a6a6c68295a0.

   Get-AzSubscription
   

5. Change your active subscription to Concierge Subscription. Be sure to replace {Your subscription ID} with the one that you copied.

   $context = Get-AzSubscription -SubscriptionId {Your subscription ID}
   Set-AzContext $context
   

Set the default resource group

You can set the default resource group and omit the parameter from the rest of the Azure PowerShell commands in this exercise. Set this default to the resource group created for you in the sandbox environment.

Set-AzDefault -ResourceGroupName <rgn>[sandbox resource group name]</rgn>

Deploy the template to Azure

Deploy the template to Azure by using the following Azure PowerShell command in the terminal. This operation can take a minute or two to complete, before you see a successful deployment.

New-AzResourceGroupDeployment -TemplateFile main.bicep

Verify the deployment

1. Go to the Azure portal and make sure you're in the sandbox subscription:

   1. Select your avatar in the upper-right corner of the page.

   2. Select Switch directory. In the list, choose the Microsoft Learn Sandbox directory.

2. On the home page, select Resource groups. The Resource groups pane appears.

3. Select [sandbox resource group name].

4. In Overview, you can see that one deployment succeeded.

   

5. Select 1 Succeeded to see the details of the deployment.

   

6. Select the deployment called main to see what resources were deployed, and then select Deployment details to expand it. In this case, there's a Cosmos DB account, database, and container listed.

   

7. Leave the page open in your browser, so you can check on deployments again later.

Continue