openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

Add OLM dependency best practices

Browse Source
This commit is contained in:
Alex Dellapenta
2020-10-07 14:50:35 -06:00
committed by openshift-cherrypick-robot
parent 756b4dbd80
commit f1bb851d8c
12 changed files with 216 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
modules/olm-adding-new-crd-version.adoc
View File

@@ -1,15 +1,15 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="olm-dependency-resolution-adding-new-crd-version_{context}"]
= Adding a new CRD version
.Procedure
To add a new version of a CRD:
To add a new version of a CRD to your Operator:
. Add a new entry in the CRD resource under the `versions` section.
. Add a new entry in the CRD resource under the `versions` section of your CSV.
+
For example, if the current CRD has one version `v1alpha1` and you want to add a
new version `v1beta1` and mark it as the new storage version:
@@ -26,7 +26,7 @@ versions:
----
<1> Add a new entry for `v1beta1`.
. Ensure the referencing version of the CRD in your CSV's `owned` section is
. Ensure the referencing version of the CRD in the `owned` section of your CSV is
updated if the CSV intends to use the new version:
+
[source,yaml]

41
modules/olm-bundle-format-dependencies-file.adoc Normal file
View File

@@ -0,0 +1,41 @@
// Module included in the following assemblies:
//
// * operators/understanding/olm/olm-packaging-format.adoc
// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
[id="olm-bundle-format-dependencies_{context}"]
= Dependencies file
The dependencies of an Operator are listed in a `dependencies.yaml` file in the
`metadata/` folder of a bundle. This file is optional and currently only used to
specify explicit Operator-version dependencies.
The dependency list contains a `type` field for each item to specify what kind
of dependency this is. There are two supported types of Operator dependencies:
* `olm.package`: A package type means this is a dependency for a specific Operator version. The
dependency information must include the package name and the version of the
package in semver format. For example, you can specify an exact version such as
`0.5.2` or a range of versions such as `>0.5.1`.
* `olm.gvk`: With a GVK type, the author can specify a dependency with GVK
information, similar to existing CRD and API-based usage in a CSV. This is a
path to enable Operator authors to consolidate all dependencies, API or explicit
versions, to be in the same place.
In the following example, dependencies are specified for a Prometheus Operator
and etcd CRDs:
.Example `dependencies.yaml` file
[source,yaml]
----
dependencies:
- type: olm.package
value:
packageName: prometheus
version: ">0.27.0"
- type: olm.gvk
value:
group: etcd.database.coreos.com
kind: EtcdCluster
version: v1beta2
----

37
modules/olm-bundle-format.adoc
View File

@@ -115,40 +115,3 @@ In case of a mismatch, the `annotations.yaml` file is authoritative because the
on-cluster Operator Registry that relies on these annotations only has access to
this file.
====
[id="olm-bundle-format-dependencies_{context}"]
== Dependencies
The dependencies of an Operator are listed in a `dependencies.yaml` file inside
the bundle's `metadata/` folder. This file is optional and currently only used
to specify explicit Operator-version dependencies.
The dependency list contains a `type` field for each item to specify what kind
of dependency this is. There are two supported types of Operator dependencies:
* `olm.package`: A package type means this is a dependency for a specific Operator version. The
dependency information must include the package name and the version of the
package in semver format. For example, you can specify an exact version such as
`0.5.2` or a range of versions such as `>0.5.1`.
* `olm.gvk`: With a GVK type, the author can specify a dependency with GVK
information, similar to existing CRD and API-based usage in a CSV. This is a
path to enable Operator authors to consolidate all dependencies, API or explicit
versions, to be in the same place.
In the following example, dependencies are specified for a Prometheus Operator
and etcd CRDs:
.Example `dependencies.yaml` file
[source,yaml]
----
dependencies:
- type: olm.package
value:
packageName: prometheus
version: ">0.27.0"
- type: olm.gvk
value:
group: etcd.database.coreos.com
kind: EtcdCluster
version: v1beta2
----

39
modules/olm-dependencies-best-practices.adoc Normal file
View File

