This week, we released our second major stable version: Garage v2.0.0. The time since the last major release, Garage v1.0.0, has been a bit more than one year. What are the changes warranting a new major release? What is our vision for making cluster administration simpler and more flexible? What will be the release schedule going forward?
The new Garage release, Garage v2.0.0, is a breaking release compared to the existing v1.x series. We will try to describe these breaking changes in this post and give a bit more context to explain why releasing a new major version was required.
Changes to the admin API
As mentioned in the release
notes, the
administration API has been completely reworked. Some calls to the /v1/
endpoints will still work but most will not. New endpoints are prefixed by
/v2/.
We replaced the previous router that used a combination of path, HTTP method
and query parameters to distinguish between different API calls, which had a
lot of ambiguity, by a simpler scheme where the name of the API call is
directly in the path with nothing else (e.g. /v2/GetClusterStatus). This
removes all ambiguity and makes for a more homogeneous API overall.
All functionalities previously implemented in CLI commands have been implemented as admin API endpoints. A lot of code has been deduplicated between the CLI and admin API: the CLI is now simply a client of the admin API.
Internally, the CLI does not call the admin API endpoints through the HTTP
admin API, but proxies its API calls over internal Garage RPC. This allows the
garage CLI to behave as before: RPC connection parameters are automatically
detected on the current node, without the need to specify an HTTP endpoint and
authentication token. This change made it possible to implement the garage json-api command that exposes admin API calls in JSON format directly from the
CLI. The internal RPC protocol has evolved to support this way of working,
breaking compatibility between old and new nodes in a same cluster, therefore
also mandating the release of a new major version.
Support for multiple admin API tokens
Garage v2.0.0 also introduced support for multiple admin API tokens, and provides full CLI and API support for managing such tokens. Admin API tokens can be restricted in scope, meaning that they can give access to only a subset of API calls. This can be useful if you need to build an application that manages a certain aspect of your Garage cluster (for instance buckets and keys), but without having access to all of the administration capabilities of the API. We hope that this will be useful to make the use of the admin API both more flexible and more secure. Admin API tokens can also have an expiration date set so that they cannot be used for more than a given amount of time.
As part of our new NLnet grant, we will develop a fully-fledged administration UI for Garage. Thanks to multiple API tokens and token expiration, you will be able to easily rotate the access token for this UI, and to rapidly revoke the current token if it is compromised. Setting a master admin API token in the configuration file, while still supported, will become a discouraged practice.
In the future, we will make the CLI be able to talk to a Garage cluster not only through RPC but also through the HTTP admin API itself. This will give you two ways of using the Garage CLI: either locally with autodetected RPC connection parameters, or remotely by specifying an admin API endpoint and authentication token. Combined with multiple API tokens with restricted scope and expiration dates, this will give you the same flexibility and safety for remote administration using the CLI as when using the web UI. We hope to have this implemented in Garage v2.1.0.
Major changes, new features, and Garage's release schedule
The v2.0.0 major version bump reflects user-facing breaking changes, but it also reflects some changes in the internal data model that were required for the implementation of new features: full support for website redirections, access key expiration and multiple admin tokens. As Garage does not support the possibility of running in a same cluster nodes that have different data models, a new major version is necessarily released when any such feature is implemented.
We would like to take this opportunity to clarify the impact of such changes on the release schedule of Garage. No new feature that would require introducing a change to the data model or to the internal RPC protocol can be released outside of a major version, as we cannot expect new nodes to run alongside old nodes in the same cluster. We are aware that major migrations are scary, and require a lot of caution to be done safely. For this reason, we are trying to limit the pace of major releases. This means that unfortunately, new features might not become immediately available in a stable release after they are implemented. We still want major versions to be released regularly so that these new features can be made available to our users without too much wait. As a compromise, our current target is to release a major version about once a year if there are major changes awaiting release, or less often if there are no such changes.