diff --git a/_topic_map.yml b/_topic_map.yml index ac709a0e1de7..26eca369baba 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -643,8 +643,13 @@ Topics: - Name: Basic tkn commands File: op-tkn-reference - Name: opm CLI - File: opm-cli + Dir: opm Distros: openshift-enterprise,openshift-origin + Topics: + - Name: Installing the opm CLI + File: cli-opm-install + - Name: opm CLI reference + File: cli-opm-ref - Name: Operator SDK Dir: osdk Distros: openshift-enterprise,openshift-origin @@ -1243,7 +1248,7 @@ Topics: Topics: - Name: What are Operators? File: olm-what-operators-are - - Name: Packaging formats + - Name: Packaging format File: olm-packaging-format - Name: Common terms File: olm-common-terms diff --git a/cli_reference/opm-cli.adoc b/cli_reference/opm-cli.adoc deleted file mode 100644 index 3dfa4660cdd4..000000000000 --- a/cli_reference/opm-cli.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="opm-cli"] -= opm CLI -include::modules/common-attributes.adoc[] -:context: opm-cli - -toc::[] - -include::modules/olm-about-opm.adoc[leveloffset=+1] -.Additional resources - -* See xref:../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for more information about the bundle format. -* To create a bundle image using the Operator SDK, see -xref:../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-working-bundle-images[Working with bundle images]. - -include::modules/olm-installing-opm.adoc[leveloffset=+1] - -[id="opm-addtl-resources"] -== Additional resources - -* See xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs[Managing custom catalogs] for `opm` procedures including creating, updating, and pruning index images. diff --git a/cli_reference/opm/cli-opm-install.adoc b/cli_reference/opm/cli-opm-install.adoc new file mode 100644 index 000000000000..a325c68e308c --- /dev/null +++ b/cli_reference/opm/cli-opm-install.adoc @@ -0,0 +1,20 @@ +[id="cli-opm-install"] += Installing the opm CLI +include::modules/common-attributes.adoc[] +:context: cli-opm-install + +toc::[] + +include::modules/olm-about-opm.adoc[leveloffset=+1] +.Additional resources + +* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging format] for more information about the bundle format. +* To create a bundle image using the Operator SDK, see +xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-working-bundle-images[Working with bundle images]. + +include::modules/olm-installing-opm.adoc[leveloffset=+1] + +[id="opm-addtl-resources"] +== Additional resources + +* See xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs[Managing custom catalogs] for `opm` procedures including creating, updating, and pruning catalogs. diff --git a/cli_reference/opm/cli-opm-ref.adoc b/cli_reference/opm/cli-opm-ref.adoc new file mode 100644 index 000000000000..b314d47f9f8b --- /dev/null +++ b/cli_reference/opm/cli-opm-ref.adoc @@ -0,0 +1,33 @@ +[id="cli-opm-ref"] += opm CLI reference +include::modules/common-attributes.adoc[] +:context: cli-opm-ref + +toc::[] + +The `opm` command-line interface (CLI) is a tool for creating and maintaining Operator catalogs. + +.`opm` CLI syntax +[source,terminal] +---- +$ opm [] [] [] +---- + +.Global flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`--skip-tls` +|Skip TLS certificate verification for container image registries while pulling bundles or indexes. + +|=== + +:FeatureName: The SQLite-based catalog format, including the related CLI commands, +include::modules/deprecated-feature.adoc[] + +include::modules/opm-cli-ref-index.adoc[leveloffset=+1] +include::modules/opm-cli-ref-init.adoc[leveloffset=+1] +include::modules/opm-cli-ref-render.adoc[leveloffset=+1] +include::modules/opm-cli-ref-validate.adoc[leveloffset=+1] +include::modules/opm-cli-ref-serve.adoc[leveloffset=+1] diff --git a/cli_reference/osdk/cli-osdk-install.adoc b/cli_reference/osdk/cli-osdk-install.adoc index d3f452cfa0da..00c4d166d440 100644 --- a/cli_reference/osdk/cli-osdk-install.adoc +++ b/cli_reference/osdk/cli-osdk-install.adoc @@ -7,6 +7,8 @@ toc::[] The Operator SDK provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. You can install the Operator SDK CLI on your workstation so that you are prepared to start authoring your own Operators. +Operator authors with cluster administrator access to a Kubernetes-based cluster, such as {product-title}, can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. + See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK. [NOTE] diff --git a/cli_reference/osdk/cli-osdk-ref.adoc b/cli_reference/osdk/cli-osdk-ref.adoc index bda8652fd799..46d5076e363d 100644 --- a/cli_reference/osdk/cli-osdk-ref.adoc +++ b/cli_reference/osdk/cli-osdk-ref.adoc @@ -13,8 +13,6 @@ The Operator SDK command-line interface (CLI) is a development kit designed to m $ operator-sdk [] [] [] ---- -Operator authors with cluster administrator access to a Kubernetes-based cluster (such as {product-title}) can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. - See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK. include::modules/osdk-cli-ref-bundle.adoc[leveloffset=+1] diff --git a/modules/olm-about-opm.adoc b/modules/olm-about-opm.adoc index 6236b36af41f..1d7bd8e0d702 100644 --- a/modules/olm-about-opm.adoc +++ b/modules/olm-about-opm.adoc @@ -1,11 +1,11 @@ // Module included in the following assemblies: // -// * operators/understanding/olm/olm-packaging-formats.adoc -// * cli_reference/opm-cli.adoc +// * operators/understanding/olm-packaging-format.adoc +// * cli_reference/opm/cli-opm-install.adoc [id="olm-about-opm_{context}"] -= About opm += About the opm CLI -The `opm` CLI tool is provided by the Operator Framework for use with the Operator bundle format. This tool allows you to create and maintain catalogs of Operators from a list of bundles, called an _index_, that are similar to software repositories. The result is a container image, called an _index image_, which can be stored in a container registry and then installed on a cluster. +The `opm` CLI tool is provided by the Operator Framework for use with the Operator bundle format. This tool allows you to create and maintain catalogs of Operators from a list of Operator bundles that are similar to software repositories. The result is a container image which can be stored in a container registry and then installed on a cluster. -An index contains a database of pointers to Operator manifest content that can be queried through an included API that is served when the container image is run. On {product-title}, Operator Lifecycle Manager (OLM) can use the index image as a catalog by referencing it in a `CatalogSource` object, which polls the image at regular intervals to enable frequent updates to installed Operators on the cluster. +A catalog contains a database of pointers to Operator manifest content that can be queried through an included API that is served when the container image is run. On {product-title}, Operator Lifecycle Manager (OLM) can reference the image in a catalog source, defined by a `CatalogSource` object, which polls the image at regular intervals to enable frequent updates to installed Operators on the cluster. diff --git a/modules/olm-bundle-format-dependencies-file.adoc b/modules/olm-bundle-format-dependencies-file.adoc index 8a1fd8691610..6d07617fede8 100644 --- a/modules/olm-bundle-format-dependencies-file.adoc +++ b/modules/olm-bundle-format-dependencies-file.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * operators/understanding/olm/olm-packaging-format.adoc +// * operators/understanding/olm-packaging-format.adoc // * operators/understanding/olm/olm-understanding-dependency-resolution.adoc [id="olm-bundle-format-dependencies_{context}"] diff --git a/modules/olm-bundle-format.adoc b/modules/olm-bundle-format.adoc index 1c3e293dfbd8..4fa2b6826936 100644 --- a/modules/olm-bundle-format.adoc +++ b/modules/olm-bundle-format.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * operators/understanding/olm/olm-packaging-format.adoc +// * operators/understanding/olm-packaging-format.adoc [id="olm-bundle-format_{context}"] = Bundle format diff --git a/modules/olm-creating-fb-catalog-image.adoc b/modules/olm-creating-fb-catalog-image.adoc new file mode 100644 index 000000000000..4e77a75c4048 --- /dev/null +++ b/modules/olm-creating-fb-catalog-image.adoc @@ -0,0 +1,164 @@ +// Module included in the following assemblies: +// +// * operators/admin/olm-managing-custom-catalogs.adoc + +ifdef::openshift-origin[] +:registry-image: quay.io/openshift/origin-operator-registry:4.9.0 +endif::[] +ifndef::openshift-origin[] +:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.9 +endif::[] + +[id="olm-creating-fb-catalog-image_{context}"] += Creating a file-based catalog image + +You can create a catalog image that uses the plain text _file-based catalog_ format (JSON or YAML), which replaces the deprecated SQLite database format. The `opm` CLI provides tooling that helps initialize a catalog in the file-based format, render new records into it, and validate that the catalog is valid. + +.Prerequisites + +* `opm` version 1.18.0+ +* `podman` version 1.9.3+ +* A bundle image built and pushed to a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] + +.Procedure + +. Initialize a catalog for a file-based catalog: + +.. Create a directory for the catalog: ++ +[source,terminal] +---- +$ mkdir -index +---- + +.. Create a Dockerfile that can build a catalog image: ++ +.Example `-index.Dockerfile` +[source,bash,subs="attributes+"] +---- +# The base image is expected to contain +# /bin/opm (with a serve subcommand) and /bin/grpc_health_probe +FROM {registry-image} + +# Configure the entrypoint and command +ENTRYPOINT ["/bin/opm"] +CMD ["serve", "/configs"] + +# Copy declarative config root into image at /configs +ADD -index /configs + +# Set DC-specific label for the location of the DC root directory +# in the image +LABEL operators.operatorframework.io.index.configs.v1=/configs +---- ++ +The Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step: ++ +.Example directory structure +[source,terminal] +---- +. +├── -index +└── -index.Dockerfile +---- + +.. Populate the catalog with your package definition: ++ +[source,terminal] +---- +$ opm init \ <.> + --default-channel=preview \ <.> + --description=./README.md \ <.> + --icon=./operator-icon.svg \ <.> + --output yaml \ <.> + > -index/index.yaml <.> +---- +<.> Operator, or package, name. +<.> Channel that subscription will default to if unspecified. +<.> Path to the Operator's `README.md` or other documentation. +<.> Path to the Operator's icon. +<.> Output format: JSON or YAML. +<.> Path for creating the catalog configuration file. ++ +This command generates an `olm.package` declarative config blob in the specified catalog configuration file. + +. Add a bundle to the catalog: ++ +[source,terminal] +---- +$ opm render //: \ <.> + --output=yaml \ + >> -index/index.yaml <.> +---- +<.> Pull spec for the bundle image. +<.> Path to the catalog configuration file. ++ +The `opm render` command generates a declarative config blob from the provided catalog images and bundle images. ++ +[NOTE] +==== +Channels must contain at least one bundle. +==== + +. Add a channel entry for the bundle. For example, modify the following example to your specifications, and add it to your `-index/index.yaml` file: ++ +.Example channel entry +[source,yaml] +---- +--- +schema: olm.channel +package: +name: preview +entries: + - name: .v0.1.0 <.> +---- +<.> Ensure that you include the period (`.`) after `` but before the `v` in the version. Otherwise, the entry will fail to pass the `opm validate` command. + +. Validate the file-based catalog: + +.. Run the `opm validate` command against the catalog directory: ++ +[source,terminal] +---- +$ opm validate -index +---- + +.. Check that the error code is `0`: ++ +[source,terminal] +---- +$ echo $? +---- ++ +.Example output +[source,terminal] +---- +0 +---- + +. Build the catalog image: ++ +[source,terminal] +---- +$ podman build . \ + -f -index.Dockerfile \ + -t //: +---- + +. Push the catalog image to a registry: + +.. If required, authenticate with your target registry: ++ +[source,terminal] +---- +$ podman login +---- + +.. Push the catalog image: ++ +[source,terminal] +---- +$ podman push //: +---- + +:!registry-image: diff --git a/modules/olm-creating-index-image.adoc b/modules/olm-creating-index-image.adoc index e68d5a7e9e02..dfbfa18b953e 100644 --- a/modules/olm-creating-index-image.adoc +++ b/modules/olm-creating-index-image.adoc @@ -3,13 +3,13 @@ // * operators/admin/olm-managing-custom-catalogs.adoc [id="olm-creating-index-image_{context}"] -= Creating an index image += Creating a SQLite-based index image -You can create an index image using the `opm` CLI. +You can create an index image based on the SQLite database format by using the `opm` CLI. .Prerequisites -* `opm` version 1.12.3+ +* `opm` version 1.18.0+ * `podman` version 1.9.3+ * A bundle image built and pushed to a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] diff --git a/modules/olm-fb-catalogs-automation.adoc b/modules/olm-fb-catalogs-automation.adoc new file mode 100644 index 000000000000..17a7ac80b839 --- /dev/null +++ b/modules/olm-fb-catalogs-automation.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-automation_{context}"] += Automation + +Operator authors and catalog maintainers are encouraged to automate their catalog maintenance with CI/CD workflows. Catalog maintainers can further improve on this by building GitOps automation to accomplish the following tasks: + +* Check that pull request (PR) authors are permitted to make the requested changes, for example by updating their package's image reference. +* Check that the catalog updates pass the `opm validate` command. +* Check that the updated bundle or catalog image references exist, the catalog images run successfully in a cluster, and Operators from that package can be successfully installed. +* Automatically merge PRs that pass the previous checks. +* Automatically rebuild and republish the catalog image. diff --git a/modules/olm-fb-catalogs-example.adoc b/modules/olm-fb-catalogs-example.adoc new file mode 100644 index 000000000000..684609db4d70 --- /dev/null +++ b/modules/olm-fb-catalogs-example.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-example_{context}"] += Example catalog + +With file-based catalogs, catalog maintainers can focus on Operator curation and compatibility. Because Operator authors have already produced Operator-specific catalogs for their Operators, catalog maintainers can build their catalog by rendering each Operator catalog into a subdirectory of the catalog's root directory. + +There are many possible ways to build a file-based catalog; the following steps outline a simple approach: + +. Maintain a single configuration file for the catalog, containing image references for each Operator in the catalog: ++ +.Example catalog configuration file +[source,yaml] +---- +name: community-operators +repo: quay.io/community-operators/catalog +tag: latest +references: +- name: etcd-operator + image: quay.io/etcd-operator/index@sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 +- name: prometheus-operator + image: quay.io/prometheus-operator/index@sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317 +---- + +. Run a script that parses the configuration file and creates a new catalog from its references: ++ +.Example script +[source,sh] +---- +name=$(yq eval '.name' catalog.yaml) +mkdir "$name" +yq eval '.name + "/" + .references[].name' catalog.yaml | xargs mkdir +for l in $(yq e '.name as $catalog | .references[] | .image + "|" + $catalog + "/" + .name + "/index.yaml"' catalog.yaml); do + image=$(echo $l | cut -d'|' -f1) + file=$(echo $l | cut -d'|' -f2) + opm render "$image" > "$file" +done +opm alpha generate dockerfile "$name" +indexImage=$(yq eval '.repo + ":" + .tag' catalog.yaml) +docker build -t "$indexImage" -f "$name.Dockerfile" . +docker push "$indexImage" +---- diff --git a/modules/olm-fb-catalogs-guidelines.adoc b/modules/olm-fb-catalogs-guidelines.adoc new file mode 100644 index 000000000000..5823abb32bd6 --- /dev/null +++ b/modules/olm-fb-catalogs-guidelines.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-guidelines_{context}"] += Guidelines + +Consider the following guidelines when maintaining file-based catalogs. + +[id="olm-fb-catalogs-immutable_{context}"] +== Immutable bundles + +The general advice with Operator Lifecycle Manager (OLM) is that bundle images and their metadata should be treated as immutable. + +If a broken bundle has been pushed to a catalog, you must assume that at least one of your users has upgraded to that bundle. Based on that assumption, you must release another bundle with an upgrade edge from the broken bundle to ensure users with the broken bundle installed receive an upgrade. OLM will not reinstall an installed bundle if the contents of that bundle are updated in the catalog. + +However, there are some cases where a change in the catalog metadata is preferred: + +* Channel promotion: If you already released a bundle and later decide that you would like to add it to another channel, you can add an entry for your bundle in another `olm.channel` blob. +* New upgrade edges: If you release a new `1.2.z` bundle version, for example `1.2.4`, but `1.3.0` is already released, you can update the catalog metadata for `1.3.0` to skip `1.2.4`. + +[id="olm-fb-catalogs-source-control_{context}"] +== Source control + +Catalog metadata should be stored in source control and treated as the source of truth. Updates to catalog images should include the following steps: + +. Update the source-controlled catalog directory with a new commit. +. Build and push the catalog image. Use a consistent tagging taxonomy, such as `:latest` or `:`, so that users can receive updates to a catalog as they become available. diff --git a/modules/olm-fb-catalogs-prop.adoc b/modules/olm-fb-catalogs-prop.adoc new file mode 100644 index 000000000000..5221e65d5c3f --- /dev/null +++ b/modules/olm-fb-catalogs-prop.adoc @@ -0,0 +1,92 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-prop_{context}"] += Properties + +Properties are arbitrary pieces of metadata that can be attached to file-based catalog schemas. The `type` field is a string that effectively specifies the semantic and syntactic meaning of the `value` field. The value can be any arbitrary JSON or YAML. + +OLM defines a handful of property types, again using the reserved `olm.*` prefix. + +[id="olm-fb-catalogs-package-prop_{context}"] +== olm.package property + +The `olm.package` property defines the package name and version. This is a required property on bundles, and there must be exactly one of these properties. The `packageName` field must match the bundle's first-class `package` field, and the `version` field must be a valid semantic version. + +.`olm.package` property +[%collapsible] +==== +[source,go] +---- +#PropertyPackage: { + type: "olm.package" + value: { + packageName: string & !="" + version: string & !="" + } +} +---- +==== + +[id="olm-fb-catalogs-gvk-prop_{context}"] +== olm.gvk property + +The `olm.gvk` property defines the group/version/kind (GVK) of a Kubernetes API that is provided by this bundle. This property is used by OLM to resolve a bundle with this property as a dependency for other bundles that list the same GVK as a required API. The GVK must adhere to Kubernetes GVK validations. + +.`olm.gvk` property +[%collapsible] +==== +[source,go] +---- +#PropertyGVK: { + type: "olm.gvk" + value: { + group: string & !="" + version: string & !="" + kind: string & !="" + } +} +---- +==== + +[id="olm-fb-catalogs-package-reqd-prop_{context}"] +== olm.package.required + +The `olm.package.required` property defines the package name and version range of another package that this bundle requires. For every required package property a bundle lists, OLM ensures there is an Operator installed on the cluster for the listed package and in the required version range. The `versionRange` field must be a valid semantic version (semver) range. + +.`olm.package.required` property +[%collapsible] +==== +[source,go] +---- +#PropertyPackageRequired: { + type: "olm.package.required" + value: { + packageName: string & !="" + versionRange: string & !="" + } +} +---- +==== + +[id="olm-fb-catalogs-gvk-reqd-prop_{context}"] +== olm.gvk.required + +The `olm.gvk.required` property defines the group/version/kind (GVK) of a Kubernetes API that this bundle requires. For every required GVK property a bundle lists, OLM ensures there is an Operator installed on the cluster that provides it. The GVK must adhere to Kubernetes GVK validations. + +.`olm.gvk.required` property +[%collapsible] +==== +[source,terminal] +---- +#PropertyGVKRequired: { + type: "olm.gvk.required" + value: { + group: string & !="" + version: string & !="" + kind: string & !="" + } +} +---- +==== diff --git a/modules/olm-fb-catalogs-schemas.adoc b/modules/olm-fb-catalogs-schemas.adoc new file mode 100644 index 000000000000..ad06deb1bcee --- /dev/null +++ b/modules/olm-fb-catalogs-schemas.adoc @@ -0,0 +1,158 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-schemas_{context}"] += Schemas + +File-based catalogs use a format, based on the link:https://cuelang.org/docs/references/spec/[CUE language specification], that can be extended with arbitrary schemas. The following `_Meta` CUE schema defines the format that all file-based catalog blobs must adhere to: + +.`_Meta` schema +[source,go] +---- +_Meta: { + // schema is required and must be a non-empty string + schema: string & !="" + + // package is optional, but if it's defined, it must be a non-empty string + package?: string & !="" + + // properties is optional, but if it's defined, it must be a list of 0 or more properties + properties?: [... #Property] +} + +#Property: { + // type is required + type: string & !="" + + // value is required, and it must not be null + value: !=null +} +---- + +[NOTE] +==== +No CUE schemas listed in this specification should be considered exhaustive. The `opm validate` command has additional validations that are difficult or impossible to express concisely in CUE. +==== + +An Operator Lifecycle Manager (OLM) catalog currently uses three schemas (`olm.package`, `olm.channel`, and `olm.bundle`), which correspond to OLM's existing package and bundle concepts. + +Each Operator package in a catalog requires exactly one `olm.package` blob, at least one `olm.channel` blob, and one or more `olm.bundle` blobs. + +[NOTE] +==== +All `olm.*` schemas are reserved for OLM-defined schemas. Custom schemas must use a unique prefix, such as a domain that you own. +==== + +[id="olm-fb-catalogs-package-schema_{context}"] +== olm.package schema + +The `olm.package` schema defines package-level metadata for an Operator. This includes its name, description, default channel, and icon. + +.`olm.package` schema +[%collapsible] +==== +[source,go] +---- +#Package: { + schema: "olm.package" + + // Package name + name: string & !="" + + // A description of the package + description?: string + + // The package's default channel + defaultChannel: string & !="" + + // An optional icon + icon?: { + base64data: string + mediatype: string + } +} +---- +==== + +[id="olm-fb-catalogs-channel-schema_{context}"] +== olm.channel schema + +The `olm.channel` schema defines a channel within a package, the bundle entries that are members of the channel, and the upgrade edges for those bundles. + +A bundle can included as an entry in multiple `olm.channel` blobs, but it can have only one entry per channel. + +It is valid for an entry's replaces value to reference another bundle name that cannot be found in this catalog or another catalog. However, all other channel invariants must hold true, such as a channel not having multiple heads. + +.`olm.channel` schema +[%collapsible] +==== +[source,go] +---- +#Channel: { + schema: "olm.channel" + package: string & !="" + name: string & !="" + entries: [...#ChannelEntry] +} + +#ChannelEntry: { + // name is required. It is the name of an `olm.bundle` that + // is present in the channel. + name: string & !="" + + // replaces is optional. It is the name of bundle that is replaced + // by this entry. It does not have to be present in the entry list. + replaces?: string & !="" + + // skips is optional. It is a list of bundle names that are skipped by + // this entry. The skipped bundles do not have to be present in the + // entry list. + skips?: [...string & !=""] + + // skipRange is optional. It is the semver range of bundle versions + // that are skipped by this entry. + skipRange?: string & !="" +} +---- +==== + +//// +For more information about defining upgrade edges, see the upgrade graph reference documentation. +//// + +[id="olm-fb-catalogs-olm-bundle_{context}"] +== olm.bundle schema + +.`olm.bundle` schema +[%collapsible] +==== +[source,go] +---- +#Bundle: { + schema: "olm.bundle" + package: string & !="" + name: string & !="" + image: string & !="" + properties: [...#Property] + relatedImages?: [...#RelatedImage] +} + +#Property: { + // type is required + type: string & !="" + + // value is required, and it must not be null + value: !=null +} + +#RelatedImage: { + // image is the image reference + image: string & !="" + + // name is an optional descriptive name for an image that + // helps identify its purpose in the context of the bundle + name?: string & !="" +} +---- +==== diff --git a/modules/olm-fb-catalogs-structure.adoc b/modules/olm-fb-catalogs-structure.adoc new file mode 100644 index 000000000000..8804b034f015 --- /dev/null +++ b/modules/olm-fb-catalogs-structure.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-fb-catalogs-structure_{context}"] += Directory structure + +File-based catalogs can be stored and loaded from directory-based file systems. The `opm` CLI loads the catalog by walking the root directory and recursing into subdirectories. The CLI attempts to load every file it finds and fails if any errors occur. + +Non-catalog files can be ignored using `.indexignore` files, which have the same rules for patterns and precedence as `.gitignore` files. + +.Example `.indexignore` file +[source,terminal] +---- +# Ignore everything except non-object .json and .yaml files +**/* +!*.json +!*.yaml +**/objects/*.json +**/objects/*.yaml +---- + +Catalog maintainers have the flexibility to choose their desired layout, but it is recommended to store each package's file-based catalog blobs in separate subdirectories. Each individual file can be either JSON or YAML; it is not necessary for every file in a catalog to use the same format. + +.Basic recommended structure +[source,terminal] +---- +catalog +├── packageA +│ └── index.yaml +├── packageB +│ ├── .indexignore +│ ├── index.yaml +│ └── objects +│ └── packageB.v0.1.0.clusterserviceversion.yaml +└── packageC + └── index.json +---- + +This recommended structure has the property that each subdirectory in the directory hierarchy is a self-contained catalog, which makes catalog composition, discovery, and navigation trivial file system operations. The catalog could also be included in a parent catalog by copying it into the parent catalog's root directory. diff --git a/modules/olm-fb-catalogs.adoc b/modules/olm-fb-catalogs.adoc new file mode 100644 index 000000000000..4b0071de4bdd --- /dev/null +++ b/modules/olm-fb-catalogs.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * operators/understanding/olm-packaging-format.adoc + +[id="olm-file-based-catalogs_{context}"] += File-based catalogs + +_File-based catalogs_ are the latest iteration of the catalog format in Operator Lifecycle Manager (OLM). It is a plain text-based (JSON or YAML) and declarative config evolution of the earlier SQLite database format, and it is fully backwards compatible. The goal of this format is to enable Operator catalog editing, composability, and extensibility. + +[NOTE] +==== +The default Red Hat-provided Operator catalogs for {product-title} 4.6 and later are currently still shipped in the SQLite database format. +==== + +Editing:: +With file-based catalogs, users interacting with the contents of a catalog are able to make direct changes to the format and verify that their changes are valid. Because this format is plain text JSON or YAML, catalog maintainers can easily manipulate catalog metadata by hand or with widely known and supported JSON or YAML tooling, such as the `jq` CLI. ++ +This editability enables the following features and user-defined extensions: ++ +-- +* Promoting an existing bundle to a new channel +* Changing the default channel of a package +* Custom algorithms for adding, updating, and removing upgrade edges +-- + +Composability:: +File-based catalogs are stored in an arbitrary directory hierarchy, which enables catalog composition. For example, consider two separate file-based catalog directories: `catalogA` and `catalogB`. A catalog maintainer can create a new combined catalog by making a new directory `catalogC` and copying `catalogA` and `catalogB` into it. ++ +This composability enables decentralized catalogs. The format permits Operator authors to maintain Operator-specific catalogs, and it permits maintainers to trivially build a catalog composed of individual Operator catalogs. File-based catalogs can be composed by combining multiple other catalogs, by extracting subsets of one catalog, or a combination of both of these. ++ +[NOTE] +==== +Duplicate packages and duplicate bundles within a package are not permitted. The `opm validate` command returns an error if any duplicates are found. +==== ++ +Because Operator authors are most familiar with their Operator, its dependencies, and its upgrade compatibility, they are able to maintain their own Operator-specific catalog and have direct control over its contents. With file-based catalogs, Operator authors own the task of building and maintaining their packages in a catalog. Composite catalog maintainers, however, only own the task of curating the packages in their catalog and publishing the catalog to users. + +Extensibility:: +The file-based catalog specification is a low-level representation of a catalog. While it can be maintained directly in its low-level form, catalog maintainers can build interesting extensions on top that can be used by their own custom tooling to make any number of mutations. ++ +For example, a tool could translate a high-level API, such as `(mode=semver)`, down to the low-level, file-based catalog format for upgrade edges. Or a catalog maintainer might need to customize all of the bundle metadata by adding a new property to bundles that meet a certain criteria. ++ +While this extensibility allows for additional official tooling to be developed on top of the low-level APIs for future {product-title} releases, the major benefit is that catalog maintainers have this capability as well. diff --git a/modules/olm-installing-opm.adoc b/modules/olm-installing-opm.adoc index 41d619ccf7e3..418563f923a2 100644 --- a/modules/olm-installing-opm.adoc +++ b/modules/olm-installing-opm.adoc @@ -1,9 +1,9 @@ // Module included in the following assemblies: // -// * cli_reference/opm-cli.adoc +// * cli_reference/opm/cli-opm-install.adoc [id="olm-installing-opm_{context}"] -= Installing opm += Installing the opm CLI You can install the `opm` CLI tool on your Linux, macOS, or Windows workstation. @@ -76,5 +76,6 @@ $ opm version .Example output [source,terminal] ---- -Version: version.Version{OpmVersion:"v1.15.4-2-g6183dbb3", GitCommit:"6183dbb3567397e759f25752011834f86f47a3ea", BuildDate:"2021-02-13T04:16:08Z", GoOs:"linux", GoArch:"amd64"} +Version: version.Version{OpmVersion:"v1.18.0", GitCommit:"32eb2591437e394bdc58a58371c5cd1e6fe5e63f", BuildDate:"2021-09-21T10:41:00Z", GoOs:"linux", GoArch:"amd64"} + ---- diff --git a/modules/olm-pruning-index-image.adoc b/modules/olm-pruning-index-image.adoc index 69e072d4bf27..b2e28288bfad 100644 --- a/modules/olm-pruning-index-image.adoc +++ b/modules/olm-pruning-index-image.adoc @@ -7,7 +7,7 @@ ifdef::openshift-origin[] :catalog-name: catalog :index-image-pullspec: quay.io/operatorhubio/catalog:latest :index-image: catalog:latest -:registry-image: quay.io/openshift/origin-operator-registry:4.8.0 +:registry-image: quay.io/openshift/origin-operator-registry:4.9.0 :package1: couchdb-operator :package2: eclipse-che :package3: etcd @@ -16,14 +16,14 @@ ifndef::openshift-origin[] :catalog-name: redhat-operators :index-image-pullspec: registry.redhat.io/redhat/redhat-operator-index:v{product-version} :index-image: redhat-operator-index:v{product-version} -:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.8 +:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.9 :package1: advanced-cluster-management :package2: jaeger-product :package3: quay-operator endif::[] [id="olm-pruning-index-image_{context}"] -= Pruning an index image += Pruning a SQLite-based index image An index image, based on the Operator bundle format, is a containerized snapshot of an Operator catalog. You can prune an index of all but a specified list of packages, which creates a copy of the source index containing only the Operators that you want. @@ -40,7 +40,7 @@ ifeval::["{context}" != "olm-managing-custom-catalogs"] endif::[] * `podman` version 1.9.3+ * link:https://github.com/fullstorydev/grpcurl[`grpcurl`] -* `opm` version 1.12.3+ +* `opm` version 1.18.0+ * Access to a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] diff --git a/modules/olm-updating-index-image.adoc b/modules/olm-updating-index-image.adoc index 9cd4e073acc7..f2aa8acc2d5b 100644 --- a/modules/olm-updating-index-image.adoc +++ b/modules/olm-updating-index-image.adoc @@ -11,7 +11,7 @@ ifndef::openshift-origin[] endif::[] [id="olm-updating-index-image_{context}"] -= Updating an index image += Updating a SQLite-based index image After configuring OperatorHub to use a catalog source that references a custom index image, cluster administrators can keep the available Operators on their cluster up to date by adding bundle images to the index image. @@ -22,7 +22,7 @@ endif::[] .Prerequisites -* `opm` version 1.12.3+ +* `opm` version 1.18.0+ * `podman` version 1.9.3+ * An index image built and pushed to a registry. * An existing catalog source referencing the index image. diff --git a/modules/opm-cli-ref-index.adoc b/modules/opm-cli-ref-index.adoc new file mode 100644 index 000000000000..320c5b67afaf --- /dev/null +++ b/modules/opm-cli-ref-index.adoc @@ -0,0 +1,219 @@ +// Module included in the following assemblies: +// +// * cli_reference/opm/cli-opm-ref.adoc + +[id="opm-cli-ref-index_{context}"] += index + +Generate Operator index container images from pre-existing Operator bundles. + +.Command syntax +[source,terminal] +---- +$ opm index [] +---- + +.`index` subcommands +[options="header",cols="1,3"] +|=== +|Subcommand |Description + +|`add` +|Add Operator bundles to an index. + +|`prune` +|Prune an index of all but specified packages. + +|`prune-stranded` +|Prune an index of stranded bundles, which are bundles that are not associated with a particular image. + +|`rm` +|Delete an entire Operator from an index. + +|=== + +[id="opm-cli-ref-index-add_{context}"] +== add + +Add Operator bundles to an index. + +.Command syntax +[source,terminal] +---- +$ opm index add [] +---- + +.`index add` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-i`, `--binary-image` +|Container image for on-image `opm` command + +|`-u`, `--build-tool` (string) +|Tool to build container images: `podman` (the default value) or `docker`. Overrides part of the `--container-tool` flag. + +|`-b`, `--bundles` (strings) +|Comma-separated list of bundles to add. + +|`-c`, `--container-tool` (string) +|Tool to interact with container images, such as for saving and building: `docker` or `podman`. + +|`-f`, `--from-index` (string) +|Previous index to add to. + +|`--generate` +|If enabled, only creates the Dockerfile and saves it to local disk. + +|`--mode` (string) +|Graph update mode that defines how channel graphs are updated: `replaces` (the default value), `semver`, or `semver-skippatch`. + +|`-d`, `--out-dockerfile` (string) +|Optional: If generating the Dockerfile, specify a file name. + +|`--permissive` +|Allow registry load errors. + +|`-p`, `--pull-tool` (string) +|Tool to pull container images: `none` (the default value), `docker`, or `podman`. Overrides part of the `--container-tool` flag. + +|`-t`, `--tag` (string) +|Custom tag for container image being built. + +|=== + +[id="opm-cli-ref-index-prune_{context}"] +== prune + +Prune an index of all but specified packages. + +.Command syntax +[source,terminal] +---- +$ opm index prune [] +---- + +.`index prune` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-i`, `--binary-image` +|Container image for on-image `opm` command + +|`-c`, `--container-tool` (string) +|Tool to interact with container images, such as for saving and building: `docker` or `podman`. + +|`-f`, `--from-index` (string) +|Index to prune. + +|`--generate` +|If enabled, only creates the Dockerfile and saves it to local disk. + +|`-d`, `--out-dockerfile` (string) +|Optional: If generating the Dockerfile, specify a file name. + +|`-p`, `--packages` (strings) +|Comma-separated list of packages to keep. + +|`--permissive` +|Allow registry load errors. + +|`-t`, `--tag` (string) +|Custom tag for container image being built. + +|=== + +[id="opm-cli-ref-index-prune-stranded_{context}"] +== prune-stranded + +Prune an index of stranded bundles, which are bundles that are not associated with a particular image. + +.Command syntax +[source,terminal] +---- +$ opm index prune-stranded [] +---- + +.`index prune-stranded` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-i`, `--binary-image` +|Container image for on-image `opm` command + +|`-c`, `--container-tool` (string) +|Tool to interact with container images, such as for saving and building: `docker` or `podman`. + +|`-f`, `--from-index` (string) +|Index to prune. + +|`--generate` +|If enabled, only creates the Dockerfile and saves it to local disk. + +|`-d`, `--out-dockerfile` (string) +|Optional: If generating the Dockerfile, specify a file name. + +|`-p`, `--packages` (strings) +|Comma-separated list of packages to keep. + +|`--permissive` +|Allow registry load errors. + +|`-t`, `--tag` (string) +|Custom tag for container image being built. + +|=== + +[id="opm-cli-ref-index-rm_{context}"] +== rm + +Delete an entire Operator from an index. + +.Command syntax +[source,terminal] +---- +$ opm index rm [] +---- + +.`index rm` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-i`, `--binary-image` +|Container image for on-image `opm` command + +|`-u`, `--build-tool` (string) +|Tool to build container images: `podman` (the default value) or `docker`. Overrides part of the `--container-tool` flag. + +|`-c`, `--container-tool` (string) +|Tool to interact with container images, such as for saving and building: `docker` or `podman`. + +|`-f`, `--from-index` (string) +|Previous index to delete from. + +|`--generate` +|If enabled, only creates the Dockerfile and saves it to local disk. + +|`-o`, `--operators` (strings) +|Comma-separated list of Operators to delete. + +|`-d`, `--out-dockerfile` (string) +|Optional: If generating the Dockerfile, specify a file name. + +|`-p`, `--packages` (strings) +|Comma-separated list of packages to keep. + +|`--permissive` +|Allow registry load errors. + +|`-p`, `--pull-tool` (string) +|Tool to pull container images: `none` (the default value), `docker`, or `podman`. Overrides part of the `--container-tool` flag. + +|`-t`, `--tag` (string) +|Custom tag for container image being built. + +|=== diff --git a/modules/opm-cli-ref-init.adoc b/modules/opm-cli-ref-init.adoc new file mode 100644 index 000000000000..560f31b35329 --- /dev/null +++ b/modules/opm-cli-ref-init.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * cli_reference/opm/cli-opm-ref.adoc + +[id="opm-cli-ref-init_{context}"] += init + +Generate an `olm.package` declarative config blob. + +.Command syntax +[source,terminal] +---- +$ opm init [] +---- + +.`init` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-c`, `--default-channel` (string) +|The channel that subscriptions will default to if unspecified. + +|`-d`, `--description` (string) +|Path to the Operator's `README.md` or other documentation. + +|`-i`, `--icon` (string) +|Path to package's icon. + +|`-o`, `--output` (string) +|Output format: `json` (the default value) or `yaml`. + +|=== diff --git a/modules/opm-cli-ref-render.adoc b/modules/opm-cli-ref-render.adoc new file mode 100644 index 000000000000..f694ddbd461c --- /dev/null +++ b/modules/opm-cli-ref-render.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * cli_reference/opm/cli-opm-ref.adoc + +[id="opm-cli-ref-render_{context}"] += render + +Generate a declarative config blob from the provided index images, bundle images, and SQLite database files. + +.Command syntax +[source,terminal] +---- +$ opm render [] +---- + +.`render` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`-o`, `--output` (string) +|Output format: `json` (the default value) or `yaml`. + +|=== diff --git a/modules/opm-cli-ref-serve.adoc b/modules/opm-cli-ref-serve.adoc new file mode 100644 index 000000000000..4f79297564b0 --- /dev/null +++ b/modules/opm-cli-ref-serve.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * cli_reference/opm/cli-opm-ref.adoc + +[id="opm-cli-ref-server_{context}"] += serve + +Serve declarative configs via a GRPC server. + +[NOTE] +==== +The declarative config directory is loaded by the `serve` command at startup. Changes made to the declarative config after this command starts are not reflected in the served content. +==== + +.Command syntax +[source,terminal] +---- +$ opm serve [] +---- + +.`serve` flags +[options="header",cols="1,3"] +|=== +|Flag |Description + +|`--debug` +|Enable debug logging. + +|`-p`, `--port` (string) +|Port number to serve on. Default: `50051`. + +|`-t`, `--termination-log` (string) +|Path to a container termination log file. Default: `/dev/termination-log`. + +|=== diff --git a/modules/opm-cli-ref-validate.adoc b/modules/opm-cli-ref-validate.adoc new file mode 100644 index 000000000000..b23b45e14503 --- /dev/null +++ b/modules/opm-cli-ref-validate.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * cli_reference/opm/cli-opm-ref.adoc + +[id="opm-cli-ref-validate_{context}"] += validate + +Validate the declarative config JSON file(s) in a given directory. + +.Command syntax +[source,terminal] +---- +$ opm validate [] +---- diff --git a/modules/osdk-control-compat.adoc b/modules/osdk-control-compat.adoc index b376736c354c..15efc1f40be4 100644 --- a/modules/osdk-control-compat.adoc +++ b/modules/osdk-control-compat.adoc @@ -53,7 +53,7 @@ metadata: annotations: "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": ""}]' <1> ---- -<1> Specify the maximum cluster version of {product-title} that your Operator is compatible with. For example, setting `value` to `4.8` prevents cluster upgrades to {product-title} versions later than 4.8 when this bundle is installed on a cluster. +<1> Specify the maximum cluster version of {product-title} that your Operator is compatible with. For example, setting `value` to `4.9` prevents cluster upgrades to {product-title} versions later than 4.9 when this bundle is installed on a cluster. . If your bundle is intended for distribution in a Red Hat-provided Operator catalog, configure the compatible versions of {product-title} for your Operator by setting the following properties. This configuration ensures your Operator is only included in catalogs that target compatible versions of {product-title}: + @@ -67,7 +67,7 @@ This step is only valid when publishing Operators in Red Hat-provided catalogs. .Example `bundle/metadata/annotations.yaml` file with compatible versions [source,yaml] ---- -com.redhat.openshift.versions: "v4.6-v4.8" <1> +com.redhat.openshift.versions: "v4.7-v4.9" <1> ---- <1> Set to a range or single version. @@ -79,6 +79,6 @@ com.redhat.openshift.versions: "v4.6-v4.8" <1> ---- LABEL com.redhat.openshift.versions="" <1> ---- -<1> Set to a range or single version, for example, `v4.6-v4.8`. This setting defines the cluster versions where the Operator should be distributed, and the Operator does not appear in a catalog of a cluster version which is outside of the range. +<1> Set to a range or single version, for example, `v4.7-v4.9`. This setting defines the cluster versions where the Operator should be distributed, and the Operator does not appear in a catalog of a cluster version which is outside of the range. You can now bundle a new version of your Operator and publish the updated version to a catalog for distribution. diff --git a/operators/admin/olm-managing-custom-catalogs.adoc b/operators/admin/olm-managing-custom-catalogs.adoc index b0e8260cb626..06b4bf2a05bc 100644 --- a/operators/admin/olm-managing-custom-catalogs.adoc +++ b/operators/admin/olm-managing-custom-catalogs.adoc @@ -5,12 +5,7 @@ include::modules/common-attributes.adoc[] toc::[] -This guide describes how to work with custom catalogs for Operators packaged using the xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[bundle format] on Operator Lifecycle Manager (OLM) in {product-title}. - -[NOTE] -==== -Support for the legacy _package manifest format_ for Operators, including custom catalogs that were using the legacy format, is removed in {product-title} 4.8 and later. -==== +Cluster administrators and Operator catalog maintainers can create and managing custom catalogs packaged using the xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[bundle format] on Operator Lifecycle Manager (OLM) in {product-title}. [IMPORTANT] ==== @@ -26,18 +21,33 @@ If your cluster is using custom catalogs, see xref:../../operators/operator_sdk/ [id="olm-managing-custom-catalogs-bundle-format-prereqs"] == Prerequisites -* Install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. +* Install the xref:../../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[`opm` CLI]. + +[id="olm-managing-custom-catalogs-fb"] +== File-based catalogs + +_File-based catalogs_ are the latest iteration of the catalog format in Operator Lifecycle Manager (OLM). It is a plain text-based (JSON or YAML) and declarative config evolution of the earlier SQLite database format, and it is fully backwards compatible. + +For more details about the file-based catalog specification, see xref:../../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[Operator Framework packaging format]. + +include::modules/olm-creating-fb-catalog-image.adoc[leveloffset=+2] + +[id="olm-managing-custom-catalogs-sqlite"] +== SQLite-based catalogs + +:FeatureName: The SQLite database format for Operator catalogs +include::modules/deprecated-feature.adoc[leveloffset=+1] + +include::modules/olm-creating-index-image.adoc[leveloffset=+2] +include::modules/olm-updating-index-image.adoc[leveloffset=+2] +include::modules/olm-pruning-index-image.adoc[leveloffset=+2] -include::modules/olm-creating-index-image.adoc[leveloffset=+1] include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1] .Additional resources * See xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source] for more details on the `CatalogSource` object spec. * If your index image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]. -include::modules/olm-updating-index-image.adoc[leveloffset=+1] -include::modules/olm-pruning-index-image.adoc[leveloffset=+1] - include::modules/olm-accessing-images-private-registries.adoc[leveloffset=+1] .Additional resources diff --git a/operators/admin/olm-restricted-networks.adoc b/operators/admin/olm-restricted-networks.adoc index 2cbd9d287798..fed2aa3ae92c 100644 --- a/operators/admin/olm-restricted-networks.adoc +++ b/operators/admin/olm-restricted-networks.adoc @@ -40,7 +40,7 @@ link:https://access.redhat.com/articles/4740011[] == Prerequisites * Log in to your {product-title} cluster as a user with `cluster-admin` privileges. -* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. +* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[`opm` CLI]. [NOTE] ==== diff --git a/operators/operator_sdk/osdk-installing-cli.adoc b/operators/operator_sdk/osdk-installing-cli.adoc index 7e84f139cf60..108ea567d0ca 100644 --- a/operators/operator_sdk/osdk-installing-cli.adoc +++ b/operators/operator_sdk/osdk-installing-cli.adoc @@ -9,6 +9,8 @@ toc::[] The Operator SDK provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. You can install the Operator SDK CLI on your workstation so that you are prepared to start authoring your own Operators. +Operator authors with cluster administrator access to a Kubernetes-based cluster, such as {product-title}, can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. + [NOTE] ==== {product-title} {product-version} supports Operator SDK {osdk_ver}. diff --git a/operators/operator_sdk/osdk-pkgman-to-bundle.adoc b/operators/operator_sdk/osdk-pkgman-to-bundle.adoc index 1a07912b0f0f..32f4b12694a8 100644 --- a/operators/operator_sdk/osdk-pkgman-to-bundle.adoc +++ b/operators/operator_sdk/osdk-pkgman-to-bundle.adoc @@ -9,6 +9,6 @@ Support for the legacy _package manifest format_ for Operators is removed in {pr include::modules/osdk-about-pkg-format-migration.adoc[leveloffset=+1] .Additional resources -* xref:../../operators/understanding/olm-packaging-format.adoc#olm-packaging-format[Operator Framework packaging formats] +* xref:../../operators/understanding/olm-packaging-format.adoc#olm-packaging-format[Operator Framework packaging format] include::modules/osdk-migrating-pkgman.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-working-bundle-images.adoc b/operators/operator_sdk/osdk-working-bundle-images.adoc index 7e6430c20e27..b10017621f63 100644 --- a/operators/operator_sdk/osdk-working-bundle-images.adoc +++ b/operators/operator_sdk/osdk-working-bundle-images.adoc @@ -29,6 +29,6 @@ include::modules/osdk-control-compat.adoc[leveloffset=+1] [id="osdk-working-bundle-images-additional-resources"] == Additional resources -* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for details on the bundle format. +* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging format] for details on the bundle format. * See xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs[Managing custom catalogs] for details on adding bundle images to index images by using the `opm` command. * See xref:../../operators/understanding/olm/olm-workflow.adoc#olm-workflow[Operator Lifecycle Manager workflow] for details on how upgrades work for installed Operators. diff --git a/operators/understanding/olm-packaging-format.adoc b/operators/understanding/olm-packaging-format.adoc index 8c501912c185..c32c89cf3478 100644 --- a/operators/understanding/olm-packaging-format.adoc +++ b/operators/understanding/olm-packaging-format.adoc @@ -1,5 +1,5 @@ [id="olm-packaging-format"] -= Operator Framework packaging formats += Operator Framework packaging format include::modules/common-attributes.adoc[] :context: olm-packaging-format @@ -19,7 +19,7 @@ include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+2] * xref:../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-understanding-dependency-resolution[Operator Lifecycle Manager dependency resolution] include::modules/olm-about-opm.adoc[leveloffset=+2] -* See xref:../../cli_reference/opm-cli.adoc#opm-cli[CLI tools] for steps on installing the `opm` CLI. +* See xref:../../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[CLI tools] for steps on installing the `opm` CLI. ifdef::openshift-origin[] [id="olm-packaging-format-addtl-resources"] @@ -34,3 +34,19 @@ See the project *Releases* page for `opm` CLI downloads: - link:https://github.com/operator-framework/operator-registry/releases[Releases] endif::[] + +include::modules/olm-fb-catalogs.adoc[leveloffset=+1] +include::modules/olm-fb-catalogs-structure.adoc[leveloffset=+2] +include::modules/olm-fb-catalogs-schemas.adoc[leveloffset=+2] +include::modules/olm-fb-catalogs-prop.adoc[leveloffset=+2] +include::modules/olm-fb-catalogs-example.adoc[leveloffset=+2] +include::modules/olm-fb-catalogs-guidelines.adoc[leveloffset=+2] + +[id="olm-fb-catalogs-cli"] +=== CLI usage + +For instructions about creating file-based catalogs by using the `opm` CLI, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-creating-fb-catalog-image_olm-managing-custom-catalogs[Managing custom catalogs]. + +For reference documentation about the `opm` CLI commands related to managing file-based catalogs, see xref:../../cli_reference/opm/cli-opm-ref.adoc#cli-opm-ref[CLI tools]. + +include::modules/olm-fb-catalogs-automation.adoc[leveloffset=+2]