@@ -0,0 +1,39 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
[id="olm-dependency-best-practices_{context}"]
= Dependency best practices
When specifying dependencies, there are best practices you should consider.
Depend on APIs or a specific version range of Operators::
Operators can add or remove APIs at any time; always specify an `olm.gvk` dependency on any APIs your Operators requires. The exception to this is if you are specifying `olm.package` constraints instead.
Set a minimum version::
The Kubernetes documentation on API changes describes what changes are allowed for Kubernetes-style Operators. These versioning conventions allow an Operator to update an API without bumping the API version, as long as the API is backwards-compatible.
For Operator dependencies, this means that knowing the API version of a dependency might not be enough to ensure the dependent Operator works as intended.
For example:
* TestOperator v1.0.0 provides v1alpha1 API version of the MyObject resource.
* TestOperator v1.0.1 adds a new field `spec.newfield` to MyObject, but still at v1alpha1.
Your Operator might require the ability to write `spec.newfield` into MyObject. An `olm.gvk` constraint alone is not enough for OLM to determine that you need TestOperator v1.0.1 and not TestOperator v1.0.0.
Whenever possible, if a specific Operator that provides an API is known ahead of time, specify an additional `olm.package` constraint to set a minimum.
Omit a maximum version or allow a very wide range::
Because Operators provide cluster-scoped resources such as API services and CRDs, an Operator that specifies a small window for a dependency might unnecessarily constrain updates for other consumers of that dependency.
Whenever possible, do not set a maximum version. Alternatively, set a very wide semantic range to prevent conflicts with other Operators. For example, `>1.0.0 <2.0.0`.
Unlike with conventional package managers, Operator authors explicitly encode that updates are safe through channels in OLM. If an update is available for an existing subscription, it is assumed that the Operator author is indicating that it can update from the previous version. Setting a maximum version for a dependency overrides the update stream of the author by unnecessarily truncating it at a particular upper bound.
[NOTE]
====
Cluster administrators cannot override dependencies set by an Operator author.
====
However, maximum versions can and should be set if there are known incompatibilities that must be avoided. Specific versions can be omitted with the version range syntax, for example `> 1.0.0 !1.2.1`.

32
modules/olm-dependencies-caveats.adoc Normal file
View File

@@ -0,0 +1,32 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
[id="olm-dependency-caveats_{context}"]
= Dependency caveats
When specifying dependencies, there are caveats you should consider.
No compound constraints (AND)::
There is currently no method for specifying an AND relationship between constraints. In other words, there is no way to specify that one Operator depends on another Operator that both provides a given API and has version `>1.1.0`.
This means that when specifying a dependency such as:
[source,yaml]
----
dependencies:
- type: olm.package
value:
packageName: etcd
version: ">3.1.0"
- type: olm.gvk
value:
group: etcd.database.coreos.com
kind: EtcdCluster
version: v1beta2
----
It would be possible for OLM to satisfy this with two Operators: one that provides EtcdCluster and one that has version `>3.1.0`. Whether that happens, or whether an Operator is selected that satisfies both constraints, depends on the ordering that potential options are visited. Dependency preferences and ordering options are well-defined and can be reasoned about, but to exercise caution, Operators should stick to one mechanism or the other.
Cross-namespace compatibility::
OLM performs dependency resolution at the namespace scope. It is possible to get into an update deadlock if updating an Operator in one namespace would be an issue for an Operator in another namespace, and vice-versa.

6
modules/olm-dependency-resolution-about.adoc
View File

@@ -13,7 +13,7 @@ However, there is one constraint that similar systems do not generally have that
OLM does: because Operators are always running, OLM attempts to ensure that you
are never left with a set of Operators that do not work with each other.
This means that OLM must never:
This means that OLM must never do the following:
- install a set of Operators that require APIs that cannot be provided, or
- update an Operator in a way that breaks another that depends upon it.
- Install a set of Operators that require APIs that cannot be provided.
- Update an Operator in a way that breaks another that depends upon it.

9
modules/olm-dependency-resolution-crd-upgrades.adoc
View File

@@ -1,16 +1,17 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="olm-dependency-resolution-crd-upgrades_{context}"]
= CustomResourceDefinition (CRD) upgrades
= CRD upgrades
OLM upgrades a CustomResourceDefinition (CRD) immediately if it is owned by a
OLM upgrades a custom resource definition (CRD) immediately if it is owned by a
singular ClusterServiceVersion (CSV). If a CRD is owned by multiple CSVs, then
the CRD is upgraded when it has satisfied all of the following backward
compatible conditions:
- All existing serving versions in the current CRD are present in the new CRD.
- All existing instances, or custom resources (CRs), that are associated with the
- All existing instances, or custom resources, that are associated with the
serving versions of the CRD are valid when validated against the validation
schema of the new CRD.

68
modules/olm-dependency-resolution-preferences.adoc Normal file
View File

