We are working on automation to deploy apps to fly.io at scale (like large number of apps, full CRUD lifecycle on apps). In terms of mechanics, we are choosing between GraphQL or just calling the flyctl. In particular… the main operations in CLI land are:
fly app create
fly app list
fly app destroy
fly certs …
fly image show …
We will use -j flag for JSON where available…
Alternatively we could peek under the covers and see how flyctl is making the API calls, and simply replicate what we need. My main reservation with GraphQL the evolution policy of the API. I know there is a playground, but no official docs on it.
What is the general philosophy with GraphQL API evolution?
Are some APIs are more likely to remain more stable than others?
When APIs do evolve - what’s a possible way for us to keep up to date / update our integration code (mailing lists, etc?)?
If we simply replicate a specific version of flyctl (from github), which uses GraphQL in a specific way, would that mitigate some risks? E.g. we then tie ourselves to all CLI users on that version of flyctl
Thanks in advance for any insights! Fly.io is awesome, so we want to integrate!
We don’t offer any stability guarantees on the GraphQL API or the flyctl interface. That said, we don’t change the CLI UX that often, because users expect the CLI to be predictable, but in theory change could come at any time.
We do offer a Machines API (spec here) that we keep stable, and you should definitely use where you can. It allows you to orchestrate machines yourself, so you can use it to create VMs, but it won’t e.g. handle blue/green or canary deploys – that’s implemented in flyctl.
We are starting to block really old versions of the flyctl CLI because we make a lot of changes to it and we don’t want users to risk app breakage. So GraphQL is likely your best bet for things not covered in the Machines API. You wouldn’t be the first customers to use it. And knowing about your use case helps us prioritize building stable APIs for these things.
Let me know how that sounds! Excited to have you on our platform!
Thanks for your insight. On the fly CLI - so far, what is the oldest CLI you support today? Just want to get a sense if fly CLI is something we can cling to (either its code, or its binary) - and how slippery it may be in future (or not!).
To add a little more context: we’ve been (just recently) slowly trying to introduce a minimum flyctl version requirement, but that’s because our Fly Launch deployments are complicated and done entirely client-side. We tweak the way apps are deployed through the CLI a lot, but the underlying Machines API used by flyctl is pretty stable.
If you build something referencing the GraphQL and Flaps clients in flyctl, it should last a very long time. Keep in mind that flyctl is using these, so any API changes that break your app would probably also break flyctl.
(I wouldn’t recommend building a product on flyctl’s json output - the target there is mostly shell scripting, and while some of us use it pretty regularly, it’s not a huge priority to keep compatibility there)