Skip to content

Commit

Permalink
update the formulary to reflect the new schema for basic catalog temp…
Browse files Browse the repository at this point in the history 
…lates (#335)

Signed-off-by: Jordan Keister <[email protected]>
  • Loading branch information
@grokspawn
grokspawn authored Nov 20, 2024
1 parent 126a95d commit 19d72bd
Show file tree
Hide file tree
Showing 2 changed files with 201 additions and 60 deletions.
259 changes: 200 additions & 59 deletions content/en/docs/advanced-tasks/catalog-update-formulary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,12 @@ weight: 5
[File-based-catalogs][file-based-catalog-spec] (FBC) and [catalog templates][templates-doc] (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 pertaining to either FBC or [semver catalog template][semver-template-doc] (semver template). Since FBC and the [basic catalog template][basic-template-doc] (basic template) both represent the upgrade graph in the set of `olm.channel` objects, instructions for FBC will also be applicable to the `basic template`. Manipulations of `olm.bundle` attributes are limited to FBC representation only.
Formulae will be identified as FBC, [basic catalog template][basic-template-doc] (basic template), or [semver catalog template][semver-template-doc] (semver template).
Schema manipulations will be modeled using YAML and [yq][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).

### semver template example
Formulae presume the following content is saved to the file `semver.yaml`
```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
```
### FBC example
Formulae presume the following content is saved to the file `fbc.yaml`

Expand Down Expand Up @@ -84,28 +62,54 @@ schema: olm.channel
```
## Formulae

### Adding a new bundle to an existing channel
#### semver
Add a new `testoperatorv1.1.1` bundle pullspec to the `Candidate` channel archetype

```bash
yq eval '.candidate.bundles += [{"image" : "quay.io/organization/testoperator:v1.1.1"}]' semver.yaml
### basic template example
Formulae presume the following context is saved to the file `basic.yaml`
```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
```

produces updated `Candidate` archetype contents:

### semver template example
Formulae presume the following content is saved to the file `semver.yaml`
```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
- image: quay.io/organization/testoperator:v1.1.1
...
```
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
Expand All @@ -131,7 +135,6 @@ schema: olm.channel
```
{{% alert title="Warning" color="warning" %}}
This example illustrates how it is possible to inadvertently create multiple channel heads
{{% /alert %}}
`opm validate` result for this output would be:

```bash
Expand All @@ -140,8 +143,56 @@ FATA[0000] invalid index:
└── invalid channel "candidate-v1.1":
├── multiple channel heads found in graph: testoperator.v1.1.0, testoperator.v1.1.1
```
{{% /alert %}}

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

```bash
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:

```yaml
...
- 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

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

produces updated `Candidate` archetype contents:

```yaml
...
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
{{% alert title="Note" color="info" %}}
This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
{{% /alert %}}

#### 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.
Expand All @@ -166,8 +217,34 @@ 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.

```bash
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:

```yaml
...
- 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
{{% alert title="Note" color="info" %}}
This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
{{% /alert %}}

#### FBC
Remove the upgrade edge from the example `candidate-v1.1` channel which refers to bundle version `testoperator.v1.1.0`.
Expand All @@ -190,34 +267,27 @@ schema: olm.channel
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`.
{{% /alert %}}

### Substituting a bundle version in the upgrade graph

#### semver
For all channels, replace instances of `quay.io/organization/testoperator:v1.1.0` with `quay.io/organization/testoperator:v1.1.0-CVE`
#### basic
Remove the upgrade edge from the example `stable` channel which refers to bundle version `testoperator.v0.2.0`.

```bash
yq '(..| select(has("image") and .image == "quay.io/organization/testoperator:v1.1.0")).image = "quay.io/organization/testoperator:v1.1.0-cve"' semver.yaml
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 template:

produces updated `stable` channel:

```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-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
...
- 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`

Expand Down Expand Up @@ -271,7 +341,60 @@ package: testoperator
schema: olm.channel
```

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

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

produces updated channels:

```yaml
...
- 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`

```bash
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:

```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-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
{{% alert title="Note" color="info" %}}
This operation is not possible for the semver template, which exclusively leverages semver ordering to generate an opinonated upgrade graph.
{{% /alert %}}

#### FBC
Substitute an existing 'replaces' link target for `testoperator.v1.1.0` with a different bundle version `testoperator.v1.0.0`.

Expand All @@ -292,6 +415,24 @@ schema: olm.channel
...
```

#### basic
Substitute an existing 'replaces' link target for `testoperator.v0.2.0` with a different bundle version `testoperator.v0.1.5`.

```bash
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:

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



Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/advanced-tasks/ship-operator-supporting-multiarch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ labels:
operatorframework.io/os.<GOOS>: supported
```
Where `<GOARCH>` and `<GOOS>` are one of the values [listed here](https://github.com/golang/go/blob/master/src/go/build/syslist.go).
Where `<GOARCH>` and `<GOOS>` are one of the values [listed here](https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go).

## Multiple Architectures

Expand Down

0 comments on commit 19d72bd

Please sign in to comment.