diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78a858d25..dbd4508d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,15 +7,16 @@ Operator Controller is an Apache 2.0 licensed project and accepts contributions By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the -contribution. See the [DCO](DCO) file for details. +contribution. See the [DCO](https://github.com/operator-framework/operator-controller/blob/main/DCO) file for details. ## Overview Thank you for your interest in contributing to the Operator-Controller. -As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](github.com/operator-framework/operator-lifecycle-manager). +As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](https://github.com/operator-framework/operator-lifecycle-manager). The user experience captured in the OLM V1 PRD introduces many requirements that are best satisfied by a microservices architecture. The OLM V1 experience currently relies on two projects: + - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install. - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content. @@ -45,6 +46,7 @@ Please keep this workflow in mind as you read through the document. ## How are Milestones Designed? It's unreasonable to attempt to consider all of the design requirements laid out in the [OLM V1 PRD](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit) from the onset of the project. Instead, the community attempts to design Milestones with the following principles: + - Milestones are tightly scoped units of work, ideally lasting one to three weeks. - Milestones are derived from the OLM V1 PRD. - Milestones are "demo driven", meaning that a set of acceptance criteria is defined upfront and the milestone is done as soon as some member of the community can run the demo. @@ -52,7 +54,7 @@ It's unreasonable to attempt to consider all of the design requirements laid out This "demo driven" development model will allow us to collect user experience and regularly course correct based on user feedback. Subsequent milestone may revert features or change the user experience based on community feedback. -The project maintainer will create a [GitHub Discussion](github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion. +The project maintainer will create a [GitHub Discussion](https://github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion. ## Where are Operator Controller Milestones? @@ -67,6 +69,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec ## Submitting Issues Unsure where to submit an issue? + - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install. - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content. @@ -87,7 +90,7 @@ approach of changes. When contributing changes that require a new dependency, check whether it's feasible to directly vendor that code [without introducing a new dependency](https://go-proverbs.github.io/). -Currently, PRs require at least one approval from a operator-controller maintainer in order to get merged. +Currently, PRs require at least one approval from an operator-controller maintainer in order to get merged. ### Code style diff --git a/Makefile b/Makefile index 746fdfb6b..49a707b3c 100644 --- a/Makefile +++ b/Makefile @@ -312,17 +312,18 @@ quickstart: $(KUSTOMIZE) manifests #EXHELP Generate the installation release man OPERATOR_CONTROLLER_API_REFERENCE_FILENAME := operator-controller-api-reference.md CATALOGD_API_REFERENCE_FILENAME := catalogd-api-reference.md CATALOGD_TMP_DIR := $(ROOT_DIR)/.catalogd-tmp/ +API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents. - rm -f $(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME) + rm -f $(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME) $(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \ - --config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \ - --renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME); + --config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \ + --renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME); rm -rf $(CATALOGD_TMP_DIR) git clone --depth 1 --branch $(CATALOGD_VERSION) https://github.com/operator-framework/catalogd $(CATALOGD_TMP_DIR) - rm -f $(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME) + rm -f $(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME) $(CRD_REF_DOCS) --source-path=$(CATALOGD_TMP_DIR)/api \ - --config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \ - --renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME) + --config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \ + --renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME) rm -rf $(CATALOGD_TMP_DIR)/ VENVDIR := $(abspath docs/.venv) diff --git a/README.md b/README.md index 83aed5f0b..298d7098d 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ OLM v1 consists of two different components: * operator-controller (this repository) * [catalogd](https://github.com/operator-framework/catalogd) -For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/general/olmv1_design_decisions.md). +For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/project/olmv1_design_decisions.md). ## Getting Started -To get started with OLM v1, please see our [Getting Started](docs/general/olmv1_getting_started.md) documentation. +To get started with OLM v1, please see our [Getting Started](docs/getting-started/olmv1_getting_started.md) documentation. ## License diff --git a/docs/refs/api/catalogd-api-reference.md b/docs/api-reference/catalogd-api-reference.md similarity index 100% rename from docs/refs/api/catalogd-api-reference.md rename to docs/api-reference/catalogd-api-reference.md diff --git a/docs/refs/api/crd-ref-docs-gen-config.yaml b/docs/api-reference/crd-ref-docs-gen-config.yaml similarity index 100% rename from docs/refs/api/crd-ref-docs-gen-config.yaml rename to docs/api-reference/crd-ref-docs-gen-config.yaml diff --git a/docs/refs/api/operator-controller-api-reference.md b/docs/api-reference/operator-controller-api-reference.md similarity index 100% rename from docs/refs/api/operator-controller-api-reference.md rename to docs/api-reference/operator-controller-api-reference.md diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 000000000..3e62f8eb7 --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,98 @@ + + + + +logo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/refs/controlling-catalog-selection.md b/docs/concepts/controlling-catalog-selection.md similarity index 94% rename from docs/refs/controlling-catalog-selection.md rename to docs/concepts/controlling-catalog-selection.md index e91a1eb0f..544f36be5 100644 --- a/docs/refs/controlling-catalog-selection.md +++ b/docs/concepts/controlling-catalog-selection.md @@ -27,7 +27,7 @@ spec: catalog: selector: matchLabels: - olm.operatorframework.io/metadata.name: my-catalog + olm.operatorframework.io/metadata.name: my-content-management ``` In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`. @@ -93,7 +93,7 @@ spec: - key: olm.operatorframework.io/metadata.name operator: NotIn values: - - unwanted-catalog + - unwanted-content-management ``` This excludes the catalog named `unwanted-catalog` from consideration. @@ -134,7 +134,7 @@ spec: source: type: image image: - ref: quay.io/example/high-priority-catalog:latest + ref: quay.io/example/high-priority-content-management:latest ``` Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution. @@ -171,7 +171,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera source: type: image image: - ref: quay.io/example/catalog-a:latest + ref: quay.io/example/content-management-a:latest ``` ```yaml @@ -186,7 +186,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera source: type: image image: - ref: quay.io/example/catalog-b:latest + ref: quay.io/example/content-management-b:latest ``` NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied @@ -209,8 +209,8 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera 3. **Apply the Resources** ```shell - kubectl apply -f catalog-a.yaml - kubectl apply -f catalog-b.yaml + kubectl apply -f content-management-a.yaml + kubectl apply -f content-management-b.yaml kubectl apply -f install-my-operator.yaml ``` diff --git a/docs/refs/crd-upgrade-safety.md b/docs/concepts/crd-upgrade-safety.md similarity index 100% rename from docs/refs/crd-upgrade-safety.md rename to docs/concepts/crd-upgrade-safety.md diff --git a/docs/refs/single-owner-objects.md b/docs/concepts/single-owner-objects.md similarity index 100% rename from docs/refs/single-owner-objects.md rename to docs/concepts/single-owner-objects.md index 0ed7dfcac..0553f70a8 100644 --- a/docs/refs/single-owner-objects.md +++ b/docs/concepts/single-owner-objects.md @@ -1,4 +1,3 @@ - # OLM Ownership Enforcement for `ClusterExtensions` In OLM, **a Kubernetes resource can only be owned by a single `ClusterExtension` at a time**. This ensures that resources within a Kubernetes cluster are managed consistently and prevents conflicts between multiple `ClusterExtensions` attempting to control the same resource. @@ -15,6 +14,7 @@ Operator bundles provide `CustomResourceDefinitions` (CRDs), which are part of a ### 2. `ClusterExtensions` Cannot Share Objects + OLM's single-owner policy means that **`ClusterExtensions` cannot share ownership of any resources**. If one `ClusterExtension` manages a specific resource (e.g., a `Deployment`, `CustomResourceDefinition`, or `Service`), another `ClusterExtension` cannot claim ownership of the same resource. Any attempt to do so will be blocked by the system. ## Error Messages diff --git a/docs/tasks/upgrade/upgrade-support.md b/docs/concepts/upgrade-support.md similarity index 99% rename from docs/tasks/upgrade/upgrade-support.md rename to docs/concepts/upgrade-support.md index 367a57ec1..9bc6e31ad 100644 --- a/docs/tasks/upgrade/upgrade-support.md +++ b/docs/concepts/upgrade-support.md @@ -1,3 +1,8 @@ +--- +hide: + - toc +--- + # Upgrade support This document explains how OLM v1 handles upgrades. diff --git a/docs/refs/version-ranges.md b/docs/concepts/version-ranges.md similarity index 98% rename from docs/refs/version-ranges.md rename to docs/concepts/version-ranges.md index d247cc19f..75e88f04e 100644 --- a/docs/refs/version-ranges.md +++ b/docs/concepts/version-ranges.md @@ -4,7 +4,7 @@ This document explains how to specify a version range to install or update an ex You define a version range in a ClusterExtension's custom resource (CR) file. -## Specifying a version range in the CR +### Specifying a version range in the CR If you specify a version range in the ClusterExtension's CR, OLM 1.0 installs or updates the latest version of the extension that can be resolved within the version range. The resolved version is the latest version of the extension that satisfies the dependencies and constraints of the extension and the environment. diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md new file mode 120000 index 000000000..f939e75f2 --- /dev/null +++ b/docs/contribute/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/general/developer.md b/docs/contribute/developer.md similarity index 98% rename from docs/general/developer.md rename to docs/contribute/developer.md index 31959de6c..b97c9d693 100644 --- a/docs/general/developer.md +++ b/docs/contribute/developer.md @@ -177,4 +177,4 @@ done ## Contributing -Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information. +Refer to [CONTRIBUTING.md](contributing.md) for more information. diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 000000000..a19687adc --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,7 @@ +/*.md-nav__title {*/ +/* visibility: hidden;*/ +/*}*/ + +.md-header__title { + visibility: hidden; +} diff --git a/docs/drafts/create-installer-service-account.md b/docs/drafts/create-installer-service-account.md deleted file mode 100644 index e66c06076..000000000 --- a/docs/drafts/create-installer-service-account.md +++ /dev/null @@ -1,3 +0,0 @@ -# Create Installer Service Account - -Placeholder. We need to document this. \ No newline at end of file diff --git a/docs/drafts/olmv1-limitations.md b/docs/drafts/olmv1-limitations.md deleted file mode 100644 index 1c351f9e9..000000000 --- a/docs/drafts/olmv1-limitations.md +++ /dev/null @@ -1,3 +0,0 @@ -# Current OLM v1 Limitations - -Placeholder. We need to document this. \ No newline at end of file diff --git a/docs/drafts/support-watchNamespaces.md b/docs/drafts/support-watchNamespaces.md deleted file mode 100644 index b10c279cc..000000000 --- a/docs/drafts/support-watchNamespaces.md +++ /dev/null @@ -1,24 +0,0 @@ -# Install Modes and WatchNamespaces in OMLv1 - -Operator Lifecycle Manager (OLM) operates with cluster-admin privileges, enabling it to grant necessary permissions to the Extensions it deploys. For extensions packaged as [`RegistryV1`][registryv1] bundles, it's the responsibility of the authors to specify supported `InstallModes` in the ClusterServiceVersion ([CSV][csv]). InstallModes define the operational scope of the extension within the Kubernetes cluster, particularly in terms of namespace availability. The four recognized InstallModes are as follows: - -1. OwnNamespace: This mode allows the extension to monitor and respond to events within its own deployment namespace. -1. SingleNamespace: In this mode, the extension is set up to observe events in a single, specific namespace other than the one it is deployed in. -1. MultiNamespace: This enables the extension to function across multiple specified namespaces. -1. AllNamespaces: Under this mode, the extension is equipped to monitor events across all namespaces within the cluster. - -When creating a cluster extension, users have the option to define a list of `watchNamespaces`. This list determines the specific namespaces within which they intend the operator to operate. The configuration of `watchNamespaces` must align with the InstallModes supported by the extension as specified by the bundle author. The supported configurations in the order of preference are as follows: - - -| Length of `watchNamespaces` specified through ClusterExtension | Allowed values | Supported InstallMode in CSV | Description | -|------------------------------|-------------------------------------------------------|----------------------|-----------------------------------------------------------------| -| **0 (Empty/Unset)** | - | AllNamespaces | Extension monitors all namespaces. | -| | - | OwnNamespace | Supported when `AllNamespaces` is false. Extension only active in its deployment namespace. | -| **1 (Single Entry)** | `""` (Empty String) | AllNamespaces | Extension monitors all namespaces. | -| | Entry equals Install Namespace | OwnNamespace | Extension watches only its install namespace. | -| | Entry is a specific namespace (not the Install Namespace) | SingleNamespace | Extension monitors a single, specified namespace in the spec. | -| **>1 (Multiple Entries)** | Entries are specific, multiple namespaces | MultiNamespace | Extension monitors each of the specified multiple namespaces in the spec. - - -[registryv1]: https://olm.operatorframework.io/docs/tasks/creating-operator-manifests/#writing-your-operator-manifests -[csv]: https://olm.operatorframework.io/docs/concepts/crds/clusterserviceversion/ \ No newline at end of file diff --git a/docs/general/olmv1_getting_started.md b/docs/getting-started/olmv1_getting_started.md similarity index 84% rename from docs/general/olmv1_getting_started.md rename to docs/getting-started/olmv1_getting_started.md index 3f05620b6..77760f4fc 100644 --- a/docs/general/olmv1_getting_started.md +++ b/docs/getting-started/olmv1_getting_started.md @@ -1,5 +1,3 @@ -# Getting Started with OLM v1 - ### Installation The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind). @@ -14,7 +12,7 @@ The latest version of Operator Controller can be installed with the following co curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s ``` -## Getting Started with OLM v1 +### Getting Started with OLM v1 This quickstart procedure will guide you through the following processes: @@ -26,11 +24,11 @@ This quickstart procedure will guide you through the following processes: OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format. These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs -can be found [here](./docs/Tasks/adding-a-catalog). +can be found [here](../tutorials/add-catalog.md). The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages -will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md). +will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](../howto/catalog-queries.md). To create the catalog, run the following command: @@ -62,7 +60,7 @@ kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeou For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator. The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install. -More information on installing extensions can be found [here](docs/Tasks/installing-an-extension). +More information on installing extensions can be found [here](../tutorials/install-extension.md). ```bash # Apply the sample ClusterExtension. Manifest already includes @@ -74,29 +72,29 @@ kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-c To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that there must be CRD compatibility between the versions being upgraded, and the target version must be -compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), -compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), -and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension). +compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md), +compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md), +and on the extension upgrade process [here](../tutorials/upgrade-extension.md). ```bash # Update to v0.11.0 -kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}' +kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}' ``` -For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md). +For information on the downgrade process, see [here](../tutorials/downgrade-extension.md). ### Uninstall the Cluster Extension To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will -remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension). +remove all resources created by the extension. More information on uninstalling extensions can be found [here](../tutorials/uninstall-extension.md). ```bash # Delete cluster extension and residing namespace kubectl delete clusterextension/argocd ``` -#### Cleanup +### Cleanup Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the extension is uninstalled, these resources can be cleaned up. diff --git a/docs/refs/catalog-queries.md b/docs/howto/catalog-queries.md similarity index 99% rename from docs/refs/catalog-queries.md rename to docs/howto/catalog-queries.md index fda87987e..7a25863ec 100644 --- a/docs/refs/catalog-queries.md +++ b/docs/howto/catalog-queries.md @@ -10,8 +10,6 @@ You can use the `curl` command with `jq` to query catalogs that are installed on curl -k https://localhost:8443/catalogs/operatorhubio/all.json | ``` - - ## Package queries Available packages in a catalog diff --git a/docs/drafts/derive-serviceaccount.md b/docs/howto/derive-service-account.md similarity index 96% rename from docs/drafts/derive-serviceaccount.md rename to docs/howto/derive-service-account.md index fec1649df..599fc103a 100644 --- a/docs/drafts/derive-serviceaccount.md +++ b/docs/howto/derive-service-account.md @@ -1,7 +1,7 @@ # Derive minimal ServiceAccount required for ClusterExtension Installation and Management -OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../refs/supported-extensions.md), -OLM must be provided a ServiceAccount configured with the appropriate permissions. For more information, see the [provided ServiceAccount](./provided-serviceaccount.md) documentation. +OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../project/olmv1_limitations.md), +OLM must be provided a ServiceAccount configured with the appropriate permissions. This document serves as a guide for how to derive the RBAC necessary to install a bundle. @@ -12,6 +12,7 @@ This bundle image contains all the manifests that make up the extension (e.g. `C as well as a [`ClusterServiceVersion`](https://olm.operatorframework.io/docs/concepts/crds/clusterserviceversion/) (CSV) that describes the extension and its service account's permission requirements. The service account must have permissions to: + - create and manage the extension's `CustomResourceDefinition`s - create and manage the resources packaged in the bundle - grant the extension controller's service account the permissions it requires for its operation @@ -30,7 +31,7 @@ Depending on the scope, each permission will need to be added to either a `Clust ### Example The following example illustrates the process of deriving the minimal RBAC required to install the [ArgoCD Operator](https://operatorhub.io/operator/argocd-operator) [v0.6.0](https://operatorhub.io/operator/argocd-operator/alpha/argocd-operator.v0.6.0) provided by [OperatorHub.io](https://operatorhub.io/). -The final permission set can be found in the [ClusterExtension sample manifest](../../config/samples/olm_v1alpha1_clusterextension.yaml) in the [samples](../../config/samples/olm_v1alpha1_clusterextension.yaml) directory. +The final permission set can be found in the [ClusterExtension sample manifest](https://github.com/operator-framework/operator-controller/blob/main/config/samples/olm_v1alpha1_clusterextension.yaml) in the [samples](https://github.com/operator-framework/operator-controller/blob/main/config/samples/olm_v1alpha1_clusterextension.yaml) directory. The bundle includes the following manifests, which can be found [here](https://github.com/argoproj-labs/argocd-operator/tree/da6b8a7e68f71920de9545152714b9066990fc4b/deploy/olm-catalog/argocd-operator/0.6.0): @@ -301,7 +302,7 @@ Once the installer service account required cluster-scoped and namespace-scoped 6. Create the `RoleBinding` between the installer service account and its role 7. Create the `ClusterExtension` -A manifest with the full set of resources can be found [here](../../config/samples/olm_v1alpha1_clusterextension.yaml). +A manifest with the full set of resources can be found [here](https://github.com/operator-framework/operator-controller/blob/main/config/samples/olm_v1alpha1_clusterextension.yaml). ### Alternatives @@ -346,6 +347,6 @@ kubectl create clusterrolebinding my-cluster-extension-installer-role-binding \ #### hack/tools/catalog In the spirit of making this process more tenable until the proper tools are in place, the scripts -in [hack/tools/catalogs](../../hack/tools/catalogs) were created to help the user navigate and search catalogs as well +in [hack/tools/catalogs](https://github.com/operator-framework/operator-controller/blob/main/hack/tools/catalogs) were created to help the user navigate and search catalogs as well as to generate the minimal RBAC requirements. These tools are offered as is, with no guarantees on their correctness, support, or maintenance. For more information, see [Hack Catalog Tools](https://github.com/operator-framework/operator-controller/blob/main/hack/tools/catalogs/README.md). \ No newline at end of file diff --git a/docs/tasks/upgrade/how-to-channel-based-upgrades.md b/docs/howto/how-to-channel-based-upgrades.md similarity index 96% rename from docs/tasks/upgrade/how-to-channel-based-upgrades.md rename to docs/howto/how-to-channel-based-upgrades.md index f1692422f..501a7f951 100644 --- a/docs/tasks/upgrade/how-to-channel-based-upgrades.md +++ b/docs/howto/how-to-channel-based-upgrades.md @@ -1,4 +1,4 @@ -## How-to: Channel-Based Automatic Upgrades +# Channel-Based Automatic Upgrades A "channel" is a package author defined stream of updates for an extension. A set of channels can be set in the Catalog source to restrict automatic updates to the set of versions defined in those channels. diff --git a/docs/tasks/upgrade/how-to-pin-version.md b/docs/howto/how-to-pin-version.md similarity index 86% rename from docs/tasks/upgrade/how-to-pin-version.md rename to docs/howto/how-to-pin-version.md index 5ba1c39db..606b994aa 100644 --- a/docs/tasks/upgrade/how-to-pin-version.md +++ b/docs/howto/how-to-pin-version.md @@ -1,4 +1,4 @@ -## How-to: Version Pin and Disable Automatic Updates +# Pin Version and Disable Automatic Updates To disable automatic updates, and pin the version of an extension, set `version` in the Catalog source to a specific version (e.g. 1.2.3). @@ -21,4 +21,4 @@ spec: name: argocd-installer ``` -For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md) +For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md) diff --git a/docs/tasks/upgrade/how-to-version-range-upgrades.md b/docs/howto/how-to-version-range-upgrades.md similarity index 90% rename from docs/tasks/upgrade/how-to-version-range-upgrades.md rename to docs/howto/how-to-version-range-upgrades.md index 15bef4a9c..ddb753fba 100644 --- a/docs/tasks/upgrade/how-to-version-range-upgrades.md +++ b/docs/howto/how-to-version-range-upgrades.md @@ -1,4 +1,4 @@ -## How-to: Version Range Automatic Updates +# Version Range Automatic Updates Set the version for the desired package in the Catalog source to a comparison string, like `">=3.0, <3.6"`, to restrict the automatic updates to the version range. Any new version of the extension released in the catalog within this range will be automatically applied. @@ -21,4 +21,4 @@ spec: name: argocd-installer ``` -For more information on SemVer version ranges see [version-rages](../../refs/version-ranges.md) \ No newline at end of file +For more information on SemVer version ranges see [version-rages](../concepts/version-ranges.md) \ No newline at end of file diff --git a/docs/tasks/upgrade/how-to-z-stream-upgrades.md b/docs/howto/how-to-z-stream-upgrades.md similarity index 89% rename from docs/tasks/upgrade/how-to-z-stream-upgrades.md rename to docs/howto/how-to-z-stream-upgrades.md index deeef2fc9..8666e09b7 100644 --- a/docs/tasks/upgrade/how-to-z-stream-upgrades.md +++ b/docs/howto/how-to-z-stream-upgrades.md @@ -1,4 +1,4 @@ -## How-to: Z-Stream Automatic Updates +# Z-Stream Automatic Updates To restrict automatic updates to only z-stream patches and avoid breaking changes, use the `"~"` version range operator when setting the version for the desired package in Catalog source. @@ -21,4 +21,4 @@ spec: name: argocd-installer ``` -For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md) +For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md) diff --git a/docs/general/olmv1_overview.md b/docs/index.md similarity index 57% rename from docs/general/olmv1_overview.md rename to docs/index.md index ca3928973..942cdd938 100644 --- a/docs/general/olmv1_overview.md +++ b/docs/index.md @@ -1,15 +1,18 @@ -# Overview +--- +hide: + - toc +--- -## What is Operator Lifecycle Manager (OLM)? +# Overview -Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the -lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing, +Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the +lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing, running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster administrators and PaaS administrators. -Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.). +Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.). Operators are a method of packaging, deploying, and managing a Kubernetes application. An Operator is composed of one or more controllers paired with one or both of the following objects: -* One or more API extensions +* One or more API extensions * One or more [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRDs). OLM helped define lifecycles for these extensions: from packaging and distribution to installation, configuration, upgrade, and removal. @@ -26,9 +29,10 @@ is a popular destination for discovering Operators, and boasts over 300 packages ## Why are we building OLM v1? -OLM v0 has been in production for over 5 years, and the community to leverage this experience and question the initial -goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience. -Compared to its predecessor, amongst other things, OLM v1 aims to provide: +The Operator Lifecycle Manager (OLM) has been in production for over five years, serving as a critical component in managing Kubernetes Operators. +Over this time, the community has gathered valuable insights from real-world usage, identifying both the strengths and limitations of the initial design, +and validating the design's initial assumptions. This process led to a complete redesign and rewrite of OLM that, compared to its predecessor, aims to +provide: * A simpler API surface and mental model * Less opinionated automation and greater flexibility @@ -37,19 +41,5 @@ Compared to its predecessor, amongst other things, OLM v1 aims to provide: * Helm Chart support * GitOps support -To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](olmv1_design_decisions.md) -and our feature [Roadmap](olmv1_roadmap.md). - -## The OLM community - -In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors. -The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/), -which provides a great entry point to quickly find something interesting to work on and contribute. - -You can reach out to the OLM community for feedbacks/discussions/contributions in the following channels: - - * Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev) - * [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework) - * Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) - -For further information on contributing, please consult the [Contribution Guide](../../CONTRIBUTING.md) +To learn more about where v1 one came from, and where it's going, please see [Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](project/olmv1_design_decisions.md) +and our feature [Roadmap](project/olmv1_roadmap.md). diff --git a/docs/general/architecture.md b/docs/project/olmv1_architecture.md similarity index 98% rename from docs/general/architecture.md rename to docs/project/olmv1_architecture.md index 5be36f9af..1672fae64 100644 --- a/docs/general/architecture.md +++ b/docs/project/olmv1_architecture.md @@ -1,5 +1,9 @@ +--- +hide: + - toc +--- -## OLM V1 Architecture +# OLM V1 Architecture This document describes the OLM v1 architecture. OLM v1 consists of two main components: @@ -54,6 +58,7 @@ flowchart TB ### Operator-controller: operator-controller is the central component of OLM v1. It is responsible: + * managing a cache of catalog metadata provided by catalogd through its HTTP server * keeping the catalog metadata cache up-to-date with the current state of the catalogs * locating the right `registry+v1` bundle, if any, that meet the constraints expressed in the `ClusterExtension` resource, such as package name, version range, channel, etc. given the current state of the cluster @@ -61,6 +66,7 @@ operator-controller is the central component of OLM v1. It is responsible: * applying the bundle manifests: installing or updating the content. It has three main sub-components: + * Cluster Extension Controller: * Queries the catalogd (catalogd HTTP Server) to get catalog information. * Once received the catalog information is saved to catalog-cache. The cache will be updated automatically if a Catalog is noticed to have a different resolved image reference. diff --git a/docs/project/olmv1_community.md b/docs/project/olmv1_community.md new file mode 100644 index 000000000..55e8cf1b8 --- /dev/null +++ b/docs/project/olmv1_community.md @@ -0,0 +1,15 @@ + +OLM is an open-source [CNCF](https://www.cncf.io/) project with a friendly and supportive community of developers, testers, + and documentation experts with a passion for Kubernetes. + +Through the effort of redesigning OLM, the community also took the opportunity to make the project more accessible, +and contributor-friendly through its weekly meetings, continuous planning, and a [GitHub project](https://github.com/orgs/operator-framework/projects/8/) + tracker that provides a convenient entry point to quickly find something interesting to work on and contribute. + +You can reach out to the OLM community for feedbacks/discussions/contributions in the following channels: + +* Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev) +* [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework) +* Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) + +For further information on contributing, please consult the [Contribution Guide](../contribute/contributing.md) \ No newline at end of file diff --git a/docs/general/olmv1_design_decisions.md b/docs/project/olmv1_design_decisions.md similarity index 99% rename from docs/general/olmv1_design_decisions.md rename to docs/project/olmv1_design_decisions.md index 79ec098fa..f8017455d 100644 --- a/docs/general/olmv1_design_decisions.md +++ b/docs/project/olmv1_design_decisions.md @@ -1,4 +1,4 @@ -# The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts +# Multi-Tenancy Challenges, Lessons Learned, and Design Shifts This provides historical context on the design explorations and challenges that led to substantial design shifts between OLM v1 and its predecessor. It explains the technical reasons why OLM v1 cannot support major v0 features, such as, diff --git a/docs/refs/supported-extensions.md b/docs/project/olmv1_limitations.md similarity index 85% rename from docs/refs/supported-extensions.md rename to docs/project/olmv1_limitations.md index 8a1e97c02..172d8cbb5 100644 --- a/docs/refs/supported-extensions.md +++ b/docs/project/olmv1_limitations.md @@ -1,8 +1,15 @@ +--- +hide: + - toc +--- + +## OLM v0 Extension Support + Currently, OLM v1 supports installing cluster extensions that meet the following criteria: * The extension must support installation via the `AllNamespaces` install mode. * The extension must not use webhooks. -* The extension must not declare dependencies using the any of following file-based catalog properties: +* The extension must not declare dependencies using any of the following file-based catalog properties: * `olm.gvk.required` * `olm.package.required` diff --git a/docs/general/olmv1_roadmap.md b/docs/project/olmv1_roadmap.md similarity index 99% rename from docs/general/olmv1_roadmap.md rename to docs/project/olmv1_roadmap.md index 23bcc5d96..5a0542a3e 100644 --- a/docs/general/olmv1_roadmap.md +++ b/docs/project/olmv1_roadmap.md @@ -1,7 +1,6 @@ --- -title: Product Requriement Doc -layout: default -nav_order: 2 +hide: + - toc --- # OLM v1 roadmap diff --git a/docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md b/docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md deleted file mode 100644 index d283869f8..000000000 --- a/docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md +++ /dev/null @@ -1,13 +0,0 @@ -# Configuring a service account when the cluster uses the `OwnerReferencesPermissionEnforcement` admission plugin - -The [`OwnerReferencesPermissionEnforcement`](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#ownerreferencespermissionenforcement) admission plugin requires a user to have permission to set finalizers on owner objects when creating or updating an object to contain an `ownerReference` with `blockOwnerDeletion: true`. - -When operator-controller installs or upgrades a `ClusterExtension`, it sets an `ownerReference` on each object with `blockOwnerDeletion: true`. Therefore, serviceaccounts configured in `.spec.serviceAccount.name` must have the following permission in a bound `ClusterRole`: - - ```yaml - - apiGroups: ["olm.operatorframework.io"] - resources: ["clusterextensions/finalizers"] - verbs: ["update"] - resourceNames: [""] - ``` - diff --git a/docs/tasks/installation/provided-serviceaccount.md b/docs/tasks/installation/provided-serviceaccount.md deleted file mode 100644 index 33f4501e9..000000000 --- a/docs/tasks/installation/provided-serviceaccount.md +++ /dev/null @@ -1,31 +0,0 @@ -# Provided ServiceAccount for ClusterExtension Installation and Management - -Adhering to OLM v1's "Secure by Default" tenet, OLM v1 does not have the permissions -necessary to install content. This follows the least privilege principle and reduces -the chance of a [confused deputy attack](https://en.wikipedia.org/wiki/Confused_deputy_problem). -Instead, users must explicitly specify a ServiceAccount that will be used to perform the -installation and management of a specific ClusterExtension. The ServiceAccount is specified -in the ClusterExtension manifest as follows: - -```yaml -apiVersion: olm.operatorframework.io/v1alpha1 -kind: ClusterExtension -metadata: - name: argocd -spec: - source: - sourceType: Catalog - catalog: - packageName: argocd-operator - version: 0.6.0 - install: - namespace: argocd - serviceAccount: - name: argocd-installer -``` - -The ServiceAccount must be configured with the RBAC permissions required by the ClusterExtension. -If the permissions do not meet the minimum requirements, installation will fail. If no ServiceAccount -is provided in the ClusterExtension manifest, then the manifest will be rejected. - -//TODO: Add link to documentation on determining least privileges required for the ServiceAccount \ No newline at end of file diff --git a/docs/tasks/catalog/adding-a-catalog.md b/docs/tutorials/add-catalog.md similarity index 98% rename from docs/tasks/catalog/adding-a-catalog.md rename to docs/tutorials/add-catalog.md index 8158f0d4a..c0961d561 100644 --- a/docs/tasks/catalog/adding-a-catalog.md +++ b/docs/tutorials/add-catalog.md @@ -1,4 +1,9 @@ -# Adding a catalog of extensions to a cluster +--- +hide: + - toc +--- + +# Add a Catalog of Extensions to a Cluster Extension authors can publish their products in catalogs. ClusterCatalogs are curated collections of Kubernetes extensions, such as Operators. diff --git a/docs/tasks/downgrade/downgrading-an-extension.md b/docs/tutorials/downgrade-extension.md similarity index 99% rename from docs/tasks/downgrade/downgrading-an-extension.md rename to docs/tutorials/downgrade-extension.md index c372ce8e2..0e57d4687 100644 --- a/docs/tasks/downgrade/downgrading-an-extension.md +++ b/docs/tutorials/downgrade-extension.md @@ -1,3 +1,7 @@ +--- +hide: + - toc +--- # Downgrade a ClusterExtension diff --git a/docs/refs/exploring-available-packages.md b/docs/tutorials/explore-available-content.md similarity index 96% rename from docs/refs/exploring-available-packages.md rename to docs/tutorials/explore-available-content.md index 6b3071001..2364501c1 100644 --- a/docs/refs/exploring-available-packages.md +++ b/docs/tutorials/explore-available-content.md @@ -1,6 +1,11 @@ -# Exploring Available Packages +--- +hide: + - toc +--- -After you add a catalog of extensions to your cluster, you must port forward your catalog as a service. +# Explore Available Content + +After you [add a catalog of extensions](add-catalog.md) to your cluster, you must port forward your catalog as a service. Then you can query the catalog by using `curl` commands and the `jq` CLI tool to find extensions to install. ## Prerequisites @@ -143,4 +148,4 @@ The following examples will show this default behavior, but for simplicity's sak ### Additional resources -* [Catalog queries](catalog-queries.md) +* [Catalog queries](../howto/catalog-queries.md) diff --git a/docs/tasks/installation/installing-an-extension.md b/docs/tutorials/install-extension.md similarity index 80% rename from docs/tasks/installation/installing-an-extension.md rename to docs/tutorials/install-extension.md index 1a0e956cf..ffd28519f 100644 --- a/docs/tasks/installation/installing-an-extension.md +++ b/docs/tutorials/install-extension.md @@ -1,4 +1,9 @@ -# Installing an extension from a catalog +--- +hide: + - toc +--- + +# Install an Extension from a Catalog In Operator Lifecycle Manager (OLM) 1.0, Kubernetes extensions are scoped to the cluster. After you add a catalog to your cluster, you can install an extension by creating a custom resource (CR) and applying it. @@ -6,9 +11,22 @@ After you add a catalog to your cluster, you can install an extension by creatin ## Prerequisites * A deployed and unpacked catalog -* The name, and optionally version, or channel, of the [supported extension](../concepts/supported-extensions.md) to be installed +* The name, and optionally version, or channel, of the [supported extension](../project/olmv1_limitations.md) to be installed * An existing namespace in which to install the extension -* A suitable service account for installation (more information can be found [here](../../drafts/create-installer-service-account.md)) + +### ServiceAccount for ClusterExtension Installation and Management + +Adhering to OLM v1's "Secure by Default" tenet, OLM v1 does not have the permissions +necessary to install content. This follows the least privilege principle and reduces +the chance of a [confused deputy attack](https://en.wikipedia.org/wiki/Confused_deputy_problem). +Instead, users must explicitly specify a ServiceAccount that will be used to perform the +installation and management of a specific ClusterExtension. + +The ServiceAccount must be configured with the RBAC permissions required by the ClusterExtension. +If the permissions do not meet the minimum requirements, installation will fail. If no ServiceAccount +is provided in the ClusterExtension manifest, then the manifest will be rejected. + +For information on determining the ServiceAccount's permission, please see [Derive minimal ServiceAccount required for ClusterExtension Installation and Management](../howto/derive-service-account.md). ## Procedure diff --git a/docs/tasks/uninstallation/uninstalling-an-extension.md b/docs/tutorials/uninstall-extension.md similarity index 94% rename from docs/tasks/uninstallation/uninstalling-an-extension.md rename to docs/tutorials/uninstall-extension.md index 575a7602a..3d20442a8 100644 --- a/docs/tasks/uninstallation/uninstalling-an-extension.md +++ b/docs/tutorials/uninstall-extension.md @@ -1,4 +1,9 @@ -# Deleting an extension +--- +hide: + - toc +--- + +# Uninstall an extension You can uninstall a Kubernetes extension and its associated custom resource definitions (CRD) by deleting the extension's custom resource (CR). diff --git a/docs/tasks/upgrade/upgrading-an-extension.md b/docs/tutorials/upgrade-extension.md similarity index 94% rename from docs/tasks/upgrade/upgrading-an-extension.md rename to docs/tutorials/upgrade-extension.md index 481a083d4..e55a53f96 100644 --- a/docs/tasks/upgrade/upgrading-an-extension.md +++ b/docs/tutorials/upgrade-extension.md @@ -1,17 +1,22 @@ -# Upgrading an Extension +--- +hide: + - toc +--- + +# Upgrade an Extension Existing extensions can be upgraded by updating the version field in the ClusterExtension resource. -For information on downgrading an extension, see [Downgrade an Extension](../downgrade/downgrading-an-extension.md). +For information on downgrading an extension, see [Downgrade an Extension](downgrade-extension.md). ## Prerequisites * You have an extension installed -* The target version is compatible with OLM v1 (see [OLM v1 limitations](../../drafts/olmv1-limitations.md)) -* CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../../refs/crd-upgrade-safety.md)) -* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../../drafts/create-installer-service-account.md)) +* The target version is compatible with OLM v1 (see [OLM v1 limitations](../project/olmv1_limitations.md)) +* CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../concepts/crd-upgrade-safety.md)) +* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../howto/derive-service-account.md)) -For more detailed information see [Upgrade Support](upgrade-support.md). +For more detailed information see [Upgrade Support](../concepts/upgrade-support.md). ## Procedure diff --git a/mkdocs.yml b/mkdocs.yml index aecac92b5..e2dc366a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,28 +1,56 @@ # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json -site_name: Operator Controller documentation +site_name: Operator Lifecycle Manager theme: - name: "material" - features: - - content.code.copy + logo: assets/logo.svg + name: "material" + palette: + primary: black + features: + - content.code.copy +# - navigation.tabs +# - navigation.indexes repo_url: https://github.com/operator-framework/operator-controller +extra_css: + - css/extra.css + nav: - - Home: 'olmv1_overview.md' - - Components: 'components.md' - - Tasks: - - Adding a catalog of extensions: 'tasks/adding-a-catalog.md' - - Finding extensions to install: 'tasks/exploring-available-packages.md' - - Installing an extension: 'tasks/installing-an-extension.md' - - Deleting an extension: 'tasks/uninstalling-an-extension.md' - - References: - - Supported extensions: 'refs/supported-extensions.md' - - API references: - - Operator Controller API reference: 'refs/api/operator-controller-api-reference.md' - - CatalogD API reference: 'refs/api/catalogd-api-reference.md' - - Catalog queries: 'refs/catalog-queries.md' - - CRD Upgrade Safety: 'refs/crd-upgrade-safety.md' + - OLM: + - Overview: index.md + - Community: project/olmv1_community.md + - Architecture: project/olmv1_architecture.md + - Design Decisions: project/olmv1_design_decisions.md + - Limitations: project/olmv1_limitations.md + - Roadmap: project/olmv1_roadmap.md + - Getting Started: getting-started/olmv1_getting_started.md + - Tutorials: + - Add a Catalog: tutorials/add-catalog.md + - Explore Content: tutorials/explore-available-content.md + - Install an Extension: tutorials/install-extension.md + - Upgrade an Extension: tutorials/upgrade-extension.md + - Downgrade an Extension: tutorials/downgrade-extension.md + - Uninstall an Extension: tutorials/uninstall-extension.md + - How-To Guides: + - Catalog queries: howto/catalog-queries.md + - Channel-Based Upgrades: howto/how-to-channel-based-upgrades.md + - Version Pinning: howto/how-to-pin-version.md + - Version Range Upgrades: howto/how-to-version-range-upgrades.md + - Z-Stream Upgrades: howto/how-to-z-stream-upgrades.md + - Derive Service Account Permissions: howto/derive-service-account.md + - Conceptual Guides: + - Single Owner Objects: concepts/single-owner-objects.md + - Upgrade Support: concepts/upgrade-support.md + - CRD Upgrade Safety: concepts/crd-upgrade-safety.md + - Content Resolution: concepts/controlling-catalog-selection.md + - Version Ranges: concepts/version-ranges.md + - API Reference: + - Operator Controller API reference: api-reference/operator-controller-api-reference.md + - CatalogD API reference: api-reference/catalogd-api-reference.md + - Contribute: + - Contributing: contribute/contributing.md + - Developing OLM v1: contribute/developer.md markdown_extensions: - pymdownx.highlight: