diff --git a/content/en/docs/Concepts/olm-architecture/_index.md b/content/en/docs/Concepts/olm-architecture/_index.md index a72847e5..24145065 100644 --- a/content/en/docs/Concepts/olm-architecture/_index.md +++ b/content/en/docs/Concepts/olm-architecture/_index.md @@ -7,70 +7,3 @@ description: > A discussion on the architecture of Operator Lifecycle Manager (OLM). --- - -The Operator Lifecycle Manager is composed of two Operators: the OLM Operator and the Catalog Operator. - -Each of these Operators are responsible for managing the CRDs that are the basis for the OLM framework: - -**_Table 1. CRDs managed by OLM and Catalog Operators_** - -| Resource | Short Name | Owner | Description | -|-----------------------|-------------|---------|---------------------------------------| -| ClusterServiceVersion | **csv** | OLM | Application metadata: name, version, icon, required resources, installation, etc. | -| InstallPlan | **ip** | Catalog | Calculated list of resources to be created in order to automatically install or upgrade a CSV. | -| CatalogSource | **catsrc** | Catalog | A repository of CSVs, CRDs, and packages that define an application. | -| Subscription | **sub** | Catalog | Used to keep CSVs up to date by tracking a channel in a package. | -| OperatorGroup | **og** | OLM | Used to group multiple namespaces and prepare them for use by an Operator. | ----------------- - -Each of these Operators are also responsible for creating resources: - -**_Table 2. Resources created by OLM and Catalog Operator_** - -| Resource | Short Name | -|------------------------------------|-------------| -| Deployments | OLM | -| ServiceAccounts | OLM | -| (Cluster)Roles | OLM | -| (Cluster)RoleBindings | OLM | -| Custom Resource Definitions (CRDs) | Catalog | -| ClusterServiceVersions (CSVs) | Catalog | ----------------- - -## OLM Operator - -OLM Operator is responsible for deploying applications defined by CSV resources after the required resources specified in the CSV are present in the cluster. - -OLM Operator is not concerned with the creation of the required resources; users can choose to manually create these resources using the CLI, or users can choose to create these resources using the Catalog Operator. This separation of concern enables users incremental buy-in in terms of how much of the OLM framework they choose to leverage for their application. - -While the OLM Operator is often configured to watch all namespaces, it can also be operated alongside other OLM Operators so long as they all manage separate namespaces. - -### _OLM Operator workflow_ - -* Watches for ClusterServiceVersion (CSVs) in a namespace and checks that requirements are met. If so, runs the install strategy for the CSV. - -{{% alert title="Note" %}}A CSV must be an active member of an OperatorGroup in order for the install strategy to be run.{{% /alert %}} - -## Catalog Operator - -The Catalog Operator is responsible for resolving and installing CSVs and the required resources they specify. It is also responsible for watching CatalogSources for updates to packages in channels and upgrading them (optionally automatically) to the latest available versions. - -A user that wishes to track a package in a channel creates a Subscription resource configuring the desired package, channel, and the CatalogSource from which to pull updates. When updates are found, an appropriate InstallPlan is written into the namespace on behalf of the user. - -Users can also create an InstallPlan resource directly, containing the names of the desired CSV and an approval strategy, and the Catalog Operator creates an execution plan for the creation of all of the required resources. After it is approved, the Catalog Operator creates all of the resources in an InstallPlan; this then independently satisfies the OLM Operator, which proceeds to install the CSVs. - -### _Catalog Operator workflow_ - -* Has a cache of CRDs and CSVs, indexed by name. -* Watches for unresolved InstallPlans created by a user: - * Finds the CSV matching the name requested and adds it as a resolved resource. - * For each managed or required CRD, adds it as a resolved resource. - * For each required CRD, finds the CSV that manages it. -* Watches for resolved InstallPlans and creates all of the discovered resources for it (if approved by a user or automatically). -* Watches for CatalogSources and Subscriptions and creates InstallPlans based on them. - -## Catalog Registry - -The Catalog Registry stores CSVs and CRDs for creation in a cluster and stores metadata about packages and channels. - -A _package manifest_ is an entry in the Catalog Registry that associates a package identity with sets of CSVs. Within a package, channels point to a particular CSV. Because CSVs explicitly reference the CSV that they replace, a package manifest provides the Catalog Operator all of the information that is required to update a CSV to the latest version in a channel, stepping through each intermediate version. diff --git a/content/en/docs/Concepts/olm-architecture/components-of-olm.md b/content/en/docs/Concepts/olm-architecture/components-of-olm.md new file mode 100644 index 00000000..1f856567 --- /dev/null +++ b/content/en/docs/Concepts/olm-architecture/components-of-olm.md @@ -0,0 +1,74 @@ +--- +title: "Components of OLM" +date: 2020-12-14 +weight: 1 +description: > + A discussion on the components that make up OLM +--- + +The Operator Lifecycle Manager is composed of two Operators: the OLM Operator and the Catalog Operator. + +Each of these Operators are responsible for managing the CRDs that are the basis for the OLM framework: + +**_Table 1. CRDs managed by OLM and Catalog Operators_** + +| Resource | Short Name | Owner | Description | +|-----------------------|-------------|---------|---------------------------------------| +| ClusterServiceVersion | **csv** | OLM | Application metadata: name, version, icon, required resources, installation, etc. | +| InstallPlan | **ip** | Catalog | Calculated list of resources to be created in order to automatically install or upgrade a CSV. | +| CatalogSource | **catsrc** | Catalog | A repository of CSVs, CRDs, and packages that define an application. | +| Subscription | **sub** | Catalog | Used to keep CSVs up to date by tracking a channel in a package. | +| OperatorGroup | **og** | OLM | Used to group multiple namespaces and prepare them for use by an Operator. | +---------------- + +Each of these Operators are also responsible for creating resources: + +**_Table 2. Resources created by OLM and Catalog Operator_** + +| Resource | Short Name | +|------------------------------------|-------------| +| Deployments | OLM | +| ServiceAccounts | OLM | +| (Cluster)Roles | OLM | +| (Cluster)RoleBindings | OLM | +| Custom Resource Definitions (CRDs) | Catalog | +| ClusterServiceVersions (CSVs) | Catalog | +---------------- + +## OLM Operator + +OLM Operator is responsible for deploying applications defined by CSV resources after the required resources specified in the CSV are present in the cluster. + +OLM Operator is not concerned with the creation of the required resources; users can choose to manually create these resources using the CLI, or users can choose to create these resources using the Catalog Operator. This separation of concern enables users incremental buy-in in terms of how much of the OLM framework they choose to leverage for their application. + +While the OLM Operator is often configured to watch all namespaces, it can also be operated alongside other OLM Operators so long as they all manage separate namespaces. + +### _OLM Operator workflow_ + +* Watches for ClusterServiceVersion (CSVs) in a namespace and checks that requirements are met. If so, runs the install strategy for the CSV. + +{{% alert title="Note" %}}A CSV must be an active member of an OperatorGroup in order for the install strategy to be run.{{% /alert %}} + +## Catalog Operator + +The Catalog Operator is responsible for resolving and installing CSVs and the required resources they specify. It is also responsible for watching CatalogSources for updates to packages in channels and upgrading them (optionally automatically) to the latest available versions. + +A user that wishes to track a package in a channel creates a Subscription resource configuring the desired package, channel, and the CatalogSource from which to pull updates. When updates are found, an appropriate InstallPlan is written into the namespace on behalf of the user. + +Users can also create an InstallPlan resource directly, containing the names of the desired CSV and an approval strategy, and the Catalog Operator creates an execution plan for the creation of all of the required resources. After it is approved, the Catalog Operator creates all of the resources in an InstallPlan; this then independently satisfies the OLM Operator, which proceeds to install the CSVs. + +### _Catalog Operator workflow_ + +* Has a cache of CRDs and CSVs, indexed by name. +* Watches for unresolved InstallPlans created by a user: + * Finds the CSV matching the name requested and adds it as a resolved resource. + * For each managed or required CRD, adds it as a resolved resource. + * For each required CRD, finds the CSV that manages it. +* Watches for resolved InstallPlans and creates all of the discovered resources for it (if approved by a user or automatically). +* Watches for CatalogSources and Subscriptions and creates InstallPlans based on them. + +## Catalog Registry + +The Catalog Registry stores CSVs and CRDs for creation in a cluster and stores metadata about packages and channels. + +A _package manifest_ is an entry in the Catalog Registry that associates a package identity with sets of CSVs. Within a package, channels point to a particular CSV. Because CSVs explicitly reference the CSV that they replace, a package manifest provides the Catalog Operator all of the information that is required to update a CSV to the latest version in a channel, stepping through each intermediate version. diff --git a/content/en/docs/Concepts/olm-architecture/operator-catalog/creating-an-update-graph.md b/content/en/docs/Concepts/olm-architecture/creating-an-update-graph.md similarity index 99% rename from content/en/docs/Concepts/olm-architecture/operator-catalog/creating-an-update-graph.md rename to content/en/docs/Concepts/olm-architecture/creating-an-update-graph.md index fc6f8421..367fd2b9 100644 --- a/content/en/docs/Concepts/olm-architecture/operator-catalog/creating-an-update-graph.md +++ b/content/en/docs/Concepts/olm-architecture/creating-an-update-graph.md @@ -1,9 +1,9 @@ --- -title: "Creating an update graph with OLM" +title: "Creating an update graph for OLM" date: 2020-12-14 -weight: 7 +weight: 2 description: > - Creating an update graph with OLM + Creating an update graph for OLM --- >Note: This document discusses creating an upgrade graph for your operator using plaintext files to store catalog metadata, which is the [latest feature][file-based-catalog-spec] of OLM catalogs. If you are looking to create an upgrade graph for your operator using the deprecated sqllite database format to store catalog metadata instead, please read the [v0.18.z version][v0.18.z-version] of this doc instead. diff --git a/content/en/docs/Concepts/olm-architecture/dependency-resolution/_index.md b/content/en/docs/Concepts/olm-architecture/dependency-resolution.md similarity index 99% rename from content/en/docs/Concepts/olm-architecture/dependency-resolution/_index.md rename to content/en/docs/Concepts/olm-architecture/dependency-resolution.md index d30291e2..39588016 100644 --- a/content/en/docs/Concepts/olm-architecture/dependency-resolution/_index.md +++ b/content/en/docs/Concepts/olm-architecture/dependency-resolution.md @@ -1,8 +1,10 @@ --- title: "Dependency Resolution" linkTitle: "Dependency Resolution" -date: 2020-09-18 -weight: 12 +date: 2022-14-01 +weight: 2 +description: > + A discussion on operator dependency resolution with OLM --- Much like system or language package managers, OLM can resolve dependencies to fulfill an operator's runtime requirements. diff --git a/content/en/docs/Reference/file-based-catalogs.md b/content/en/docs/Reference/file-based-catalogs.md index 4e31960f..837f1270 100644 --- a/content/en/docs/Reference/file-based-catalogs.md +++ b/content/en/docs/Reference/file-based-catalogs.md @@ -215,7 +215,7 @@ The `olm.channel` [cue][cuelang-spec] schema is: For more information about defining upgrade edges, see the [upgrade graph reference documentation][upgrade-graph-doc]. -[upgrade-graph-doc]: /docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph +[upgrade-graph-doc]: /docs/concepts/olm-architecture/creating-an-update-graph #### `olm.bundle` diff --git a/content/en/docs/Tasks/Troubleshooting/catalogsource.md b/content/en/docs/Tasks/Troubleshooting/catalogsource.md index 972c8833..e3a51dac 100644 --- a/content/en/docs/Tasks/Troubleshooting/catalogsource.md +++ b/content/en/docs/Tasks/Troubleshooting/catalogsource.md @@ -58,4 +58,4 @@ If the operator is present, check if the version you want is available: If you are attempting to pull images from a private registry, make sure to specify a secret key in the `CatalogSource.Spec.Secrets` field. -[olm-arch-doc]: /docs/concepts/olm-architecture#catalog-operator \ No newline at end of file +[olm-arch-doc]: /docs/concepts/olm-architecture/components-of-olm/#catalog-operator \ No newline at end of file diff --git a/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md b/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md index 433fb0fe..6716989c 100644 --- a/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md +++ b/content/en/docs/Tasks/Troubleshooting/olm-and-catalog-operators.md @@ -43,4 +43,4 @@ $ kubectl -n olm logs olm-operator-6999db5767-5r5zs ... ``` -[olm-arch-doc]: /docs/concepts/olm-architecture +[olm-arch-doc]: /docs/concepts/olm-architecture/components-of-olm diff --git a/content/en/docs/Tasks/creating-a-catalog.md b/content/en/docs/Tasks/creating-a-catalog.md index cf21f416..b1120bfe 100644 --- a/content/en/docs/Tasks/creating-a-catalog.md +++ b/content/en/docs/Tasks/creating-a-catalog.md @@ -128,5 +128,5 @@ Now the catalog image is available for clusters to use and reference with `Catal [catalogsource-crd]: /docs/concepts/crds/catalogsource [file-based-catalog-spec]: /docs/reference/file-based-catalogs -[upgrade-graph-doc]: /docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph +[upgrade-graph-doc]: /docs/concepts/olm-architecture/creating-an-update-graph [v0.18.z-version]: https://v0-18-z.olm.operatorframework.io/docs/tasks/make-index-available-on-cluster/ diff --git a/content/en/docs/contribution-guidelines/upgrade-graphs.md b/content/en/docs/contribution-guidelines/upgrade-graphs.md index b561631b..13bb5c39 100644 --- a/content/en/docs/contribution-guidelines/upgrade-graphs.md +++ b/content/en/docs/contribution-guidelines/upgrade-graphs.md @@ -236,6 +236,6 @@ flowchart TB {{}} | [olm-channel]:/docs/reference/file-based-catalogs/#olmchannel -[upgrade-path-replaces]:/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/#replaces -[upgrade-path-skips]:/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/#skips -[upgrade-path-skiprange]:/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/#skiprange \ No newline at end of file +[upgrade-path-replaces]:/docs/concepts/olm-architecture/creating-an-update-graph/#replaces +[upgrade-path-skips]:/docs/concepts/olm-architecture/creating-an-update-graph/#skips +[upgrade-path-skiprange]:/docs/concepts/olm-architecture/creating-an-update-graph/#skiprange \ No newline at end of file