Equinix recklessly EOLing APIs without providing an alternative

[bahamat]

What happened?

Using the metal cli client, when I call metal virtual-network get -p <project> I get an error that the interface is deprecated and will be removed soon. The URL that it references does not explain what alternative API exists or I should be using.

] metal virtual-network get -p 557db33f-28d9-46ce-86b2-5cf372ac81d5
2023/06/09 15:20:47 WARNING: "GET /metal/v1/projects/557db33f-28d9-46ce-86b2-5cf372ac81d5/virtual-networks" reported deprecation on Tue, 30 May 2023 00:00:00 GMT
2023/06/09 15:20:47 WARNING: "GET /metal/v1/projects/557db33f-28d9-46ce-86b2-5cf372ac81d5/virtual-networks" reported sunsetting on Fri, 01 Dec 2023 00:00:00 GMT
2023/06/09 15:20:47 WARNING: See <https://feedback.equinixmetal.com/changelog/bye-facilities-hello-again-metros> for deprecation details

The "by facilities hello again metros" document does not provide any guidance about what to do with virtual-network.

How can we reproduce it?

Run metal virtual-network get -p <project>.

CLI version (metal --version):

] metal --version
metal version v0.14.1

---

I'm trying to update my code to use metros instead of facilities, but I'm being told that what I'm doing is wrong without any guidance for an alternative.

The VLAN API documentation (https://deploy.equinix.com/developers/api/metal/#tag/VLANs) does not indicate in any way that the API endpoint is deprecated, nor does it suggest any alternative.

[bahamat]

Talking with some good folks on the equinix Slack, it seems that this is the API incorrectly reporting the error to metal-cli. This issue might need to be migrated to a different project (perhaps internally?), but I'll leave it open for now since these spurious messages will be seen by metal-cli users.

[displague]

The Equinix Metal API is returning Deprecation + Sunset headers as a way to inform users of usage patterns that will be affected by scheduled (or already applied) changes.

The relevant deprecation (per the warnings printed in the PR description):

• https://feedback.equinixmetal.com/changelog/bye-facilities-hello-again-metros
• https://feedback.equinixmetal.com/changelog/reminder-facilities-turns-to-metros-on-may-30

Updates such as these can be found in the Equinix Metal console on the notification bell:

Metal CLI (and other Equinix Metal tools) have been taking advantage of this feature to report those errors in a user-visible way. If metal-cli gets this API response but doesn't emit it, some users may not find out until it is too late.

From this report, I can see a need for metal-cli to suppress these messages. This can be done by the user by redirecting stderr elsewhere, but that risks missing other warnings and status responses.

In the case of this specific API Deprecation notice, I do not believe we should be seeing that from metal vlans list.
metal vlans list does not utilize any facility query parameters, nor include values. I believe the API is actively aggressively in reporting the deprecation in this case. This API call, and the Metal CLI implementation of it, will continue to work after the sunset date.

For new Equinix Metal users who have metro provisioning features alone, this API call (GET /projects/{id}/virtual-networks) will continue to work. It should not, IMHO, emit a deprecation header.

I'll report this back to the engineering team that can address this concern.

[displague]

Related to this metal vlan command, facilities are returned per VLAN but not metros. 🐛

[ctreatma]

This has been addressed upstream. In some cases, the API was reporting deprecation even when facility/facilities was not used; it has been updated to only report deprecation when the affected parameters are included in the request.