equinix/ansible-collection-metal

Deprecated. See Equinix collection linked below

Ansible Collection - equinix.metal

Important

This repository is Deprecated!

The Equinix Ansible Collection has been created to provide an interface to Equinix APIs throughout the platform. Please transition to the Ansible Equinix Collection which has module parity with this Metal collection. The module names and parameters may differ slightly but the same backend APIs are utilized. The Equinix Collection is backed by the more comprehensive and more maintainable metal-python SDK. This collection and metal-python follow upstream API naming and structures closely.

• Equinix Deploy: https://deploy.equinix.com/labs/ansible-collection-equinix/
• Ansible Collection: https://galaxy.ansible.com/ui/repo/published/equinix/cloud/
• GitHub: https://github.com/equinix-labs/ansible-collection-equinix

The Ansible Equinix Metal collection includes a variety of Ansible content to help automate the management of Equinix Metal resources. This collection is now deprecated.

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.9.10.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Python version compatibility

This collection depends on packet-python. This collection requires Python 2.7 or greater.

Included content

Inventory plugins

Name	Description
equinix.metal.device	Equinix Metal Device inventory source

Modules

Name	Description
equinix.metal.capacity_info	Gather information about Equinix Metal capacity
equinix.metal.device	Manage a bare metal server in Equinix Metal
equinix.metal.device_info	Gather information about Equinix Metal devices
equinix.metal.facility_info	Gather information about Equinix Metal facilities
equinix.metal.ip_info	Gather information about project IP Addresses
equinix.metal.ip_subnet	Assign IP subnet to a bare metal server.
equinix.metal.operating_system_info	Gather information about Equinix Metal operating_systems
equinix.metal.org_info	Gather information about Equinix Metal organizations
equinix.metal.plan_info	Gather information about Equinix Metal plans
equinix.metal.project	Create/delete a project in Equinix Metal
equinix.metal.project_info	Gather information about Equinix Metal projects
equinix.metal.sshkey	Create/delete an SSH key in Equinix Metal
equinix.metal.sshkey_info	Gather information about Equinix Metal SSH keys
equinix.metal.user_info	Gather information about the logged in user

Installing this collection

You can install the Equinix Metal collection with the Ansible Galaxy CLI:

ansible-galaxy collection install equinix.metal

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: equinix.metal

The python module dependencies are not installed by ansible-galaxy. They can be manually installed using pip:

pip install -r requirements.txt

or:

pip install packet-python

Using this collection

You can either call modules by their Fully Qualified Collection Namespace (FQCN), such as equinix.metal.device, or you can call modules by their short name if you list the equinix.metal collection in the playbook's collections keyword:

---
TODO

NOTE: For Ansible 2.9, you may not see deprecation warnings when you run your playbooks with this collection. Use this documentation to track when a module is deprecated.

See Also:

• Ansible Using collections for more details.

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Equinix Metal collection repository.

