From 655635e11b4de4728ae59156affb10e8d4201a9c Mon Sep 17 00:00:00 2001 From: Jordan Keister Date: Thu, 30 Jun 2022 15:49:01 -0500 Subject: [PATCH 1/3] initial add Signed-off-by: Jordan Keister --- content/en/docs/Reference/veneers.md | 447 ++++++++++++++++++ content/en/docs/Tasks/creating-a-catalog.md | 74 ++- .../make-catalog-available-on-cluster.md | 4 +- hack/ci/link-check.sh | 5 +- 4 files changed, 517 insertions(+), 13 deletions(-) create mode 100644 content/en/docs/Reference/veneers.md diff --git a/content/en/docs/Reference/veneers.md b/content/en/docs/Reference/veneers.md new file mode 100644 index 00000000..4a0bf943 --- /dev/null +++ b/content/en/docs/Reference/veneers.md @@ -0,0 +1,447 @@ +--- +title: "Veneers" +linkTitle: "Veneers (alpha)" +weight: 5 +date: 2022-06-30 +--- + +>Note: `veneers` are **ALPHA** functionality and may adopt breaking changes + + +## Concept and Design + +File-Based Catalogs (FBC) are a major improvement to the imperative update graph approaches of previous versions. FBCs give operator authors a [declarative and deterministic approach to defining their update graph](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/). However, FBCs can get complex, especially as the number of releases and dependencies scale. We introduce the concept of a `veneer` as an approach to simplifying interacting with FBCs. + +In this context, there are two components to every `veneer`: +1. An arbitrary API +2. An executable which processes #1 and produces a valid FBC. + +The veneers supported by [`opm`](opm-tool) are: +- the [`basic veneer`](#basic-veneer), which provides a simplified abstraction of an FBC; and +- the [`semver veneer`](#semver-veneer), which provides the capability to generate an entire upgrade graph + +## Basic Veneer +The `basic veneer` is an input schema which eliminates FBC information that can be retrieved from existing registries when we process it. +Users provide all components of an [FBC schema](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#olm-defined-schemas), but supply only the bundle image reference for any `olm.bundle` objects. This results in a greatly simplified, smaller document. +This approach may be attractive to operator authors who maintain existing catalogs and just want to make the job easier, or for operator authors who need to retain a channel graph which is not based on `semver`. + +### Usage + +```sh +opm alpha render-veneer basic [flags] +``` + + +| Flag | Description | +| ------------------- | -------------------------------------------------------------------------------------- | +| -h, --help | prints help/usage information | +| -o, --output | the output format, can be `yaml` or `json` | +| --skip-tls-verify | skip TLS certificate verification for container image registries while pulling bundles | +| --use-http | use plain HTTP for container image registries while pulling bundles | + +`--skip-tls-verify` and `--use-http` are mutually exclusive flags. + +### Example + +In a very simple example, we define an `olm.package` and an `olm.channel` composed of two `olm.bundle` objects that have an image name attribute but no other attributes/properties. +```yaml +--- +schema: olm.package +name: example-operator +defaultChannel: stable +--- +schema: olm.channel +package: example-operator +name: stable +entries: +- name: example-operator.v0.1.0 +- name: example-operator.v0.2.0 + replaces: example-operator.v0.1.0 +--- +schema: olm.bundle +image: docker.io/example/example-operator-bundle:0.1.0 +--- +schema: olm.bundle +image: docker.io/example-operator-bundle:0.2.0 +``` + + +Using the `opm alpha render-veneer basic` command on this input generates the full FBC:
(click here to display full output) + +(data blobs truncated with '... [snip] ...' for brevity) + +```yaml +--- +defaultChannel: stable +name: example-operator +schema: olm.package +--- +entries: +- name: example-operator.v0.1.0 +- name: example-operator.v0.2.0 + replaces: example-operator.v0.1.0 +name: stable +package: example-operator +schema: olm.channel +--- +image: docker.io/example/example-operator-bundle:0.1.0 +name: example-operator.v0.1.0 +package: example-operator +properties: +- type: olm.gvk + value: + group: example.com + kind: App + version: v1 +- type: olm.package + value: + packageName: example-operator + version: 0.1.0 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoidjEiLCJraW5kIjoiU2VydmljZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJsYWJlbHMiOnsiY29udHJvbC1wbGFuZSI6ImNvbnRyb2xsZXItbWFuYWdlciJ9LCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1jb250cm9sbGVyLW1hbmFnZXItbWV0cmljcy1zZXJ2aWNlIn0sInNwZWMiOnsicG9ydHMiOlt7Im5hbWUiOiJodHRwcyIsInBvcnQiOjg0NDMsInByb3RvY29sIjoiVENQIiwidGFyZ2V0UG9ydCI6Imh0dHBzIn1dLCJzZWxlY3RvciI6eyJjb250cm9sLXBsYW5lIjoiY29udHJvbGxlci1tYW5hZ2VyIn19LCJzdGF0dXMiOnsibG9hZEJhbGFuY2VyIjp7fX19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoidjEiLCJkYXRhIjp7ImNvbnRyb2xsZXJfbWFuYWdlcl9jb25maWcueWFtbCI6ImFwaVZlcnNpb246IGNvbnRyb2xsZXItcnVudGltZS5zaWdzLms4cy5pby92MWFscGhhMVxua2luZDogQ29udHJvbGxlck1hbmFnZXJDb25maWdcbmhlYWx0aDpcbiAgaGVhbHRoUHJvYmVCaW5kQWRkcmVzczogOjgwODFcbm1ldHJpY3M6XG4gIGJpbmRBZGRyZXNzOiAxMjcuMC4wLjE6ODA4MFxud2ViaG9vazpcbiAgcG9ydDogOTQ0M1xubGVhZGVyRWxlY3Rpb246XG4gIGxlYWRlckVsZWN0OiB0cnVlXG4gIHJlc291cmNlTmFtZTogY2RmNjA0MTIuY29tXG4ifSwia2luZCI6IkNvbmZpZ01hcCIsIm1ldGFkYXRhIjp7Im5hbWUiOiJleGFtcGxlLW9wZXJhdG9yLW1hbmFnZXItY29uZmlnIn19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoicmJhYy5hdXRob3JpemF0aW9uLms4cy5pby92MSIsImtpbmQiOiJDbHVzdGVyUm9sZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1tZXRyaWNzLXJlYWRlciJ9LCJydWxlcyI6W3sibm9uUmVzb3VyY2VVUkxzIjpbIi9tZXRyaWNzIl0sInZlcmJzIjpbImdldCJdfV19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ== +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ== +relatedImages: +- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0 + name: "" +- image: docker.io/example/example-operator-bundle:0.1.0 + name: "" +- image: docker.io/example/example-operator:0.1.0 + name: "" +schema: olm.bundle +--- +image: docker.io/example/example-operator-bundle:0.2.0 +name: example-operator.v0.2.0 +package: example-operator +properties: +- type: olm.gvk + value: + group: example.com + kind: App + version: v1 +- type: olm.package + value: + packageName: example-operator + version: 0.2.0 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoidjEiLCJraW5kIjoiU2VydmljZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJsYWJlbHMiOnsiY29udHJvbC1wbGFuZSI6ImNvbnRyb2xsZXItbWFuYWdlciJ9LCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1jb250cm9sbGVyLW1hbmFnZXItbWV0cmljcy1zZXJ2aWNlIn0sInNwZWMiOnsicG9ydHMiOlt7Im5hbWUiOiJodHRwcyIsInBvcnQiOjg0NDMsInByb3RvY29sIjoiVENQIiwidGFyZ2V0UG9ydCI6Imh0dHBzIn1dLCJzZWxlY3RvciI6eyJjb250cm9sLXBsYW5lIjoiY29udHJvbGxlci1tYW5hZ2VyIn19LCJzdGF0dXMiOnsibG9hZEJhbGFuY2VyIjp7fX19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoidjEiLCJkYXRhIjp7ImNvbnRyb2xsZXJfbWFuYWdlcl9jb25maWcueWFtbCI6ImFwaVZlcnNpb246IGNvbnRyb2xsZXItcnVudGltZS5zaWdzLms4cy5pby92MWFscGhhMVxua2luZDogQ29udHJvbGxlck1hbmFnZXJDb25maWdcbmhlYWx0aDpcbiAgaGVhbHRoUHJvYmVCaW5kQWRkcmVzczogOjgwODFcbm1ldHJpY3M6XG4gIGJpbmRBZGRyZXNzOiAxMjcuMC4wLjE6ODA4MFxud2ViaG9vazpcbiAgcG9ydDogOTQ0M1xubGVhZGVyRWxlY3Rpb246XG4gIGxlYWRlckVsZWN0OiB0cnVlXG4gIHJlc291cmNlTmFtZTogY2RmNjA0MTIuY29tXG4ifSwia2luZCI6IkNvbmZpZ01hcCIsIm1ldGFkYXRhIjp7Im5hbWUiOiJleGFtcGxlLW9wZXJhdG9yLW1hbmFnZXItY29uZmlnIn19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW9uIjoicmJhYy5hdXRob3JpemF0aW9uLms4cy5pby92MSIsImtpbmQiOiJDbHVzdGVyUm9sZSIsIm1ldGFkYXRhIjp7ImNyZWF0aW9uVGltZXN0YW1wIjpudWxsLCJuYW1lIjoiZXhhbXBsZS1vcGVyYXRvci1tZXRyaWNzLXJlYWRlciJ9LCJydWxlcyI6W3sibm9uUmVzb3VyY2VVUkxzIjpbIi9tZXRyaWNzIl0sInZlcmJzIjpbImdldCJdfV19 +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ== +- type: olm.bundle.object + value: + data: eyJhcGlWZXJzaW ... [snip] ... jEuMCJ9fQ== +relatedImages: +- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0 + name: "" +- image: docker.io/example/example-operator-bundle:0.2.0 + name: "" +- image: docker.io/example/example-operator:0.2.0 + name: "" +schema: olm.bundle + +``` +
+ +## Semver Veneer + +Since a `veneer` is identified as an input schema which is processed to generate a valid FBC, we can define a `semver veneer` as a schema which uses channel conventions to facilitate the auto-generation of channels adhering to [Semantic Versioning](https://semver.org/) (semver) guidelines and consistent with best practices on [channel naming](/docs/best-practices/channel-naming/#naming). This approach may be attractive to operator authors who are defining a new upgrade graph, or are already close enough to the veneer conventions to be able to adopt it (i.e. already use semver, only promote a single channel, etc.). + +>**DISCLAIMER:** since version build metadata [MUST be ignored when determining version precedence](https://semver.org/#spec-item-10) when using semver, it cannot be used in any bundle included in the `semver veneer` and will result in a fatal error. + +This alpha version of the `semver veneer` has the following goals: +- terse grammar to minimize creation/maintenance effort +- idempotent output +- simple channel promotion +- demonstration of a common type of channel maturity model +- minor-version (Y-stream) and major-version (X-stream) versioning capabilities +- clear mapping between input schema and output FBC attributes + +### Specification +Like best practices [recommended channel naming](/docs/best-practices/channel-naming/#recommended-channel-naming), this veneer supports channel names `Candidate`, `Fast`, and `Stable`, in order of increasing channel stability. We leverage this relationship when calculating the default channel for the package. + +`GenerateMajorChannels` and `GenerateMinorChannels` dictate whether this veneer will generate X-stream or Y-stream channels (attributes can be set independently). If omitted, only minor (Y-stream) channels will be generated. + +Under each channel are a list of bundle image references which contribute to that channel. At least one channel must have bundle images. + +The `olm.semver` [cue](cuelang-spec) schema is: + +```cue +#Package: { + schema: "olm.semver" + + // optional flag to control generating minor-version channels, defaults to _true_ if unspecified + GenerateMinorChannels?: bool + + // optional flag to control generating major-version channels, defaults to _false_ if unspecified + GenerateMajorChannels?: bool + + // optional candidate channel + Candidate?: { + Bundles: [...#ImageEntry] + } + + // optional fast channel + Fast?: { + Bundles: [...#ImageEntry] + } + + // optional stable channel + Stable?: { + Bundles: [...#ImageEntry] + } + + #ImageEntry: { + Image: string + } +} +``` + +### Usage + +```sh +opm alpha render-veneer semver [flags] +``` + + +| Flag | Description | +| ------------------- | -------------------------------------------------------------------------------------- | +| -h, --help | prints help/usage information | +| -o, --output | the output format, can be `yaml` or `json` | +| --skip-tls-verify | skip TLS certificate verification for container image registries while pulling bundles | +| --use-http | use plain HTTP for container image registries while pulling bundles | + +`--skip-tls-verify` and `--use-http` are mutually exclusive flags. + +### Example + +With the following (hypothetical) example we define a mock bundle which has 11 versions, represented across each of the channel types: + +```yaml +Schema: olm.semver +GenerateMajorChannels: true +GenerateMinorChannels: true +Candidate: + Bundles: + - Image: quay.io/foo/olm:testoperator.v0.1.0 + - Image: quay.io/foo/olm:testoperator.v0.1.1 + - Image: quay.io/foo/olm:testoperator.v0.1.2 + - Image: quay.io/foo/olm:testoperator.v0.1.3 + - Image: quay.io/foo/olm:testoperator.v0.2.0 + - Image: quay.io/foo/olm:testoperator.v0.2.1 + - Image: quay.io/foo/olm:testoperator.v0.2.2 + - Image: quay.io/foo/olm:testoperator.v0.3.0 + - Image: quay.io/foo/olm:testoperator.v1.0.0 + - Image: quay.io/foo/olm:testoperator.v1.0.1 + - Image: quay.io/foo/olm:testoperator.v1.1.0 +Fast: + Bundles: + - Image: quay.io/foo/olm:testoperator.v0.2.1 + - Image: quay.io/foo/olm:testoperator.v0.2.2 + - Image: quay.io/foo/olm:testoperator.v0.3.0 + - Image: quay.io/foo/olm:testoperator.v1.0.1 + - Image: quay.io/foo/olm:testoperator.v1.1.0 +Stable: + Bundles: + - Image: quay.io/foo/olm:testoperator.v1.0.1 +``` + +In this example, `Candidate` has the entire version range of bundles, `Fast` has a mix of older and more-recent versions, and `Stable` channel only has a single published entry. + +If we set the veneer attributes + +```yaml +GenerateMajorChannels: true +GenerateMinorChannels: false +``` + +we generate the following major channels (filtering out `olm.bundle` objects): +```yaml +--- +defaultChannel: stable-v1 +name: testoperator +schema: olm.package +--- +entries: +- name: testoperator.v0.1.0 +- name: testoperator.v0.1.1 +- name: testoperator.v0.1.2 +- name: testoperator.v0.1.3 + skips: + - testoperator.v0.1.0 + - testoperator.v0.1.1 + - testoperator.v0.1.2 +- name: testoperator.v0.2.0 +- name: testoperator.v0.2.1 +- name: testoperator.v0.2.2 + replaces: testoperator.v0.1.3 + skips: + - testoperator.v0.2.0 + - testoperator.v0.2.1 +- name: testoperator.v0.3.0 + replaces: testoperator.v0.2.2 +name: candidate-v0 +package: testoperator +schema: olm.channel +--- +entries: +- name: testoperator.v1.0.0 +- name: testoperator.v1.0.1 + skips: + - testoperator.v1.0.0 +- name: testoperator.v1.1.0 + replaces: testoperator.v1.0.1 +name: candidate-v1 +package: testoperator +schema: olm.channel +--- +entries: +- name: testoperator.v0.2.1 +- name: testoperator.v0.2.2 + skips: + - testoperator.v0.2.1 +- name: testoperator.v0.3.0 + replaces: testoperator.v0.2.2 +name: fast-v0 +package: testoperator +schema: olm.channel +--- +entries: +- name: testoperator.v1.0.1 +- name: testoperator.v1.1.0 + replaces: testoperator.v1.0.1 +name: fast-v1 +package: testoperator +schema: olm.channel +--- +entries: +- name: testoperator.v1.0.1 +name: stable-v1 +package: testoperator +schema: olm.channel +``` + +We generated a channel for each veneer channel entity corresponding to each of the 0.\#.\#, 1.\#.\# major version ranges with skips to the head of the highest semver in a channel. We also generated a replaces edge to traverse across minor version transitions within each major channel. Finally, we generated an `olm.package` object, setting as default the most-stable channel head we created. This process will prefer `Stable` channel over `Fast`, over `Candidate` and then a higher bundle version over a lower version. +(Please note that the naming of the generated channels indicates the digits of significance for that channel. For example, `fast-v1` is a decomposed channel of the `fast` type which contains only major versions of contributing bundles matching `v1`.) + +For contrast, if we set the veneer attributes + +```yaml +GenerateMinorChannels: true +GenerateMajorChannels: false +``` + + we generate the following minor channels (again filtering out `olm.bundle` objects): + +```yaml +--- +defaultChannel: stable-v1.0 +name: testoperator +schema: olm.package +--- +entries: + - name: testoperator.v0.1.0 + - name: testoperator.v0.1.1 + - name: testoperator.v0.1.2 + - name: testoperator.v0.1.3 + skips: + - testoperator.v0.1.0 + - testoperator.v0.1.1 + - testoperator.v0.1.2 +name: candidate-v0.1 +package: testoperator +schema: olm.channel +--- +entries: + - name: testoperator.v0.2.0 + - name: testoperator.v0.2.1 + - name: testoperator.v0.2.2 + replaces: testoperator.v0.1.3 + skips: + - testoperator.v0.2.0 + - testoperator.v0.2.1 +name: candidate-v0.2 +package: testoperator +schema: olm.channel +--- +entries: + - name: testoperator.v0.3.0 + replaces: testoperator.v0.2.2 +name: candidate-v0.3 +package: testoperator +schema: olm.channel +--- +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 +name: candidate-v1.1 +package: testoperator +schema: olm.channel +--- +entries: + - name: testoperator.v0.2.1 + - name: testoperator.v0.2.2 + skips: + - testoperator.v0.2.1 +name: fast-v0.2 +package: testoperator +schema: olm.channel +--- +entries: + - name: testoperator.v0.3.0 + replaces: testoperator.v0.2.2 +name: fast-v0.3 +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 + +``` + +Here, a channel is generated for each veneer channel which differs by minor version, and each channel has a `replaces` edge from the predecessor channel to the next-lesser minor bundle version. Please note that at no time do we transgress across major-version boundaries with the channels, to be consistent with [the semver convention](https://semver.org/) for major versions, where the purpose is to make incompatible API changes. + + diff --git a/content/en/docs/Tasks/creating-a-catalog.md b/content/en/docs/Tasks/creating-a-catalog.md index 61eb6cd4..06eab9f9 100644 --- a/content/en/docs/Tasks/creating-a-catalog.md +++ b/content/en/docs/Tasks/creating-a-catalog.md @@ -7,9 +7,13 @@ description: > ## Prerequisites -- [opm](https://github.com/operator-framework/operator-registry/releases) `v1.19.0+` +- [opm](https://github.com/operator-framework/operator-registry/releases) `v1.19.0+` (for file-based catalogs), **OR** +- [opm](https://github.com/operator-framework/operator-registry/releases) `v1.23.1+` (for catalog veneers) + +>Note: This document discusses creating a catalog of operators using plaintext files to store catalog metadata, which is the [latest feature][file-based-catalog-spec] of OLM catalogs. If you are looking to build catalogs using the deprecated sqlite database format to store catalog metadata instead, please read the [v0.18.z version][v0.18.z-version] of this doc instead. + +>Note: `veneers` are **ALPHA** functionality and may adopt breaking changes ->Note: This document discusses creating a catalog of operators using plaintext files to store catalog metadata, which is the [latest feature][file-based-catalog-spec] of OLM catalogs. If you are looking to build catalogs using the deprecated sqllite database format to store catalog metadata instead, please read the [v0.18.z version][v0.18.z-version] of this doc instead. ## Creating a Catalog `OLM`'s `CatalogSource` [CRD][catalogsource-crd] accepts a container image reference to a catalog of operators that can @@ -17,15 +21,63 @@ be made available to install in a cluster. You can make your operator bundle ava it to a catalog, packaging the catalog in a container image, and then using that image reference in the `CatalogSource`. This image contains all of the metadata required for OLM to manage the lifecycle of all of the operators it contains. -OLM uses a plaintext [file-based catalog][file-based-catalog-spec] format (JSON or YAML) to store these records in a Catalog, and `opm` has tooling -that helps initialize a Catalog, add new operators into it, and then validate that the catalog is valid. Let's walk -through a simple example. +OLM uses a plaintext [file-based catalog][file-based-catalog-spec] format (JSON or YAML) to store these records in a Catalog, and there are two approaches we can take to creating a Catalog, adding operators to it, and validating it. +Let's walk through a simple example for both approaches. + +### Catalog Creation Using Veneers +[Veneers][veneers-doc] are a purpose-built simplification of [File-Based Catalogs][file-based-catalog-spec] to ease common catalog operations. For this example, we'll be using the [semver veneer][semver-veneer-doc]. +>Note: We strongly recommend that authors create and maintain their veneers in a version-controlled environment discrete from their generated catalogs. Further, we recommend that authors focus on the veneer as the sole artifact connecting the operator to the catalog (even going so far as only generating the file-based catalog during CI/CD tooling so it is only provided for catalog contribution.) + +#### Catalog Creation +First we need to create the Catalog hierarchy and Dockerfile for generating the image +```sh +$ mkdir -p cool-catalog/example-operator +$ opm generate dockerfile cool-catalog +``` + +#### Organizing the Bundles into Channels + +Let's assume that this isn't the first time that we have released this operator into the catalog, but it's our first foray into veneers. We need to ensure an upgrade graph edge between the older bundle version and the new one. We also want to promote this latest version in a "stable" channel. Lastly, we already use [Semantic Versioning](https://semver.org) for our release numbering, and we really only care about new major (e.g. X.\#.\#) releases. + +>Note: we presume this step and veneer processing are performed in the source-controlled location related to operator bundle release, or at least separate from the catalog + +```sh +$ cat << EOF >> example-operator-veneer.yaml +Schema: olm.semver +GenerateMajorChannels: true +GenerateMinorChannels: false +Stable: + Bundles: + - Image: repository-uri/example-operator:v0.8.9 + - Image: repository-uri/example-operator:v0.9.0 +EOF +``` + +#### Generating the Catalog + +```sh +$ opm alpha render-veneer semver -o yaml < example-operator-veneer.yaml > cool-catalog/catalog.yaml +``` + +Validate the catalog to ensure that the result is functional + +```sh +$ opm validate cool-catalog +$ echo $? +0 +``` + + +### Catalog Creation with Raw File-Based Catalogs + + +#### Catalog Creation First, we need to initialize our Catalog, so we'll make a directory for it, generate a Dockerfile that can build a Catalog image, and then populate our catalog with our operator. -### Initialize the Catalog +#### Initializing the Catalog ```sh $ mkdir cool-catalog $ opm generate dockerfile cool-catalog @@ -48,7 +100,7 @@ FATA[0000] invalid index: Alright, so it's not valid. It looks like we need to add a bundle, so let's do that next... -### Add a bundle to the Catalog +#### Add a bundle to the Catalog ```sh $ opm render quay.io/example-inc/example-operator-bundle:v0.1.0 \ @@ -61,7 +113,7 @@ $ opm validate cool-catalog FATA[0000] package "example-operator", bundle "example-operator.v0.1.0" not found in any channel entries ``` -### Add a channel entry for the bundle +#### Add a channel entry for the bundle We rendered the bundle, but we still haven't yet added it to any channels. Let's initialize a channel: @@ -86,7 +138,7 @@ $ echo $? Success! There were no errors and we got a `0` error code. -#### Summary +#### Raw File-Based Catalogs Summary In the general case, adding a bundle involves three discrete steps: - Render the bundle into the catalog using `opm render `. - Add the bundle into desired channels and update the channels' upgrade edges @@ -115,7 +167,7 @@ There are some guidelines to keep in mind though: ### Build and push the catalog image -Lastly, we can build and push our catalog image: +The last step is building and pushing the catalog image. For either approach, this is the same: ```sh $ docker build . \ @@ -128,5 +180,7 @@ Now the catalog image is available for clusters to use and reference with `Catal [catalogsource-crd]: /docs/concepts/crds/catalogsource [file-based-catalog-spec]: /docs/reference/file-based-catalogs +[veneers-doc]: /docs/reference/veneers +[semver-veneer-doc]: /docs/reference/veneers#semver-veneer [upgrade-graph-doc]: /docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph [v0.18.z-version]: https://v0-18-z.olm.operatorframework.io/docs/tasks/make-index-available-on-cluster/ diff --git a/content/en/docs/Tasks/make-catalog-available-on-cluster.md b/content/en/docs/Tasks/make-catalog-available-on-cluster.md index 2a6e161d..687bf719 100644 --- a/content/en/docs/Tasks/make-catalog-available-on-cluster.md +++ b/content/en/docs/Tasks/make-catalog-available-on-cluster.md @@ -47,7 +47,7 @@ cool-catalog-dtqv2 1/1 Running 0 30s It is possible to configure the `CatalogSource` to poll a source, such as an image registry, to check whether the catalog source pod should be updated. A common use case would be pushing new bundles to the same catalog source tag, and seeing updated operators from those bundles being installed in the cluster. -For example, say currently you have Operator X v1.0 installed in the cluster from the catalog `quay.io/my-namespace/cool-catalog:main`. This is the latest version of the X operator in the catalog. When a new v2.0 of Operator X is published, the v2.0 version of the X operator can be included in the catalog using the same steps described in the [creating catalog doc][creating-a-catalog-summary], then the catalog image can be rebuilt and pushed to the same `main` tag. With catalog polling enabled, OLM will pull down the newer version of the catalog image and make the new information available. +For example, say currently you have Operator X v1.0 installed in the cluster from the catalog `quay.io/my-namespace/cool-catalog:main`. This is the latest version of the X operator in the catalog. When a new v2.0 of Operator X is published, the v2.0 version of the X operator can be included in the catalog using the same steps described in the [creating catalog doc][creating-a-catalog-steps], then the catalog image can be rebuilt and pushed to the same `main` tag. With catalog polling enabled, OLM will pull down the newer version of the catalog image and make the new information available. Each type of check for an updated catalog source is called an `updateStrategy`. Only one `updateStrategy` is supported at a time. `registryPoll` is a type of `updateStrategy` that checks an image registry for an updated version of the same tag(via image SHAs). The `interval` defines the amount of time between each successive poll. @@ -85,4 +85,4 @@ spec: interval: 10m ``` -[creating-a-catalog-summary]: /docs/tasks/creating-a-catalog/#summary \ No newline at end of file +[creating-a-catalog-steps]: /docs/tasks/creating-a-catalog/#creating-a-catalog \ No newline at end of file diff --git a/hack/ci/link-check.sh b/hack/ci/link-check.sh index 404caffc..61f05cf8 100755 --- a/hack/ci/link-check.sh +++ b/hack/ci/link-check.sh @@ -14,4 +14,7 @@ trap cleanup EXIT ${CONTAINER_ENGINE} volume create ${volume_name} ${CONTAINER_ENGINE} run --rm ${CONTAINER_RUN_EXTRA_OPTIONS} -v "$(pwd):/src" -v ${volume_name}:/src/public klakegg/hugo:0.73.0-ext-ubuntu -${CONTAINER_ENGINE} run --rm -v ${volume_name}:/target mtlynch/htmlproofer /target --empty-alt-ignore --http-status-ignore 429 --allow_hash_href +# ignore +# 1: links going back to help.github.com are rate-limited and can make this flaky +# 2: docsy autogenerated edit links to original markdown source, which will fail if the markdown file is new +${CONTAINER_ENGINE} run --rm -v ${volume_name}:/target mtlynch/htmlproofer /target --empty-alt-ignore --http-status-ignore 429 --allow_hash_href --url-ignore '/help.github.com/,/edit\/master\/.*\.md/' From 694c92136ce558f0568c1ffb4444dd574ffd13ea Mon Sep 17 00:00:00 2001 From: Jordan Keister Date: Thu, 21 Jul 2022 14:22:44 -0500 Subject: [PATCH 2/3] revise --- content/en/docs/Reference/veneers.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/en/docs/Reference/veneers.md b/content/en/docs/Reference/veneers.md index 4a0bf943..fb44f2ad 100644 --- a/content/en/docs/Reference/veneers.md +++ b/content/en/docs/Reference/veneers.md @@ -16,7 +16,7 @@ In this context, there are two components to every `veneer`: 1. An arbitrary API 2. An executable which processes #1 and produces a valid FBC. -The veneers supported by [`opm`](opm-tool) are: +The veneers supported by [`opm`](https://github.com/operator-framework/operator-registry/blob/master/docs/design/opm-tooling.md) are: - the [`basic veneer`](#basic-veneer), which provides a simplified abstraction of an FBC; and - the [`semver veneer`](#semver-veneer), which provides the capability to generate an entire upgrade graph @@ -182,7 +182,7 @@ Like best practices [recommended channel naming](/docs/best-practices/channel-na Under each channel are a list of bundle image references which contribute to that channel. At least one channel must have bundle images. -The `olm.semver` [cue](cuelang-spec) schema is: +The `olm.semver` [cue](https://cuelang.org/docs/references/spec/) schema is: ```cue #Package: { @@ -444,4 +444,3 @@ schema: olm.channel Here, a channel is generated for each veneer channel which differs by minor version, and each channel has a `replaces` edge from the predecessor channel to the next-lesser minor bundle version. Please note that at no time do we transgress across major-version boundaries with the channels, to be consistent with [the semver convention](https://semver.org/) for major versions, where the purpose is to make incompatible API changes. - From 2af26d74bfd6962dad131f8fa248e9568c862520 Mon Sep 17 00:00:00 2001 From: Jordan Keister Date: Thu, 21 Jul 2022 16:05:41 -0500 Subject: [PATCH 3/3] updating disclaimer on build-metadata version compare since op-registry #988 just merged --- content/en/docs/Reference/veneers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Reference/veneers.md b/content/en/docs/Reference/veneers.md index fb44f2ad..3c0991b8 100644 --- a/content/en/docs/Reference/veneers.md +++ b/content/en/docs/Reference/veneers.md @@ -165,7 +165,7 @@ schema: olm.bundle Since a `veneer` is identified as an input schema which is processed to generate a valid FBC, we can define a `semver veneer` as a schema which uses channel conventions to facilitate the auto-generation of channels adhering to [Semantic Versioning](https://semver.org/) (semver) guidelines and consistent with best practices on [channel naming](/docs/best-practices/channel-naming/#naming). This approach may be attractive to operator authors who are defining a new upgrade graph, or are already close enough to the veneer conventions to be able to adopt it (i.e. already use semver, only promote a single channel, etc.). ->**DISCLAIMER:** since version build metadata [MUST be ignored when determining version precedence](https://semver.org/#spec-item-10) when using semver, it cannot be used in any bundle included in the `semver veneer` and will result in a fatal error. +>**DISCLAIMER:** since version build metadata [MUST be ignored when determining version precedence](https://semver.org/#spec-item-10) when using semver, if any bundles differ only by build metadata the render attempt will generate a fatal error. This alpha version of the `semver veneer` has the following goals: - terse grammar to minimize creation/maintenance effort