diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e7c1607e..bd624d6ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,12 +15,10 @@ 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](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 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 components: -- [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. - -Each of the projects listed above have their own governance, release milestones, and release cadence. However, from a technical perspective, the "OLM V1 experience" matches the experienced offered by the operator-controller project, the top level component which depends on Catalogd. +- [Operator-Controller](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install. +- [Catalogd](https://github.com/operator-framework/operator-controller/tree/main/catalogd), which hosts operator content and helps users discover installable content. ## How do we collaborate @@ -119,10 +117,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec 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. - -Don't worry if you accidentally submit an issue against the wrong project, if we notice that an issue would fit better with a separate project we'll move it to the correct repository and mention it in the #olm-dev slack channel. +- [Operator-Controller](https://github.com/operator-framework/operator-controller/), which contains both components, is the project allowing users to specify operators they'd like to install. ## Submitting Pull Requests diff --git a/README.md b/README.md index 9824f5bb9..783276d9b 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,154 @@ The documentation currently lives at [website](https://operator-framework.github To get started with OLM v1, please see our [Getting Started](https://operator-framework.github.io/operator-controller/getting-started/olmv1_getting_started/) documentation. +## ClusterCatalog + +### Quickstart DEMO + +[![asciicast](https://asciinema.org/a/682344.svg)](https://asciinema.org/a/682344) + +### ClusterCatalog Quickstart Steps + +Procedure steps marked with an asterisk (`*`) are likely to change with future API updates. + +**NOTE:** The examples below use the `-k` flag in curl to skip validating the TLS certificates. This is for demonstration purposes only. + +1. To get started with OLM v1, please see our [Getting Started](https://operator-framework.github.io/operator-controller/getting-started/olmv1_getting_started/) documentation. + +1. Create a `ClusterCatalog` object that points to the OperatorHub Community catalog by running the following command: + + ```sh + $ kubectl apply -f - << EOF + apiVersion: olm.operatorframework.io/v1 + kind: ClusterCatalog + metadata: + name: operatorhubio + spec: + source: + type: Image + image: + ref: quay.io/operatorhubio/catalog:latest + EOF + ``` + +1. Verify the `ClusterCatalog` object was created successfully by running the following command: + + ```sh + $ kubectl describe clustercatalog/operatorhubio + ``` + + *Example output* + ```sh + Name: operatorhubio + Namespace: + Labels: olm.operatorframework.io/metadata.name=operatorhubio + Annotations: + API Version: olm.operatorframework.io/v1 + Kind: ClusterCatalog + Metadata: + Creation Timestamp: 2024-10-17T13:48:46Z + Finalizers: + olm.operatorframework.io/delete-server-cache + Generation: 1 + Resource Version: 7908 + UID: 34eeaa91-9f8e-4254-9937-0ae9d25e92df + Spec: + Availability Mode: Available + Priority: 0 + Source: + Image: + Ref: quay.io/operatorhubio/catalog:latest + Type: Image + Status: + Conditions: + Last Transition Time: 2024-10-17T13:48:59Z + Message: Successfully unpacked and stored content from resolved source + Observed Generation: 1 + Reason: Succeeded + Status: False + Type: Progressing + Last Transition Time: 2024-10-17T13:48:59Z + Message: Serving desired content from resolved source + Observed Generation: 1 + Reason: Available + Status: True + Type: Serving + Last Unpacked: 2024-10-17T13:48:58Z + Resolved Source: + Image: + Last Successful Poll Attempt: 2024-10-17T14:49:59Z + Ref: quay.io/operatorhubio/catalog@sha256:82be554b15ff246d8cc428f8d2f4cf5857c02ce3225d95d92a769ea3095e1fc7 + Type: Image + Urls: + Base: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio + Events: + ``` + +1. Port forward the `catalogd-service` service in the `olmv1-system` namespace: + ```sh + $ kubectl -n olmv1-system port-forward svc/catalogd-service 8080:443 + ``` + +1. Access the `v1/all` service endpoint and filter the results to a list of packages by running the following command: + + ```sh + $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.package") | .name' + ``` + + *Example output* + ```sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 110M 100 110M 0 0 112M 0 --:--:-- --:--:-- --:--:-- 112M + "ack-acm-controller" + "ack-apigatewayv2-controller" + "ack-applicationautoscaling-controller" + "ack-cloudtrail-controller" + "ack-cloudwatch-controller" + "ack-dynamodb-controller" + "ack-ec2-controller" + "ack-ecr-controller" + "ack-eks-controller" + "ack-elasticache-controller" + "ack-emrcontainers-controller" + "ack-eventbridge-controller" + "ack-iam-controller" + "ack-kinesis-controller" + ... + ``` +1. Run the following command to get a list of channels for the `ack-acm-controller` package: + + ```sh + $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.channel") | select(.package == "ack-acm-controller") | .name' + ``` + + *Example output* + ```sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 110M 100 110M 0 0 115M 0 --:--:-- --:--:-- --:--:-- 116M + "alpha" + ``` + +1. Run the following command to get a list of bundles belonging to the `ack-acm-controller` package: + + ```sh + $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.bundle") | select(.package == "ack-acm-controller") | .name' + ``` + + *Example output* + ```sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 110M 100 110M 0 0 122M 0 --:--:-- --:--:-- --:--:-- 122M + "ack-acm-controller.v0.0.1" + "ack-acm-controller.v0.0.2" + "ack-acm-controller.v0.0.4" + "ack-acm-controller.v0.0.5" + "ack-acm-controller.v0.0.6" + "ack-acm-controller.v0.0.7" + ``` + ## License Copyright 2022-2024. diff --git a/catalogd/README.md b/catalogd/README.md deleted file mode 100644 index 04a462f92..000000000 --- a/catalogd/README.md +++ /dev/null @@ -1,169 +0,0 @@ -# catalogd - -Catalogd is a Kubernetes extension that unpacks [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content for on-cluster clients. Currently, catalogd unpacks FBC content that is packaged and distributed as container images. The catalogd road map includes plans for unpacking other content sources, such as Git repositories and OCI artifacts. For more information, see the catalogd [issues](https://github.com/operator-framework/catalogd/issues/) page. - -Catalogd helps customers discover installable content by hosting catalog metadata for Kubernetes extensions, such as Operators and controllers. For more information on the Operator Lifecycle Manager (OLM) v1 suite of microservices, see the [documentation](https://github.com/operator-framework/operator-controller/tree/main/docs) for the Operator Controller. - -## Quickstart DEMO -[![asciicast](https://asciinema.org/a/682344.svg)](https://asciinema.org/a/682344) - -## Quickstart Steps -Procedure steps marked with an asterisk (`*`) are likely to change with future API updates. - -**NOTE:** The examples below use the `-k` flag in curl to skip validating the TLS certificates. This is for demonstration purposes only. - -1. To install catalogd, navigate to the [releases](https://github.com/operator-framework/catalogd/releases/) page, and follow the install instructions included in the release you want to install. - -1. Create a `ClusterCatalog` object that points to the OperatorHub Community catalog by running the following command: - - ```sh - $ kubectl apply -f - << EOF - apiVersion: olm.operatorframework.io/v1 - kind: ClusterCatalog - metadata: - name: operatorhubio - spec: - source: - type: Image - image: - ref: quay.io/operatorhubio/catalog:latest - EOF - ``` - -1. Verify the `ClusterCatalog` object was created successfully by running the following command: - - ```sh - $ kubectl describe clustercatalog/operatorhubio - ``` - - *Example output* - ```sh - Name: operatorhubio - Namespace: - Labels: olm.operatorframework.io/metadata.name=operatorhubio - Annotations: - API Version: olm.operatorframework.io/v1 - Kind: ClusterCatalog - Metadata: - Creation Timestamp: 2024-10-17T13:48:46Z - Finalizers: - olm.operatorframework.io/delete-server-cache - Generation: 1 - Resource Version: 7908 - UID: 34eeaa91-9f8e-4254-9937-0ae9d25e92df - Spec: - Availability Mode: Available - Priority: 0 - Source: - Image: - Ref: quay.io/operatorhubio/catalog:latest - Type: Image - Status: - Conditions: - Last Transition Time: 2024-10-17T13:48:59Z - Message: Successfully unpacked and stored content from resolved source - Observed Generation: 1 - Reason: Succeeded - Status: False - Type: Progressing - Last Transition Time: 2024-10-17T13:48:59Z - Message: Serving desired content from resolved source - Observed Generation: 1 - Reason: Available - Status: True - Type: Serving - Last Unpacked: 2024-10-17T13:48:58Z - Resolved Source: - Image: - Last Successful Poll Attempt: 2024-10-17T14:49:59Z - Ref: quay.io/operatorhubio/catalog@sha256:82be554b15ff246d8cc428f8d2f4cf5857c02ce3225d95d92a769ea3095e1fc7 - Type: Image - Urls: - Base: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio - Events: - ``` - -1. Port forward the `catalogd-service` service in the `olmv1-system` namespace: - ```sh - $ kubectl -n olmv1-system port-forward svc/catalogd-service 8080:443 - ``` - -1. Access the `v1/all` service endpoint and filter the results to a list of packages by running the following command: - - ```sh - $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.package") | .name' - ``` - - *Example output* - ```sh - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 110M 100 110M 0 0 112M 0 --:--:-- --:--:-- --:--:-- 112M - "ack-acm-controller" - "ack-apigatewayv2-controller" - "ack-applicationautoscaling-controller" - "ack-cloudtrail-controller" - "ack-cloudwatch-controller" - "ack-dynamodb-controller" - "ack-ec2-controller" - "ack-ecr-controller" - "ack-eks-controller" - "ack-elasticache-controller" - "ack-emrcontainers-controller" - "ack-eventbridge-controller" - "ack-iam-controller" - "ack-kinesis-controller" - ... - ``` -1. Run the following command to get a list of channels for the `ack-acm-controller` package: - - ```sh - $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.channel") | select(.package == "ack-acm-controller") | .name' - ``` - - *Example output* - ```sh - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 110M 100 110M 0 0 115M 0 --:--:-- --:--:-- --:--:-- 116M - "alpha" - ``` - -1. Run the following command to get a list of bundles belonging to the `ack-acm-controller` package: - - ```sh - $ curl https://localhost:8080/catalogs/operatorhubio/api/v1/all | jq -s '.[] | select(.schema == "olm.bundle") | select(.package == "ack-acm-controller") | .name' - ``` - - *Example output* - ```sh - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 110M 100 110M 0 0 122M 0 --:--:-- --:--:-- --:--:-- 122M - "ack-acm-controller.v0.0.1" - "ack-acm-controller.v0.0.2" - "ack-acm-controller.v0.0.4" - "ack-acm-controller.v0.0.5" - "ack-acm-controller.v0.0.6" - "ack-acm-controller.v0.0.7" - ``` - -## Contributing -Thanks for your interest in contributing to `catalogd`! - -`catalogd` is in the very early stages of development and a more in depth contributing guide will come in the near future. - -In the meantime, it is assumed you know how to make contributions to open source projects in general and this guide will only focus on how to manually test your changes (no automated testing yet). - -If you have any questions, feel free to reach out to us on the Kubernetes Slack channel [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2) or [create an issue](https://github.com/operator-framework/catalogd/issues/new) -### Testing Local Changes -**Prerequisites** -- [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) - -**Test it out** - -```sh -make run -``` - -This will build a local container image for the catalogd controller, create a new KIND cluster and then deploy onto that cluster. diff --git a/catalogd/docs/fetching-catalog-contents.md b/catalogd/docs/fetching-catalog-contents.md index ccc0ff231..8944828a9 100644 --- a/catalogd/docs/fetching-catalog-contents.md +++ b/catalogd/docs/fetching-catalog-contents.md @@ -133,11 +133,11 @@ This section outlines a way of exposing the `Catalogd` Service's endpoints outsi - [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) - Assuming `kind` is installed, create a `kind` cluster with `extraPortMappings` and `node-labels` as shown in the [kind documentation](https://kind.sigs.k8s.io/docs/user/ingress/) -- Install latest version of `Catalogd` by navigating to the [releases page](https://github.com/operator-framework/catalogd/releases) and following the install instructions included in the release you want to install. +- Install OLM V1, see the [Getting Started](https://operator-framework.github.io/operator-controller/getting-started/olmv1_getting_started/) documentation. - Install the `Ingress NGINX` Controller by running the below command: ```sh - $ kubectl apply -k https://github.com/operator-framework/catalogd/tree/main/config/nginx-ingress + $ kubectl apply -k https://github.com/operator-framework/operator-controller/tree/main/catalogd/config/base/nginx-ingress ``` By running that above command, the `Ingress` Controller is installed. Along with it, the `Ingress` Resource will be applied automatically as well, thereby creating an `Ingress` Object on the cluster. @@ -201,4 +201,4 @@ This section outlines a way of exposing the `Catalogd` Service's endpoints outsi $ kubectl -n olmv1-system get ingress ``` - You can further use the `curl` commands outlined in the [Catalogd README](https://github.com/operator-framework/catalogd/blob/main/README.md) to filter out the JSON content by list of bundles, channels & packages. + You can further use the `curl` commands outlined in the [README](https://github.com/operator-framework/operator-controller/blob/main/README.md) to filter out the JSON content by list of bundles, channels & packages. diff --git a/docs/api-reference/catalogd-webserver.md b/docs/api-reference/catalogd-webserver.md index 3aed2f6bd..dc0b9bb0a 100644 --- a/docs/api-reference/catalogd-webserver.md +++ b/docs/api-reference/catalogd-webserver.md @@ -1,6 +1,6 @@ # Catalogd web server -[Catalogd](https://github.com/operator-framework/catalogd), the OLM v1 component for making catalog contents available on cluster, includes +[Catalogd](https://github.com/operator-framework/operator-controller/tree/main/catalogd), the OLM v1 component for making catalog contents available on cluster, includes a web server that serves catalog contents to clients via an HTTP(S) endpoint. The endpoint to retrieve this information can be composed from the `.status.urls.base` of a `ClusterCatalog` resource with the selected access API path. diff --git a/docs/contribute/developer.md b/docs/contribute/developer.md index a87f3a682..ef9842b0a 100644 --- a/docs/contribute/developer.md +++ b/docs/contribute/developer.md @@ -89,7 +89,7 @@ Follow Tilt's [instructions](https://docs.tilt.dev/install.html) for installatio ### Installing catalogd operator-controller requires -[catalogd](https://github.com/operator-framework/catalogd). Please make sure it's installed, either normally or via its own Tiltfile., before proceeding. If you want to use Tilt, make sure you specify a unique `--port` flag to each `tilt up` invocation. +[catalogd](https://github.com/operator-framework/operator-controller/tree/main/catalogd). When you give a `tilt up` invocation, catalogd will be started along with operator-controller. ### Starting Tilt diff --git a/docs/project/olmv1_architecture.md b/docs/project/olmv1_architecture.md index 1bfea0ef8..09889cc8d 100644 --- a/docs/project/olmv1_architecture.md +++ b/docs/project/olmv1_architecture.md @@ -8,7 +8,7 @@ hide: This document provides an overview of the architecture of OLM v1, which consists of two primary components: 1. [operator-controller](https://github.com/operator-framework/operator-controller) -2. [catalogD](https://github.com/operator-framework/catalogd) +2. [catalogD](https://github.com/operator-framework/operator-controller/tree/main/catalogd) The diagram below visually represents the architecture of OLM v1, followed by descriptions of each component and its role within the system. diff --git a/docs/tutorials/add-catalog.md b/docs/tutorials/add-catalog.md index 650f86678..2d7bdfce2 100644 --- a/docs/tutorials/add-catalog.md +++ b/docs/tutorials/add-catalog.md @@ -17,8 +17,7 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// ## Prerequisites * Access to a Kubernetes cluster, for example `kind`, using an account with `cluster-admin` permissions -* [Operator Controller installed](https://github.com/operator-framework/operator-controller/releases) on the cluster -* [Catalogd installed](https://github.com/operator-framework/catalogd/releases/) on the cluster +* [Operator Controller and Catalogd installed](https://github.com/operator-framework/operator-controller/releases) on the cluster * Kubernetes CLI (`kubectl`) installed on your workstation ## Procedure