github.com/operator-framework/operator-lifecycle-manager@v0.30.0/doc/design/resolving-bundle-images.md (about)

     1  # Resolving Bundle Images
     2  
     3  An operator [UpdateGraph](https://operator-framework.github.io/olm-book/docs/glossary.html#upgrade-graph) may refer to an operator [Bundle](https://operator-framework.github.io/olm-book/docs/glossary.html#bundle) with a reference to a [Bundle Image](https://operator-framework.github.io/olm-book/docs/glossary.html#bundle-image) containing its content. This means that the content of these referenced bundles is not immediately available for application to a cluster and must first be pulled and unpacked.
     4  
     5  ## Resolving
     6  
     7  The same metadata available for bundles queried from a [`CatalogSource`](https://operator-framework.github.io/olm-book/docs/glossary.html#catalogsources) is available for bundle images. This lets OLM resolve dependencies and updates without pulling them to the cluster. Once the final set of operators has been identified for install, OLM codifies the information needed to pull any included bundle images in the `status.BundleLookups` field of the resulting `InstallPlan`:
     8  
     9  ```yaml
    10  status:
    11    bundleLookups:
    12    - path: quay.io/coreos/prometheus-operator@sha256...
    13      replaces: ""
    14      catalogSourceRef:
    15        Namespace: operators
    16        Name: monitoring
    17  ```
    18  
    19  ## Unpacking
    20  
    21  OLM uses the `status.bundleLookups` field, added to `InstallPlans` during dependency resolution, to determine which bundle images need to be unpacked.
    22  
    23  Given an `InstallPlan` with the following `status`:
    24  
    25  ```yaml
    26  status:
    27    bundleLookups:
    28    - path: quay.io/coreos/prometheus-operator@sha256...
    29      replaces: ""
    30      catalogSourceRef:
    31        Namespace: operators
    32        Name: monitoring
    33    - path: quay.io/coreos/etcd-operator@sha256...
    34      replaces: "etcd-operator.v4.1"
    35      catalogSourceRef:
    36        Namespace: operators
    37        Name: storage
    38  ```
    39  
    40  __Note:__ Image tag references may be used in place of digests, but once a tag has been unpacked, updates to the underlying image will not be respected unless the resources described below are deleted._
    41  
    42  Each unique `BundlePath` will result in OLM creating four top-level resources in the namespace of the referenced `CatalogSource`:
    43  
    44  1. A `ConfigMap` to hold the unpacked manifests
    45  2. A `Role` allowing `create`, `get`, and `update` on that `ConfigMap`
    46  3. A `RoleBinding` granting that `Role` to the default `ServiceAccount`
    47  4. An unpack `Job` using the default `ServiceAccount` to export the bundle image's content into that `ConfigMap`
    48  
    49  OLM uses the same reproducible name for all of these resources; the `sha256` checksum of the respective `BundlePath`.
    50  
    51  __Note:__ _This choice of name allows OLM to reuse previously unpacked bundles between `InstallPlans` by making them discoverable and ensuring resource uniqueness._
    52  
    53  The `Role`, `RoleBinding`, and `Job` have `OwnerReferences` to the `ConfigMap`, while the `ConfigMap` has an `OwnerReference` to the `CatalogSource` referenced by its respective `BundleLookup`. If the referenced `CatalogSource` is not found, a `BundleLookupPending` condition is added to the `BundleLookup`:
    54  
    55  ```yaml
    56  path: quay.io/coreos/prometheus-operator@sha256...
    57  replaces: ""
    58  catalogSourceRef:
    59    Namespace: operators
    60    Name: monitoring
    61  conditions:
    62    type: BundleLookupPending
    63    status: "True"
    64    reason: CatalogSourceMissing
    65    message: "referenced catalogsource not found"
    66    lastTransitionTime: "2020-01-08T23:42:59Z"
    67  ```
    68  
    69  A given unpack `Job` will start a `Pod` consisting of two containers:
    70  
    71  1. An init container that has a release of the [`opm`](https://github.com/operator-framework/operator-registry/tree/master/cmd/opm) binary
    72  2. A container from the bundle image reference
    73  
    74  These two containers share a volume mount into which the init container copies its `opm` binary. After initalization, the bundle image container uses this copy to execute the `opm bundle extract` command, extracting the bundle content from its filesystem into the bundle's respective `ConfigMap`.
    75  
    76  When an unpack `Job` exists but is not in a `Complete` state, a `BundleLookupPending` condition is added to its `BundleLookup`:
    77  
    78  ```yaml
    79  path: quay.io/coreos/prometheus-operator@sha256...
    80  replaces: ""
    81  catalogSourceRef:
    82    Namespace: operators
    83    Name: monitoring
    84  conditions:
    85    type: BundleLookupPending
    86    status: "True"
    87    reason: JobIncomplete
    88    message: "unpack job not completed"
    89    lastTransitionTime: "2020-01-08T23:43:30Z"
    90  ```
    91  
    92  Once an unpack `Job` runs to completion, the data in the respective `ConfigMap` is converted into a set of install steps and is added to the status the `InstallPlan`. In the same transaction, the `BundleLookup` entry is removed.