Machines OpenAPI spec omissions

General
, , ,
22

@praneetloke the changes went live:

  1. current_version docs updated (link).
  2. PATCH and PUT were doing the same operation because of legacy reasons. PUT is deprecated now. Docs were also updated to reflect what it does to keys that aren’t mentioned.
  3. There is no intention (yet) to convert PUT to “replace all metadata” op
23

@dangra @nullhypothesis thank you for making the updates. I’ll review them asap!

24

@dangra @nullhypothesis I’ve looked at the changes. Here are my thoughts on the current state of the Update Machine endpoint:

  1. Rename the current_version to version in the request body so it lines up with the request body of the Create Machine endpoint. One could take the response from the Create Machine endpoint, tweak the config and update the machine without having to set a new current_version property.

  2. As for the second thing…I previously brought this up and lilian explained that it is POST because the endpoint is creating a new version. I’d argue that the Update Machine endpoint acts as a “replace the configuration of the machine with this config if the version matches”. I think a PUT would be more appropriate since the user would essentially be replacing the entire configuration with a new one. If not, that’s fine and I can try to work around it. I figured I would give it another shot at proposing the change given other changes.

I would love to know what you think.

25

I’d rather not rename attributes or change methods; not because I find your suggestions unreasonable (they’re actually good!) but because every change must be backwards compatible, which means that we’d have to deprecate the old stuff, introduce new stuff, and make sure that nothing breaks. It’s a bit of a hassle and I’d prefer to avoid it as much as possible, even if it means foregoing opportunities to make the API more consistent.

26

It’s a bit of a hassle and I’d prefer to avoid it as much as possible, even if it means foregoing opportunities to make the API more consistent.

Fair enough. I had a feeling that was going to be the case. I’ve been there. I’ll work around those points I brought up about the Update Machine endpoint.

By the way, what is the purpose of the Remove certificate endpoint? I see that both Acme and custom certificates have a corresponding Remove Acme and Remove custom endpoint.

27

that’s for deleting all certificates on the app, whether ACME or custom. (both can be on the app at the same time)

28

Ah, got it. Thank you, @lillian!

29

I’ve made the repo public now that I have gotten a successful generation of Pulumi SDKs from the OpenAPI spec. I will test the SDK with my Fly account and once I confirm things to be working well, I’ll publish the SDKs to the respective registries.

30

I have been testing the Pulumi provider. It mostly works. The following are a few of the observations I made.

Network Policies

Network policies API is listed in the docs here but it’s missing in the spec. I don’t see any other way to manage them.

Moreover, POST /v1/apps/<app_name>/network_policies is used for both create and update. It would be great if there was a separate endpoint for updating a policy similar to the DELETE endpoint: DELETE /v1/apps/<app_name>/network_policies/<policy_id>.

There is also no endpoint to fetch a single network policy by its id.

Storage Objects

I am curious if there is any plan to add APIs to manage the following resources:

  • Fly.io Storage (Tigris) Buckets to the Machines API?
  • Fly Kubernetes Service

I realize it’s Machines API, so maybe a separate “platform” API group?

Rate Limits

The rate limit is easily triggered by the metadata endpoints. Trying to mutate (add/update/delete) multiple metadata keys for a machine will result in 429s. I can work around this by slowing-down the metadata requests for a machine but I wanted to mention it in case there is any room for easing the limits for certain endpoints. The alternate, of course, is that a user manages metadata as part of the machine config rather than using the dedicated /metadata/{key} endpoint. I am going to do more testing and part of it is to port something off Render.

31

tigris is a separate company and product; you can use their own APIs to manage storage buckets, the flyctl integration is mostly just a convenience.

this is deprecated and should no longer be used.

for metadata, raising the limits is probably not workable as each update is expensive on our end, maybe you can use the bulk update endpoint instead?

I’m not personally familiar with network policies.

32

the flyctl integration is mostly just a convenience.

Ah, that’s good to know. I wasn’t sure if there was a special thing with fly’s control plane.

Fly Kubernetes Service

this is deprecated and should no longer be used.

Got it! That’s simple enough :slight_smile:

for metadata, raising the limits is probably not workable as each update is expensive on our end, maybe you can use the bulk update endpoint instead?

Hmm yeah I seem to have forgotten about this endpoint altogether. Thank you for pointing this out to me. I’ll think of a strategy to use this.

I’m not personally familiar with network policies.

Do you know anyone who might be able to look into it?

Thank you as always!