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/permissions-for-owner-references-permission-enforcement-plugin.md b/docs/concepts/permissions-for-owner-references-permission-enforcement-plugin.md similarity index 100% rename from docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md rename to docs/concepts/permissions-for-owner-references-permission-enforcement-plugin.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..263c0f40e 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..5fcb11760 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). 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). ```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 100% rename from docs/refs/catalog-queries.md rename to docs/howto/catalog-queries.md 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..07f48cb3b 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), +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 80% rename from docs/general/olmv1_overview.md rename to docs/index.md index ca3928973..bfe99e4c2 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. @@ -27,7 +30,7 @@ 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. +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: * A simpler API surface and mental model @@ -37,19 +40,19 @@ 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). +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](project/olmv1_design_decisions.md) +and our feature [Roadmap](project/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/), +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) +* 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) +For further information on contributing, please consult the [Contribution Guide](contribute/CONTRIBUTING.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..d73ce7a65 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: 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/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..aac49d645 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) 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). ## 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..8a5ea90b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,28 +1,55 @@ # 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 + - 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 + - Cluster Extension 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: