From 65e0f37fc05500dcd8f68b2e4a3294fb1db6849a Mon Sep 17 00:00:00 2001 From: Fred-sun <37327967+Fred-sun@users.noreply.github.com> Date: Wed, 17 Jul 2019 03:18:20 +0800 Subject: [PATCH] Update azure_rm_virtualnetwork related document (#59023) * Update azure_rm_virtualnetwork related documentation --- .../cloud/azure/azure_rm_virtualnetwork.py | 118 ++++++++++++------ .../azure/azure_rm_virtualnetwork_facts.py | 65 +++++++--- .../azure/azure_rm_virtualnetworkgateway.py | 41 +++--- 3 files changed, 150 insertions(+), 74 deletions(-) diff --git a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork.py b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork.py index 2963886a7d..ed21a2698b 100644 --- a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork.py +++ b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork.py @@ -18,51 +18,49 @@ DOCUMENTATION = ''' --- module: azure_rm_virtualnetwork version_added: "2.1" -short_description: Manage Azure virtual networks. +short_description: Manage Azure virtual networks description: - Create, update or delete a virtual networks. Allows setting and updating the available IPv4 address ranges - and setting custom DNS servers. Use the azure_rm_subnet module to associate subnets with a virtual network. + and setting custom DNS servers. Use the M(azure_rm_subnet) module to associate subnets with a virtual network. options: resource_group: description: - - name of resource group. + - Name of resource group. required: true address_prefixes_cidr: description: - - List of IPv4 address ranges where each is formatted using CIDR notation. Required when creating - a new virtual network or using purge_address_prefixes. + - List of IPv4 address ranges where each is formatted using CIDR notation. + - Required when creating a new virtual network or using I(purge_address_prefixes). aliases: - address_prefixes dns_servers: description: - - Custom list of DNS servers. Maximum length of two. The first server in the list will be treated - as the Primary server. This is an explicit list. Existing DNS servers will be replaced with the - specified list. Use the purge_dns_servers option to remove all custom DNS servers and revert to - default Azure servers. + - Custom list of DNS servers. Maximum length of two. + - The first server in the list will be treated as the Primary server. This is an explicit list. + - Existing DNS servers will be replaced with the specified list. + - Use the I(purge_dns_servers) option to remove all custom DNS servers and revert to default Azure servers. location: description: - - Valid azure location. Defaults to location of the resource group. + - Valid Azure location. Defaults to location of the resource group. name: description: - - name of the virtual network. + - Name of the virtual network. required: true purge_address_prefixes: description: - - Use with state present to remove any existing address_prefixes. + - Use with I(state=present) to remove any existing I(address_prefixes). type: bool default: 'no' aliases: - purge purge_dns_servers: description: - - Use with state present to remove existing DNS servers, reverting to default Azure servers. Mutually - exclusive with dns_servers. + - Use with I(state=present) to remove existing DNS servers, reverting to default Azure servers. Mutually exclusive with DNS servers. type: bool default: 'no' state: description: - - Assert the state of the virtual network. Use C(present) to create or update and - C(absent) to delete. + - State of the virtual network. Use C(present) to create or update and C(absent) to delete. default: present choices: - absent @@ -73,8 +71,8 @@ extends_documentation_fragment: - azure_tags author: - - "Chris Houseknecht (@chouseknecht)" - - "Matt Davis (@nitzmahone)" + - Chris Houseknecht (@chouseknecht) + - Matt Davis (@nitzmahone) ''' @@ -101,26 +99,72 @@ EXAMPLES = ''' ''' RETURN = ''' state: - description: Current state of the virtual network. + description: + - Current state of the virtual network. returned: always - type: dict - sample: { - "address_prefixes": [ - "10.1.0.0/16", - "172.100.0.0/16" - ], - "dns_servers": [ - "127.0.0.1", - "127.0.0.3" - ], - "etag": 'W/"0712e87c-f02f-4bb3-8b9e-2da0390a3886"', - "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVirtualNetwork", - "location": "eastus", - "name": "my_test_network", - "provisioning_state": "Succeeded", - "tags": null, - "type": "Microsoft.Network/virtualNetworks" - } + type: complex + contains: + address_prefixes: + description: + - The virtual network IPv4 address ranges. + returned: always + type: list + sample: [ + "10.1.0.0/16", + "172.100.0.0/16" + ] + dns_servers: + description: + - DNS servers. + returned: always + type: list + sample: [ + "127.0.0.1", + "127.0.0.3" + ] + etag: + description: + - A unique read-only string that changes whenever the resource is update. + returned: always + type: str + sample: 'W/"0712e87c-f02f-4bb3-8b9e-2da0390a3886"' + id: + description: + - Resource ID. + returned: always + type: str + sample: "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroup/myResourceGroup/providers/ + Microsoft.Network/virtualNetworks/myVirtualNetwork" + location: + description: + - The Geo-location where the resource lives. + returned: always + type: str + sample: eastus + name: + description: + - Resource name. + returned: always + type: str + sample: my_test_network + provisioning_state: + description: + - Provisioning state of the virtual network. + returned: always + type: str + sample: Succeeded + tags: + description: + - Resource tags, such as { 'tags1':'value1' } + returned: always + type: dict + sample: { 'key1':'value1' } + type: + descriptioin: + - Resource type. + returned: always + type: str + sample: Microsoft.Network/virtualNetworks ''' try: diff --git a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork_facts.py b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork_facts.py index 1e41f15977..43af90af3c 100644 --- a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork_facts.py +++ b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetwork_facts.py @@ -20,7 +20,7 @@ module: azure_rm_virtualnetwork_facts version_added: "2.1" -short_description: Get virtual network facts. +short_description: Get virtual network facts description: - Get facts for a specific virtual network or all virtual networks within a resource group. @@ -40,8 +40,8 @@ extends_documentation_fragment: - azure author: - - "Chris Houseknecht (@chouseknecht) " - - "Matt Davis (@nitzmahone) " + - Chris Houseknecht (@chouseknecht) + - Matt Davis (@nitzmahone) ''' @@ -62,7 +62,8 @@ EXAMPLES = ''' ''' RETURN = ''' azure_virtualnetworks: - description: List of virtual network dicts. + description: + - List of virtual network dicts. returned: always type: list example: [{ @@ -83,78 +84,110 @@ azure_virtualnetworks: "type": "Microsoft.Network/virtualNetworks" }] virtualnetworks: - description: List of virtual network dicts with same format as azure_rm_virtualnetwork module parameters. + description: + - List of virtual network dicts with same format as M(azure_rm_virtualnetwork) module parameters. returned: always - type: list + type: complex contains: id: description: - - Resource ID. + - Resource ID of the virtual network. sample: /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/vnet2001 + returned: always type: str address_prefixes: description: - List of IPv4 address ranges where each is formatted using CIDR notation. sample: ["10.10.0.0/16"] + returned: always type: list dns_servers: description: - Custom list of DNS servers. + returned: always type: list sample: ["www.azure.com"] location: description: - - Valid azure location. + - Valid Azure location. + returned: always type: str sample: eastus tags: description: - Tags assigned to the resource. Dictionary of string:string pairs. + returned: always type: dict sample: { "tag1": "abc" } provisioning_state: description: - Provisioning state of the resource. - sample: Successed + returned: always + sample: Succeeded type: str name: description: - - name of the virtual network. + - Name of the virtual network. + returned: always type: str sample: foo subnets: description: - - Subnets associate to this virtual network. + - Subnets associated with the virtual network. + returned: always type: list contains: id: description: - - Resource ID. + - Resource ID of the subnet. + returned: always type: str + sample: "/subscriptions/f64d4ee8-be94-457d-ba26-3fa6b6506cef/resourceGroups/v-xisuRG/providers/ + Microsoft.Network/virtualNetworks/vnetb57dc95232/subnets/vnetb57dc95232" name: description: - - Resource Name. + - Name of the subnet. + returned: always type: str + sample: vnetb57dc95232 provisioning_state: description: - - provision state of the Resource. + - Provisioning state of the subnet. + returned: always type: str - sample: Successed + sample: Succeeded address_prefix: description: - The address prefix for the subnet. + returned: always + type: str + sample: '10.1.0.0/16' network_security_group: description: - - Existing security group id with which to associate the subnet. + - Existing security group ID with which to associate the subnet. + returned: always type: str + sample: null route_table: description: - The reference of the RouteTable resource. + returned: always type: str + sample: null service_endpoints: description: - An array of service endpoints. + returned: always type: list + sample: [ + { + "locations": [ + "southeastasia", + "eastasia" + ], + "service": "Microsoft.Storage" + } + ] ''' try: diff --git a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetworkgateway.py b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetworkgateway.py index 7e82228ae7..87183d0127 100644 --- a/lib/ansible/modules/cloud/azure/azure_rm_virtualnetworkgateway.py +++ b/lib/ansible/modules/cloud/azure/azure_rm_virtualnetworkgateway.py @@ -15,11 +15,11 @@ module: azure_rm_virtualnetworkgateway version_added: "2.8" -short_description: Manage Azure virtual network gateways. +short_description: Manage Azure virtual network gateways description: - - Create, update or delete a virtual network gateway(VPN Gateway). When creating a VPN Gateway you must provide the name of an - existing virtual network. + - Create, update or delete a virtual network gateway(VPN Gateway). + - When creating a VPN Gateway you must provide the name of an existing virtual network. options: resource_group: @@ -32,8 +32,7 @@ options: required: true state: description: - - Assert the state of the VPN Gateway. Use 'present' to create or update VPN gateway and - 'absent' to delete VPN gateway. + - State of the VPN Gateway. Use C(present) to create or update VPN gateway and C(absent) to delete VPN gateway. default: present choices: - absent @@ -41,58 +40,58 @@ options: required: false location: description: - - Valid azure location. Defaults to location of the resource group. + - Valid Azure location. Defaults to location of the resource group. required: false virtual_network: description: - - An existing virtual network with which the VPN Gateway will be associated. Required - when creating a VPN Gateway. - - It can be the virtual network's name. - - Make sure your virtual network is in the same resource group as VPN gateway when you give only the name. - - It can be the virtual network's resource id. - - It can be a dict which contains C(name) and C(resource_group) of the virtual network. + - An existing virtual network with which the VPN Gateway will be associated. + - Required when creating a VPN Gateway. + - Can be the name of the virtual network. + - Must be in the same resource group as VPN gateway when specified by name. + - Can be the resource ID of the virtual network. + - Can be a dict which contains I(name) and I(resource_group) of the virtual network. aliases: - virtual_network_name required: true ip_configurations: description: - - List of ip configurations + - List of IP configurations. suboptions: name: description: - - Name of the ip configuration. + - Name of the IP configuration. required: true private_ip_allocation_method: description: - - private ip allocation method. + - Private IP allocation method. choices: - dynamic - static default: dynamic public_ip_address_name: description: - - Name of the public ip address. None for disable ip address. + - Name of the public IP address. Use 'None' to disable the public IP address. subnet: description: - ID of the gateway subnet for VPN. default: GatewaySubnet gateway_type: description: - - The type of this virtual network gateway + - The type of this virtual network gateway. default: vpn choices: - vpn - express_route vpn_type: description: - - The type of this virtual network gateway + - The type of this virtual private network. default: route_based choices: - route_based - policy_based enable_bgp: description: - - Whether BGP is enabled for this virtual network gateway or not + - Whether BGP is enabled for this virtual network gateway or not. default: false sku: description: @@ -116,7 +115,7 @@ extends_documentation_fragment: - azure_tags author: - - "Madhura Naniwadekar (@Madhura-CSI)" + - Madhura Naniwadekar (@Madhura-CSI) ''' EXAMPLES = ''' @@ -159,7 +158,7 @@ EXAMPLES = ''' RETURN = ''' id: description: - - Virtual Network Gateway resource ID + - Virtual Network Gateway resource ID. returned: always type: str sample: "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworkGateways/myV