azure_rm_networkinterface – Manage Azure network interfaces — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# azure_rm_networkinterface – Manage Azure network interfaces

- Synopsis
- Requirements
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## Synopsis

- Create, update or delete a network interface.
- When creating a network interface you must provide the name of an existing virtual network, the name of an existing subnet within the virtual network.
- A default security group and public IP address will be created automatically.
- Or you can provide the name of an existing security group and public IP address.
- See the examples below for more details.

## Requirements

The below requirements are needed on the host that executes this module.

- python >= 2.7
- azure >= 2.0.0

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
ad_user string |  | Active Directory username. Use when authenticating with an Active Directory user rather than service principal.
adfs_authority_url string added in 2.6 |  | Azure AD authority url. Use when authenticating with Username/password, and has your own ADFS authority.
api_profile string added in 2.5 | Default: "latest" | Selects an API profile to use when communicating with Azure services. Default value of `latest` is appropriate for public clouds; future values will allow use with Azure Stack.
append_tags boolean | Choices: no yes ← | Use to control if tags field is canonical or just appends to existing tags. When canonical, any tags not found in the tags parameter will be removed from the object's metadata.
auth_source string added in 2.5 | Choices: auto cli credential_file env msi | Controls the source of the credentials to use for authentication. If not specified, ANSIBLE_AZURE_AUTH_SOURCE environment variable will be used and default to `auto` if variable is not defined. `auto` will follow the default precedence of module parameters -> environment variables -> default profile in credential file `~/.azure/credentials`. When set to `cli`, the credentials will be sources from the default Azure CLI profile. Can also be set via the `ANSIBLE_AZURE_AUTH_SOURCE` environment variable. When set to `msi`, the host machine must be an azure resource with an enabled MSI extension. `subscription_id` or the environment variable `AZURE_SUBSCRIPTION_ID` can be used to identify the subscription ID if the resource is granted access to more than one subscription, otherwise the first subscription is chosen. The `msi` was added in Ansible 2.6.
cert_validation_mode string added in 2.5 | Choices: ignore validate | Controls the certificate validation behavior for Azure endpoints. By default, all modules will validate the server certificate, but when an HTTPS proxy is in use, or against Azure Stack, it may be necessary to disable this behavior by passing `ignore`. Can also be set via credential file profile or the `AZURE_CERT_VALIDATION` environment variable.
client_id string |  | Azure client ID. Use when authenticating with a Service Principal.
cloud_environment string added in 2.4 | Default: "AzureCloud" | For cloud environments other than the US public cloud, the environment name (as defined by Azure Python SDK, eg, `AzureChinaCloud`, `AzureUSGovernment`), or a metadata discovery endpoint URL (required for Azure Stack). Can also be set via credential file profile or the `AZURE_CLOUD_ENVIRONMENT` environment variable.
create_with_security_group boolean added in 2.6 | Choices: no yes ← | Whether a security group should be be created with the NIC. If this flag set to `True` and no security_group set, a default security group will be created.
dns_servers list added in 2.7 |  | Which DNS servers should the NIC lookup. List of IP addresses.
enable_accelerated_networking boolean added in 2.7 | Choices: no ← yes | Whether the network interface should be created with the accelerated networking feature or not.
enable_ip_forwarding boolean added in 2.7 | Choices: no ← yes | Whether to enable IP forwarding. aliases: ip_forwarding
ip_configurations - added in 2.5 |  | List of IP configurations. Each configuration object should include field private_ip_address, private_ip_allocation_method, public_ip_address_name, public_ip, public_ip_allocation_method, name.
| application_security_groups - added in 2.8 |  | List of application security groups in which the IP configuration is included. Element of the list could be a resource id of application security group, or dict of resource_group and name.
| load_balancer_backend_address_pools - added in 2.6 |  | List of existing load-balancer backend address pools to associate with the network interface. Can be written as a resource ID. Also can be a dict of name and load_balancer.
| name - / required |  | Name of the IP configuration.
| primary boolean | Choices: no ← yes | Whether the IP configuration is the primary one in the list.
| private_ip_address - |  | Private IP address for the IP configuration.
| private_ip_allocation_method - | Choices: Dynamic ← Static | Private IP allocation method.
| public_ip_address_name - |  | Name of the public IP address. None for disable IP address. aliases: public_ip_address, public_ip_name
| public_ip_allocation_method - | Choices: Dynamic ← Static | Public IP allocation method.
location - |  | Valid Azure location. Defaults to location of the resource group.
name - / required |  | Name of the network interface.
open_ports - |  | When a default security group is created for a Linux host a rule will be added allowing inbound TCP connections to the default SSH port `22`, and for a Windows host rules will be added allowing inbound access to RDP ports `3389` and `5986`. Override the default ports by providing a list of open ports.
os_type - | Choices: Windows Linux ← | Determines any rules to be added to a default security group. When creating a network interface, if no security group name is provided, a default security group will be created. If the os_type=Windows, a rule allowing RDP access will be added. If the os_type=Linux, a rule allowing SSH access will be added.
password string |  | Active Directory user password. Use when authenticating with an Active Directory user rather than service principal.
private_ip_address - |  | (Deprecate) Valid IPv4 address that falls within the specified subnet. This option will be deprecated in 2.9, use ip_configurations instead.
private_ip_allocation_method - | Choices: Dynamic ← Static | (Deprecate) Whether or not the assigned IP address is permanent. When creating a network interface, if you specify private_ip_address=Static, you must provide a value for private_ip_address. You can update the allocation method to `Static` after a dynamic private IP address has been assigned. This option will be deprecated in 2.9, use ip_configurations instead.
profile string |  | Security profile found in ~/.azure/credentials file.
public_ip boolean | Choices: no yes ← | (Deprecate) When creating a network interface, if no public IP address name is provided a default public IP address will be created. Set to `false` if you do not want a public IP address automatically created. This option will be deprecated in 2.9, use ip_configurations instead.
public_ip_address_name - |  | (Deprecate) Name of an existing public IP address object to associate with the security group. This option will be deprecated in 2.9, use ip_configurations instead. aliases: public_ip_address, public_ip_name
public_ip_allocation_method - | Choices: Dynamic ← Static | (Deprecate) If a public_ip_address_name is not provided, a default public IP address will be created. The allocation method determines whether or not the public IP address assigned to the network interface is permanent. This option will be deprecated in 2.9, use ip_configurations instead.
resource_group - / required |  | Name of a resource group where the network interface exists or will be created.
secret string |  | Azure client secret. Use when authenticating with a Service Principal.
security_group - |  | An existing security group with which to associate the network interface. If not provided, a default security group will be created when create_with_security_group=true. It can be the name of security group. Make sure the security group is in the same resource group when you only give its name. It can be the resource id. It can be a dict contains security_group's name and resource_group. aliases: security_group_name
state - | Choices: absent present ← | Assert the state of the network interface. Use `present` to create or update an interface and `absent` to delete an interface.
subnet_name - / required |  | Name of an existing subnet within the specified virtual network. Required when creating a network interface. Use the `virtual_network`'s resource group. aliases: subnet
subscription_id string |  | Your Azure subscription Id.
tags dictionary |  | Dictionary of string:string pairs to assign as metadata to the object. Metadata tags on the object will be updated with any provided values. To remove tags set append_tags option to false.
tenant string |  | Azure tenant ID. Use when authenticating with a Service Principal.
virtual_network - / required |  | An existing virtual network with which the network interface will be associated. Required when creating a network interface. It can be the virtual network's name. Make sure your virtual network is in the same resource group as NIC when you give only the name. It can be the virtual network's resource id. It can be a dict which contains name and resource_group of the virtual network. aliases: virtual_network_name

