Tutorial: Configure Azure Cosmos DB accounts using Ansible

Article
10/27/2022

Important

Ansible 2.8 (or later) is required to run the sample playbooks in this article.

Azure Cosmos DB is a database service that supports several database types. These databases types include document, key-value, wide-column, and graph. Using Ansible, you can automate the deployment and configuration of resources in your environment.

In this article, you learn how to:

Create an account
Retrieve the account keys
Delete the account

Prerequisites

Azure subscription: If you don't have an Azure subscription, create a free account before you begin.

Azure service principal: Create a service principal, making note of the following values: appId, displayName, password, and tenant.

Install Ansible: Do one of the following options:
- Install and configure Ansible on a Linux virtual machine
- Configure Azure Cloud Shell and - if you don't have access to a Linux virtual machine - create a virtual machine with Ansible.

Create a random postfix

The sample playbook snippet creates a random postfix. The postfix is used as part of the Azure Cosmos DB account name.

  - hosts: localhost
    tasks:
      - name: Prepare random postfix
        set_fact:
          rpfx: "{{ 1000 | random }}"
        run_once: yes

Create resource group

The sample playbook snippet creates an Azure resource group. A resource group is a logical container in which Azure resources are deployed and managed.

  - name: Create a resource group
    azure_rm_resourcegroup:
      name: "{{ resource_group }}"
      location: "{{ location }}"

Create virtual network and subnet

The following code creates a virtual network and subnet for the Azure Cosmos DB account:

  - name: Create virtual network
    azure_rm_virtualnetwork:
      resource_group: "{{ resource_group }}"
      name: "{{ vnet_name }}"
      address_prefixes_cidr:
        - 10.1.0.0/16
        - 172.100.0.0/16
      dns_servers:
        - 127.0.0.1
        - 127.0.0.3

  - name: Add subnet
    azure_rm_subnet:
      name: "{{ subnet_name }}"
      virtual_network_name: "{{ vnet_name }}"
      resource_group: "{{ resource_group }}"
      address_prefix_cidr: "10.1.0.0/24"

Create an Azure Cosmos DB account

The following code creates the Azure Cosmos DB account:

  - name: Create instance of Cosmos DB Account
    azure_rm_cosmosdbaccount:
      resource_group: "{{ resource_group }}"
      name: "{{ cosmosdbaccount_name }}"
      location: eastus
      kind: global_document_db
      geo_rep_locations:
        - name: eastus
          failover_priority: 0
        - name: westus
          failover_priority: 1
      database_account_offer_type: Standard
      is_virtual_network_filter_enabled: yes
      virtual_network_rules:
        - subnet:
            resource_group: "{{ resource_group }}"
            virtual_network_name: "{{ vnet_name }}"
            subnet_name: "{{ subnet_name }}"
          ignore_missing_vnet_service_endpoint: yes
      enable_automatic_failover: yes

The account creation takes a few minutes to complete.

Retrieve the keys

The following code fetches the keys to use in your app.

  - name: Get Cosmos DB Account facts with keys
    azure_rm_cosmosdbaccount_facts:
      resource_group: "{{ resource_group }}"
      name: "{{ cosmosdbaccount_name }}"
      retrieve_keys: all
    register: output

  - name: Display Cosmos DB Acccount facts output
    debug:
      var: output

Delete the Azure Cosmos DB account

Finally, the last snippet shows how to delete an Azure Cosmos DB account.

  - name: Delete instance of Cosmos DB Account
    azure_rm_cosmosdbaccount:
      resource_group: "{{ resource_group }}"
      name: "{{ cosmosdbaccount_name }}"
      state: absent

Get the sample playbook

There are two ways to get the complete sample playbook:

Download the playbook and save it to cosmosdb.yml.
Create a new file named cosmosdb.yml and copy the following contents into it:

---
- hosts: localhost
  tasks:
    - name: Prepare random postfix
      set_fact:
        rpfx: "{{ 1000 | random }}"
      run_once: yes

- hosts: localhost
#  roles:
#    - azure.azure_preview_modules
  vars:
    resource_group: "{{ resource_group_name }}"
    location: eastus
    vnet_name: myVirtualNetwork
    subnet_name: mySubnet
    cosmosdbaccount_name: cosmos{{ rpfx }}

  tasks:
    - name: Create a resource group
      azure_rm_resourcegroup:
        name: "{{ resource_group }}"
        location: "{{ location }}"

    - name: Create virtual network
      azure_rm_virtualnetwork:
        resource_group: "{{ resource_group }}"
        name: "{{ vnet_name }}"
        address_prefixes_cidr:
          - 10.1.0.0/16
          - 172.100.0.0/16
        dns_servers:
          - 127.0.0.1
          - 127.0.0.3

    - name: Add subnet
      azure_rm_subnet:
        name: "{{ subnet_name }}"
        virtual_network_name: "{{ vnet_name }}"
        resource_group: "{{ resource_group }}"
        address_prefix_cidr: "10.1.0.0/24"

    - name: Create instance of Cosmos DB Account
      azure_rm_cosmosdbaccount:
        resource_group: "{{ resource_group }}"
        name: "{{ cosmosdbaccount_name }}"
        location: eastus
        kind: global_document_db
        geo_rep_locations:
          - name: eastus
            failover_priority: 0
          - name: westus
            failover_priority: 1
        database_account_offer_type: Standard
        is_virtual_network_filter_enabled: yes
        virtual_network_rules:
          - subnet:
              resource_group: "{{ resource_group }}"
              virtual_network_name: "{{ vnet_name }}"
              subnet_name: "{{ subnet_name }}"
            ignore_missing_vnet_service_endpoint: yes
        enable_automatic_failover: yes

    - name: Get Cosmos DB Account facts with keys
      azure_rm_cosmosdbaccount_facts:
        resource_group: "{{ resource_group }}"
        name: "{{ cosmosdbaccount_name }}"
        retrieve_keys: all
      register: output

    - name: Display Cosmos DB Account facts output
      debug:
        var: output

    - name: Delete instance of Cosmos DB Account
      azure_rm_cosmosdbaccount:
        resource_group: "{{ resource_group }}"
        name: "{{ cosmosdbaccount_name }}"
        state: absent

Run the sample playbook

In this section, run the playbook to test various features shown in this article.

Before running the playbook, make the following changes:

In the vars section, replace the {{ resource_group_name }} placeholder with the name of your resource group.
Ensure that the `cosmosdbaccount_name contains only lowercase characters and is globally unique.

Run the playbook using ansible-playbook

ansible-playbook cosmosdb.yml

Clean up resources

Save the following code as delete_rg.yml.

---
- hosts: localhost
  tasks:
    - name: Deleting resource group - "{{ name }}"
      azure_rm_resourcegroup:
        name: "{{ name }}"
        state: absent
      register: rg
    - debug:
        var: rg

Run the playbook using the ansible-playbook command. Replace the placeholder with the name of the resource group to be deleted. All resources within the resource group will be deleted.
```
ansible-playbook delete_rg.yml --extra-vars "name=<resource_group>"
```
Key points:
- Because of the register variable and debug section of the playbook, the results display when the command finishes.

Run az group delete to delete the resource group. All resources within the resource group will be deleted.
```
az group delete --name <resource_group>
```
Verify that the resource group was deleted by using az group show.
```
az group show --name <resource_group>
```

Run Remove-AzResourceGroup to delete the resource group. All resources within the resource group will be deleted.
```
Remove-AzResourceGroup -Name <resource_group>
```
Verify that the resource group was deleted by using Get-AzResourceGroup.
```
Get-AzResourceGroup -Name <resource_group>
```

Next steps

Ansible on Azure