azure.azcollection.azure_rm_networkinterface module – Manage Azure network interfaces
Note
This module is part of the azure.azcollection collection (version 3.0.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install azure.azcollection.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: azure.azcollection.azure_rm_networkinterface.
New in azure.azcollection 0.1.0
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
The host that executes this module must have the azure.azcollection collection installed via galaxy
All python packages listed in collection’s requirements.txt must be installed via pip on the host that executes modules from azure.azcollection
Full installation instructions may be found https://galaxy.ansible.com/azure/azcollection
Parameters
Parameter |
Comments |
|---|---|
Active Directory username. Use when authenticating with an Active Directory user rather than service principal. |
|
Azure AD authority url. Use when authenticating with Username/password, and has your own ADFS authority. |
|
Selects an API profile to use when communicating with Azure services. Default value of Default: |
|
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. Choices:
|
|
Controls the source of the credentials to use for authentication. Can also be set via the When set to When set to When set to When set to When set to The Choices:
|
|
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 Choices:
|
|
Azure client ID. Use when authenticating with a Service Principal or Managed Identity (msi). Can also be set via the |
|
For cloud environments other than the US public cloud, the environment name (as defined by Azure Python SDK, eg, Default: |
|
Whether a security group should be be created with the NIC. If this flag set to Choices:
|
|
Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached such as in private clouds or Azure Stack. The process of instance discovery entails retrieving authority metadata from https://login.microsoft.com/ to validate the authority. By setting this to **True**, the validation of the authority is disabled. As a result, it is crucial to ensure that the configured authority host is valid and trustworthy. Set via credential file profile or the Choices:
|
|
Which DNS servers should the NIC lookup. List of IP addresses. |
|
Whether the network interface should be created with the accelerated networking feature or not. Choices:
|
|
Whether to enable IP forwarding. Choices:
|
|
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. Default: |
|
List of existing application gateway backend address pools to associate with the network interface. Can be written as a resource ID. Also can be a dict of name and application_gateway. |
|
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 the name of the application security group located in the current resource group, or a dictionary with resource groups and names. |
|
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 of the IP configuration. |
|
Whether the IP configuration is the primary one in the list. The first IP configuration default set to primary=True. Choices:
|
|
Private IP address for the IP configuration. |
|
The version of the IP configuration. Choices:
|
|
Private IP allocation method. Choices:
|
|
Name of the public IP address. None for disable IP address. |
|
Public IP allocation method. Choices:
|
|
Valid Azure location. Defaults to location of the resource group. |
|
Parent argument. |
|
Parent argument. |
|
Name of the network interface. |
|
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 |
|
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. Choices:
|
|
Active Directory user password. Use when authenticating with an Active Directory user rather than service principal. |
|
Security profile found in ~/.azure/credentials file. |
|
Name of a resource group where the network interface exists or will be created. |
|
Azure client secret. Use when authenticating with a Service Principal. |
|
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. |
|
Assert the state of the network interface. Use Choices:
|
|
Name of an existing subnet within the specified virtual network. Required when creating a network interface. Use the Required when creating. |
|
Your Azure subscription Id. |
|
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. Currently, Azure DNS zones and Traffic Manager services also don’t allow the use of spaces in the tag. Azure Front Door doesn’t support the use of Azure Automation and Azure CDN only support 15 tags on resources. |
|
Azure tenant ID. Use when authenticating with a Service Principal. |
|
The thumbprint of the private key specified in x509_certificate_path. Use when authenticating with a Service Principal. Required if x509_certificate_path is defined. |
|
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. Required when creating. |
|
Path to the X509 certificate used to create the service principal in PEM format. The certificate must be appended to the private key. Use when authenticating with a Service Principal. |
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 logincommand.
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 network interface attached to application gateway backend address pool
azure_rm_networkinterface:
name: nic-appgw
resource_group: myResourceGroup
virtual_network: vnet001
subnet_name: subnet001
create_with_security_group: false
ip_configurations:
- name: default
primary: true
application_gateway_backend_address_pools:
- name: myApplicationGatewayBackendAddressPool
application_gateway: myApplicationGateway
- 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 |
Description |
|---|---|
The current state of the network interface. Returned: always |
|
Which DNS servers should the NIC lookup. List of IP addresses. Returned: success Sample: |
|
The DNS settings in network interface. Returned: success Sample: |
|
Whether the network interface should be created with the accelerated networking feature or not. Returned: success Sample: |
|
Whether to enable IP forwarding. Returned: success Sample: |
|
A unique read-only string that changes whenever the resource is updated. Returned: success Sample: |
|
Id of the network interface. Returned: success Sample: |
|
List of IP configurations. Returned: success |
|
List of existing application gateway backend address pool resource IDs associated with the network interface. Returned: success Sample: |
|
List of existing load-balancer backend address pools associated with the network interface. Returned: success |
|
Name of the IP configuration. Returned: success Sample: |
|
Private IP address for the IP configuration. Returned: success Sample: |
|
The version of the IP configuration. Returned: success Sample: |
|
Private IP allocation method. Returned: success Sample: |
|
Name of the public IP address. None for disable IP address. Returned: success Sample: |
|
The reference of the subnet resource. Returned: success Sample: |
|
The network interface resource location. Returned: success Sample: |
|
The MAC address of the network interface. Returned: success |
|
Name of the network interface. Returned: success Sample: |
|
The reference of the network security group resource. Returned: success Sample: |
|
Get whether this is a primary network interface on virtual machine. Returned: success Sample: |
|
The provisioning state of the public IP resource. Returned: success Sample: |
|
-Tags of the network interface. Returned: success Sample: |
|
Type of the resource. Returned: success Sample: |