From d1a4dbfc78db4828962d7a430624b05f2b1c0057 Mon Sep 17 00:00:00 2001 From: Lalatendu Mohanty Date: Tue, 24 Sep 2024 23:40:31 -0400 Subject: [PATCH] :book: Adding OLM V1 architecture document (#1301) * Adding OLM V1 architecture document The documentation contains description of the components and a diagram. Removed the components.md file as the architecture doc contains the same information Fixes : [#1124](https://github.com/operator-framework/operator-controller/issues/1124) Signed-off-by: Lalatendu Mohanty * Update docs/drafts/architecture.md Co-authored-by: Per Goncalves da Silva * Update docs/drafts/architecture.md Co-authored-by: Per Goncalves da Silva * Update docs/drafts/architecture.md Co-authored-by: Per Goncalves da Silva * Update docs/drafts/architecture.md Co-authored-by: Per Goncalves da Silva * Addressing the review comments for the arch doc Signed-off-by: Lalatendu Mohanty --------- Signed-off-by: Lalatendu Mohanty Co-authored-by: Per Goncalves da Silva --- docs/components.md | 5 --- docs/drafts/architecture.md | 85 +++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 5 deletions(-) delete mode 100644 docs/components.md create mode 100644 docs/drafts/architecture.md diff --git a/docs/components.md b/docs/components.md deleted file mode 100644 index 160e72117..000000000 --- a/docs/components.md +++ /dev/null @@ -1,5 +0,0 @@ -OLM v1 is composed of various component projects: - -* [operator-controller](https://github.com/operator-framework/operator-controller): operator-controller is the central component of OLM v1, that consumes all of the components below to extend Kubernetes to allows users to install, and manage the lifecycle of other extensions - -* [catalogD](https://github.com/operator-framework/catalogd): Catalogd is a Kubernetes extension that unpacks [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content that is packaged and shipped in container images, for consumption by clients on-clusters (unpacking from other sources, like git repos, OCI artifacts etc, are in the roadmap for catalogD). As component of the Operator Lifecycle Manager (OLM) v1 microservices architecture, catalogD hosts metadata for Kubernetes extensions packaged by the authors of the extensions, as a result helping customers discover installable content. diff --git a/docs/drafts/architecture.md b/docs/drafts/architecture.md new file mode 100644 index 000000000..5be36f9af --- /dev/null +++ b/docs/drafts/architecture.md @@ -0,0 +1,85 @@ + +## OLM V1 Architecture + +This document describes the OLM v1 architecture. OLM v1 consists of two main components: + +* [operator-controller](https://github.com/operator-framework/operator-controller) +* [catalogD](https://github.com/operator-framework/catalogd) + +The diagram below illustrates the OLM v1 architecture and its components, and the following sections describe each of the components in detail. + +### Diagram + +```mermaid +flowchart TB + A(bundle) + B(registry repo) + C(catalog author) + D(bundle author) + E(file based catalog) + F(extension controller) + G(bundle cache) + H(catalog cache) + I(resolver) + J(catalog controller) + K(catalog content cache) + L(catalog http server) + + subgraph Image-registry + B + end + subgraph Cluster + subgraph Operator-controller + F-->G + F-->I + I-->H + end + subgraph Catalogd + J-->K + L<-->K + end + end + + F-->L + F-->B + J-->B + C -- creates --> E + E -- pushed to --> B + D -- creates --> A + A -- pushed to --> B +``` + +**Note**: The direction of the arrow indicates the active part of communication i.e. if arrow starts from A and points to B that means A consumes the information from B unless specifically mentioned. + +### Operator-controller: + +operator-controller is the central component of OLM v1. It is responsible: + * managing a cache of catalog metadata provided by catalogd through its HTTP server + * keeping the catalog metadata cache up-to-date with the current state of the catalogs + * locating the right `registry+v1` bundle, if any, that meet the constraints expressed in the `ClusterExtension` resource, such as package name, version range, channel, etc. given the current state of the cluster + * unpacking the bundle + * applying the bundle manifests: installing or updating the content. + + It has three main sub-components: + * Cluster Extension Controller: + * Queries the catalogd (catalogd HTTP Server) to get catalog information. + * Once received the catalog information is saved to catalog-cache. The cache will be updated automatically if a Catalog is noticed to have a different resolved image reference. + * Reaches out to the registry to download the bundle container images, saves it to the bundle cache, unpacks it and applies the bundle manifests to the cluster. + * It is also Responsible for figuring out which bundle to upgrade + * Resolver: + * Helps the cluster extension controller to filter the bundle reference after applying the user restrictions (e.g. name, priority etc) and returns the bundle reference to the extension controller. + * Bundle Cache: + * Bundle cache returns the cache for the bundle. If a cache does not already exist, a new one will be created. + +### Catalogd: + +Catalogd unpacks [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content that is packaged and shipped in container images, for consumption by clients on-clusters (unpacking from other sources, like git repos, OCI artifacts etc, are in the roadmap for catalogD). It serves the extension metadata, provided by the extension authors, found in the FBC, making it possible for on-cluster clients to discover installable content. + +* Catalogd can be broken down in to three sub-components i.e. ClusterCatalog controller, catalogd http server, catalogd content cache. +* Catalog controller is responsible for pulling FBC based catalog images from registry and unpacking them into the catalog content cache. It is also responsible for reconciling the latest changes in the cluster catalog. +* Catalogd http server is responsible for serving catalog information to clients e.g. cluster extension controller. +* Catalogd content cache is maintained by the catalog controller and used by the catalogd http server to answer queries from clients. + + + +