Catalog Update Formulary

Background

File-based-catalogs (FBC) and catalog templates (templates) provide operator authors with standardized schemas to express operator upgrade graphs. However, without explicit tooling users require clear examples of how to achieve routine goals. This document is an attempt to establish a formulary of common operations, specifically with the intention of making these pieces automatable. This is in no way an exhaustive list.

Conventions

Formulae will be identified as FBC, basic catalog template (basic template), or semver catalog template (semver template). Schema manipulations will be modeled using YAML and yq. Wherever possible, example input will be limited to the relevant object hierarchies. Truncation is indicated by elipses (…) before and after the text.

Examples

For brevity, all formulae will refer to the same example, for semver template and FBC. For convenience, all semver bundle image pullspecs will express versions which match the bundle version (instead of SHAs).

FBC example

Formulae presume the following content is saved to the file fbc.yaml

---
defaultChannel: stable-v1.0
name: testoperator
schema: olm.package
---
entries:
  - name: testoperator.v1.0.0
  - name: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
name: candidate-v1.0
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.1.0
    replaces: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
name: candidate-v1.1
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.0.1
name: fast-v1.0
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.1.0
    replaces: testoperator.v1.0.1
name: fast-v1.1
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel

basic template example

Formulae presume the following context is saved to the file basic.yaml

schema: olm.template.basic
entries:
  - schema: olm.package
    name: testoperator
    defaultChannel: stable
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator.v0.1.0
      - name: testoperator.v0.2.0
        replaces: testoperator.v0.1.0
  - schema: olm.bundle
    image: quay.io/organization/testoperator:v0.1.0
  - schema: olm.bundle
    image: quay.io/organization/testoperator:v0.2.0

semver template example

Formulae presume the following content is saved to the file semver.yaml

schema: olm.semver
generateMajorChannels: false
generateMinorChannels: true
candidate:
  bundles:
  - image: quay.io/organization/testoperator:v1.0.0
  - image: quay.io/organization/testoperator:v1.0.1
  - image: quay.io/organization/testoperator:v1.1.0
fast:
  bundles:
  - image: quay.io/organization/testoperator:v1.0.1
  - image: quay.io/organization/testoperator:v1.1.0
stable:
  bundles:
  - image: quay.io/organization/testoperator:v1.0.1

Formulae

Adding a new bundle to an existing channel

FBC

Add a new testoperator.v1.1.1 edge to an existing candidate-v1.1 channel

yq eval 'select(.schema=="olm.channel" and .name == "candidate-v1.1").entries += [{"name" : "testoperator.v1.1.1"}]' fbc.yaml

produces updated candidate-v1.1 channel:

...
entries:
  - name: testoperator.v1.1.0
    replaces: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
  - name: testoperator.v1.1.1
name: candidate-v1.1
package: testoperator
schema: olm.channel
...

Warning

This example illustrates how it is possible to inadvertently create multiple channel heads opm validate result for this output would be:

FATA[0000] invalid index:
└── invalid package "testoperator":
    └── invalid channel "candidate-v1.1":
        ├── multiple channel heads found in graph: testoperator.v1.1.0, testoperator.v1.1.1

basic

Add a new testoperator.v0.2.1 bundle pullspec to the existing stable channel

yq eval 'select(.schema == "olm.template.basic").entries[] |= select(.schema == "olm.channel" and .name == "stable").entries += [{"name" : "testoperator.v0.2.1", "replaces": "testoperator.v0.2.0"}]' basic.yaml

produces updated stable channel:

...
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator.v0.1.0
      - name: testoperator.v0.2.0
        replaces: testoperator.v0.1.0
      - name: testoperator.v0.2.1
        replaces: testoperator.v0.2.0
...

semver

Add a new testoperator.v1.1.1 bundle pullspec to the Candidate channel archetype

yq eval '.candidate.bundles += [{"image" : "quay.io/organization/testoperator:v1.1.1"}]' semver.yaml

produces updated Candidate archetype contents:

...
candidate:
  bundles:
  - image: quay.io/organization/testoperator:v1.0.0
  - image: quay.io/organization/testoperator:v1.0.1
  - image: quay.io/organization/testoperator:v1.1.0
  - image: quay.io/organization/testoperator:v1.1.1
...

Adding a new ‘replaces’ link between two existing bundles

Note

This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.

FBC

Adding a new testoperator.v1.1.1 bundle version edge with a replaces link to its predecessor testoperator.v1.1.0 version which already exists in the channel.

yq eval 'select(.schema == "olm.channel" and .name == "candidate-v1.1").entries += [{"name" : "testoperator:v1.1.1", "replaces": "testoperator:v1.1.0"}]' fbc.yaml

produces updated candidate-v1.1 channel:

...
entries:
  - name: testoperator.v1.1.0
    replaces: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
  - name: testoperator:v1.1.1
    replaces: testoperator:v1.1.0
name: candidate-v1.1
package: testoperator
schema: olm.channel
...

