bug: Docs for nic module show usage of lan but there is no explanation

Description

For the ionoscloudsdk.ionoscloud.nic module you show the usage of LAN. But in the Explination there is no entry for the LAN prob in state create.

module-ansible/docs/api/compute-engine/nic.md

Lines 131 to 234 in de698cd

    
           ### Available parameters for state **present**: 
        
           &nbsp; 
        
           <table data-full-width="true"> 
        
             <thead> 
        
               <tr> 
        
                 <th width="70">Name</th> 
        
                 <th width="40" align="center">Required</th> 
        
                 <th>Description</th> 
        
               </tr> 
        
             </thead> 
        
             <tbody> 
        
             <tr> 
        
             <td>name<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">True</td> 
        
             <td>The name of the  resource.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>datacenter<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">True</td> 
        
             <td>The datacenter name or UUID in which to operate.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>server<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">True</td> 
        
             <td>The server name or UUID.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>dhcp<br/><mark style="color:blue;">bool</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Indicates if the NIC will reserve an IP using DHCP.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>dhcpv6<br/><mark style="color:blue;">bool</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Indicates if the NIC will receive an IPv6 using DHCP. It can be set to 'true' or 'false' only if this NIC is connected to an IPv6 enabled LAN.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>firewall_active<br/><mark style="color:blue;">bool</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Activate or deactivate the firewall. By default, an active firewall without any defined rules will block all incoming network traffic except for the firewall rules that explicitly allows certain protocols, IP addresses and ports.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>ips<br/><mark style="color:blue;">list</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Collection of IP addresses, assigned to the NIC. Explicitly assigned public IPs need to come from reserved IP blocks. Passing value null or empty array will assign an IP address automatically.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>ipv6_ips<br/><mark style="color:blue;">list</mark></td> 
        
             <td align="center">False</td> 
        
             <td>If this NIC is connected to an IPv6 enabled LAN then this property contains the IPv6 IP addresses of the NIC. The maximum number of IPv6 IP addresses per NIC is 50, if you need more, contact support. If you leave this property 'null' when adding a NIC, when changing the NIC's IPv6 CIDR block, when changing the LAN's IPv6 CIDR block or when moving the NIC to a different IPv6 enabled LAN, then we will automatically assign the same number of IPv6 addresses which you had before from the NICs new CIDR block. If you leave this property 'null' while not changing the CIDR block, the IPv6 IP addresses won't be changed either. You can also provide your own self choosen IPv6 addresses, which then must be inside the IPv6 CIDR block of this NIC.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>ipv6_cidr<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>[The IPv6 feature is in beta phase and not ready for production usage.] The /80 IPv6 CIDR block if this NIC is connected to an IPv6-enabled LAN. If you leave this 'null' when adding a NIC to an IPv6-enabled LAN, an IPv6 block will be automatically assigned to the NIC, but you can also specify an /80 IPv6 CIDR block for the NIC on your own, which then must be inside the IPv6 CIDR block of the LAN. An IPv6-enabled LAN is limited to a maximum of 65,536 NICs.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>allow_replace<br/><mark style="color:blue;">bool</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Boolean indincating if the resource should be recreated when the state cannot be reached in another way. This may be used to prevent resources from being deleted from specifying a different value to an immutable property. An error will be thrown instead<br />Default: False</td> 
        
             </tr> 
        
             <tr> 
        
             <td>api_url<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>The Ionos API base URL.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>certificate_fingerprint<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>The Ionos API certificate fingerprint.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>username<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>The Ionos username. Overrides the IONOS_USERNAME environment variable.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>password<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>The Ionos password. Overrides the IONOS_PASSWORD environment variable.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>token<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>The Ionos token. Overrides the IONOS_TOKEN environment variable.</td> 
        
             </tr> 
        
             <tr> 
        
             <td>wait<br/><mark style="color:blue;">bool</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Wait for the resource to be created before returning.<br />Default: True<br />Options: [True, False]</td> 
        
             </tr> 
        
             <tr> 
        
             <td>wait_timeout<br/><mark style="color:blue;">int</mark></td> 
        
             <td align="center">False</td> 
        
             <td>How long before wait gives up, in seconds.<br />Default: 600</td> 
        
             </tr> 
        
             <tr> 
        
             <td>state<br/><mark style="color:blue;">str</mark></td> 
        
             <td align="center">False</td> 
        
             <td>Indicate desired state of the resource.<br />Default: present<br />Options: ['present', 'absent', 'update']</td> 
        
             </tr> 
        
             </tbody> 
        
           </table>

Expected behavior

