mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-12-25 07:29:38 -05:00
Write version API RFC (#635)
This commit is contained in:
Malte Poll
GitHub
parent
b3a135a166
commit
d2c6e833e5
120
rfc/version-api.md
Normal file
120
rfc/version-api.md
Normal file
@ -0,0 +1,120 @@
|
||||
# Version API
|
||||
|
||||
The version API should expose easy, straightforward, extensible and forward compatible version information to the Constellation CLI (and possibly more consumers).
|
||||
|
||||
Design goals:
|
||||
|
||||
- Simple
|
||||
- Can be implemented using static HTTP file server
|
||||
- Generic over different kinds of resources
|
||||
- OS image versions
|
||||
- Microservice versions
|
||||
- CLI versions
|
||||
- Kubernetes versions
|
||||
|
||||
The following HTTP endpoints are available:
|
||||
|
||||
- `GET /constellation/v1/versions/stream/<stream>/latest/` contains files showing the latest version available
|
||||
- `image.json` contains the latest image version
|
||||
- `microservice.json` contains the latest microservice version
|
||||
- `cli.json` contains the latest cli version
|
||||
- `kubernetes.json` contains the latest supported version of Kubernetes
|
||||
- `GET /constellation/v1/versions/stream/<stream>/major/<major-version>/` contains files with version information for this major version
|
||||
- `image.json` contains a list of all minor image versions that belong to a major version
|
||||
- `microservice.json` contains a list of all minor microservice versions that belong to a major version
|
||||
- `cli.json` contains a list of all minor cli versions that belong to a major version
|
||||
- `kubernetes.json` contains a list of all supported minor version of Kubernetes that belong to a major version
|
||||
- `GET /constellation/v1/versions/stream/<stream>/minor/<minor-version>/` contains files with version information for this minor version
|
||||
- `image.json` contains a list of all patch image versions that belong to a minor version
|
||||
- `microservice.json` contains a list of all patch microservice versions that belong to a minor version
|
||||
- `cli.json` contains a list of all patch cli versions that belong to a minor version
|
||||
- `kubernetes.json` contains a list of all supported patch version of Kubernetes that belong to a minor version
|
||||
|
||||
`stream` is used to distinguish between different release streams. For example, `stable` and `beta` could be two different streams.
|
||||
Currently, only `stable` is supported. The parameter exists to allow for future expansion.
|
||||
|
||||
## Examples
|
||||
|
||||
This shows the version information for the latest OS image. The file could be extended to include more metadata.
|
||||
|
||||
```
|
||||
https://cdn.confidential.cloud/constellation/v1/versions/stream/stable/latest/image.json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"stream": "stable",
|
||||
"kind": "image",
|
||||
"version": "v2.3.0"
|
||||
}
|
||||
```
|
||||
|
||||
This shows the version information for the latest Kubernetes release. The file could be extended to include more metadata.
|
||||
|
||||
```
|
||||
https://cdn.confidential.cloud/constellation/v1/versions/stream/stable/latest/kubernetes.json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"stream": "stable",
|
||||
"kind": "kubernetes",
|
||||
"version": "v1.25.4"
|
||||
}
|
||||
```
|
||||
|
||||
This shows a list of all minor releases of the microservices for the major version `v2`. The file could be extended to include more metadata.
|
||||
|
||||
```
|
||||
https://cdn.confidential.cloud/constellation/v1/versions/stream/stable/major/v2/microservice.json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"stream": "stable",
|
||||
"granularity": "major",
|
||||
"base": "v2",
|
||||
"kind": "microservice",
|
||||
"versions": ["v2.0", "v2.1", "v2.2", "v2.3"]
|
||||
}
|
||||
```
|
||||
|
||||
This shows a list of all patch releases of the CLI for the minor version `v2.3`. The file could be extended to include more metadata.
|
||||
|
||||
```
|
||||
https://cdn.confidential.cloud/constellation/v1/versions/stream/stable/minor/v2.3/cli.json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"stream": "stable",
|
||||
"granularity": "minor",
|
||||
"base": "v2.3",
|
||||
"kind": "cli",
|
||||
"versions": ["v2.3.0", "v2.3.1", "v2.3.2", "v2.3.3"]
|
||||
}
|
||||
```
|
||||
|
||||
## Version discovery
|
||||
|
||||
The version API can be used to find new versions efficiently and can be used to perform simple selection of available upgrades using semantic versioning.
|
||||
Below are some example use cases.
|
||||
|
||||
### Inform about new versions
|
||||
|
||||
The CLI can query the `latest` endpoint to inform users about new releases of the CLI itself.
|
||||
|
||||
### Propose compatible image versions
|
||||
|
||||
The CLI can query the `minor` endpoint to retrieve a list of all patch releases of a Constellation OS image. This can be used to only select compatible versions for image updates if combined with a downgrade protection (only allow updating to image versions that are newer than the one currently in use).
|
||||
|
||||
|
||||
## Possible future extensions
|
||||
|
||||
- Explicit compatbility information between different resource kinds
|
||||
- Example: OS image `v2.3.4` requires microservice version > `v2.3.1`
|
||||
- Allows fine grained control in case of unexpected incompatibility
|
||||
- Version metadata
|
||||
- Changelogs
|
||||
- Deprecation warnings
|
||||
- Security information
|
||||
Loading…
Reference in New Issue
Block a user