Aerie version discovery endpoint

cartermak commented 3 weeks ago

Background

In the near future we're planning to release some breaking changes to the Aerie backend (for procedural scheduling), and we'll also need to release a new version of the aerie-cli tool to support this. There is some (valid) concern from aerie-cli users about accidentally running a ~old~ new version of the CLI against an old version of the Aerie backend, causing errors or unexpected results.

The plan for handling this is to have future versions of aerie-cli query the Aerie backend to check its version, & throw an error to the user if they are incompatible (eg. "Unsupported aerie version 2.18.0 - update your aerie-cli version to run this command"). However, there aren't any endpoints on the backend today which expose the current Aerie version.

Describe the feature request

Add a new endpoint called /version to aerie-gateway which reports the Aerie version. It should be safe to assume that Gateway and the other backend services will be running the same versions. The response from the endpoint should look like:

{
  "version": "2.17.0",
  "db_schema_version": 19
}

Notes/Questions

The db_schema_version would be the schema version from the database ie. would tell you if you're fully migrated to the latest schema or not. This is a bonus and not required if difficult.
Any special handling/additional fields for if the backend is on a non-release version ie. a development branch? Per discussion with @Mythicaeda we think it's most valuable to include the "base" version as is - ie. if you're running a local branch based on 2.18.0 + some additional local changes it should report the version as 2.18.0. But if there is any better way of handling this, we're open to it.

dandelany commented 3 weeks ago

Thanks for filing this @cartermak - I updated the description above based on discussion with @Mythicaeda today, let me know if there are any more details to hash out. Assigning to @Mythicaeda

cartermak commented 3 weeks ago

There is some (valid) concern from aerie-cli users about accidentally running an old version of the CLI against a new version of the Aerie backend, causing errors or unexpected results.

The concern from Clipper is more that we have users try to run new Aerie-CLI against old Aerie. While Clipper GDS manages Aerie deployments, we can't control which of client software is installed by users. Still, having any future version of Aerie-CLI identify that an Aerie 2.11.2 host is out-of-date will address this issue.

Any special handling/additional fields for if the backend is on a non-release version ie. a development branch? Per discussion with @Mythicaeda we think it's most valuable to include the "base" version as is - ie. if you're running a local branch based on 2.18.0 + some additional local changes it should report the version as 2.18.0. But if there is any better way of handling this, we're open to it.

I'll just state my case here and let you both make any final call. IMO, it's safer to have a develop branch report a non-release version tag. That could be just develop or something on top of a release tag (e.g., 2.18.0+dev), but I think that two use cases are better-served by this strategy:

Users who are interacting with an Aerie host without knowing that it's running an unreleased version may be misled by having an endpoint return a release version.
Breaking changes would need to be developed on Aerie-CLI without changing the manifest of allowed Aerie versions until the final release, because Aerie-CLI would need to accept the previous version.

The second point would also be addressed by making the "base" be the upcoming version release and updating Aerie-CLI to accept that version as soon as development starts on that release, which I'm open to, but I think making Aerie-CLI give special treatment to a "develop" tag is a cleaner solution.

dandelany commented 3 weeks ago

The concern from Clipper is more that we have users try to run new Aerie-CLI against old Aerie.

Thanks - I typo'ed that and meant what you said - will update in the description.

I'll just state my case here and let you both make any final call. IMO, it's safer to have a develop branch report a non-release version tag.

I agree with your points, however we're going to proceed with just exposing the base (most-recently-released) version for the first implementation & discuss options for doing that as a follow up. It will take quite a lot more work to detect and report a development branch, and there are some tricky implementation details re: how to represent the branch name/commit & how to handle it on the CLI side. I'd like to get the base version implemented & released ASAP so we can work on the proposed CLI changes which rely on it.

dandelany commented 3 weeks ago

@cartermak the version endpoint has been added to aerie-gateway and is available in the most recent 2.18.0 release.

The response looks like {version: "2.18.0" }
It only reports the "base" version (ie. most recent release version) & doesn't display anything different for a develop branch

We're going to keep this ticket open for now because we'd like to also discuss including other useful version information here such as the database schema version & potentially git branch information (if possible) - but the currently-released version should be enough to implement version-checking on the CLI side now.

dandelany commented 2 weeks ago

Closing this - will consider adding other version info at a later date.

NASA-AMMOS / aerie