Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

📖 Docs for version range support #544

Merged
merged 3 commits into from
Nov 28, 2023
Merged

📖 Docs for version range support #544

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
76a1ac1
Issue #407: Docs for version range support
michaelryanpeter Nov 16, 2023
a112f0f
Address feedback. Define operators and comparisons.
michaelryanpeter Nov 20, 2023
164bb28
Apply review feedback
michaelryanpeter Nov 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/drafts/version-ranges.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Operator version ranges
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created a follow up issue to add example CRs to the doc: #552


This document explains how to specify a version range to install or update an Operator with OLM 1.0.

You define an Operator's target version in its custom resource (CR) file.
The following list describes how OLM resolves an Operator's target version, and the resulting actions:

Not specifying a version in the CR
michaelryanpeter marked this conversation as resolved.
Show resolved Hide resolved
: Installs or updates the latest version of the Operator.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

latest

Technically, it's the latest version that satisfies resolution. I think it's important to call that out pretty clearly somewhere, and possibly explain with an example.

For example:

In the catalog:

  • packageA v1.0.0 exists and depends on packageB v1.2.0
  • packageB v1.2.0 exists
  • packageB v1.2.1 exists

On the cluster:

  • Operator for packageA says spec.version: 1.0.0
  • Operator for packageB says spec.version: 1.2.x

The version that will ultimately be chosen for packageB is 1.2.0 even though 1.2.1 is available, because that's what packageA requires.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the moment, I linked to Deppy's README to explain resolution. WDYT of creating a follow up issue to port the OCP docs about dependency resolution upstream?

Updates are applied automatically when they are published to the catalog.

Specifying a version in the CR
: Installs or updates the specified version.
Updates are not applied automatically.
If you want to update the Operator, you must manually edit the CR and apply the changes to the cluster.

Specifying a channel
: Installs or updates the latest version of the Operator in the channel.
Updates are applied automatically when they are published to the specified channel.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would expect this doc to be purely about spec.version, so I'd suggest striking this.

In a higher-level doc, I'd expect something that talks about the various spec fields and their interactions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.


Specifying a version range in the CR
: Installs or updates the latest version of the Operator within the version range.
Updates that are within the specified range are automatically installed.
Updates that are outside of the specified range are not installed.

The `spec.version` field uses the Masterminds `semver` package to enable the version range functionality.

OLM 1.0 does not support following methods for specifying a version range:

* Using tags and labels are not supported.
You must use semantic versioning to define a version range.
* Using [hypen range comparisons](https://github.com/Masterminds/semver#hyphen-range-comparisons) are not supported.
michaelryanpeter marked this conversation as resolved.
Show resolved Hide resolved
For example, the following range option is not supported:

```yaml
version: 3.0 - 3.6
```

To specify a range option, use a method similar to the following example:

```yaml
version: >=3.0 <3.6
```

You can use the `x`, `X`, and `*` characters as wildcard characters in all comparison operations.

For more information about parsing, sorting, checking, and comparing version constraints, see the [Masterminds SemVer README](https://github.com/Masterminds/semver#semver).

## Example CRs that specify a version range
michaelryanpeter marked this conversation as resolved.
Show resolved Hide resolved
Loading