If you require support, please email [email protected], visit the Equinix Metal IRC channel (#equinixmetal on freenode), subscribe to the Equinix Metal Community Slack channel or post an issue within this repository.

If you want to develop new content for this collection or improve what is already here, the easiest way to work on the collection is to clone it into one of the configured COLLECTIONS_PATHS, and work on it there.

Testing with ansible-test

Running sanity tests: ansible-test sanity --docker -v Running unit tests: ansible-test units -v --docker

Running integration tests:

cat << EOF > tests/integration/integration_config.yml
api_token: <YOUR EQUINIX METAL API TOKEN>
EOF
 ansible-test integration -v --docker

More information about contributing

• Ansible Community Guide - Details on contributing to Ansible
• Contributing to Collections - How to check out collection git repositories correctly

Release notes

This project tags releases based on the Semantic Versioning specification. See https://semver.org/#semantic-versioning-specification-semver for more details. Please pin your dependencies accordingly.

Changes to this project can be reviewed in the CHANGELOG.rst file.

It is possible to follow changes to the changelog by subscribing to https://github.com/equinix/ansible-collection-metal/releases.atom, or "Watching" releases using the GitHub UI.

Roadmap

Publishing New Version

Prepare the release:

• Refresh the README.md: tox -e add_docs
• Refresh the changelog: tox -e antsibull-changelog -- release --verbose --version 1.1.0
• Clean up the changelog fragments.
• Commit everything and push a PR for review

Push the release:

• Tag the release: git tag -s 1.0.0
• Push the tag: git push origin 1.0.0

More information

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Collections Checklist
• Ansible Community code of conduct
• The Bullhorn (the Ansible Contributor newsletter)
• Changes impacting Contributors

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.

ansible-collection-metal's Issues

Add support for Metal Port resources

SUMMARY

Metal port resources allow Equinix Metal server device ethernet ports to be put into the desired state. This is necessary for configuring L2 and/or L3 modes, configuring bonding, and attaching VLANs (as well as defining the native VLAN).

https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/equinix_metal_port

ISSUE TYPE

• Feature Idea

COMPONENT NAME

ADDITIONAL INFORMATION

Release, versioning, and deprecation policy

Originally from ansible-collections/ansible-inclusion#15

has a policy of releasing, versioning and deprecation announced to contributors and users in some way

Comment: cannot find, MUST be fixed (via an issue for example, see examples in collections, such issues are usually pinned)

Guidance is provided about how Ansible collections should handle versioning and deprecation:
https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#contributor-workflow

This project offers a CHANGELOG at https://github.com/equinix/ansible-collection-metal/blob/main/CHANGELOG.rst describing releases. It is possible to follow changes to the changelog by subscribing to https://github.com/equinix/ansible-collection-metal/releases.atom, or "Watching" releases using the GitHub UI.

There is no predefined roadmap or timeline for new features or upcoming releases.

New semver releases will be made as demands based on incoming issues or enhancements and the maintainers perceived need to distribute the resultant changes. See https://semver.org/#semantic-versioning-specification-semver for more details.

Maintainers may update this issue as needed

Add support for Metal Gateway and VRF

SUMMARY

Create a plugin for managing MetalGateways and VRF. This will require packet-python support (packethost/packet-python#134)

https://registry.terraform.io/providers/equinix/equinix/latest/docs/resources/equinix_metal_gateway for example.

More info at https://metal.equinix.com/developers/docs/networking/metal-gateway/
API at https://metal.equinix.com/developers/api/#tag/MetalGateways

ISSUE TYPE

• Feature Idea

COMPONENT NAME

ADDITIONAL INFORMATION

Crosslink to the Ansible Scenario Guide for Equinix Metal

This project should link to any appropriate scenario guides (and call for the update or removal of outdated guides):

• https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/scenario_guides/guide_packet.rst

TODO:

• Revisit https://docs.ansible.com/ansible/latest/scenario_guides/guide_packet.html to reflect this project
  • Determine if the old file should be renamed/replaced, or if a new file is needed
  • File an issue on ansible/ansible (or just PR?)
• Reference these guides in this project's README.md

Ansible Inclusion

This issue is tracking remaining Ansible Collections requirements checklist (https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst) items:

• #24 has a policy of releasing, versioning and deprecation announced to contributors and users in some way
  @Andersson007: cannot find, MUST be fixed (via an issue for example, see examples in collections, such issues are usually pinned)
• #25 adheres to semantic versioning
  @Andersson007: I can't see semver mentioned neither in README no in anywhere else. MUST be fixed.
• #26 follows the Ansible documentation standards and the style guide
  @Andersson007: The following issues found (I understand that the stuff was moved from c.g. but we fix these things when find
  them and we claim it for all new content):

  return device_id: no sample (check everywhere)
  short_description: line 1 ends with a dot (must not)
  return capacity: line 1 does not end with a dot (in return sections lines must end with a dot)
  no "notes" section, it should, at least, contain info about check_mode support, please put something like:
  notes:
  - Supports / Does not support C(check_mode).
  opt user_data: line 1 does not end with a dot (pleas recheck all the options end with a dot).
  

• #27 modules (or plugins) from ansible-base use ansible.builtin. as a FQCN prefix
  @Andersson007: plugins/modules/device.py: - {{ lookup('file', 'my_equinix_metal_sshkey') }} MUST be ansible.builtin.file
• has CI tests up and running against each of the "major versions" of ansible-base/ansible-core that the collection supports
• all CI tests run against every pull request
• all CI tests run against a commit that releases the collection; if they don't pass, the collection won't be released
• all CI tests run regularly (nightly, or at least once per week)

Originally from ansible-collections/ansible-inclusion#15

Add hardware_reservation_id support for equinix.metal.device

SUMMARY

It should be possible to deploy server device instances from hardware reservations using the API's hardware_reservation_id field (also present in packet-pyton) which accepts either "next_available" or a specific hardware reservation id (UUID).

ISSUE TYPE

• Feature Idea

COMPONENT NAME

equinix.metal.device

ADDITIONAL INFORMATION

Provisioning a new device via `equinix.metal.device` can sometimes succeed with 0 returned devices.

SUMMARY

There seems to be a race condition when provisioning a new device and waiting for the provisioning to complete (either via setting state: active or via wait_for_public_IPv: 4/6). Specifically, if the device disappears from the active devices list while waiting for either of those conditions, the equinix.metal.device module will success with an empty device list instead of failing. This can happen, for example, when attempting to provision a new host with the same hostname as a host in the process of being de-provisioned.

This seems to be due to the fact that the wait_for_devices_active and wait_for_public_IPv functions attempt to wait for their conditions to be met by polling the results refresh_devices_list and checking that all devices returned match their requirements, but refresh_devices_list only returns devices visible from the API without checking to see if that includes all the device IDs passed as a parameter.

ISSUE TYPE

• Bug Report

COMPONENT NAME

equinix.metal.device

STEPS TO REPRODUCE

1. Provision a server with the following play:

- name: Provision an Equinix server.
  register: output
  equinix.metal.device:
            api_token: "{{ apikey }}"
            project_id: "{{ project }}"
            name: "{{ name }}"
            state: present
            plan: "{{ plan }}"
            operating_system: "ubuntu_20_04"
            facility: "{{ region }}"
            wait_for_public_IPv: 6
            user_data: "{{ user_data }}"

2. Begin a de-provisioning of that server, either via the web UI or via setting state to absent on the above play.

3. Before the de-provisioning of the host created in Step 1 completes, re-run the above play.

EXPECTED RESULTS

Either the module to throw an error or to wait for the previous host to finish de-provisioning before attempting to re-provision.

ACTUAL RESULTS

The play succeeds, except output.devices is empty.

use ansible.builtin.file instead of file

modules (or plugins) from ansible-base use ansible.builtin. as a FQCN prefix

Comment: plugins/modules/device.py: - {{ lookup('file', 'my_equinix_metal_sshkey') }} MUST be ansible.builtin.file

Originally from ansible-collections/ansible-inclusion#15

Deprecate this module (Ansible Collection Metal)

SUMMARY

This project should be deprecated in favor of https://github.com/equinix-labs/ansible-collection-equinix which has near parity with this provider and will be gaining additional capabilities over time.

Parity is being tracked in https://github.com/equinix-labs/ansible-collection-equinix/milestone/2

https://community.equinix.com/t5/Announcements/Ansible-Collection-Equinix-v0-1-0-Release/ba-p/1343

The README.md should be updated and any Ansible collection practices around deprecation should be applied. https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/usage_guide/collections/?h=deprecate#deleting-and-deprecating-collections

• Deprecate: https://galaxy.ansible.com/ui/repo/published/equinix/metal/
• Include a notice that this repo is deprecated
• Update the project URL (GH Settings) to point to the new project
• Create a migration guide in the new project (https://github.com/equinix-labs/ansible-collection-equinix/blob/main/MIGRATION.md)

Possibly related: #24

ISSUE TYPE

• Documentation Report

COMPONENT NAME

ANSIBLE VERSION

Document that this project follows semver

This project currently abides my https://semver.org versioning, https://github.com/equinix/ansible-collection-metal/tags.

The documentation should state as much.

adheres to semantic versioning

Comment: I can't see semver mentioned neither in README no in anywhere else. MUST be fixed.

Originally from ansible-collections/ansible-inclusion#15

Add stable-2.11 (Ansible 4) to test matrix

SUMMARY

Testing does not include stable-2.11, which is the target version for Ansible 4.

ISSUE TYPE

• Bug Report

COMPONENT NAME

Github workflows, including ansible-build; see the ansible-build.yml as one example.

ansible-collection-metal/.github/workflows/ansible-build.yml

Lines 26 to 30 in 9070914

	matrix:
	ansible:
	- stable-2.9
	- stable-2.10
	- devel

ANSIBLE VERSION

The relevant version is stable-2.11 of ansible-core, per #28 (comment)

OS / ENVIRONMENT

This is for testing in the CI environment against the ansible-core used for Ansible 4.

STEPS TO REPRODUCE

Observe that the test matrix does not include stable-2.11.

EXPECTED RESULTS

Tests pass on stable-2.11 (Ansible 4 baseline).

ACTUAL RESULTS

Tests are not run on stable-2.11.

Device module integration tests cleanup is not consistent for all Ansible versions

SUMMARY

The cleanup we are doing in tests/integration/targets/device/tasks/main.yml is not working consistently for all versions of Ansible/python. In some cases it appears to be iterating over strings rather than lists.

ISSUE TYPE

• Bug Report

COMPONENT NAME

tests/integration/targets/device/tasks/main.yml

STEPS TO REPRODUCE

View the integration test output and compare the output of the cleanup tasks for the device integration test between ansible and python versions.

fix Ansible documentation style guide violations

Originally from ansible-collections/ansible-inclusion#15

follows the Ansible documentation standards and the style guide

Comment: The following issues found (I understand that the stuff was moved from c.g. but we fix these things when find them and we claim it for all new content):

return device_id: no sample (check everywhere)
short_description: line 1 ends with a dot (must not)
return capacity: line 1 does not end with a dot (in return sections lines must end with a dot)
no "notes" section, it should, at least, contain info about check_mode support, please put something like:
notes:
- Supports / Does not support C(check_mode).
opt user_data: line 1 does not end with a dot (pleas recheck all the options end with a dot).

https://docs.ansible.com/ansible/devel/dev_guide/style_guide/index.html#style-guide
https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html

Error 422: Public ipv4 subnet size '31' is invalid for VMware ESXi 7.0

SUMMARY

It seems equinix.metal.device is deploying with a default /31 subnet even on ESXI and Windows. Deploying fails with the error:

ESXI:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: packet.baseapi.ResponseError: Error 422: Public ipv4 subnet size '31' is invalid for VMware ESXi 7.0
fatal: [localhost]: FAILED! => {"changed": false, "msg": "failed to set device state present, error: Error 422: Public ipv4 subnet size '31' is invalid for VMware ESXi 7.0"}

Windows:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: packet.baseapi.ResponseError: Error 422: Public ipv4 subnet size '31' is invalid for Windows 2019 Standard
fatal: [localhost]: FAILED! => {"changed": false, "msg": "failed to set device state present, error: Error 422: Public i
pv4 subnet size '31' is invalid for Windows 2019 Standard"}

ISSUE TYPE

• Bug Report

COMPONENT NAME

equinix.metal.device

ANSIBLE VERSION

ansible [core 2.12.2]
  config file = None
  configured module search path = ['/Users/user/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /Users/user/projects/equinix-metal/ansible/windowstest/.venv/lib/python3.9/site-packages/ansible
  ansible collection location = /Users/user/.ansible/collections:/usr/share/ansible/collections
  executable location = /Users/user/projects/equinix-metal/ansible/windowstest/.venv/bin/ansible
  python version = 3.9.10 (main, Jan 15 2022, 11:48:00) [Clang 13.0.0 (clang-1300.0.29.3)]
  jinja version = 3.0.3
  libyaml = True

CONFIGURATION

none

OS / ENVIRONMENT

Mac OS

STEPS TO REPRODUCE

  tasks:
    - name: deploy esxi
      equinix.metal.device:
        count: 1
        hostnames: jp-ansible-module-01
        operating_system: vmware_esxi_7_0
        plan: c3.small.x86
        facility: sv15
        project_id: "{{ project_id }}"
        api_token: "{{ api_token }}"

EXPECTED RESULTS

Will deploy esxi with /29 private/public IP which is the default behaviour of the API

ACTUAL RESULTS

Deploying Windows / ESXI fails with the error:

ESXI:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: packet.baseapi.ResponseError: Error 422: Public ipv4 subnet size '31' is invalid for VMware ESXi 7.0
fatal: [localhost]: FAILED! => {"changed": false, "msg": "failed to set device state present, error: Error 422: Public ipv4 subnet size '31' is invalid for VMware ESXi 7.0"}

Windows:

An exception occurred during task execution. To see the full traceback, use -vvv. The error was: packet.baseapi.ResponseError: Error 422: Public ipv4 subnet size '31' is invalid for Windows 2019 Standard
fatal: [localhost]: FAILED! => {"changed": false, "msg": "failed to set device state present, error: Error 422: Public i
pv4 subnet size '31' is invalid for Windows 2019 Standard"}

Add support for Equinix Metal Metros

Equinix Metal facilities can now be treated as aggregate, in many ways, using metros:

• https://feedback.equinixmetal.com/changelog/new-metros-feature-live

TODO

(add more or sub-levels as needed)

• Introduce a new metro_info module
• Introduce Metro features where applicable (info, inventory, and managing modules):
  • Facilities (now include a metro field)
  • Plans (now include available_in_metros)
  • Capacity Info (now has a separate /capacity/metros GET/POST endpoint)
  • Devices (now include a metro field)
  • VLANs (may include a metro field)
  • (N/A, not implemented in Ansible) Hardware Reservation, Batch, SpotMarket, SpotMarketPrices
  • (N/A, not implemented in packet-python) Connections (packethost/packet-python#111), IP reservations (packethost/packet-python#109)
  • (N/A, not metro-enabled) Volumes (also not in Ansible)

When provisioning these resources, either a facility or a metro parameter should be provided.

Device and IP Address responses, for existing resources, will return both facility and metro responses.
VLAN resources will only return a metro or facility (along with metro_code, facility_code) depending on how they were provisioned.

Depends on packethost/packet-python#108