|
2 | 2 |
|
3 | 3 | This document explains how to specify a version range to install or update an Operator with OLM 1.0. |
4 | 4 |
|
5 | | -You define an Operator's target version in its custom resource (CR) file. |
6 | | -The following list describes how OLM resolves an Operator's target version, and the resulting actions: |
| 5 | +You define a version range in an Operator's custom resource (CR) file. |
7 | 6 |
|
8 | | -Not specifying a version in the CR |
9 | | -: Installs or updates the latest version of the Operator. |
10 | | -Updates are applied automatically when they are published to the catalog. |
| 7 | +## Specifying a version range in the CR |
11 | 8 |
|
12 | | -Specifying a version in the CR |
13 | | -: Installs or updates the specified version. |
14 | | -Updates are not applied automatically. |
15 | | -If you want to update the Operator, you must manually edit the CR and apply the changes to the cluster. |
| 9 | +If you specify a version range in the Operator's CR, OLM 1.0 installs or updates the latest version of the Operator that can be resolved within the version range. |
| 10 | +The resolved version is the latest version of the Operator that satisfies the dependencies and constraints of the Operator and the environment. |
| 11 | +Operator updates within the specified range are automatically installed if they can be resolved successfully. |
| 12 | +Updates are not installed if they are outside of the specified range or if they cannot be resolved successfully. |
16 | 13 |
|
17 | | -Specifying a channel |
18 | | -: Installs or updates the latest version of the Operator in the channel. |
19 | | -Updates are applied automatically when they are published to the specified channel. |
| 14 | +For more information about dependency and constraint resolution in OLM 1.0, see the [Deppy introduction](https://github.com/operator-framework/deppy#introductionhttps://github.com/operator-framework/deppy#introductionhttps://github.com/operator-framework/deppy#introduction) |
20 | 15 |
|
21 | | -Specifying a version range in the CR |
22 | | -: Installs or updates the latest version of the Operator within the version range. |
23 | | -Updates that are within the specified range are automatically installed. |
24 | | -Updates that are outside of the specified range are not installed. |
| 16 | +### Comparisons |
25 | 17 |
|
26 | | -The `spec.version` field uses the Masterminds `semver` package to enable the version range functionality. |
| 18 | +You define a version range by adding a comparison string to the `spec.version` field. A comparison string is composed of a list of comma or space separated values and one or more comparison operators. You can add an additional comparison string by including an OR (`||`) operator between the strings. |
27 | 19 |
|
28 | | -OLM 1.0 does not support following methods for specifying a version range: |
| 20 | +#### Basic comparisons |
29 | 21 |
|
30 | | -* Using tags and labels are not supported. |
31 | | -You must use semantic versioning to define a version range. |
32 | | -* Using [hypen range comparisons](https://github.com/Masterminds/semver#hyphen-range-comparisons) are not supported. |
| 22 | +| Operator | Definition | |
| 23 | +|----------|-----------------------------------| |
| 24 | +| `=` | equal (not aliased to an operator | |
| 25 | +| `!=` | not equal | |
| 26 | +| `>` | greater than | |
| 27 | +| `<` | less than | |
| 28 | +| `>=` | greater than or equal to | |
| 29 | +| `<=` | less than or equal to | |
| 30 | + |
| 31 | +#### Range comparisons |
| 32 | + |
| 33 | +OLM 1.0 does not support hypen range comparisons. |
33 | 34 | For example, the following range option is not supported: |
34 | 35 |
|
35 | 36 | ```yaml |
36 | 37 | version: 3.0 - 3.6 |
37 | 38 | ``` |
38 | 39 |
|
39 | | - To specify a range option, use a method similar to the following example: |
| 40 | +To specify a version range, use a method similar to the following example: |
40 | 41 |
|
41 | | - ```yaml |
42 | | - version: >=3.0 <3.6 |
43 | | - ``` |
| 42 | +```yaml |
| 43 | +version: >=3.0, <3.6 |
| 44 | +``` |
| 45 | +
|
| 46 | +#### Wildcards in comparisons |
44 | 47 |
|
45 | 48 | You can use the `x`, `X`, and `*` characters as wildcard characters in all comparison operations. |
| 49 | +If you use a wildcard character with the `=` operator, you define a patch level comparision. |
| 50 | +This is equivalent to making a tilde range comparison. |
| 51 | + |
| 52 | +*Example comparisons with wildcard characters* |
| 53 | +| Comparison | Equivalent | |
| 54 | +|------------|---------------------| |
| 55 | +| `1.2.x` | `>= 1.2.0, < 1.3.0` | |
| 56 | +| `>= 1.2.x` | `>= 1.2.0` | |
| 57 | +| `<= 2.x` | `< 3` | |
| 58 | +| `*` | `>= 0.0.0` | |
| 59 | + |
| 60 | + |
| 61 | +#### Patch release or tilde (`~`) range comparison |
| 62 | + |
| 63 | +You can use the tilde (`~`) operator to make patch release comparisons. |
| 64 | +This is useful when you want to specify a minor version up to the next major version. |
| 65 | + |
| 66 | +*Example patch release comparisons* |
| 67 | +| Comparison | Equivalent | |
| 68 | +|------------|---------------------| |
| 69 | +| `~1.2.3` | `>= 1.2.3, < 1.3.0` | |
| 70 | +| `~1` | `>= 1, <2` | |
| 71 | +| `~2.3` | `>= 2.3, < 2.4` | |
| 72 | +| `~1.2.x` | `>= 1.2.0, < 1.3.0` | |
| 73 | +| `~1.x` | `>= 1, < 2` | |
| 74 | + |
| 75 | + |
| 76 | +#### Major release or caret (`^`) range comparisons |
| 77 | + |
| 78 | +You can use the caret (`^`) operator to make major release comparisons after a stable, `1.0.0`, version is published. |
| 79 | +If you make a major release comparison before a stable version is published, minor versions define the API stability level. |
46 | 80 |
|
47 | | -For more information about parsing, sorting, checking, and comparing version constraints, see the [Masterminds SemVer README](https://github.com/Masterminds/semver#semver). |
| 81 | +*Example major release comparisons* |
48 | 82 |
|
49 | | -## Example CRs that specify a version range |
| 83 | +| Comparison | Equivalent | |
| 84 | +|------------|----------------------------------------| |
| 85 | +| `^1.2.3` | `>= 1.2.3, < 2.0.0``>= 1.2.3, < 2.0.0` | |
| 86 | +| `^1.2.x` | `>= 1.2.0, < 2.0.0` | |
| 87 | +| `^2.3` | `>= 2.3, < 3` | |
| 88 | +| `^2.x` | `>= 2.0.0, < 3` | |
| 89 | +| `^0.2.3` | `>=0.2.3 <0.3.0` | |
| 90 | +| `^0.2` | `>=0.2.0 <0.3.0` | |
| 91 | +| `^0.0.3` | `>=0.0.3 <0.0.4` | |
| 92 | +| `^0.0` | `>=0.0.0 <0.1.0` | |
| 93 | +| `^0` | `>=0.0.0 <1.0.0` | |
0 commit comments