feat: add metal_port module

[ctreatma]

Closes #61.

This introduces a metal_port module so that Ansible collection users can modify the network port configuration of their Metal devices. The metal_port Ansible module is based heavily on the metal_port Terraform resource.

Device ports cannot be created or deleted, and updating a device port involves conditionally making multiple different API requests, so the metal_port module does not fit the assumptions made by the metal utility package of this collection. In light of that, the metal_port module has been written in the style of the amazon.aws collection. In that style, each Ansible module uses an API client directly rather than offloading to a shared package that encapsulates all API requests.

[displague]

Any reason native is not assigned/unassigned/reassigned in batch via the native flag?

https://deploy.equinix.com/developers/api/metal/#tag/Ports/operation/createPortVlanAssignmentBatch

[ctreatma]

Handling native in the batch increases the complexity of the code to construct the batch, with minimal benefit (one less API request).

[ocobles]

maybe it would be nice to translate the examples that are defined in https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/network_types#metal-port to add them in these ansible docs since it is not very obvious the different combinations needed to achieve each mode

[displague]

Is this formatting what black or other linters would product? (with ''' not in the same column)

[ctreatma]

This is how the module template is formatted (and as a result, every other module in this collection). We may want to change this and (add a linter and/or formatter) but that's a bigger scope than just one module.

[displague]

I agree with what @ocobles pointed out, that we could benefit from the test cases as examples with some contextual text, similar to https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/network_types#metal-port

[ctreatma]

The example string specified in the code is dumped into a fenced code block, so we don't have a lot of flexibility on how that's rendered at the moment. I added more example tasks with descriptive names to the example string. We could add more text in YAML comments inside the example block, but IMO that's not a great experience.

[ctreatma]

We have one richer Markdown example for the collection, although I don't see anything that links to or references it: https://github.com/equinix/ansible-collection-equinix/tree/main/examples/device_assign_ip

Something like that would be good for metal_port, but I'd prefer to add that in a separate PR so we can take some time to think about how and where to reference it.

[displague]

So many tests! 🚀