Microsoft Azure Guide

Ansible includes a suite of modules for interacting with Azure Resource Manager, giving you the tools to easily createand orchestrate infrastructure on the Microsoft Azure Cloud.

Requirements

Using the Azure Resource Manager modules requires having specific Azure SDK modulesinstalled on the host running Ansible.

  1. $ pip install 'ansible[azure]'

If you are running Ansible from source, you can install the dependencies from theroot directory of the Ansible repo.

  1. $ pip install .[azure]

You can also directly run Ansible in Azure Cloud Shell, where Ansible is pre-installed.

Authenticating with Azure

Using the Azure Resource Manager modules requires authenticating with the Azure API. You can choose from two authentication strategies:

  • Active Directory Username/Password
  • Service Principal Credentials

Follow the directions for the strategy you wish to use, then proceed to Providing Credentials to Azure Modules forinstructions on how to actually use the modules and authenticate with the Azure API.

Using Service Principal

There is now a detailed official tutorial describing how to create a service principal.

After stepping through the tutorial you will have:

  • Your Client ID, which is found in the “client id” box in the “Configure” page of your application in the Azure portal
  • Your Secret key, generated when you created the application. You cannot show the key after creation.If you lost the key, you must create a new one in the “Configure” page of your application.
  • And finally, a tenant ID. It’s a UUID (e.g. ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing yourapplication. You will find it in the URL from within the Azure portal, or in the “view endpoints” of any given URL.

Using Active Directory Username/Password

To create an Active Directory username/password:

  • Connect to the Azure Classic Portal with your admin account
  • Create a user in your default AAD. You must NOT activate Multi-Factor Authentication
  • Go to Settings - Administrators
  • Click on Add and enter the email of the new user.
  • Check the checkbox of the subscription you want to test with this user.
  • Login to Azure Portal with this new user to change the temporary password to a new one. You will not be able to use thetemporary password for OAuth login.

Providing Credentials to Azure Modules

The modules offer several ways to provide your credentials. For a CI/CD tool such as Ansible Tower or Jenkins, you willmost likely want to use environment variables. For local development you may wish to store your credentials in a filewithin your home directory. And of course, you can always pass credentials as parameters to a task within a playbook. Theorder of precedence is parameters, then environment variables, and finally a file found in your home directory.

Using Environment Variables

To pass service principal credentials via the environment, define the following variables:

  • AZURE_CLIENT_ID
  • AZURE_SECRET
  • AZURE_SUBSCRIPTION_ID
  • AZURE_TENANT

To pass Active Directory username/password via the environment, define the following variables:

  • AZURE_AD_USER
  • AZURE_PASSWORD

To pass Active Directory username/password in ADFS via the environment, define the following variables:

  • AZURE_AD_USER
  • AZURE_PASSWORD
  • AZURE_CLIENT_ID
  • AZURE_TENANT
  • AZURE_ADFS_AUTHORITY_URL

“AZURE_ADFS_AUTHORITY_URL” is optional. It’s necessary only when you have own ADFS authority like https://xxx.com/adfs.

Storing in a File

When working in a development environment, it may be desirable to store credentials in a file. The modules will lookfor credentials in $HOME/.azure/credentials. This file is an ini style file. It will look as follows:

  1. [default]
  2. subscription_id=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  3. client_id=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. secret=xxxxxxxxxxxxxxxxx
  5. tenant=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

It is possible to store multiple sets of credentials within the credentials file by creating multiple sections. Eachsection is considered a profile. The modules look for the [default] profile automatically. Define AZURE_PROFILE in theenvironment or pass a profile parameter to specify a specific profile.

Passing as Parameters

If you wish to pass credentials as parameters to a task, use the following parameters for service principal:

  • client_id
  • secret
  • subscription_id
  • tenant

Or, pass the following parameters for Active Directory username/password:

  • ad_user
  • password

Or, pass the following parameters for ADFS username/pasword:

  • ad_user
  • password
  • client_id
  • tenant
  • adfs_authority_url

“adfs_authority_url” is optional. It’s necessary only when you have own ADFS authority like https://xxx.com/adfs.

Other Cloud Environments

To use an Azure Cloud other than the default public cloud (eg, Azure China Cloud, Azure US Government Cloud, Azure Stack),pass the “cloud_environment” argument to modules, configure it in a credential profile, or set the “AZURE_CLOUD_ENVIRONMENT”environment variable. The value is either a cloud name as defined by the Azure Python SDK (eg, “AzureChinaCloud”,“AzureUSGovernment”; defaults to “AzureCloud”) or an Azure metadata discovery URL (for Azure Stack).

Creating Virtual Machines

There are two ways to create a virtual machine, both involving the azure_rm_virtualmachine module. We can either createa storage account, network interface, security group and public IP address and pass the names of these objects to themodule as parameters, or we can let the module do the work for us and accept the defaults it chooses.

Creating Individual Components

An Azure module is available to help you create a storage account, virtual network, subnet, network interface,security group and public IP. Here is a full example of creating each of these and passing the names to theazure_rm_virtualmachine module at the end:

  1. - name: Create storage account
  2.   azure_rm_storageaccount:
  3.     resource_group: Testing
  4.     name: testaccount001
  5.     account_type: Standard_LRS
  6.  
  7. - name: Create virtual network
  8.   azure_rm_virtualnetwork:
  9.     resource_group: Testing
  10.     name: testvn001
  11.     address_prefixes: "10.10.0.0/16"
  12.  
  13. - name: Add subnet
  14.   azure_rm_subnet:
  15.     resource_group: Testing
  16.     name: subnet001
  17.     address_prefix: "10.10.0.0/24"
  18.     virtual_network: testvn001
  19.  
  20. - name: Create public ip
  21.   azure_rm_publicipaddress:
  22.     resource_group: Testing
  23.     allocation_method: Static
  24.     name: publicip001
  25.  
  26. - name: Create security group that allows SSH
  27.   azure_rm_securitygroup:
  28.     resource_group: Testing
  29.     name: secgroup001
  30.     rules:
  31.       - name: SSH
  32.         protocol: Tcp
  33.         destination_port_range: 22
  34.         access: Allow
  35.         priority: 101
  36.         direction: Inbound
  37.  
  38. - name: Create NIC
  39.   azure_rm_networkinterface:
  40.     resource_group: Testing
  41.     name: testnic001
  42.     virtual_network: testvn001
  43.     subnet: subnet001
  44.     public_ip_name: publicip001
  45.     security_group: secgroup001
  46.  
  47. - name: Create virtual machine
  48.   azure_rm_virtualmachine:
  49.     resource_group: Testing
  50.     name: testvm001
  51.     vm_size: Standard_D1
  52.     storage_account: testaccount001
  53.     storage_container: testvm001
  54.     storage_blob: testvm001.vhd
  55.     admin_username: admin
  56.     admin_password: Password!
  57.     network_interfaces: testnic001
  58.     image:
  59.       offer: CentOS
  60.       publisher: OpenLogic
  61.       sku: '7.1'
  62.       version: latest

Each of the Azure modules offers a variety of parameter options. Not all options are demonstrated in the above example.See each individual module for further details and examples.

Creating a Virtual Machine with Default Options

If you simply want to create a virtual machine without specifying all the details, you can do that as well. The onlycaveat is that you will need a virtual network with one subnet already in your resource group. Assuming you have avirtual network already with an existing subnet, you can run the following to create a VM:

  1. azure_rm_virtualmachine:
  2.   resource_group: Testing
  3.   name: testvm10
  4.   vm_size: Standard_D1
  5.   admin_username: chouseknecht
  6.   ssh_password_enabled: false
  7.   ssh_public_keys: "{{ ssh_keys }}"
  8.   image:
  9.     offer: CentOS
  10.     publisher: OpenLogic
  11.     sku: '7.1'
  12.     version: latest

Dynamic Inventory Script

If you are not familiar with Ansible’s dynamic inventory scripts, check out Intro to Dynamic Inventory.

The Azure Resource Manager inventory script is called azure_rm.py. It authenticates with the Azure API exactly the same as theAzure modules, which means you will either define the same environment variables described above in Using Environment Variables,create a $HOME/.azure/credentials file (also described above in Storing in a File), or pass command line parameters. To see available commandline options execute the following:

  1. $ ./ansible/contrib/inventory/azure_rm.py --help

As with all dynamic inventory scripts, the script can be executed directly, passed as a parameter to the ansible command,or passed directly to ansible-playbook using the -i option. No matter how it is executed the script produces JSON representingall of the hosts found in your Azure subscription. You can narrow this down to just hosts found in a specific set ofAzure resource groups, or even down to a specific host.

For a given host, the inventory script provides the following host variables:

  1. {
  2.   "ansible_host": "XXX.XXX.XXX.XXX",
  3.   "computer_name": "computer_name2",
  4.   "fqdn": null,
  5.   "id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Compute/virtualMachines/object-name",
  6.   "image": {
  7.     "offer": "CentOS",
  8.     "publisher": "OpenLogic",
  9.     "sku": "7.1",
  10.     "version": "latest"
  11.   },
  12.   "location": "westus",
  13.   "mac_address": "00-00-5E-00-53-FE",
  14.   "name": "object-name",
  15.   "network_interface": "interface-name",
  16.   "network_interface_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/networkInterfaces/object-name1",
  17.   "network_security_group": null,
  18.   "network_security_group_id": null,
  19.   "os_disk": {
  20.     "name": "object-name",
  21.     "operating_system_type": "Linux"
  22.   },
  23.   "plan": null,
  24.   "powerstate": "running",
  25.   "private_ip": "172.26.3.6",
  26.   "private_ip_alloc_method": "Static",
  27.   "provisioning_state": "Succeeded",
  28.   "public_ip": "XXX.XXX.XXX.XXX",
  29.   "public_ip_alloc_method": "Static",
  30.   "public_ip_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/publicIPAddresses/object-name",
  31.   "public_ip_name": "object-name",
  32.   "resource_group": "galaxy-production",
  33.   "security_group": "object-name",
  34.   "security_group_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/networkSecurityGroups/object-name",
  35.   "tags": {
  36.     "db": "mysql"
  37.   },
  38.   "type": "Microsoft.Compute/virtualMachines",
  39.   "virtual_machine_size": "Standard_DS4"
  40. }

Host Groups

By default hosts are grouped by:

  • azure (all hosts)
  • location name
  • resource group name
  • security group name
  • tag key
  • tag key_value
  • os_disk operating_system_type (Windows/Linux)

You can control host groupings and host selection by either defining environment variables or creating anazure_rm.ini file in your current working directory.

NOTE: An .ini file will take precedence over environment variables.

NOTE: The name of the .ini file is the basename of the inventory script (i.e. ‘azure_rm’) with a ‘.ini’extension. This allows you to copy, rename and customize the inventory script and have matching .ini files all inthe same directory.

Control grouping using the following variables defined in the environment:

  • AZURE_GROUP_BY_RESOURCE_GROUP=yes
  • AZURE_GROUP_BY_LOCATION=yes
  • AZURE_GROUP_BY_SECURITY_GROUP=yes
  • AZURE_GROUP_BY_TAG=yes
  • AZURE_GROUP_BY_OS_FAMILY=yes

Select hosts within specific resource groups by assigning a comma separated list to:

  • AZURE_RESOURCE_GROUPS=resource_group_a,resource_group_b

Select hosts for specific tag key by assigning a comma separated list of tag keys to:

  • AZURE_TAGS=key1,key2,key3

Select hosts for specific locations by assigning a comma separated list of locations to:

  • AZURE_LOCATIONS=eastus,eastus2,westus

Or, select hosts for specific tag key:value pairs by assigning a comma separated list key:value pairs to:

  • AZURE_TAGS=key1:value1,key2:value2

If you don’t need the powerstate, you can improve performance by turning off powerstate fetching:

  • AZURE_INCLUDE_POWERSTATE=no

A sample azure_rm.ini file is included along with the inventory script in contrib/inventory. An .inifile will contain the following:

  1. [azure]
  2. # Control which resource groups are included. By default all resources groups are included.
  3. # Set resource_groups to a comma separated list of resource groups names.
  4. #resource_groups=
  5.  
  6. # Control which tags are included. Set tags to a comma separated list of keys or key:value pairs
  7. #tags=
  8.  
  9. # Control which locations are included. Set locations to a comma separated list of locations.
  10. #locations=
  11.  
  12. # Include powerstate. If you don't need powerstate information, turning it off improves runtime performance.
  13. # Valid values: yes, no, true, false, True, False, 0, 1.
  14. include_powerstate=yes
  15.  
  16. # Control grouping with the following boolean flags. Valid values: yes, no, true, false, True, False, 0, 1.
  17. group_by_resource_group=yes
  18. group_by_location=yes
  19. group_by_security_group=yes
  20. group_by_tag=yes
  21. group_by_os_family=yes

Examples

Here are some examples using the inventory script:

  1. # Execute /bin/uname on all instances in the Testing resource group
  2. $ ansible -i azure_rm.py Testing -m shell -a "/bin/uname -a"
  3.  
  4. # Execute win_ping on all Windows instances
  5. $ ansible -i azure_rm.py windows -m win_ping
  6.  
  7. # Execute win_ping on all Windows instances
  8. $ ansible -i azure_rm.py winux -m ping
  9.  
  10. # Use the inventory script to print instance specific information
  11. $ ./ansible/contrib/inventory/azure_rm.py --host my_instance_host_name --resource-groups=Testing --pretty
  12.  
  13. # Use the inventory script with ansible-playbook
  14. $ ansible-playbook -i ./ansible/contrib/inventory/azure_rm.py test_playbook.yml

Here is a simple playbook to exercise the Azure inventory script:

  1. - name: Test the inventory script
  2.   hosts: azure
  3.   connection: local
  4.   gather_facts: no
  5.   tasks:
  6.     - debug: msg="{{ inventory_hostname }} has powerstate {{ powerstate }}"

You can execute the playbook with something like:

  1. $ ansible-playbook -i ./ansible/contrib/inventory/azure_rm.py test_azure_inventory.yml

Disabling certificate validation on Azure endpoints

When an HTTPS proxy is present, or when using Azure Stack, it may be necessary to disable certificate validation forAzure endpoints in the Azure modules. This is not a recommended security practice, but may be necessary when the systemCA store cannot be altered to include the necessary CA certificate. Certificate validation can be controlled by settingthe “cert_validation_mode” value in a credential profile, via the “AZURE_CERT_VALIDATION_MODE” environment variable, orby passing the “cert_validation_mode” argument to any Azure module. The default value is “validate”; setting the valueto “ignore” will prevent all certificate validation. The module argument takes precedence over a credential profile value,which takes precedence over the environment value.