diff --git a/README.md b/README.md index 822bab9b2..275486209 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,12 @@ 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/olmv1_overview.md). - -## Getting Started -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. - -> [!NOTE] -> Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). +For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md). ### 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). + > [!CAUTION] > Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command > may affect an existing installation of cert-manager and cause cluster instability. @@ -37,10 +33,24 @@ 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 ``` -### Create a ClusterCatalog +## Getting Started with OLM v1 + +This quickstart procedure will guide you through the following processes: +* Deploying a catalog +* Installing, upgrading, or downgrading an extension +* Deleting catalogs and extensions + +### Create a Catalog -The ClusterCatalog resource supports file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) images. -The following example uses the official [OperatorHub](https://operatorhub.io) catalog. +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). + +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). + +To create the catalog, run the following command: ```bash # Create ClusterCatalog @@ -58,148 +68,70 @@ spec: EOF ``` +Once the catalog is unpacked successfully, its content will be available for installation. + ```bash # Wait for the ClusterCatalog to be unpacked kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s ``` -### Install Cluster Extension +### Install a Cluster Extension + +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). ```bash # Apply the sample ClusterExtension. Manifest already includes # namespace and adequately privileged service account -kubectl apply -f config/samples/olm_v1alpha1_clusterextension.yaml -``` - -#### Upgrade/Downgrade - -```bash -# Update the required version -kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"version": "0.11.0"}}' -``` - -#### Uninstall - -```bash -# Delete cluster extension and residing namespace -kubectl delete clusterextension/argocd && kubectl delete namespace argocd -``` - -```bash -# Delete cluster-scoped resources -kubectl delete --ignore-not-found=true -f config/samples/olm_v1alpha1_clusterextension.yaml +kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml ``` -### Advanced Usage - -> [!WARNING] -> The scripts referenced in this section are best-effort and may not always work as -> intended. They are provided as a stopgap until we can offer production grade tooling -> for tasks such as: searching the catalog, discovering supported bundles, and determining -> the least-privilege set of permissions required by the installer service account to install -> the content. +### Upgrade the Cluster Extension -#### Installation - -An extension needs a namespace in which to be installed and a service account with sufficient -privileges to install the content. For instance: +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). ```bash -# Create argocd namespace for the argocd-operator -kubectl create ns argocd -``` +# Update to v0.11.0 +kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}' -```bash -# Create installer service account -kubectl create serviceaccount -n argocd-system argocd-installer ``` -> [!WARNING] -> We work around the absence of reliable tooling to determine the set of least privileges -> for the installer service account to be able to install a given bundle by giving -> the installer service account cluster admin privileges. -> This is not an option for production clusters due to the security implications. -> The OLM community is working hard to bridge this tooling gap. +For information on the downgrade process, see [here](./docs/drafts/Tasks/downgrading-an-extension.md). -```bash -# Give service account cluster admin privileges -# This works with KIND - consult documentation for instructions on how -# to grant admin privileges for your kubernetes distribution -kubectl create clusterrolebinding "argocd-operator-installer-cluster-admin" \ - --clusterrole=cluster-admin \ - --serviceaccount="argocd-system:argocd-operator-installer" -``` +### Uninstall the Cluster Extension -```bash -# Apply ClusterExtension -cat < --type='merge' -p '{"spec": {"source": {"catalog": {"version": ""}}}}' + ``` + + `extension_name` + : Specifies the name defined in the `metadata.name` field of the extension's CR. + + `target_version` + : Specifies the version to upgrade or downgrade to. + + ??? success + ``` text title="Example output" + clusterextension.olm.operatorframework.io/argocd-operator patched + ``` + +### Verification + +* Verify that the Kubernetes extension is deleted: + + ``` terminal + kubectl get clusterextension.olm.operatorframework.io/ + ``` + + ??? success + ``` text title="Example output" + Name: argocd + Namespace: + Labels: olm.operatorframework.io/owner-kind=ClusterExtension + olm.operatorframework.io/owner-name=argocd + Annotations: + API Version: olm.operatorframework.io/v1alpha1 + Kind: ClusterExtension + Metadata: + Creation Timestamp: 2024-09-06T13:38:38Z + Finalizers: + olm.operatorframework.io/cleanup-unpack-cache + olm.operatorframework.io/cleanup-contentmanager-cache + Generation: 5 + Resource Version: 21167 + UID: 5abdf57d-aedc-45d4-ba0d-a86e785fd34a + Spec: + Install: + Namespace: argocd + Service Account: + Name: argocd-installer + Source: + Catalog: + Package Name: argocd-operator + Selector: + Upgrade Constraint Policy: Enforce + Version: 0.6.0 + Source Type: Catalog + Status: + Conditions: + Last Transition Time: 2024-09-06T13:38:38Z + Message: + Observed Generation: 5 + Reason: Deprecated + Status: False + Type: Deprecated + Last Transition Time: 2024-09-06T13:38:38Z + Message: + Observed Generation: 5 + Reason: Deprecated + Status: False + Type: PackageDeprecated + Last Transition Time: 2024-09-06T13:38:38Z + Message: + Observed Generation: 5 + Reason: Deprecated + Status: False + Type: ChannelDeprecated + Last Transition Time: 2024-09-06T13:38:38Z + Message: + Observed Generation: 5 + Reason: Deprecated + Status: False + Type: BundleDeprecated + Last Transition Time: 2024-09-06T13:40:14Z + Message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3" + Observed Generation: 5 + Reason: Success + Status: True + Type: Resolved + Last Transition Time: 2024-09-06T13:38:38Z + Message: unpack successful: + Observed Generation: 5 + Reason: UnpackSuccess + Status: True + Type: Unpacked + Last Transition Time: 2024-09-06T13:40:31Z + Message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3 successfully + Observed Generation: 5 + Reason: Success + Status: True + Type: Installed + Install: + Bundle: + Name: argocd-operator.v0.6.0 + Version: 0.6.0 + Resolution: + Bundle: + Name: argocd-operator.v0.6.0 + Version: 0.6.0 + ``` diff --git a/docs/drafts/refs/olmv1-limitations.md b/docs/drafts/refs/olmv1-limitations.md new file mode 100644 index 000000000..1c351f9e9 --- /dev/null +++ b/docs/drafts/refs/olmv1-limitations.md @@ -0,0 +1,3 @@ +# Current OLM v1 Limitations + +Placeholder. We need to document this. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4ac56f7f1..2c71be2a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,9 +13,9 @@ nav: - Components: 'components.md' - Tasks: - Adding a catalog of extensions: 'Tasks/adding-a-catalog.md' - - Finding extensions to install: 'Tasks/explore-available-packages.md' + - Finding extensions to install: 'Tasks/exploring-available-packages.md' - Installing an extension: 'Tasks/installing-an-extension.md' - - Deleting an extension: 'Tasks/uninstall-an-extension.md' + - Deleting an extension: 'Tasks/uninstalling-an-extension.md' - References: - Catalog queries: 'refs/catalog-queries.md' - CRD Upgrade Safety: 'refs/crd-upgrade-safety.md'