@@ -0,0 +1,68 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
[id="olm-dependency-resolution-preferences_{context}"]
= Dependency preferences
There can be many options that equally satisfy a dependency of an Operator. The dependency resolver in Operator Lifecycle Manager (OLM) determines which option best fits the requirements of the requested Operator. As an Operator author or user, it can be important to understand how these choices are made so that dependency resolution is clear.
[id="olm-dependency-catalog-priority_{context}"]
== Catalog priority
On {product-title} cluster, OLM reads CatalogSources to know which Operators are available for installation.
.CatalogSource object
[source,yaml]
----
apiVersion: "operators.coreos.com/v1alpha1"
kind: "CatalogSource"
metadata:
name: "my-operators"
namespace: "operators"
spec:
sourceType: grpc
image: example.com/my/operator-index:v1
displayName: "My Operators"
priority: 100
----
CatalogSource has a `priority` field, which is used by the resolver to know how to prefer options for a dependency.
There are two rules that govern catalog preference:
* Options in higher-priority catalogs are preferred to options in lower-priority catalogs.
* Options in the same catalog as the dependent are preferred to any other catalogs.
[id="olm-dependency-catalog-ordering_{context}"]
== Channel ordering
An Operator package in a catalog is a collection of update channels that a user can subscribe to in a {product-title} cluster. Channels can be used to provide a particular stream of updates for a minor release (`1.2`, `1.3`) or a simple release frequency (`stable`, `fast`).
It is likely that a dependency might be satisfied by Operators in the same package, but different channels. For example, version `1.2` of an Operator might exist in both the `stable` and `fast` channels.
Each package has a default channel, which is always preferred to non-default channels. If no option in the default channel can satisfy a dependency, options are considered from the remaining channels in lexicographic order of the channel name.
[id="olm-dependency-order-winthin-channel_{context}"]
== Order within a channel
There are almost always multiple options to satisfy a dependency within a single channel. For example, Operators in one package and channel provide the same set of APIs.
When a user creates a Subscription, they indicate which channel to receive updates from. This immediately reduces the search to just that one channel. But within the channel, it is likely that many Operators satisfy a dependency.
Within a channel, newer Operators that are higher up in the update graph are preferred. If the head of a channel satisfies a dependency, it will be tried first.
[id="olm-dependency-preferences-other_{context}"]
== Other constraints
In addition to the constraints supplied by package dependencies, OLM includes additional constraints to represent the desired user state and enforce resolution invariants.
[id="olm-dependency-sub-constraint_{context}"]
=== Subscription constraint
A Subscription constraint filters the set of Operators that can satisfy a subscription. Subscriptions are user-supplied constraints for the dependency resolver. They declare the intent to either install a new Operator if it is not already on the cluster, or to keep an existing Operator updated.
[id="olm-dependency-package-constraint_{context}"]
=== Package constraint
Within a namespace, no two Operators may come from the same package.

2
modules/olm-removing-crd-version.adoc
View File

@@ -1,6 +1,6 @@
// Module included in the following assemblies:
//
// * operators/olm-understanding-dependency-resolution.adoc
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="olm-dependency-resolution-removing-crd-version_{context}"]
= Deprecating or removing a CRD version

3
operators/operator_sdk/osdk-generating-csvs.adoc
View File

@@ -74,6 +74,9 @@ include::modules/osdk-owned-crds.adoc[leveloffset=+2]
include::modules/osdk-required-crds.adoc[leveloffset=+2]
include::modules/osdk-crd-templates.adoc[leveloffset=+2]
include::modules/osdk-hiding-internal-objects.adoc[leveloffset=+2]
include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+2]
include::modules/olm-adding-new-crd-version.adoc[leveloffset=+3]
include::modules/olm-removing-crd-version.adoc[leveloffset=+3]
include::modules/osdk-apiservices.adoc[leveloffset=+1]

5
operators/understanding/olm-packaging-format.adoc
View File

@@ -10,6 +10,11 @@ Lifecycle Manager (OLM) in {product-title}.
include::modules/olm-package-manifest-format.adoc[leveloffset=+1]
include::modules/olm-bundle-format.adoc[leveloffset=+1]
include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+2]
.Additional resources
* xref:../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-understanding-dependency-resolution[Operator Lifecycle Manager dependency resolution]
include::modules/olm-opm.adoc[leveloffset=+2]
ifdef::openshift-origin[]

20
operators/understanding/olm/olm-understanding-dependency-resolution.adoc
View File

@@ -5,12 +5,22 @@ include::modules/common-attributes.adoc[]
toc::[]
This guide outlines dependency resolution and Custom Resource Definition (CRD)
upgrade lifecycles with Operator Lifecycle Manager (OLM) in
{product-title}.
This guide outlines dependency resolution and custom resource definition (CRD)
upgrade lifecycles with Operator Lifecycle Manager (OLM) in {product-title}.
include::modules/olm-dependency-resolution-about.adoc[leveloffset=+1]
include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+1]
include::modules/olm-dependency-resolution-preferences.adoc[leveloffset=+1]
include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+1]
include::modules/olm-adding-new-crd-version.adoc[leveloffset=+2]
include::modules/olm-removing-crd-version.adoc[leveloffset=+2]
.Additional resources
* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-dependency-resolution-adding-new-crd-version_osdk-generating-csvs[Adding a new CRD version]
* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-dependency-resolution-removing-crd-version_osdk-generating-csvs[Deprecating or removing a CRD version]
include::modules/olm-dependencies-best-practices.adoc[leveloffset=+1]
.Additional resources
* Kubernetes documentation: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#readme[Changing the API]
include::modules/olm-dependencies-caveats.adoc[leveloffset=+1]
include::modules/olm-dependency-resolution-examples.adoc[leveloffset=+1]