Docs show all available parameters with explanation. Including lan of it is an option.

Question will the LAN be created if it is not existent when your create a NIC?

Environment

Web

Ansible version:

Does not apply

Module version:

v6.x & v7.x

OS:

Web

Configuration Files

How to Reproduce

Error and Debug Output

Additional Notes

References

Hello,
There is an error in the docs, lan should be listed for the 'present' state as well, we will fix this in the following release. Thank you for helping us find the bug.
Regarding your question, the answer is no, the lan will not be created if it does not exist

Could you please do a general review of your docs. There are several other mismatches in there. Often the example does not reflect the actual correct usage of the module.

Often things are required but not in the example see ip block with the ipblock prob.

Also how are you able to set the LAN ID/Number with ansible? Because the NIC modules expects that.

Regarding your question, the answer is no, the lan will not be created if it does not exist

Okay but why does the update state for the NIC create a lan but not the create state. Seems inconsistent.
From the docs:

The LAN ID the NIC will be on. If the LAN ID does not exist, it will be implicitly created.

Thank you for bringing these points to our attention. We appreciate your patience as we work on aligning our examples with the actual module usage and ensuring all parameters are correctly indicated.

We will look into the discrepancy you've mentioned and update our documentation and examples accordingly.

Regarding the inconsistency you pointed out in the NIC module, I apologize for any confusion caused by my previous response. To clarify, Ansible itself does not directly create a LAN if it is not existent when creating a NIC. However, the underlying API does handle this by implicitly creating a LAN if it does not exist, both during the 'create' and 'update' states of a NIC. This behavior is consistent across these states, ensuring that the NIC is always associated with a valid LAN.

Link #187

Regarding the inconsistency you pointed out in the NIC module, I apologize for any confusion caused by my previous response. To clarify, Ansible itself does not directly create a LAN if it is not existent when creating a NIC. However, the underlying API does handle this by implicitly creating a LAN if it does not exist, both during the 'create' and 'update' states of a NIC. This behavior is consistent across these states, ensuring that the NIC is always associated with a valid LAN.

This behavior is buggy:

If you rely on ansible/api to create the LAN for you it will. But it will create a LAN with IPv6 disabled, therefor a NIC with DHCPv6 enabled will not be able to connect to that LAN. This might also cause problems when you want to auto create public LANs.

But then again you cant create a LAN (with IPv6) and set the LAN ID yourself, only the name.

The whole network setup is intransparent, very limited and not ready to be serve anything that goes beyond a demo setup. Why are there no real virtual private networks with my own net rage and multiple subsets. Why does the DCD delete LANs if there is nothing connected to them. Why cant you create NICs or LANs without a server in the DCD UI. The internal DCD API works entirely different (having batching support) than your REST API.

Sorry when this sound impolite but at some time it just gets exhausting, The goal is to provide a nice service with the resources ionos offers but for that to happen there needs to be exchange about the pain points of tools and services of the platform.

Is there a plan for resolving these issues @ionoscloudsdk?

Hello,

Regarding the DCD and API issues, these are not made and supported by us so we cannot offer an answer regarding how these work and if they will be changed. We have sent your feedback to the responsible teams. If you have any questions or more feedback related to the DCD, we encourage you to contact our support team directly by emailing support@cloud.ionos.com. This is the official and recommended communication channel to address DCD issues. This is a relatively new feature and we are happy for every feedback we receive.

The way IPV6 works right now is that you need a LAN with IPV6 enabled so the LAN should exist before creating the NIC. You can find more info about that here https://docs.ionos.com/cloud/compute/networks/ipv6.

Regarding the need to manually create a LAN with a certain ID (and not automatically via NIC creation) - that is not possible in the API at the moment. You can create a LAN without providing the ID and the API will generate one for it.
Also, if you want, you can provide us more details about your desired setup and we can assist.

Hello, I have merged the pull request containing the changes to the lan parameter on the nic module and also fixes to some examples. I will leave this issue open until we go through all the examples and update them. Thank you for signaling the issues to us. Happy holidays!

This is great to hear and a welcoming change. However, this is no longer of any interests for me, as the planned project will not be pursued further.

I hope others will benefit from this.

