Proposal 114: Add support for multiple API versions to the agent

114-agent-multiple-api.md

@@ -0,0 +1,197 @@
+# enhancement-114: Add support for multiple API versions to the agent
+
+<!-- toc -->
+- [Release Signoff Checklist](#release-signoff-checklist)
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (optional)](#user-stories-optional)
+    - [Story 1](#story-1)
+    - [Story 2](#story-2)
+  - [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
+<!-- /toc -->
+
+## Release Signoff Checklist
+
+- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
+- [ ] Core members have approved the issue with the label `implementable`
+- [ ] Design details are appropriately documented
+- [ ] Test plan is in place
+- [ ] User-facing documentation has been created in [keylime/keylime-docs]
+
+## Summary
+
+Add support for multiple API versions in the agent, making it possible for it to
+communicate with older versions of the verifier, registrar, and tenant.
+
+## Motivation
+
+Currently, the agent only supports the latest API version, meaning that it will
+not accept connections from older versions of the other Keylime components nor
+make requests using an older API version to communicate with them.
+This means that deployments based on older versions of the Keylime server
+components cannot monitor machines running agents that have a newer API version.
+
+Specifically for long-term supported distributions, such as RHEL, the lack of
+the ability to monitor systems that have a newer version of the agent with
+infrastructure based on older server components means that the agent cannot be
+updated without breaking compatibility.  This is not acceptable for long-term
+supported distributions, resulting in the agent being held in an older version
+for a long period to keep compatibility, making maintenance difficult as the
+time passes, since the gap between the latest upstream version and the supported
+version could grow too big.
+
+The other components already support communicating with older versions of the
+agent; adding this support to the agent would make it possible to have
+deployments with components on mixed versions.
+
+### Goals
+
+Make the agent backwards compatible, allowing a system running a newer version
+of the agent to be monitored by attestation infrastructure based on an older
+versions of the server components.
+
+### Non-Goals
+
+Support all existing API versions is a non-goal: only a number of the latest
+versions should be supported, given they are compatible.
+
+## Proposal
+
+The proposal is to make the agent capable of communicating with older versions
+of the other components. For this, it is required that the agent support
+receiving connections using older API versions, as well as making it possible
+for the agent to use older API versions when making requests to the other
+components.
+
+To make it possible for the agent to receive connections from older versions of
+the other components, the agent should provide endpoints under multiple API
+versions instead of using only the latest API version.
+
+On the other way around, for the agent to be able to connect to a server that
+supports only older versions of the API, the agent should use a compatible API
+version when making requests (e.g. when registering itself with the registrar).
+
+To make the agent capable of choosing a compatible API version when making
+requests, the other components should implement an endpoint similar to the
+`/version` endpoint provided by the agent.  This endpoint should provide the
+latest supported API version, making it easy for the agent to query for the
+supported API version and adjust its requests accordingly.
+
+In the absence of this new endpoint, the agent can try to reach the other
+components by trial and error using supported older versions.  Although this is
+not an efficient method, it is the only way for the agent to communicate with
+older versions of the other components without having a way to query the
+supported version.
+
+If possible, the user should be able to select a subset of the supported API
+versions to enable via configuration options.  To keep the current behavior
+(only accept the latest API version), the configuration option could support a
+special keyword (e.g. "latest") to only support the latest API version.
+
+### User Stories (optional)
+
+#### Story 1
+
+As a system administrator with an existing Keylime deployment in production, I
+want to add new machines to be monitored, but using a newer version of the
+Keylime agent on those machines.  The newer version of the Keylime agent running
+on those machines should be able to communicate with my existing deployed
+Keylime components (verifier, registrar, and tenant).
+
+#### Story 2
+
+As a system administrator with an existing Keylime deployment in production, I
+want to update the version of the Keylime agent used in my monitored machines.
+The updated version of the Keylime agent should be able to communicate with my
+existing deployed Keylime components (verified, registrar, and tenant).
+
+### Notes/Constraints/Caveats (optional)
+
+No caveats were identified at the moment.
+
+### Risks and Mitigations
+
+No risks were identified at the moment.
+
+## Design Details
+
+The proposed changes to the server components other than the agent are:
+ - Provide the `/version` endpoint which replies to `GET` requests with the
+   latest supported API version. The provided endpoint response format should
+   follow the current response provided by the agent `/version` endpoint:
+
+```json
+{
+  "code": 200,
+  "status": "Success",
+  "results": {
+    "supported_version": "2.0"
+  }
+}
+```
+
+The proposed changes to the agent are:
+ - The agent provides the endpoints to receive connections under multiple API
+   versions (e.g. `/v2.1/quotes/identity` and `/v2.0/quotes/identity`)
+   - Ideally the user can configure a subset of the supported API versions to
+     enable via configuration. The agent should provide the endpoints under the
+     selected API versions.
+     - For example: from the set of supported versions `['2.0', '2.1', '2.2]`,
+       the user could select which versions to enable by setting the
+       configuration option `api_versions = ['2.1', '2.2']`
+ - When connecting to a remote server, the agent makes requests using an API
+   version supported by the remote server it is contacting.
+   - If the remote server provides the `/version` endpoint, the agent should
+     first query this endpoint with a `GET` request to obtain the latest
+     supported version. Then the agent should adjust all the requests it creates
+     to use the supported version
+   - In the absence of the `/version` endpoint on the remote server (which will
+     be the case for the current existing server components), the agent should
+     try older supported API versions, starting with the newest to contact the
+     remote server. Once the connection is established, the agent should store
+     the used API version and reuse in future connections.
+
+### Test Plan
+
+Unit tests should be added to the repository test suite. Functional and
+end-to-end tests should be added to the tests repository
+(https://github.com/RedHat-SP-Security/keylime-tests) and added to the CI.
+
+The tests should include mixing agents running older API versions with other
+components running newer API versions and vice-versa.
+
+### Upgrade / Downgrade Strategy
+
+When upgrading, the agent should be configured with a sane default value. The
+suggested is to be configured with all the latest compatible API versions.
+
+### Dependencie requirements
+
+No new dependencies should be required
+
+## Drawbacks
+
+No drawbacks were identified at the moment
+
+## Alternatives
+
+Not implementing this enhancement. In this case, the agent will continue to be
+incompatible with components using older API versions.
+
+Users would not be able to monitor agents running with newer API versions with
+other components on older API versions. They can still monitor agent running on
+older API versions with other components that have a newer API version.
+
+## Infrastructure Needed (optional)
+
+No special infrastructure is needed.