diff --git a/content/en/docs/Concepts/Custom resource definitions/_index.md b/content/en/docs/Concepts/Custom resource definitions/_index.md new file mode 100755 index 00000000..00221534 --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/_index.md @@ -0,0 +1,15 @@ + +--- +title: "Custom Resource Definitions" +linkTitle: "Custom Resource Definitions" +weight: 4 +description: > + This page describes [Custom Resource Definitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) that are defined by OLM +--- + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + + diff --git a/content/en/docs/Concepts/Custom resource definitions/catalog-source.md b/content/en/docs/Concepts/Custom resource definitions/catalog-source.md new file mode 100644 index 00000000..f5d4a1d9 --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/catalog-source.md @@ -0,0 +1,16 @@ +--- +title: "Catalog Source" +linkTitle: "Catalog Source" +weight: 5 +description: > + This guide introduces the concept of Catalog Source in OpenShift Lifecycle Manager. +--- + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + +### Definition + +The CatalogSource represents a repository of bundles, which are collections of resources that must contain [CSVs](#ClusterServiceVersion), [CRDs](#CustomResourceDefinitions), and package definitions. There are multiple implementations of a CatalogSource backend, the current recommendation is to use a [registry image](#Index). \ No newline at end of file diff --git a/content/en/docs/Concepts/Custom resource definitions/cluster-service-version.md b/content/en/docs/Concepts/Custom resource definitions/cluster-service-version.md new file mode 100644 index 00000000..937a0bda --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/cluster-service-version.md @@ -0,0 +1,17 @@ +--- +title: "Cluster Service Version" +linkTitle: "Cluster Service Version" +weight: 4 +description: > + This guide introduces the concept of Cluster Service Version(CSV) in OpenShift Lifecycle Manager. +--- + + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + + +### Definition +The ClusterServiceVersion represents a particular version of a ClusterService and its operator. It includes metadata such as name, description, version, repository link, labels, icon, etc. It declares `owned`/`required` CRDs, cluster requirements, and install strategy that tells OLM how to create required resources and set up the operator as a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). diff --git a/content/en/docs/Concepts/Custom resource definitions/intall-plan.md b/content/en/docs/Concepts/Custom resource definitions/intall-plan.md new file mode 100644 index 00000000..714dc7b4 --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/intall-plan.md @@ -0,0 +1,17 @@ +--- +title: "Install Plan" +linkTitle: "Install Plan" +weight: 7 +description: > + This guide introduces the concept of Install Plan in OpenShift Lifecycle Manager. +--- + + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + +## Definition + +The InstallPlan defines a set of resources to be created in order to install or upgrade to a specific version of a ClusterService defined by a CSV. \ No newline at end of file diff --git a/content/en/docs/Concepts/Custom resource definitions/operator-group.md b/content/en/docs/Concepts/Custom resource definitions/operator-group.md new file mode 100644 index 00000000..ca1a874c --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/operator-group.md @@ -0,0 +1,15 @@ +--- +title: "Operator Group" +linkTitle: "Operator Group" +weight: 6 +description: > + This guide introduces the concept of Operator Group in OpenShift Lifecycle Manager. +--- + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + +### Definition + The OperatorGroup selects a set of target namespaces in which to generate required RBAC access for its member Operators. \ No newline at end of file diff --git a/content/en/docs/Concepts/Custom resource definitions/subscription.md b/content/en/docs/Concepts/Custom resource definitions/subscription.md new file mode 100644 index 00000000..ac5cf7ea --- /dev/null +++ b/content/en/docs/Concepts/Custom resource definitions/subscription.md @@ -0,0 +1,78 @@ +--- +title: "Subscription" +linkTitle: "Subscription" +weight: 8 +description: > + This guide introduces the concept of Subscription in OpenShift Lifecycle Manager. +--- + +Subscriptions are Custom Resources that relate an operator to a CatalogSource. Subscriptions describe which channel of an operator package to subscribe to and whether to perform updates automatically or manually. If set to automatic, the Subscription ensures OLM will manage and upgrade the operator to ensure the latest version is always running in the cluster. + +Here's an example of a Subscription definition: + +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: my-operator + namespace: openshift-operators +spec: + channel: stable + name: my-operator + source: redhat-operators + sourceNamespace: openshift-marketplace +``` + +This Subscription object defines the name and namespace of the operator, as well as the catalog from which the operator data can be found. The channel (such as alpha, beta, or stable) helps determine which stream of the operator should be installed from the CatalogSource. + +## Manually Approving Upgrades via Subscriptions + +By default, OLM will automatically approve updates to an operator as new versions become available via a CatalogSource. When creating a subscription, it is possible to disable automatic updates by setting the `approval` field to `Manual` like so: + +```yaml +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: my-operator + namespace: openshift-operators +spec: + channel: stable + name: my-operator + source: redhat-operators + sourceNamespace: openshift-marketplace + approval: Manual +``` + +Setting the `approval` field to manual will prevent OLM from automatically installing the operator. As such, you will need to approve the installPlan which can be done with the following commands: + +```bash +kubectl -n openshift-operators get installplans +NAME CSV APPROVAL APPROVED +install-bfmxd my-operator.v0.1.0 Manual false + +$ kubectl -n default patch installplan install-bfmxd -p '{"spec":{"approved":true}}' --type merge +installplan.operators.coreos.com/install-bfmxd patched + +$ kubectl -n openshift-operators get installplans +NAME CSV APPROVAL APPROVED +install-bfmxd my-operator.v0.1.0 Manual true +``` + +Now that the `install-bfmxd` installPlan is in the approved state, OLM will install the operator defined by the `my-operator.v0.1.0` CSV. + +When the CatalogSource is updated with a newer version of that operator in the channel you selected, a new installPlan will be created in the namespace that you installed the operator to, as shown below: + +```bash +$ kubectl -n openshift-operators get installplans +NAME CSV APPROVAL APPROVED +install-bfmxd my-operator.v0.1.0 Manual true +install-svojy my-operator.v0.2.0 Manual false +``` + +From here, you can approve `install-svojy` using the patch command shown earlier. + +With the new installPlan in the approve state, the `my-operator.v0.2.0` CSV will be deployed to the cluster and if the CSV reaches the `Succeeded` state the old CSV will be deleted. If the new CSV fails to reach the `Succeeded` state, both CSVs will continue to exist and it is up to the user to resolve the failure. In either case, OLM will not delete old installPlans as they act as a record of CSVs that were installed on your cluster. + +## How do I know when an update is available for an operator + +It is possible to identify when there is a newer version of an operator available by inspecting the status of the operator's subscription. The value associated with the `currentCSV` field is the newest version that is known to OLM, and `installedCSV` is the version that is installed on the cluster. \ No newline at end of file diff --git a/content/en/docs/Concepts/_index.md b/content/en/docs/Concepts/_index.md index cfb778fe..06753867 100644 --- a/content/en/docs/Concepts/_index.md +++ b/content/en/docs/Concepts/_index.md @@ -1,105 +1,14 @@ --- title: "Concepts" linkTitle: "Concepts" -weight: 4 +weight: 3 description: > - This page contains a list of terms defined by OLM, along with their definitions and common Aliases. + This page contains a list of terms defined by OLM, along with their definitions and common Aliases. --- {{% alert title="Warning" color="warning" %}} -These pages are under construction. Please continue to use the [docs in -OLM git book](https://github.com/operator-framework/olm-book) -for now. +These pages are under construction. +ToDo: *Complete this* {{% /alert %}} -## CustomResourceDefinitions (CRDs) - -The following [CustomResourceDefinitions](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) are defined by the OLM. - -### ClusterServiceVersion - -**Definition**: The ClusterServiceVersion represents a particular version of a ClusterService and its operator. It includes metadata such as name, description, version, repository link, labels, icon, etc. It declares `owned`/`required` CRDs, cluster requirements, and install strategy that tells OLM how to create required resources and set up the operator as a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). - -**Aliases**: CSV(s) - -### CatalogSources - -**Definition**: The CatalogSource represents a repository of bundles, which are collections of resources that must contain [CSVs](#ClusterServiceVersion), [CRDs](#CustomResourceDefinitions), and package definitions. There are multiple implementations of a CatalogSource backend, the current recommendation is to use a [registry image](#Index). - -**Aliases**: CatSrc(s) - -### InstallPlans - -**Definition**: The InstallPlan defines a set of resources to be created in order to install or upgrade to a specific version of a ClusterService defined by a CSV. - -**Aliases**: IP(s) - -### OperatorGroups - -**Definition**: The OperatorGroup selects a set of target namespaces in which to generate required RBAC access for its member Operators. - -**Aliases**: OG(s) - -### OperatorSources - -**Definition**: The OperatorSources are a way of pointing to external app registry namespaces that contain a catalog of operators. Applying an OperatorSource to a cluster makes the operators in that OperatorSource available for installation in that cluster. - -**Aliases**: OpSrc(s) - -### Subscriptions - -**Definition**: Subscriptions are Custom Resources that relate an operator to a CatalogSource. Subscriptions describe which channel of an operator package to subscribe to, and whether to perform updates automatically or manually. If set to automatic, the Subscription ensures OLM will manage and upgrade the operator to ensure the latest version is always running in the cluster. - -**Aliases**: Subs(s) - -## OLM Concepts - -### Bundle - -**Definition**: A collection of Operator [CSV](#ClusterServiceVersion), manifests, and metadata which together form a unique version of an Operator that can be installed onto the cluster. - -### Bundle Image - -**Definition**: An image of a bundle is built from operator manifests and contains exactly one [bundle](#Bundle). The bundle images are stored and distributed by OCI spec container registries such as Quay.io or DockerHub. - -### Channel - -**Definition**: The channel defines a stream of updates for an operator and is used to roll out updates for subscribers. The head points at the latest version of that channel. For example, a stable channel would have all stable versions of an operator arranged from the earliest to the latest. An operator can have several channels, and a subscription binding to a certain channel would only look for updates in that channel. - -### Channel Head - -**Definition**: Head refers to the latest known update in a particular [channel](#Channel). - -### Catalog Image - -**Definition**: A catalog image is a containerized datastore that describes a set of operator and update metadata that can be installed onto a cluster via OLM. - -**Aliases**: OPM Index - -### Dependency - -**Definition**: An Operator may have a dependency on another Operator being present in the cluster. For example, the Vault Operator has a dependency on the Etcd Operator for its data persistence layer. OLM resolves these dependencies by ensuring all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a Catalog that satisfies the required CRD API, and not related to [packages](#Packages)/[bundles](#Bundles). - -**Aliases**: Operator Dependency, GVK Dependency, API Dependency, Required CRD - -### Index - -**Definition**: The Index refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs, CRDs, etc of all versions. This index can host a history of used operators on a cluster and be maintained by adding or removing operators. - -**Aliases**: Registry DB, Catalog DB, OPM registry - -### Package - -**Definition**: A package is a directory that encloses all released history of an Operator with each version contained - in the bundle format. A released version of an Operator is described in a ClusterServiceVersion manifest alongside the CustomResourceDefinitions. - -### Registry - -**Definition**: A database which stores [Bundle Images](#Bundle-Image) of Operators, each with all of its latest/historical versions in all [channels](#Channel). - -### Upgrade Graph - -**Definition**: An upgrade graph links versions of [CSV](#ClusterServiceVersions) together, similar to the upgrade graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added. This is automatically resolved as part - - diff --git a/content/en/docs/Concepts/additional-concepts.md b/content/en/docs/Concepts/additional-concepts.md new file mode 100644 index 00000000..a761bfc2 --- /dev/null +++ b/content/en/docs/Concepts/additional-concepts.md @@ -0,0 +1,61 @@ +--- +title: "Additional Concepts" +linkTitle: "Additional Concepts" +weight: 5 +description: > + This guide introduces the additional OLM concepts. +--- + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this** +{{% /alert %}} + + +### Bundle + +**Definition**: A collection of Operator [CSV](../custom-resource-definitions/cluster-service-version), manifests, and metadata which together form a unique version of an Operator that can be installed onto the cluster. + +### Bundle Image + +**Definition**: An image of a bundle is built from operator manifests and contains exactly one [bundle](#Bundle). The bundle images are stored and distributed by OCI spec container registries such as Quay.io or DockerHub. + +### Channel + +**Definition**: The channel defines a stream of updates for an operator and is used to roll out updates for subscribers. The head points at the latest version of that channel. For example, a stable channel would have all stable versions of an operator arranged from the earliest to the latest. An operator can have several channels, and a subscription binding to a certain channel would only look for updates in that channel. + +### Channel Head + +**Definition**: Head refers to the latest known update in a particular [channel](#Channel). + +### Catalog Image + +**Definition**: A catalog image is a containerized datastore that describes a set of operator and update metadata that can be installed onto a cluster via OLM. + +**Aliases**: OPM Index + +### Dependency + +**Definition**: An Operator may have a dependency on another Operator being present in the cluster. For example, the Vault Operator has a dependency on the Etcd Operator for its data persistence layer. OLM resolves these dependencies by ensuring all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a Catalog that satisfies the required CRD API, and not related to [packages](#Packages)/[bundles](#Bundles). + +**Aliases**: Operator Dependency, GVK Dependency, API Dependency, Required CRD + +### Index + +**Definition**: The Index refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs, CRDs, etc of all versions. This index can host a history of used operators on a cluster and be maintained by adding or removing operators. + +**Aliases**: Registry DB, Catalog DB, OPM registry + +### Package + +**Definition**: A package is a directory that encloses all released history of an Operator with each version contained + in the bundle format. A released version of an Operator is described in a ClusterServiceVersion manifest alongside the CustomResourceDefinitions. + +### Registry + +**Definition**: A database which stores [Bundle Images](#Bundle-Image) of Operators, each with all of its latest/historical versions in all [channels](#Channel). + +### Upgrade Graph + +**Definition**: An upgrade graph links versions of [CSV](../custom-resource-definitions/cluster-service-version) together, similar to the upgrade graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added. This is automatically resolved as part + diff --git a/content/en/docs/Concepts/olm-architecture.md b/content/en/docs/Concepts/olm-architecture.md new file mode 100644 index 00000000..598c0e1b --- /dev/null +++ b/content/en/docs/Concepts/olm-architecture.md @@ -0,0 +1,83 @@ +--- +title: "OLM Architecture" +linkTitle: "OLM Architecture" +weight: 3 +description: > + This guide outlines the concepts and architecture of the Operator Lifecycle Manager (OLM) in OpenShift Container Platform. +--- + +{{% alert title="Warning" color="warning" %}} +These pages are under construction. +**ToDo: Complete this (Inlude an image?) ** +{{% /alert %}} + + +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. \ No newline at end of file