This should be solved in 7.4.1, please let us know if there are other issues.

	### Available parameters for state present:


	<table data-full-width="true">
	<thead>
	<tr>
	<th width="70">Name</th>
	<th width="40" align="center">Required</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td>name<br/><mark style="color:blue;">str</mark></td>
	<td align="center">True</td>
	<td>The name of the resource.</td>
	</tr>
	<tr>
	<td>datacenter<br/><mark style="color:blue;">str</mark></td>
	<td align="center">True</td>
	<td>The datacenter name or UUID in which to operate.</td>
	</tr>
	<tr>
	<td>server<br/><mark style="color:blue;">str</mark></td>
	<td align="center">True</td>
	<td>The server name or UUID.</td>
	</tr>
	<tr>
	<td>dhcp<br/><mark style="color:blue;">bool</mark></td>
	<td align="center">False</td>
	<td>Indicates if the NIC will reserve an IP using DHCP.</td>
	</tr>
	<tr>
	<td>dhcpv6<br/><mark style="color:blue;">bool</mark></td>
	<td align="center">False</td>
	<td>Indicates if the NIC will receive an IPv6 using DHCP. It can be set to 'true' or 'false' only if this NIC is connected to an IPv6 enabled LAN.</td>
	</tr>
	<tr>
	<td>firewall_active<br/><mark style="color:blue;">bool</mark></td>
	<td align="center">False</td>
	<td>Activate or deactivate the firewall. By default, an active firewall without any defined rules will block all incoming network traffic except for the firewall rules that explicitly allows certain protocols, IP addresses and ports.</td>
	</tr>
	<tr>
	<td>ips<br/><mark style="color:blue;">list</mark></td>
	<td align="center">False</td>
	<td>Collection of IP addresses, assigned to the NIC. Explicitly assigned public IPs need to come from reserved IP blocks. Passing value null or empty array will assign an IP address automatically.</td>
	</tr>
	<tr>
	<td>ipv6_ips<br/><mark style="color:blue;">list</mark></td>
	<td align="center">False</td>
	<td>If this NIC is connected to an IPv6 enabled LAN then this property contains the IPv6 IP addresses of the NIC. The maximum number of IPv6 IP addresses per NIC is 50, if you need more, contact support. If you leave this property 'null' when adding a NIC, when changing the NIC's IPv6 CIDR block, when changing the LAN's IPv6 CIDR block or when moving the NIC to a different IPv6 enabled LAN, then we will automatically assign the same number of IPv6 addresses which you had before from the NICs new CIDR block. If you leave this property 'null' while not changing the CIDR block, the IPv6 IP addresses won't be changed either. You can also provide your own self choosen IPv6 addresses, which then must be inside the IPv6 CIDR block of this NIC.</td>
	</tr>
	<tr>
	<td>ipv6_cidr<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>[The IPv6 feature is in beta phase and not ready for production usage.] The /80 IPv6 CIDR block if this NIC is connected to an IPv6-enabled LAN. If you leave this 'null' when adding a NIC to an IPv6-enabled LAN, an IPv6 block will be automatically assigned to the NIC, but you can also specify an /80 IPv6 CIDR block for the NIC on your own, which then must be inside the IPv6 CIDR block of the LAN. An IPv6-enabled LAN is limited to a maximum of 65,536 NICs.</td>
	</tr>
	<tr>
	<td>allow_replace<br/><mark style="color:blue;">bool</mark></td>
	<td align="center">False</td>
	<td>Boolean indincating if the resource should be recreated when the state cannot be reached in another way. This may be used to prevent resources from being deleted from specifying a different value to an immutable property. An error will be thrown instead<br />Default: False</td>
	</tr>
	<tr>
	<td>api_url<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>The Ionos API base URL.</td>
	</tr>
	<tr>
	<td>certificate_fingerprint<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>The Ionos API certificate fingerprint.</td>
	</tr>
	<tr>
	<td>username<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>The Ionos username. Overrides the IONOS_USERNAME environment variable.</td>
	</tr>
	<tr>
	<td>password<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>The Ionos password. Overrides the IONOS_PASSWORD environment variable.</td>
	</tr>
	<tr>
	<td>token<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>The Ionos token. Overrides the IONOS_TOKEN environment variable.</td>
	</tr>
	<tr>
	<td>wait<br/><mark style="color:blue;">bool</mark></td>
	<td align="center">False</td>
	<td>Wait for the resource to be created before returning.<br />Default: True<br />Options: [True, False]</td>
	</tr>
	<tr>
	<td>wait_timeout<br/><mark style="color:blue;">int</mark></td>
	<td align="center">False</td>
	<td>How long before wait gives up, in seconds.<br />Default: 600</td>
	</tr>
	<tr>
	<td>state<br/><mark style="color:blue;">str</mark></td>
	<td align="center">False</td>
	<td>Indicate desired state of the resource.<br />Default: present<br />Options: ['present', 'absent', 'update']</td>
	</tr>
	</tbody>
	</table>