## Notes

Note

- For authentication with Azure you can pass parameters, set environment variables, use a profile stored in ~/.azure/credentials, or log in before you run your tasks or playbook with `az login`.
- Authentication is also possible using a service principal or Active Directory user.
- To authenticate via service principal, pass subscription_id, client_id, secret and tenant or set environment variables AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_SECRET and AZURE_TENANT.
- To authenticate via Active Directory user, pass ad_user and password, or set AZURE_AD_USER and AZURE_PASSWORD in the environment.
- Alternatively, credentials can be stored in ~/.azure/credentials. This is an ini file containing a [default] section and the following keys: subscription_id, client_id, secret and tenant or subscription_id, ad_user and password. It is also possible to add additional profiles. Specify the profile by passing profile or setting AZURE_PROFILE in the environment.

## See Also

See also

Sign in with Azure CLI
  How to authenticate using the `az login` command.

## Examples

    - name: Create a network interface with minimal parameters
      azure_rm_networkinterface:
        name: nic001
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        ip_configurations:
          - name: ipconfig1
            public_ip_address_name: publicip001
            primary: True

    - name: Create a network interface with private IP address only (no Public IP)
      azure_rm_networkinterface:
        name: nic001
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        create_with_security_group: False
        ip_configurations:
          - name: ipconfig1
            primary: True

    - name: Create a network interface for use in a Windows host (opens RDP port) with custom RDP port
      azure_rm_networkinterface:
        name: nic002
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        os_type: Windows
        rdp_port: 3399
        security_group: "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/myResourceGroup/providers/Microsoft.Network/networkSecurit
                         yGroups/nsg001"
        ip_configurations:
          - name: ipconfig1
            public_ip_address_name: publicip001
            primary: True

    - name: Create a network interface using existing security group and public IP
      azure_rm_networkinterface:
        name: nic003
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        security_group: secgroup001
        ip_configurations:
          - name: ipconfig1
            public_ip_address_name: publicip001
            primary: True

    - name: Create a network with multiple ip configurations
      azure_rm_networkinterface:
        name: nic004
        resource_group: myResourceGroup
        subnet_name: subnet001
        virtual_network: vnet001
        security_group:
          name: testnic002
          resource_group: Testing1
        ip_configurations:
          - name: ipconfig1
            public_ip_address_name: publicip001
            primary: True
          - name: ipconfig2
            load_balancer_backend_address_pools:
              - "{{ loadbalancer001.state.backend_address_pools[0].id }}"
              - name: backendaddrpool1
                load_balancer: loadbalancer001

    - name: Create a network interface in accelerated networking mode
      azure_rm_networkinterface:
        name: nic005
        resource_group: myResourceGroup
        virtual_network_name: vnet001
        subnet_name: subnet001
        enable_accelerated_networking: True

    - name: Create a network interface with IP forwarding
      azure_rm_networkinterface:
        name: nic001
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        ip_forwarding: True
        ip_configurations:
          - name: ipconfig1
            public_ip_address_name: publicip001
            primary: True

    - name: Create a network interface with dns servers
      azure_rm_networkinterface:
        name: nic009
        resource_group: myResourceGroup
        virtual_network: vnet001
        subnet_name: subnet001
        dns_servers:
          - 8.8.8.8

    - name: Delete network interface
      azure_rm_networkinterface:
        resource_group: myResourceGroup
        name: nic003
        state: absent

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
state complex | always | The current state of the network interface.
| dns_server list |  | Which DNS servers should the NIC lookup. List of IP addresses. Sample: ['8.9.10.11', '7.8.9.10']
| dns_setting dictionary |  | The DNS settings in network interface. Sample: {'applied_dns_servers': [], 'dns_servers': ['8.9.10.11', '7.8.9.10'], 'internal_dns_name_label': None, 'internal_fqdn': None}
| enable_accelerated_networking boolean |  | Whether the network interface should be created with the accelerated networking feature or not. Sample: True
| enable_ip_forwarding boolean |  | Whether to enable IP forwarding. Sample: True
| etag string |  | A unique read-only string that changes whenever the resource is updated. Sample: W/"be115a43-2148-4545-a324-f33ad444c926"
| id string |  | Id of the network interface. Sample: /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/myResourceGroup/providers/Microsoft.Network/networkInterfaces/nic003
| ip_configurations complex |  | List of IP configurations.
|  | load_balancer_backend_address_pools list |  | List of existing load-balancer backend address pools to associate with the network interface.
|  | name string |  | Name of the IP configuration. Sample: default
|  | private_ip_address string |  | Private IP address for the IP configuration. Sample: 10.1.0.10
|  | private_ip_allocation_method string |  | Private IP allocation method. Sample: Static
|  | public_ip_address dictionary |  | Name of the public IP address. None for disable IP address. Sample: {'id': '/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/myResourceGroup/providers/Microsoft.Network/publicIPAddresse s/publicip001', 'name': 'publicip001'}
|  | subnet dictionary |  | The reference of the subnet resource. Sample: {'id': '/subscriptions/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ myresourcegroup/providers/Microsoft.Network/virtualNetworks/tnb57dc95318/subnets/tnb57dc95318', 'name': 'tnb57dc95318', 'resource_group': 'myresourcegroup', 'virtual_network_name': 'tnb57dc95318'}
| location string |  | The network interface resource location. Sample: eastus
| mac_address string |  | The MAC address of the network interface.
| name string |  | Name of the network interface. Sample: nic003
| network_security_group dictionary |  | The reference of the network security group resource. Sample: {'id': '/subscriptions//xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/ myResourceGroup/providers/Microsoft.Network/networkSecurityGroups/nsg001', 'name': 'nsg001'}
| primary boolean |  | Get whether this is a primary network interface on virtual machine. Sample: True
| provisioning_state string |  | The provisioning state of the public IP resource. Sample: Succeeded
| tags dictionary |  | -Tags of the network interface. Sample: {'key': 'value'}
| type string |  | Type of the resource. Sample: Microsoft.Network/networkInterfaces

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Chris Houseknecht (@chouseknecht)
- Matt Davis (@nitzmahone)
- Yuwei Zhou (@yuwzho)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.