[Metal] default Metal Gateway responses do not match the API spec

[ctreatma]

This is a finding from investigation on equinix-labs/metal-go#137.
This also relates to equinix-labs/metal-go#128.

The Metal Gateway API endpoints are all specified as returning the following schema:

oneOf:
- $ref: ./MetalGateway.yaml
- $ref: ./VrfMetalGateway.yaml

In OpenAPI 3, a oneOf has to match exactly one of the nested schemas, but by default, the Metal API response from Metal Gateway endpoints does not include enough information to differentiate between gateways (anything that matches the VrfMetalGateway schema will also match the MetalGateway schema).

This could be addressed with API changes, or possibly with spec changes that do not require an API change, but in the meantime the best workaround we have found is to add the following to all Metal Gateway API requests made with this SDK:

.Includes([]string{"ip_reservation"})

This workaround instructs the API to include IP reservation details in the API response. IPReservation and VrfIpReservation can be distinguished by the SDK, which enables the SDK to determine the gateway type (because MetalGateway has an IPReservation and VrfMetalGateway has a VrfIpReservation.

NOTE: because the Metal Gateway deletes are async, you also need to include the IP reservation in delete requests to avoid a response validation error.

You can see an example of the .Include() call here: https://github.com/equinix/terraform-provider-equinix/blob/611e78a32a865aa374d2e4896cd0978252b983c4/internal/resources/metal/gateway/resource.go#L173

[bjenkins-metal]

Hey gang! Just adding a +1 that this is impacting me with a project I am working on now. I had to use the httpResp return and not the err or the actual response. No way to get an ID reliably right now without touching the http responses. At least nothing I could find.

[displague]

Hey @bjenkins-metal

In https://github.com/equinix/metal-cli/pull/481/files there is an example of getting either the MetalGateway or the VrfMetalGateway from a FindMetalGatewayById call. This example is obtuse because it attempts to handle MetalGateways and VrfGateways in a compatible way for output using a gatewayIsh interface and wrappers to abstract the common functions (GetId, GetIpReservation, ...).

The main take-away is that you'll need to specify the includes, specifically ip_reservation, and to use either of the two Gateway fields, whichever is not nil. (The code that was replaced in the PR was more direct about this).

[bjenkins-metal]

Thank you. Include did in fact fix the schema return problem I was having. Hope this example helps someone else.
resp, _, err := apiClient.MetalGatewaysApi.CreateMetalGateway(context.Background(), projectId).CreateMetalGatewayRequest(*metalGatewayInput).Include([]string{"ip_reservation"}).Execute()