basic

Adding a new testoperator.v0.1.1 bundle version edge with a replaces link to its predecessor testoperator.v0.1.0 version which already exists in the channel.

yq eval 'select(.schema == "olm.template.basic").entries[] |= select(.schema == "olm.channel" and .name == "stable").entries += [{"name" : "testoperator:v0.1.1", "replaces": "testoperator:v0.1.0"}]' basic.yaml

produces updated stable channel:

...
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator.v0.1.0
      - name: testoperator.v0.2.0
        replaces: testoperator.v0.1.0
      - name: testoperator:v0.1.1
        replaces: testoperator:v0.1.0
...

Removing a specific bundle version

Note

This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.

FBC

Remove the upgrade edge from the example candidate-v1.1 channel which refers to bundle version testoperator.v1.1.0.

yq eval 'del(select(.schema == "olm.channel" and .name == "candidate-v1.1" ).entries[]| select(.name == "testoperator.v1.1.0"))' fbc.yaml

produces updated candidate-v1.1 channel:

...
entries: []
name: candidate-v1.1
package: testoperator
schema: olm.channel
...

Warning

Please note that removing the only edge for a channel as in this example will yield an explicitly empty array. This will produce an error in opm validate.

basic

Remove the upgrade edge from the example stable channel which refers to bundle version testoperator.v0.2.0.

yq eval 'select(.schema == "olm.template.basic").entries[] |= del(select(.schema == "olm.channel" and .name == "stable").entries[]| select(.name == "testoperator.v0.2.0"))' basic.yaml

produces updated stable channel:

...
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator.v0.1.0
...

Substituting a bundle version in the upgrade graph

FBC

For all graph edges, replaces instances of testoperator.v1.1.0 with a different bundle version testoperator.v1.1.0-CVE

yq '(.. | select(has("entries") and .entries[].name == "testoperator.v1.1.0" ).entries[]).name = "testoperator.v1.1.0-cve"' fbc.yaml

produces updated channels:

---
defaultChannel: stable-v1.0
name: testoperator
schema: olm.package
---
entries:
  - name: testoperator.v1.0.0
  - name: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
name: candidate-v1.0
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.1.0-cve
    replaces: testoperator.v1.0.1
    skips:
      - testoperator.v1.0.0
name: candidate-v1.1
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.0.1
name: fast-v1.0
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.1.0-cve
    replaces: testoperator.v1.0.1
name: fast-v1.1
package: testoperator
schema: olm.channel
---
entries:
  - name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel

basic

For all channels, replace instances of testoperator:v0.1.0 with testoperator:v0.1.0-CVE

yq '(..| select(. == "testoperator.v0.1.0")) |="testoperator.v0.1.0-CVE"' basic.yaml

produces updated channels:

...
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator.v0.1.0-CVE
      - name: testoperator.v0.2.0
        replaces: testoperator.v0.1.0-CVE
...

semver

For all channels, replace instances of quay.io/organization/testoperator:v1.1.0 with quay.io/organization/testoperator:v1.1.0-CVE

yq '(..| select(has("image") and .image == "quay.io/organization/testoperator:v1.1.0")).image = "quay.io/organization/testoperator:v1.1.0-cve"' semver.yaml

produces updated template:

schema: olm.semver
generatemajorchannels: false
generateminorchannels: true
candidate:
  bundles:
    - image: quay.io/organization/testoperator:v1.0.0
    - image: quay.io/organization/testoperator:v1.0.1
    - image: quay.io/organization/testoperator:v1.1.0-cve
fast:
  bundles:
    - image: quay.io/organization/testoperator:v1.0.1
    - image: quay.io/organization/testoperator:v1.1.0-cve
stable:
  bundles:
    - image: quay.io/organization/testoperator:v1.0.1

Introducing a new replacement relationship in the upgrade graph

Note

This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.

FBC

Substitute an existing ‘replaces’ link target for testoperator.v1.1.0 with a different bundle version testoperator.v1.0.0.

yq eval 'select(.schema == "olm.channel" and .name == "candidate-v1.1").entries |= [{"name" : "testoperator:v1.1.0", "replaces": "testoperator:v1.0.0"}]' fbc.yaml

produces updated candidate-v1.1 channel:

...
entries:
  - name: testoperator:v1.1.0
    replaces: testoperator:v1.0.0
name: candidate-v1.1
package: testoperator
schema: olm.channel
...

basic

Substitute an existing ‘replaces’ link target for testoperator.v0.2.0 with a different bundle version testoperator.v0.1.5.

yq eval '.entries[] |= select(.schema == "olm.channel" and .name == "stable").entries |= [{"name" : "testoperator:v0.2.0", "replaces": "testoperator:v0.1.5"}]' basic.yaml

produces updated stable channel:

...
  - schema: olm.channel
    package: testoperator
    name: stable
    entries:
      - name: testoperator:v0.2.0
        replaces: testoperator:v0.1.5
...