diff --git a/docs/api-reference/catalogd-webserver.md b/docs/api-reference/catalogd-webserver.md new file mode 100644 index 000000000..a95772ead --- /dev/null +++ b/docs/api-reference/catalogd-webserver.md @@ -0,0 +1,88 @@ +# Catalogd web server + +[Catalogd](https://github.com/operator-framework/catalogd), the OLM v1 component for making catalog contents available on cluster, includes +a web server that serves catalog contents to clients via an HTTP(S) endpoint. + +The endpoint to retrieve this information is provided in the `.status.contentURL` of a `ClusterCatalog` resource. +As an example: + +```yaml + contentURL: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio/all.json +``` + +!!! note + + The value of the `.status.contentURL` field in a `ClusterCatalog` resource is an arbitrary string value and can change at any time. + While there are no guarantees on the exact value of this field, it will always be a URL that resolves successfully for clients using + it to make a request from within the cluster. + +## Interacting With the Server + +### Supported HTTP Methods + +The HTTP request methods supported by the catalogd web server are: + +- [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) +- [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +### Response Format + +Responses are encoded as a [JSON Lines](https://jsonlines.org/) stream of [File-Based Catalog](https://olm.operatorframework.io/docs/reference/file-based-catalogs) (FBC) [Meta](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#schema) objects delimited by newlines. + +??? example "Example JSON-encoded FBC snippet" + + ```json + { + "schema": "olm.package", + "name": "cockroachdb", + "defaultChannel": "stable-v6.x", + } + { + "schema": "olm.channel", + "name": "stable-v6.x", + "package": "cockroachdb", + "entries": [ + { + "name": "cockroachdb.v6.0.0", + "skipRange": "<6.0.0" + } + ] + } + { + "schema": "olm.bundle", + "name": "cockroachdb.v6.0.0", + "package": "cockroachdb", + "image": "quay.io/openshift-community-operators/cockroachdb@sha256:d3016b1507515fc7712f9c47fd9082baf9ccb070aaab58ed0ef6e5abdedde8ba", + "properties": [ + { + "type": "olm.package", + "value": { + "packageName": "cockroachdb", + "version": "6.0.0" + } + }, + ], + } + ``` + + Corresponding JSON lines response: + ```jsonlines + {"schema":"olm.package","name":"cockroachdb","defaultChannel":"stable-v6.x"} + {"schema":"olm.channel","name":"stable-v6.x","package":"cockroachdb","entries":[{"name":"cockroachdb.v6.0.0","skipRange":"<6.0.0"}]} + {"schema":"olm.bundle","name":"cockroachdb.v6.0.0","package":"cockroachdb","image":"quay.io/openshift-community-operators/cockroachdb@sha256:d3016b1507515fc7712f9c47fd9082baf9ccb070aaab58ed0ef6e5abdedde8ba","properties":[{"type":"olm.package","value":{"packageName":"cockroachdb","version":"6.0.0"}}]} + ``` + +### Compression Support + +The `catalogd` web server supports gzip compression of responses, which can significantly reduce associated network traffic. In order to signal that the client handles compressed responses, the client must include `Accept-Encoding: gzip` as a header in the HTTP request. + +The web server will include a `Content-Encoding: gzip` header in compressed responses. + +!!! note + + Only catalogs whose uncompressed response body would result in a response size greater than 1400 bytes will be compressed. + +### Cache Header Support + +For clients interested in caching the information returned from the `catalogd` web server, the `Last-Modified` header is set +on responses and the `If-Modified-Since` header is supported for requests. diff --git a/docs/project/public-api.md b/docs/project/public-api.md new file mode 100644 index 000000000..fed6a7d7b --- /dev/null +++ b/docs/project/public-api.md @@ -0,0 +1,12 @@ +# Public API +The public API of OLM v1 is as follows: + +- Kubernetes APIs. For more information on these APIs, see: + - [operator-controller API reference](./api/operator-controller-api-reference.md) + - [catalogd API reference](./api/catalogd-api-reference.md) +- `Catalogd` web server. For more information on what this includes, see the [catalogd web server documentation](./api/catalogd-webserver.md) + +!!! warning + + Only what is mentioned in the above documentation references is considered part of the public API + and follows SemVer. Anything not mentioned in the above references is prone to breaking changes. diff --git a/mkdocs.yml b/mkdocs.yml index 7680fd461..7df6b7eba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ nav: - Design Decisions: project/olmv1_design_decisions.md - Limitations: project/olmv1_limitations.md - Roadmap: project/olmv1_roadmap.md + - Public API: project/public-api.md - Getting Started: getting-started/olmv1_getting_started.md - Tutorials: - Add a Catalog: tutorials/add-catalog.md @@ -49,6 +50,7 @@ nav: - API Reference: - Operator Controller API reference: api-reference/operator-controller-api-reference.md - CatalogD API reference: api-reference/catalogd-api-reference.md + - CatalogD Web Server reference: api-reference/catalogd-webserver.md - Contribute: - Contributing: contribute/contributing.md - Developing OLM v1: contribute/developer.md