diff --git a/114-agent-multiple-api.md b/114-agent-multiple-api.md new file mode 100644 index 0000000..76dfd44 --- /dev/null +++ b/114-agent-multiple-api.md @@ -0,0 +1,197 @@ +# enhancement-114: Add support for multiple API versions to the agent + + +- [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) + + +## 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.