github.com/operator-framework/operator-lifecycle-manager@v0.30.0/doc/design/how-to-update-operators.md (about)

     1  # How do operator upgrades work in Operator Lifecycle Manager (OLM)?
     2  
     3  
     4  ## Introduction
     5  Resources Operator Lifecycle Manager uses to resolve upgrades:
     6  1. ClusterServiceVersion (CSV)
     7  2. CatalogSource
     8  3. Subscription
     9  
    10  ## Sourcing Upgrades
    11  
    12  In the OLM ecosystem, operator metadata (e.g. CSVs) can be stored in a collection called a `CatalogSource`. OLM uses CatalogSources, which use [Operator Registry API](https://github.com/operator-framework/operator-registry), to query for available operators as well as upgrades for installed operators.
    13  
    14  ![CatalogSource Image](images/catalogsource.png)
    15  
    16  Within a `CatalogSource`, operators are organized into packages and streams of updates called “channels” - which should be a familiar update pattern from OpenShift or other “evergreen” software like Google Chrome.
    17  
    18  ![Channels Image](images/channels.png)
    19  
    20  ## Subscribing to Upgrades
    21  
    22  A user indicates a particular package (etcd) and channel (alpha) in a particular `CatalogSource` in a `Subscription`. If a `Subscription` is made to a package that hasn’t yet been installed in the namespace, the newest operator in the catalog/package/channel is installed.
    23  
    24  ## Replaces / Channels
    25  
    26  An operator’s definition, also known as `ClusterServiceVersion` (CSV), has a `replaces` field that indicates which operator it replaces. This builds a DAG ([directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph)) of CSVs that can be queried by OLM, and updates can be shared between channels. Channels can be thought of as entrypoints into the DAG of updates. A more accurate diagram would be:
    27  
    28  Channels example:
    29  ```yaml
    30  packageName: example
    31  channels:
    32  - name: alpha
    33    currentCSV: example.v0.1.2
    34  - name: beta
    35    currentCSV: example.v0.1.3
    36  defaultChannel: alpha
    37  ```
    38  
    39  ![Replaces Image](images/replaces.png)
    40  
    41  ## Upgrade Path
    42  
    43  Given the upgrade scenario, there is an installed operator corresponding to CSV version `0.1.1`. OLM queries `CatalogSource` and detects an upgrade in the subscribed channel with new CSV version `0.1.3` that is replacing an older but not-installed CSV version `0.1.2` which in turn replaces older but installed CSV version `0.1.1`. OLM will walk back from channel head to previous versions via `replaces` field specified in CSVs to determine the upgrade path: `0.1.3` -> `0.1.2` -> `0.1.1` (the direction of arrow indicates the former is replacing the latter). OLM will upgrade operator one version at the time until it reaches the channel head. For this given scenario, OLM will install operator version `0.1.2` to replace existing operator version `0.1.1`. Then, install operator version `0.1.3` to replace previously-installed operator version `0.1.2`. At this point, the installed operator version `0.1.3` matches the channel head and the upgrade is completed.
    44  
    45  ## Catalog Invariant
    46  
    47  For OLM to successfully query for updates, the following invariant must hold:
    48  
    49  * Given a (`CatalogSource`, `Package`, `Channel`, `ClusterServiceVersion`) a catalog should be able to return, unambiguously and deterministically, a single CSV that `replaces` the input CSV.
    50  
    51  # Skipping updates
    52  
    53  OLM’s happy path for updates is:
    54  
    55  * A `CatalogSource` is updated with one or more updates to an operator
    56  * We traverse every version of the operator until we’re at the newest version the `CatalogSource` contains.
    57  
    58  But sometimes this is not a safe operation to perform. There will be cases where a published version of an operator should never be installed on a cluster if it hasn’t already (e.g. because that version introduces a serious vulnerability).
    59  
    60  In those cases we have to consider two cluster states and provide an update graph that supports both:
    61  
    62  * The “bad” intermediate operator has been seen by a cluster and installed
    63  * The “bad” intermediate operator has not yet been installed onto a cluster
    64  
    65  By shipping a new catalog and adding a “skipped” release, we can keep our catalog invariant (always get a single unique update) regardless of the cluster state and whether it has seen the bad update yet.
    66  
    67  For example:
    68  
    69  ```yaml
    70  apiVersion: operators.coreos.com/v1alpha1
    71  kind: ClusterServiceVersion
    72  metadata:
    73    name: etcdoperator.v0.9.2
    74    namespace: placeholder
    75    annotations:
    76  spec:
    77      displayName: etcd
    78      description: Etcd Operator
    79      replaces: etcdoperator.v0.9.0
    80      skips:
    81      - etcdoperator.v0.9.1
    82  ```
    83  
    84  ![Skipping Updates Image](images/skipping-updates.png)
    85  
    86  This has the properties that we want:
    87  
    88  * Any operator found in Old has a single replacement in New
    89  * Any operator found in New has a single replacement in New
    90  * If the bad update has not yet been installed, it will never be
    91  
    92  # Replacing Multiple Operators
    93  
    94  Creating the “New Catalog” described above requires publishing CSVs that `replace` one operator, but can `skip` several.
    95  
    96  ## skipRange
    97  
    98  ```
    99  olm.skipRange: <semver range>
   100  ```
   101  where <semver range> has the version range format supported by the [semver library](https://github.com/blang/semver#ranges).
   102  
   103  When searching catalogs for updates, if the head of a channel has `skipRange` annotation and the currently installed operator has a `version` field that falls in the range, we will update to the latest entry in the channel.
   104  
   105  The order of precedence is:
   106  
   107  1. Channel head in the source specified by `sourceName` on the subscription, if the other criteria for skipping are met
   108  2. The next operator that replaces the current one, in the source specified by `sourceName`
   109  3. Channel head in another source that is visible to the subscription, if the other criteria for skipping are met
   110  4. The next operator that replaces the current one in any source visible to the subscription
   111  
   112  `skipRange` example:
   113  
   114  ```yaml
   115  apiVersion: operators.coreos.com/v1alpha1
   116  kind: ClusterServiceVersion
   117  metadata:
   118      name: elasticsearch-operator.v4.1.2
   119      namespace: placeholder
   120      annotations:
   121          olm.skipRange: '>=4.1.0 <4.1.2'
   122  ```
   123  
   124  ## Z-stream support
   125  
   126  A z-stream (patch release) needs to replace all previous z-stream releases for the same minor version. OLM doesn’t care about major/minor/patch versions, we just need to build the correct graph in a catalog.
   127  
   128  In other words, we need to be able to take a graph as in “Old Catalog” and, similar to before, generate a graph as in “New Catalog”
   129  
   130  ![Z-stream Image](images/z-stream.png)
   131  
   132  These are the properties that we want:
   133  
   134  * Any operator found in Old has a single replacement in New
   135  * Any operator found in New has a single replacement in New
   136  * Any z-stream release in Old will update to the latest z-stream release in New
   137  * Greyed-out releases can be considered “virtual” graph nodes (their content doesn’t need to exist, the registry just needs to respond as if the graph looks like this)