From 09a6148d2c6c8cd6d222b459487ea7862ffb5d7f Mon Sep 17 00:00:00 2001 From: Tayler Geiger Date: Fri, 14 Jun 2024 10:09:08 -0500 Subject: [PATCH] Update docs for catalogd TLS and other cleanup - remove $ prompt from command examples - a couple small fixes in the README Signed-off-by: Tayler Geiger --- README.md | 4 ++-- docs/Tasks/adding-a-catalog.md | 26 ++++++++++++------------ docs/Tasks/explore-available-packages.md | 13 +++++++----- docs/Tasks/installing-an-extension.md | 4 ++-- docs/Tasks/uninstall-an-extension.md | 4 ++-- docs/refs/catalog-queries.md | 8 +++++++- 6 files changed, 34 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index eea4a117c..ab22b0752 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ OLM’s purpose is to provide APIs, controllers, and tooling that support the pa OLM v1 is the follow-up to OLM v0, located [here](https://github.com/operator-framework/operator-lifecycle-manager). -OLM v1 consists of four different components: +OLM v1 consists of three different components: * operator-controller (this repository) * [deppy](https://github.com/operator-framework/deppy) * [catalogd](https://github.com/operator-framework/catalogd) @@ -90,7 +90,7 @@ More information can be found via the [Kubebuilder Documentation](https://book.k ## License -Copyright 2022-2023. +Copyright 2022-2024. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/docs/Tasks/adding-a-catalog.md b/docs/Tasks/adding-a-catalog.md index 8961d1d9a..cf9a7deb0 100644 --- a/docs/Tasks/adding-a-catalog.md +++ b/docs/Tasks/adding-a-catalog.md @@ -1,9 +1,9 @@ # Adding a catalog of extensions to a cluster Extension authors can publish their products in catalogs. -Catalogs are curated collections of Kubernetes extensions, such as Operators. -Cluster administrators can add these catalogs to their cluster. -Cluster administrators can enable polling to get over-the-air updates to catalogs when extension authors publish changes such as bug fixes and new features. +ClusterCatalogs are curated collections of Kubernetes extensions, such as Operators. +Cluster administrators can add these ClusterCatalogs to their cluster. +Cluster administrators can enable polling to get over-the-air updates to ClusterCatalogs when extension authors publish changes such as bug fixes and new features. For example, the [Kubernetes community Operators catalog](https://github.com/k8s-operatorhub/community-operators) is a catalog of curated extensions that is developed by the Kubernetes community. You can see the available extensions at [Operatorhub.io](https://operatorhub.io). @@ -20,9 +20,9 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// 1. Create a catalog custom resource (CR): - ``` yaml title="catalog_cr.yaml" + ``` yaml title="clustercatalog_cr.yaml" apiVersion: catalogd.operatorframework.io/v1alpha1 - kind: Catalog + kind: ClusterCatalog metadata: name: operatorhubio spec: @@ -44,7 +44,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// ``` yaml title="Example `operatorhubio.yaml` CR" apiVersion: catalogd.operatorframework.io/v1alpha1 - kind: Catalog + kind: ClusterCatalog metadata: name: operatorhub spec: @@ -55,14 +55,14 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// pollInterval: 1h ``` -2. Apply the catalog CR: +2. Apply the ClusterCatalog CR: ``` terminal - $ kubectl apply -f .yaml + kubectl apply -f .yaml ``` ``` text title="Example output" - catalog.catalogd.operatorframework.io/redhat-operators created + clustercatalog.catalogd.operatorframework.io/operatorhubio created ``` ### Verification @@ -72,7 +72,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// * Check if your catalog is available on the cluster: ``` terminal - $ kubectl get catalog + kubectl get clustercatalog ``` ``` terminal title="Example output" @@ -83,7 +83,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// * Check the status of your catalog: ``` terminal - $ kubectl describe catalog + kubectl describe clustercatalog ``` ``` terminal title="Example output" @@ -92,7 +92,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// Labels: Annotations: API Version: catalogd.operatorframework.io/v1alpha1 - Kind: Catalog + Kind: ClusterCatalog Metadata: Creation Timestamp: 2024-03-12T19:34:50Z Finalizers: @@ -113,7 +113,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// Reason: UnpackSuccessful Status: True Type: Unpacked - Content URL: http://catalogd-catalogserver.olmv1-system.svc/catalogs/operatorhubio/all.json + Content URL: https://catalogd-catalogserver.olmv1-system.svc/catalogs/operatorhubio/all.json Observed Generation: 2 Phase: Unpacked Resolved Source: diff --git a/docs/Tasks/explore-available-packages.md b/docs/Tasks/explore-available-packages.md index e377bf9f8..001867dd2 100644 --- a/docs/Tasks/explore-available-packages.md +++ b/docs/Tasks/explore-available-packages.md @@ -3,20 +3,23 @@ Then you can query the catalog by using `curl` commands and the `jq` CLI tool to ## Prerequisites -* You have added a catalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster. +* You have added a ClusterCatalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster. * You have installed the `jq` CLI tool. +**Note:** By default, Catalogd is installed with TLS enabled for the catalog webserver. +The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag. + ## Procedure 1. Port forward the catalog server service: ``` terminal - $ kubectl -n olmv1-system port-forward svc/catalogd-catalogserver 8080:80 + kubectl -n olmv1-system port-forward svc/catalogd-catalogserver 8443:443 ``` 2. Return a list of all the extensions in a catalog: ``` terminal - $ curl http://localhost:8080/catalogs/operatorhubio/all.json | jq -s '.[] | select(.schema == "olm.package") | .name' + curl -k https://localhost:8443/catalogs/operatorhubio/all.json | jq -s '.[] | select(.schema == "olm.package") | .name' ``` ??? success @@ -86,7 +89,7 @@ Then you can query the catalog by using `curl` commands and the `jq` CLI tool to * Return list of packages that support `AllNamespaces` install mode and do not use webhooks: ``` terminal - $ curl http://localhost:8080/catalogs/operatorhubio/all.json | jq -c 'select(.schema == "olm.bundle") | {"package":.package, "version":.properties[] | select(.type == "olm.bundle.object").value.data | @base64d | fromjson | select(.kind == "ClusterServiceVersion" and (.spec.installModes[] | select(.type == "AllNamespaces" and .supported == true) != null) and .spec.webhookdefinitions == null).spec.version}' + curl -k https://localhost:8443/catalogs/operatorhubio/all.json | jq -c 'select(.schema == "olm.bundle") | {"package":.package, "version":.properties[] | select(.type == "olm.bundle.object").value.data | @base64d | fromjson | select(.kind == "ClusterServiceVersion" and (.spec.installModes[] | select(.type == "AllNamespaces" and .supported == true) != null) and .spec.webhookdefinitions == null).spec.version}' ``` ??? success @@ -117,7 +120,7 @@ Then you can query the catalog by using `curl` commands and the `jq` CLI tool to 3. Inspect the contents of an extension's metadata: ``` terminal - $ curl http://localhost:8080/catalogs/operatorhubio/all.json | jq -s '.[] | select( .schema == "olm.package") | select( .name == "")' + curl -k https://localhost:8443/catalogs/operatorhubio/all.json | jq -s '.[] | select( .schema == "olm.package") | select( .name == "")' ``` `package_name` diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md index a82645aab..9b4ac52bc 100644 --- a/docs/Tasks/installing-an-extension.md +++ b/docs/Tasks/installing-an-extension.md @@ -54,7 +54,7 @@ After you add a catalog to your cluster, you can install an extension by creatin 2. Apply the CR to the cluster: ``` terminal - $ kubectl apply -f .yaml + kubectl apply -f .yaml ``` ??? success @@ -67,7 +67,7 @@ After you add a catalog to your cluster, you can install an extension by creatin * Describe the installed extension: ``` terminal - $ kubectl describe clusterextensions + kubectl describe clusterextensions ``` ??? success diff --git a/docs/Tasks/uninstall-an-extension.md b/docs/Tasks/uninstall-an-extension.md index 048a8cca5..06105b234 100644 --- a/docs/Tasks/uninstall-an-extension.md +++ b/docs/Tasks/uninstall-an-extension.md @@ -11,7 +11,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi * Delete the extension's CR: ``` terminal - $ kubectl delete clusterextensions + kubectl delete clusterextensions ``` `extension_name` @@ -26,7 +26,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi * Verify that the Kubernetes extension is deleted: ``` terminal - $ kubectl get clusterextension.olm.operatorframework.io + kubectl get clusterextension.olm.operatorframework.io ``` ``` text title="Example output" diff --git a/docs/refs/catalog-queries.md b/docs/refs/catalog-queries.md index 0f78b44e5..fda87987e 100644 --- a/docs/refs/catalog-queries.md +++ b/docs/refs/catalog-queries.md @@ -1,11 +1,17 @@ # Catalog queries +**Note:** By default, Catalogd is installed with TLS enabled for the catalog webserver. +The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag. + + You can use the `curl` command with `jq` to query catalogs that are installed on your cluster. ``` terminal title="Query syntax" -$ curl http://localhost:8080/catalogs/operatorhubio/all.json | +curl -k https://localhost:8443/catalogs/operatorhubio/all.json | ``` + + ## Package queries Available packages in a catalog