From 7220ae0a009524bf0555979fbd73c016b4496d1b Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Fri, 23 Jul 2021 12:38:00 +0530 Subject: [PATCH 01/12] Add documentation for operator and operator installation --- .../cluster-setup/kubernetes.md | 65 +++++++++++++++++++ .../cluster-setup/operators.md | 12 ++++ 2 files changed, 77 insertions(+) create mode 100644 website/docs/getting-started/cluster-setup/kubernetes.md create mode 100644 website/docs/getting-started/cluster-setup/operators.md diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md new file mode 100644 index 00000000000..3e66d190a94 --- /dev/null +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -0,0 +1,65 @@ +--- +title: Kubernetes +sidebar_position: 2 +--- + +# Setup a minikube cluster + +Please note that this documentation only helps setup a development environment. + +This guide assumes that you have installed minikube on your system. +If you do not have it installed, follow the official [minikube installation guide](https://minikube.sigs.k8s.io/docs/start/) to get started. + +Next step is installing operators. To learn about what operators, see [Getting Started > Cluster Setup > Operators](operators.md). We will be using the [Redis Enterprise](https://operatorhub.io/operator/redis-enterprise) operator as an example for this guide. + +### Installing operators on a minikube cluster +1. To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) to the minikube cluster. + ```shell + minikube addons enable olm + ``` + + Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure of two things: + 1. The namespace in which we are installing has an `OperatorGroup` resource. + 2. An operator installed in one namespace should also be accessible in all the other namespaces. + + By default, enabling `olm` addon takes care of creating an `OperatorGroup` resource in its default `operators` namespace; check that they were created with the help of the command below: + ```shell + kubectl get og -n operators + ``` + + **Note**: Not all operators support installation in all the namespaces, some restrict access to a single namespace. + + If you do not see the `OperatorGroup` resource, you can manually create one with the help of the command below: + ```shell + kubectl create -f - << EOF + apiVersion: operators.coreos.com/v1 + kind: OperatorGroup + metadata: + name: global-operators + namespace: operators + spec: + targetNamespaces: + - operators + EOF + ``` + If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. + +2. Now we install the postgresql operator. + ```shell + kubectl create -f - << EOF + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: my-redis-enterprise + namespace: operators + spec: + channel: alpha + name: redis-enterprise + source: operatorhubio-catalog + sourceNamespace: olm + EOF + ``` + Wait for a few seconds for the operator to install. Confirm that it has been installed by running the below command: + ```shell + kubectl get csv + ``` \ No newline at end of file diff --git a/website/docs/getting-started/cluster-setup/operators.md b/website/docs/getting-started/cluster-setup/operators.md new file mode 100644 index 00000000000..eef31120041 --- /dev/null +++ b/website/docs/getting-started/cluster-setup/operators.md @@ -0,0 +1,12 @@ +--- +title: Installing Operators +sidebar_position: 4 +--- + +### Agenda +1. What is an operator?(./) +2. What is an operator backed service? +3. How to create and delete operator backed services? +4. How to link an odo component with an operator backed service? + +### What is an operator? \ No newline at end of file From 397ac748c5a8d14ce453fe064e32cd22c5ee8375 Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Fri, 23 Jul 2021 13:19:45 +0530 Subject: [PATCH 02/12] Modify operator --- .../cluster-setup/kubernetes.md | 50 +++---------------- 1 file changed, 8 insertions(+), 42 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 3e66d190a94..5b53a7ac8a2 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -10,56 +10,22 @@ Please note that this documentation only helps setup a development environment. This guide assumes that you have installed minikube on your system. If you do not have it installed, follow the official [minikube installation guide](https://minikube.sigs.k8s.io/docs/start/) to get started. -Next step is installing operators. To learn about what operators, see [Getting Started > Cluster Setup > Operators](operators.md). We will be using the [Redis Enterprise](https://operatorhub.io/operator/redis-enterprise) operator as an example for this guide. +Next step is installing operators. To learn about what operators, see [Getting Started > Cluster Setup > Operators](operators.md). We will be using the [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) operator as an example for this guide. -### Installing operators on a minikube cluster +### Installing OLM on the cluster 1. To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) to the minikube cluster. + Running the script below will take some time to install all the necessary namespaces and other resources. ```shell - minikube addons enable olm + curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.1/install.sh | bash -s v0.18.1 ``` - - Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure of two things: - 1. The namespace in which we are installing has an `OperatorGroup` resource. - 2. An operator installed in one namespace should also be accessible in all the other namespaces. + Note: We are not using the latest v0.18.2 because it is buggy. - By default, enabling `olm` addon takes care of creating an `OperatorGroup` resource in its default `operators` namespace; check that they were created with the help of the command below: +2. Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. ```shell - kubectl get og -n operators - ``` - - **Note**: Not all operators support installation in all the namespaces, some restrict access to a single namespace. - - If you do not see the `OperatorGroup` resource, you can manually create one with the help of the command below: - ```shell - kubectl create -f - << EOF - apiVersion: operators.coreos.com/v1 - kind: OperatorGroup - metadata: - name: global-operators - namespace: operators - spec: - targetNamespaces: - - operators - EOF + kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml ``` If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. - -2. Now we install the postgresql operator. - ```shell - kubectl create -f - << EOF - apiVersion: operators.coreos.com/v1alpha1 - kind: Subscription - metadata: - name: my-redis-enterprise - namespace: operators - spec: - channel: alpha - name: redis-enterprise - source: operatorhubio-catalog - sourceNamespace: olm - EOF - ``` Wait for a few seconds for the operator to install. Confirm that it has been installed by running the below command: ```shell - kubectl get csv + kubectl get csv -n operators ``` \ No newline at end of file From d2c9295475b42c51f3c6cfc7a43413845fc770ee Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Tue, 3 Aug 2021 10:29:16 +0530 Subject: [PATCH 03/12] Add TODO --- .../getting-started/cluster-setup/kubernetes.md | 13 ++++++++++++- .../docs/getting-started/cluster-setup/operators.md | 1 + 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 5b53a7ac8a2..bff5f5c35ae 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -20,7 +20,18 @@ Next step is installing operators. To learn about what operators, see [Getting S ``` Note: We are not using the latest v0.18.2 because it is buggy. -2. Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. +### Installing Operator into the cluster +1. Navigate to [OperatorHub](https://operatorhub.io). +2. Search for the operator. +3. Navigate to its detail's page. +4. Follow the instruction in the installation popup. + ```shell + kubectl create -f + ``` + +### Installing Service Binding Operator +// TODO: Explain why we have a separate section on installing the SBO +1. Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. ```shell kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml ``` diff --git a/website/docs/getting-started/cluster-setup/operators.md b/website/docs/getting-started/cluster-setup/operators.md index eef31120041..48f56193283 100644 --- a/website/docs/getting-started/cluster-setup/operators.md +++ b/website/docs/getting-started/cluster-setup/operators.md @@ -8,5 +8,6 @@ sidebar_position: 4 2. What is an operator backed service? 3. How to create and delete operator backed services? 4. How to link an odo component with an operator backed service? +5. How to install an operator into the cluster? ### What is an operator? \ No newline at end of file From 74591ae73b7cd3c92e5d200134e2a386edbf755e Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Mon, 9 Aug 2021 12:41:56 +0530 Subject: [PATCH 04/12] Add cluster setup guide --- .../cluster-setup/kubernetes.md | 109 ++++++++++++++---- .../cluster-setup/openshift.md | 56 +++++++++ .../cluster-setup/operators.md | 13 --- 3 files changed, 140 insertions(+), 38 deletions(-) create mode 100644 website/docs/getting-started/cluster-setup/openshift.md delete mode 100644 website/docs/getting-started/cluster-setup/operators.md diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index bff5f5c35ae..458ef495f91 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -1,42 +1,101 @@ --- title: Kubernetes -sidebar_position: 2 +sidebar_position: 1 --- # Setup a minikube cluster +Please note that this documentation is only useful in setting up a development environment, it is not recommended for a production environment. -Please note that this documentation only helps setup a development environment. +This guide assumes that you have [installed minikube](https://minikube.sigs.k8s.io/docs/start/) on your system. -This guide assumes that you have installed minikube on your system. -If you do not have it installed, follow the official [minikube installation guide](https://minikube.sigs.k8s.io/docs/start/) to get started. +If you are using a Kubernetes cluster other than minikube, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; operator installation is only possible with an admin user. -Next step is installing operators. To learn about what operators, see [Getting Started > Cluster Setup > Operators](operators.md). We will be using the [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) operator as an example for this guide. +**Agenda for this guide:** +* [Install the OLM](#install-the-olm) +* [Install the Service Binding Operator](#install-the-service-binding-operator) +* [Install an operator](#install-an-operator) +* [Verify the operator installation](#verify-the-operator-installation) -### Installing OLM on the cluster -1. To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) to the minikube cluster. - Running the script below will take some time to install all the necessary namespaces and other resources. - ```shell - curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.1/install.sh | bash -s v0.18.1 - ``` - Note: We are not using the latest v0.18.2 because it is buggy. +## Install the OLM +The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) -### Installing Operator into the cluster -1. Navigate to [OperatorHub](https://operatorhub.io). -2. Search for the operator. -3. Navigate to its detail's page. -4. Follow the instruction in the installation popup. +To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) addon to the minikube cluster. +Running the script below will take some time to install all the necessary namespaces and other resources. +```shell +curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.3/install.sh | bash -s v0.18.3 +``` + +To install OLM on a Kubernetes cluster setup other than minikube, please refer the [installation instructions on GitHub](https://github.com/operator-framework/operator-lifecycle-manager/#installation). + +## Install the Service Binding Operator +odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. + +Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. +```shell +kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml +``` + +If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. + +See [Verify the Operator installation](#verify-the-operator-installation) to ensure the operator is installed successfully. + +## Install an operator +1. Visit the [OperatorHub](https://operatorhub.io) website. +2. Search for an operator of your choice. +3. Navigate to its detail page. +4. Click on `Install`. +5. Follow the instruction in the installation popup. +6. [Verify the operator was installed successfully](#verify-the-operator-installation). + +## Verify the Operator installation +Wait for a few seconds for the operator to install. +To verify that the operator is installed successfully and see the CRDs associated with it, run the following command. +```shell +odo catalog list services +``` +The output can look similar to: +```shell +$ odo catalog list services +Services available through Operators +NAME CRDs +datadog-operator.v0.6.0 DatadogAgent, DatadogMetric, DatadogMonitor +service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding +``` +If you do not see your installed operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. + +## Troubleshoot the Operator installation +There are two ways to confirm that the operator has been installed properly. +The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). +1. Verify that its pod started and is in “Running” state. + ```s****************hell + kubectl get pods -n operators + ``` +The output can look similar to: + ```shell + $ kubectl get csv -n operators + NAME READY STATUS RESTARTS AGE + datadog-operator-manager-5db67c7f4-hgb59 1/1 Running 0 2m13s + service-binding-operator-c8d7587b8-lxztx 1/1 Running 5 6d23h + ``` +2. Verify that the csv is in Succeeded or Installing phase. ```shell - kubectl create -f + kubectl get csv -n operators + ``` + The output can look similar to the following: + ```shell + $ kubectl get csv -n operators + NAME DISPLAY VERSION REPLACES PHASE + datadog-operator.v0.6.0 Datadog Operator 0.6.0 datadog-operator.v0.5.0 Succeeded + service-binding-operator.v0.9.1 Service Binding Operator 0.9.1 service-binding-operator.v0.9.0 Succeeded ``` -### Installing Service Binding Operator -// TODO: Explain why we have a separate section on installing the SBO -1. Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. + If you see the value under PHASE column to be anything other than _Installing_ or _Succeeded_, please take a look at the pods in `olm` namespace and ensure that the pod starting with name `operatorhubio-catalog` is in Running state: ```shell - kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml + $ kubectl get pods -n olm + NAME READY STATUS RESTARTS AGE + operatorhubio-catalog-x24dq 0/1 CrashLoopBackOff 6 9m40s ``` - If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. - Wait for a few seconds for the operator to install. Confirm that it has been installed by running the below command: + If you see output like above where the pod is in CrashLoopBackOff state or any other state other than Running, delete the pod: ```shell - kubectl get csv -n operators + kubectl delete pods -n olm ``` \ No newline at end of file diff --git a/website/docs/getting-started/cluster-setup/openshift.md b/website/docs/getting-started/cluster-setup/openshift.md new file mode 100644 index 00000000000..b996fa42b6d --- /dev/null +++ b/website/docs/getting-started/cluster-setup/openshift.md @@ -0,0 +1,56 @@ +--- +title: OpenShift +sidebar_position: 2 +--- + +# Setup a CRC cluster +Please note that this documentation is only useful in setting up a development environment, it is not recommended for a production environment. + +This guide assumes that you have [installed and setup crc](https://crc.dev/crc/#installing-codeready-containers_gsg). + +If you are using an OpenShift cluster other than crc, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; operator installation is only possible with an admin user. + +**Agenda for this guide:** +* [Install the Service Binding Operator](#install-the-service-binding-operator) +* [Install an operator](#install-an-operator) +* [Verify the operator installation](#verify-the-operator-installation) + +## Install the Service Binding Operator +odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. + +1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. +2. Make sure that the Project is set to All Projects. +3. Search for `Service Binding Operator` in the search box under `All Items`. +4. Click on the `Service Binding Operator`; this should open a side pane. +5. Click on the `Install` button on the side pane; this should open an `Install Operator` page. +6. Make sure the `Installation mode` is set to `All namespaces on the cluster(default)`; `Installed Namespace` is set to `openshift-operators`; and `Approval Strategy` is `Automatic`. +7. Click on the `Install` button. +8. Wait until the operator is installed. +9. Once the operator is installed, you should see **Installed operator - ready for use**, and a **View Operator** button appears on the page. +10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. + +## Install an operator +1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. +2. Make sure that the Project is set to All Projects. +3. Search for an operator of your choice in the search box under `All Items`. +4. Click on the operator; this should open a side pane. +5. Click on the `Install` button on the side pane; this should open an `Install Operator` page. +6. Set the `Installation mode`, `Installed Namespace` and `Approval Strategy` as per your requirement. +7. Click on the `Install` button. +8. Wait until the operator is installed. +9. Once the operator is installed, you should see `Installed operator - ready for use`, and a `View Operator` button appears on the page. +10. Click on the `View Operator` button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. + +## Verify the operator installation +Once the operator is successfully installed on the crc/OpenShift cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: +```shell +odo catalog list services +``` +The output can look similar to: +```shell +$ odo catalog list services +Services available through Operators +NAME CRDs +datadog-operator.v0.6.0 DatadogAgent, DatadogMetric, DatadogMonitor +service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding +``` diff --git a/website/docs/getting-started/cluster-setup/operators.md b/website/docs/getting-started/cluster-setup/operators.md deleted file mode 100644 index 48f56193283..00000000000 --- a/website/docs/getting-started/cluster-setup/operators.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Installing Operators -sidebar_position: 4 ---- - -### Agenda -1. What is an operator?(./) -2. What is an operator backed service? -3. How to create and delete operator backed services? -4. How to link an odo component with an operator backed service? -5. How to install an operator into the cluster? - -### What is an operator? \ No newline at end of file From df3b08cb4397822ad4f24e4d97b52cab5d323d81 Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Tue, 10 Aug 2021 12:56:28 +0530 Subject: [PATCH 05/12] Add information about ingress controller --- .../cluster-setup/kubernetes.md | 24 +++++++++++++++---- website/docs/getting-started/features.md | 2 +- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 458ef495f91..0881b7b7917 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -15,6 +15,7 @@ If you are using a Kubernetes cluster other than minikube, this guide assumes th * [Install the Service Binding Operator](#install-the-service-binding-operator) * [Install an operator](#install-an-operator) * [Verify the operator installation](#verify-the-operator-installation) +* [Enable Ingress addon](#enable-ingress-addon) ## Install the OLM The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) @@ -63,11 +64,26 @@ service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding ``` If you do not see your installed operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. +## Enable Ingress addon +To access an application externally, odo creates a URL; addons such as ingress helps enable this feature on a Kubernetes cluster. + +To enable the **ingress** addon on a minikube cluster, run the following command: +```shell +minikube addons enable ingress +``` +To enable this feature on a Kubernetes cluster other than minikube, run the following command to install the default setup: +```shell +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.48.1/deploy/static/provider/cloud/deploy.yaml +``` +To learn more about setting up ingress, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. + +To learn more about ingress addon, see the [official kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). + ## Troubleshoot the Operator installation There are two ways to confirm that the operator has been installed properly. The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). -1. Verify that its pod started and is in “Running” state. - ```s****************hell +1. Verify that its pod started and is in “Running” state. + ```shell kubectl get pods -n operators ``` The output can look similar to: @@ -97,5 +113,5 @@ The output can look similar to: ``` If you see output like above where the pod is in CrashLoopBackOff state or any other state other than Running, delete the pod: ```shell - kubectl delete pods -n olm - ``` \ No newline at end of file + kubectl delete pods/ -n olm + ``` diff --git a/website/docs/getting-started/features.md b/website/docs/getting-started/features.md index 9e33b409f57..c9094a4d0e3 100644 --- a/website/docs/getting-started/features.md +++ b/website/docs/getting-started/features.md @@ -9,7 +9,7 @@ By using odo, application developers can develop, test, debug, and deploy micros odo follows "create and push" workflow for almost everything. It means, as a user, when you "create", something the information (or manifest) is stored in a configuration file, and then upon doing a "push" it gets created on the Kubernetes cluster. You can take an existing git repository and create an odo component from it, which can be pushed to a Kubernetes cluster. -odo helps "deploy and link" multiple components and services with each other. Using odo, developers can create and deploy services based on [Kubernetes Operators](https://github.com/operator-framework/) in their development cluster. These services can be created using any of the Operators available on [OperatorHub.io](https://operatorhub.io). Next, upon linking this service, odo injects the service configuration into the microservice created using odo. Your application can use this configuration to communicate with the Operator backed service. +odo helps "deploy and link" multiple components and services with each other. Using odo, developers can create and deploy services based on [Kubernetes Operators](https://github.com/operator-framework/) in their development cluster. These services can be created using any of the Operators available on [OperatorHub.io](https://operatorhub.io). Next, upon linking this service, odo injects the service configuration into the microservice created using odo. Your application can use this configuration to communicate with the Operator backed service. ### What can odo do? From da27dda7a9f1f076adf94ba3dc3c0321b087f8ff Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Wed, 11 Aug 2021 11:37:53 +0530 Subject: [PATCH 06/12] Requested changes, and remove agenda --- .../getting-started/cluster-setup/kubernetes.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 0881b7b7917..145b316d13b 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -4,20 +4,14 @@ sidebar_position: 1 --- # Setup a minikube cluster -Please note that this documentation is only useful in setting up a development environment, it is not recommended for a production environment. +*Note that this documentation is only useful in setting up a development environment; it is not recommended for a production environment.* +## Prerequisites This guide assumes that you have [installed minikube](https://minikube.sigs.k8s.io/docs/start/) on your system. -If you are using a Kubernetes cluster other than minikube, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; operator installation is only possible with an admin user. +If you are using a Kubernetes cluster other than minikube, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; Operator installation is only possible with an admin user. -**Agenda for this guide:** -* [Install the OLM](#install-the-olm) -* [Install the Service Binding Operator](#install-the-service-binding-operator) -* [Install an operator](#install-an-operator) -* [Verify the operator installation](#verify-the-operator-installation) -* [Enable Ingress addon](#enable-ingress-addon) - -## Install the OLM +## Install the Operator Lifecycle Manager(OLM) The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) addon to the minikube cluster. @@ -40,7 +34,7 @@ If you want to access this resource from other namespaces as well, add your targ See [Verify the Operator installation](#verify-the-operator-installation) to ensure the operator is installed successfully. -## Install an operator +## Install an Operator 1. Visit the [OperatorHub](https://operatorhub.io) website. 2. Search for an operator of your choice. 3. Navigate to its detail page. From f81964babeaef6849b2d36afd9b44f7d579e0dec Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Thu, 12 Aug 2021 14:00:53 +0530 Subject: [PATCH 07/12] Add requested changes and refactor --- Changelog.md | 2 + .../cluster-setup/kubernetes.md | 63 ++++++++++--------- .../cluster-setup/openshift.md | 23 +++---- 3 files changed, 46 insertions(+), 42 deletions(-) diff --git a/Changelog.md b/Changelog.md index d2c83427e5b..e5646d4a37e 100644 --- a/Changelog.md +++ b/Changelog.md @@ -28,6 +28,8 @@ ### Documentation - Documents steps for component creation ([#4982](https://github.com/openshift/odo/pull/4982)) +- Add Cluster setup documentation ([#4973](https://github.com/openshift/odo/pull/4973)) + ## 2.2.4 ### Feature/Enhancements diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 145b316d13b..a8484ad1f1e 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -3,36 +3,58 @@ title: Kubernetes sidebar_position: 1 --- -# Setup a minikube cluster -*Note that this documentation is only useful in setting up a development environment; it is not recommended for a production environment.* +# Setup a Kubernetes cluster +*Note that this guide is only helpful in setting up a development environment; this setup is not recommended for a production environment.* ## Prerequisites -This guide assumes that you have [installed minikube](https://minikube.sigs.k8s.io/docs/start/) on your system. +* This guide assumes that you have a Kubernetes cluster setup, this could also be a [minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. -If you are using a Kubernetes cluster other than minikube, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; Operator installation is only possible with an admin user. +* This guide also assumes that you have admin privileges to the cluster, since the operator installation is only possible with an admin user. + +## Enable Ingress +To access an application externally, odo creates a URL; installing an ingress-controller helps in using this feature on a Kubernetes cluster. + +To enable the Ingress feature on a Kubernetes cluster _other than minikube_, run the following command to install the default setup: +```shell +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.48.1/deploy/static/provider/cloud/deploy.yaml +``` +To learn more about enabling this feature on your cluster, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. + +**Minikube:** To install an ingress-controller on a minikube cluster, enable the **ingress** addon with the following command: +```shell +minikube addons enable ingress +```` +To learn more about ingress addon, see the [official kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). ## Install the Operator Lifecycle Manager(OLM) The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) -To install operators, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) addon to the minikube cluster. -Running the script below will take some time to install all the necessary namespaces and other resources. +What are Operators? +>The Operator pattern aims to capture the key aim of a human operator who is managing a service or set of services. Human operators who look after specific applications and services have deep knowledge of how the system ought to behave, how to deploy it, and how to react if there are problems. +> +>People who run workloads on Kubernetes often like to use automation to take care of repeatable tasks. The Operator pattern captures how you can write code to automate a task beyond what Kubernetes itself provides. +> [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) + +To install an operator, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) on the cluster. ```shell curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.3/install.sh | bash -s v0.18.3 ``` +Running the script will take some time to install all the necessary resources. -To install OLM on a Kubernetes cluster setup other than minikube, please refer the [installation instructions on GitHub](https://github.com/operator-framework/operator-lifecycle-manager/#installation). +Note: Check the OLM [release page](https://github.com/operator-framework/operator-lifecycle-manager/releases/) to use the latest version. ## Install the Service Binding Operator -odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. +odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps to connect an odo component to a service or another component. -Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. Running the command below will create the necessary resource in `operators` namespace. +Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. ```shell kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml ``` +Running the command will create the necessary resource in `operators` namespace. If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. -See [Verify the Operator installation](#verify-the-operator-installation) to ensure the operator is installed successfully. +See [Verify the Operator installation](#verify-the-operator-installation) to ensure that the operator was installed successfully. ## Install an Operator 1. Visit the [OperatorHub](https://operatorhub.io) website. @@ -40,11 +62,11 @@ See [Verify the Operator installation](#verify-the-operator-installation) to ens 3. Navigate to its detail page. 4. Click on `Install`. 5. Follow the instruction in the installation popup. -6. [Verify the operator was installed successfully](#verify-the-operator-installation). +6. Wait for a few seconds for the operator to install. +7. [Verify the operator installation](#verify-the-operator-installation). ## Verify the Operator installation -Wait for a few seconds for the operator to install. -To verify that the operator is installed successfully and see the CRDs associated with it, run the following command. +Once the operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` @@ -58,21 +80,6 @@ service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding ``` If you do not see your installed operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. -## Enable Ingress addon -To access an application externally, odo creates a URL; addons such as ingress helps enable this feature on a Kubernetes cluster. - -To enable the **ingress** addon on a minikube cluster, run the following command: -```shell -minikube addons enable ingress -``` -To enable this feature on a Kubernetes cluster other than minikube, run the following command to install the default setup: -```shell -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.48.1/deploy/static/provider/cloud/deploy.yaml -``` -To learn more about setting up ingress, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. - -To learn more about ingress addon, see the [official kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). - ## Troubleshoot the Operator installation There are two ways to confirm that the operator has been installed properly. The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). diff --git a/website/docs/getting-started/cluster-setup/openshift.md b/website/docs/getting-started/cluster-setup/openshift.md index b996fa42b6d..7dad7e15997 100644 --- a/website/docs/getting-started/cluster-setup/openshift.md +++ b/website/docs/getting-started/cluster-setup/openshift.md @@ -3,17 +3,12 @@ title: OpenShift sidebar_position: 2 --- -# Setup a CRC cluster -Please note that this documentation is only useful in setting up a development environment, it is not recommended for a production environment. +# Setup an OpenShift cluster +*Note that this guide is only helpful in setting up a development environment; this setup is not recommended for a production environment.* -This guide assumes that you have [installed and setup crc](https://crc.dev/crc/#installing-codeready-containers_gsg). - -If you are using an OpenShift cluster other than crc, this guide assumes that you have admin privileges to the cluster and are logged in with the admin user; operator installation is only possible with an admin user. - -**Agenda for this guide:** -* [Install the Service Binding Operator](#install-the-service-binding-operator) -* [Install an operator](#install-an-operator) -* [Verify the operator installation](#verify-the-operator-installation) +## Prerequisites +* This guide assumes that you have an OpenShift cluster setup, this could also be a [crc](https://crc.dev/crc/#installing-codeready-containers_gsg) cluster. +* This guide also assumes that you have admin privileges to the cluster, since Operator installation is only possible with an admin user. ## Install the Service Binding Operator odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. @@ -29,7 +24,7 @@ odo uses [Service Binding Operator](https://operatorhub.io/operator/service-bind 9. Once the operator is installed, you should see **Installed operator - ready for use**, and a **View Operator** button appears on the page. 10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. -## Install an operator +## Install an Operator 1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. 2. Make sure that the Project is set to All Projects. 3. Search for an operator of your choice in the search box under `All Items`. @@ -37,12 +32,12 @@ odo uses [Service Binding Operator](https://operatorhub.io/operator/service-bind 5. Click on the `Install` button on the side pane; this should open an `Install Operator` page. 6. Set the `Installation mode`, `Installed Namespace` and `Approval Strategy` as per your requirement. 7. Click on the `Install` button. -8. Wait until the operator is installed. -9. Once the operator is installed, you should see `Installed operator - ready for use`, and a `View Operator` button appears on the page. +8. Wait until the Operator is installed. +9. Once the Operator is installed, you should see `Installed operator - ready for use`, and a `View Operator` button appears on the page. 10. Click on the `View Operator` button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. ## Verify the operator installation -Once the operator is successfully installed on the crc/OpenShift cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: +Once the operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` From 6fedb44f67930e780a650f5c392d3c8a26ff3eff Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Thu, 12 Aug 2021 19:53:31 +0530 Subject: [PATCH 08/12] Rebase and reorg --- .../cluster-setup/kubernetes.md | 9 ++-- .../cluster-setup/openshift.md | 41 +++++++++++-------- 2 files changed, 29 insertions(+), 21 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index a8484ad1f1e..724d9f269c6 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -8,7 +8,6 @@ sidebar_position: 1 ## Prerequisites * This guide assumes that you have a Kubernetes cluster setup, this could also be a [minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. - * This guide also assumes that you have admin privileges to the cluster, since the operator installation is only possible with an admin user. ## Enable Ingress @@ -29,11 +28,13 @@ To learn more about ingress addon, see the [official kubernetes documentation](h ## Install the Operator Lifecycle Manager(OLM) The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) -What are Operators? +[//]: # (Move this section to Architecture > Service Binding or create a new Operators doc) +What are Operators? >The Operator pattern aims to capture the key aim of a human operator who is managing a service or set of services. Human operators who look after specific applications and services have deep knowledge of how the system ought to behave, how to deploy it, and how to react if there are problems. > >People who run workloads on Kubernetes often like to use automation to take care of repeatable tasks. The Operator pattern captures how you can write code to automate a task beyond what Kubernetes itself provides. > [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) +[//]: # (Move until here) To install an operator, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) on the cluster. ```shell @@ -60,7 +61,7 @@ See [Verify the Operator installation](#verify-the-operator-installation) to ens 1. Visit the [OperatorHub](https://operatorhub.io) website. 2. Search for an operator of your choice. 3. Navigate to its detail page. -4. Click on `Install`. +4. Click on **Install**. 5. Follow the instruction in the installation popup. 6. Wait for a few seconds for the operator to install. 7. [Verify the operator installation](#verify-the-operator-installation). @@ -89,7 +90,7 @@ The examples you may see in this guide uses [Datadog Operator](https://operatorh ``` The output can look similar to: ```shell - $ kubectl get csv -n operators + $ kubectl get csv -n operators NAME READY STATUS RESTARTS AGE datadog-operator-manager-5db67c7f4-hgb59 1/1 Running 0 2m13s service-binding-operator-c8d7587b8-lxztx 1/1 Running 5 6d23h diff --git a/website/docs/getting-started/cluster-setup/openshift.md b/website/docs/getting-started/cluster-setup/openshift.md index 7dad7e15997..b545b67d2da 100644 --- a/website/docs/getting-started/cluster-setup/openshift.md +++ b/website/docs/getting-started/cluster-setup/openshift.md @@ -9,35 +9,42 @@ sidebar_position: 2 ## Prerequisites * This guide assumes that you have an OpenShift cluster setup, this could also be a [crc](https://crc.dev/crc/#installing-codeready-containers_gsg) cluster. * This guide also assumes that you have admin privileges to the cluster, since Operator installation is only possible with an admin user. +[//]: # (Move this section to Architecture > Service Binding or create a new Operators doc) +**What are Operators?** +>The Operator pattern aims to capture the key aim of a human operator who is managing a service or set of services. Human operators who look after specific applications and services have deep knowledge of how the system ought to behave, how to deploy it, and how to react if there are problems. +> +>People who run workloads on Kubernetes often like to use automation to take care of repeatable tasks. The Operator pattern captures how you can write code to automate a task beyond what Kubernetes itself provides. +> [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) +[//]: # (Move until here) ## Install the Service Binding Operator odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. 1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. 2. Make sure that the Project is set to All Projects. -3. Search for `Service Binding Operator` in the search box under `All Items`. -4. Click on the `Service Binding Operator`; this should open a side pane. -5. Click on the `Install` button on the side pane; this should open an `Install Operator` page. -6. Make sure the `Installation mode` is set to `All namespaces on the cluster(default)`; `Installed Namespace` is set to `openshift-operators`; and `Approval Strategy` is `Automatic`. -7. Click on the `Install` button. -8. Wait until the operator is installed. -9. Once the operator is installed, you should see **Installed operator - ready for use**, and a **View Operator** button appears on the page. -10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. +3. Search for _**Service Binding Operator**_ in the search box under **All Items**. +4. Click on the **Service Binding Operator**; this should open a side pane. +5. Click on the **Install** button on the side pane; this should open an **Install Operator** page. +6. Make sure the **Installation mode** is set to "_All namespaces on the cluster(default)_"; **Installed Namespace** is set to "_openshift-operators_"; and **Approval Strategy** is "_Automatic_". +7. Click on the **Install** button. +8. Wait until the Operator is installed. +9. Once the Operator is installed, you should see **_Installed operator - ready for use_**, and a **View Operator** button appears on the page. +10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your Operator. ## Install an Operator 1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. 2. Make sure that the Project is set to All Projects. -3. Search for an operator of your choice in the search box under `All Items`. -4. Click on the operator; this should open a side pane. -5. Click on the `Install` button on the side pane; this should open an `Install Operator` page. -6. Set the `Installation mode`, `Installed Namespace` and `Approval Strategy` as per your requirement. -7. Click on the `Install` button. +3. Search for an Operator of your choice in the search box under **All Items**. +4. Click on the Operator; this should open a side pane. +5. Click on the **Install** button on the side pane; this should open an **Install Operator** page. +6. Set the **Installation mode**, **Installed Namespace** and **Approval Strategy** as per your requirement. +7. Click on the **Install** button. 8. Wait until the Operator is installed. -9. Once the Operator is installed, you should see `Installed operator - ready for use`, and a `View Operator` button appears on the page. -10. Click on the `View Operator` button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your operator. +9. Once the Operator is installed, you should see _**Installed operator - ready for use**_, and a **View Operator** button appears on the page. +10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your Operator. -## Verify the operator installation -Once the operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: +## Verify the Operator installation +Once the Operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` From e07132870fb240b5f04c73ebd2ba781f8d309edd Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Tue, 17 Aug 2021 18:23:29 +0530 Subject: [PATCH 09/12] Changes requested by Philippe --- .../cluster-setup/kubernetes.md | 55 ++++++++++--------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 724d9f269c6..dfd5adfcdbf 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -3,29 +3,29 @@ title: Kubernetes sidebar_position: 1 --- -# Setup a Kubernetes cluster +# Setting up a Kubernetes cluster *Note that this guide is only helpful in setting up a development environment; this setup is not recommended for a production environment.* ## Prerequisites -* This guide assumes that you have a Kubernetes cluster setup, this could also be a [minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. -* This guide also assumes that you have admin privileges to the cluster, since the operator installation is only possible with an admin user. +* You have a Kubernetes cluster setup, this could for example be a [minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. +* You have admin privileges to the cluster, since the operator installation is only possible with an admin user. -## Enable Ingress -To access an application externally, odo creates a URL; installing an ingress-controller helps in using this feature on a Kubernetes cluster. - -To enable the Ingress feature on a Kubernetes cluster _other than minikube_, run the following command to install the default setup: -```shell -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.48.1/deploy/static/provider/cloud/deploy.yaml -``` -To learn more about enabling this feature on your cluster, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. +## Enabling Ingress +To access an application externally, you will create _URLs_ using odo, which are implemented on a Kubernetes cluster by the ingress resources; installing an ingress-controller helps in using this feature on a Kubernetes cluster. **Minikube:** To install an ingress-controller on a minikube cluster, enable the **ingress** addon with the following command: ```shell minikube addons enable ingress ```` -To learn more about ingress addon, see the [official kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). +To learn more about ingress addon, see [the documentation on Kubernetes website](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). + +**Other Kubernetes Cluster**: To enable the Ingress feature on a Kubernetes cluster _other than minikube_, using the nginx controller see [the official nginx installation documentation](https://kubernetes.github.io/ingress-nginx/deploy/). -## Install the Operator Lifecycle Manager(OLM) +To use a different controller, see [the ingress controller documentation](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). + +To learn more about enabling this feature on your cluster, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. + +## Installing the Operator Lifecycle Manager(OLM) The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) [//]: # (Move this section to Architecture > Service Binding or create a new Operators doc) @@ -36,38 +36,39 @@ What are Operators? > [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) [//]: # (Move until here) -To install an operator, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) on the cluster. +To install an Operator, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) on the cluster. ```shell curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.3/install.sh | bash -s v0.18.3 ``` -Running the script will take some time to install all the necessary resources. +Running the script will take some time to install all the necessary resources in the Kubernetes cluster including the `OperatorGroup` resource,.... Note: Check the OLM [release page](https://github.com/operator-framework/operator-lifecycle-manager/releases/) to use the latest version. -## Install the Service Binding Operator +## Installing the Service Binding Operator odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps to connect an odo component to a service or another component. -Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). To install an operator, we need to make sure that the namespace contains `OperatorGroup` resource. +Operators can be installed in a specific namespace or across the cluster(i.e. in all the namespaces). ```shell kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml ``` -Running the command will create the necessary resource in `operators` namespace. +Running the command will create the necessary resource in the `operators` namespace. If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. -See [Verify the Operator installation](#verify-the-operator-installation) to ensure that the operator was installed successfully. +See [Verifying the Operator installation](#verifying-the-operator-installation) to ensure that the operator was installed successfully. -## Install an Operator +## Installing an Operator 1. Visit the [OperatorHub](https://operatorhub.io) website. -2. Search for an operator of your choice. +2. Search for an Operator of your choice. 3. Navigate to its detail page. 4. Click on **Install**. -5. Follow the instruction in the installation popup. -6. Wait for a few seconds for the operator to install. -7. [Verify the operator installation](#verify-the-operator-installation). +5. Follow the instruction in the installation popup. Please make sure to install the operator in your desired namespace or cluster-wide, depending on your choice and the Operator capability. +6. [Verifying the operator installation](#verifying-the-operator-installation). + +## Verifying the Operator installation +Wait for a few seconds for the Operator to install. -## Verify the Operator installation -Once the operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: +Once the operator is successfully installed on the cluster, you can use `odo` to verify the Operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` @@ -81,7 +82,7 @@ service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding ``` If you do not see your installed operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. -## Troubleshoot the Operator installation +## Troubleshooting the Operator installation There are two ways to confirm that the operator has been installed properly. The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). 1. Verify that its pod started and is in “Running” state. From 5873157a8a3460aeca2abdb77911eb890c2e6710 Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Fri, 20 Aug 2021 12:15:50 +0530 Subject: [PATCH 10/12] operator->Operator and changes suggested by feloy --- .../getting-started/cluster-setup/kubernetes.md | 14 +++++++------- .../getting-started/cluster-setup/openshift.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index dfd5adfcdbf..2413cf93993 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -8,7 +8,7 @@ sidebar_position: 1 ## Prerequisites * You have a Kubernetes cluster setup, this could for example be a [minikube](https://minikube.sigs.k8s.io/docs/start/) cluster. -* You have admin privileges to the cluster, since the operator installation is only possible with an admin user. +* You have admin privileges to the cluster, since the Operator installation is only possible with an admin user. ## Enabling Ingress To access an application externally, you will create _URLs_ using odo, which are implemented on a Kubernetes cluster by the ingress resources; installing an ingress-controller helps in using this feature on a Kubernetes cluster. @@ -55,20 +55,20 @@ Running the command will create the necessary resource in the `operators` namesp If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. -See [Verifying the Operator installation](#verifying-the-operator-installation) to ensure that the operator was installed successfully. +See [Verifying the Operator installation](#verifying-the-operator-installation) to ensure that the Operator was installed successfully. ## Installing an Operator 1. Visit the [OperatorHub](https://operatorhub.io) website. 2. Search for an Operator of your choice. 3. Navigate to its detail page. 4. Click on **Install**. -5. Follow the instruction in the installation popup. Please make sure to install the operator in your desired namespace or cluster-wide, depending on your choice and the Operator capability. -6. [Verifying the operator installation](#verifying-the-operator-installation). +5. Follow the instruction in the installation popup. Please make sure to install the Operator in your desired namespace or cluster-wide, depending on your choice and the Operator capability. +6. [Verifying the Operator installation](#verifying-the-operator-installation). ## Verifying the Operator installation Wait for a few seconds for the Operator to install. -Once the operator is successfully installed on the cluster, you can use `odo` to verify the Operator installation and see the CRDs associated with it; run the following command: +Once the Operator is successfully installed on the cluster, you can use `odo` to verify the Operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` @@ -80,10 +80,10 @@ NAME CRDs datadog-operator.v0.6.0 DatadogAgent, DatadogMetric, DatadogMonitor service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding ``` -If you do not see your installed operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. +If you do not see your installed Operator in the list, follow the [troubleshooting guide](#troubleshoot-the-operator-installation) to find the issue and debug it. ## Troubleshooting the Operator installation -There are two ways to confirm that the operator has been installed properly. +There are two ways to confirm that the Operator has been installed properly. The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). 1. Verify that its pod started and is in “Running” state. ```shell diff --git a/website/docs/getting-started/cluster-setup/openshift.md b/website/docs/getting-started/cluster-setup/openshift.md index b545b67d2da..13db46783e8 100644 --- a/website/docs/getting-started/cluster-setup/openshift.md +++ b/website/docs/getting-started/cluster-setup/openshift.md @@ -44,7 +44,7 @@ odo uses [Service Binding Operator](https://operatorhub.io/operator/service-bind 10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your Operator. ## Verify the Operator installation -Once the Operator is successfully installed on the cluster, you can also use `odo` to verify the operator installation and see the CRDs associated with it; run the following command: +Once the Operator is successfully installed on the cluster, you can also use `odo` to verify the Operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services ``` @@ -53,6 +53,6 @@ The output can look similar to: $ odo catalog list services Services available through Operators NAME CRDs -datadog-operator.v0.6.0 DatadogAgent, DatadogMetric, DatadogMonitor + datadog-operator.v0.6.0 DatadogAgent, DatadogMetric, DatadogMonitor service-binding-operator.v0.9.1 ServiceBinding, ServiceBinding ``` From 15f745fc519bc01ef06d4a568351e76a755c1224 Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Fri, 20 Aug 2021 15:12:19 +0530 Subject: [PATCH 11/12] Add changes requested by feloy --- .../cluster-setup/kubernetes.md | 23 ++++++++++--------- .../cluster-setup/openshift.md | 13 +++++++---- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index 2413cf93993..e2db1d1a713 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -11,22 +11,22 @@ sidebar_position: 1 * You have admin privileges to the cluster, since the Operator installation is only possible with an admin user. ## Enabling Ingress -To access an application externally, you will create _URLs_ using odo, which are implemented on a Kubernetes cluster by the ingress resources; installing an ingress-controller helps in using this feature on a Kubernetes cluster. +To access an application externally, you will create _URLs_ using odo, which are implemented on a Kubernetes cluster by Ingress resources; installing an Ingress controller helps in using this feature on a Kubernetes cluster. -**Minikube:** To install an ingress-controller on a minikube cluster, enable the **ingress** addon with the following command: +**Minikube:** To install an Ingress controller on a minikube cluster, enable the **ingress** addon with the following command: ```shell minikube addons enable ingress ```` To learn more about ingress addon, see [the documentation on Kubernetes website](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). -**Other Kubernetes Cluster**: To enable the Ingress feature on a Kubernetes cluster _other than minikube_, using the nginx controller see [the official nginx installation documentation](https://kubernetes.github.io/ingress-nginx/deploy/). +*Other Kubernetes Cluster**: To enable the Ingress feature on a Kubernetes cluster _other than minikube_, using the NGINX Ingress controller see [the official NGINX Ingress controller installation documentation](https://kubernetes.github.io/ingress-nginx/deploy/). -To use a different controller, see [the ingress controller documentation](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). +To use a different controller, see [the Ingress controller documentation](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). To learn more about enabling this feature on your cluster, see the [Ingress prerequisites](https://kubernetes.io/docs/concepts/services-networking/ingress/#prerequisites) on the official kubernetes documentation. -## Installing the Operator Lifecycle Manager(OLM) -The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way.[(Source)](https://olm.operatorframework.io/) +## Installing the Operator Lifecycle Manager (OLM) +The Operator Lifecycle Manager(OLM) is a component of the Operator Framework, an open source toolkit to manage Kubernetes native applications, called Operators, in a streamlined and scalable way. [(Source)](https://olm.operatorframework.io/) [//]: # (Move this section to Architecture > Service Binding or create a new Operators doc) What are Operators? @@ -53,17 +53,18 @@ kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml ``` Running the command will create the necessary resource in the `operators` namespace. -If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list. +If you want to access this resource from other namespaces as well, add your target namespace to `.spec.targetNamespaces` list in the `service-binding-operator.yaml` file before running `kubectl create`. See [Verifying the Operator installation](#verifying-the-operator-installation) to ensure that the Operator was installed successfully. ## Installing an Operator +To install an operator from the OperatorHub website: 1. Visit the [OperatorHub](https://operatorhub.io) website. 2. Search for an Operator of your choice. 3. Navigate to its detail page. 4. Click on **Install**. 5. Follow the instruction in the installation popup. Please make sure to install the Operator in your desired namespace or cluster-wide, depending on your choice and the Operator capability. -6. [Verifying the Operator installation](#verifying-the-operator-installation). +6. [Verify the Operator installation](#verifying-the-operator-installation). ## Verifying the Operator installation Wait for a few seconds for the Operator to install. @@ -84,19 +85,19 @@ If you do not see your installed Operator in the list, follow the [troubleshooti ## Troubleshooting the Operator installation There are two ways to confirm that the Operator has been installed properly. -The examples you may see in this guide uses [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). +The examples you may see in this guide use [Datadog Operator](https://operatorhub.io/operator/datadog-operator) and [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator). 1. Verify that its pod started and is in “Running” state. ```shell kubectl get pods -n operators ``` The output can look similar to: ```shell - $ kubectl get csv -n operators + $ kubectl get pods -n operators NAME READY STATUS RESTARTS AGE datadog-operator-manager-5db67c7f4-hgb59 1/1 Running 0 2m13s service-binding-operator-c8d7587b8-lxztx 1/1 Running 5 6d23h ``` -2. Verify that the csv is in Succeeded or Installing phase. +2. Verify that the ClusterServiceVersion (csv) resource is in Succeeded or Installing phase. ```shell kubectl get csv -n operators ``` diff --git a/website/docs/getting-started/cluster-setup/openshift.md b/website/docs/getting-started/cluster-setup/openshift.md index 13db46783e8..c89cac4c003 100644 --- a/website/docs/getting-started/cluster-setup/openshift.md +++ b/website/docs/getting-started/cluster-setup/openshift.md @@ -7,8 +7,9 @@ sidebar_position: 2 *Note that this guide is only helpful in setting up a development environment; this setup is not recommended for a production environment.* ## Prerequisites -* This guide assumes that you have an OpenShift cluster setup, this could also be a [crc](https://crc.dev/crc/#installing-codeready-containers_gsg) cluster. -* This guide also assumes that you have admin privileges to the cluster, since Operator installation is only possible with an admin user. +* You have an OpenShift cluster setup, this could for example be a [crc](https://crc.dev/crc/#installing-codeready-containers_gsg) cluster. +* You have admin privileges to the cluster, since Operator installation is only possible with an admin user. + [//]: # (Move this section to Architecture > Service Binding or create a new Operators doc) **What are Operators?** >The Operator pattern aims to capture the key aim of a human operator who is managing a service or set of services. Human operators who look after specific applications and services have deep knowledge of how the system ought to behave, how to deploy it, and how to react if there are problems. @@ -17,9 +18,10 @@ sidebar_position: 2 > [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) [//]: # (Move until here) -## Install the Service Binding Operator +## Installing the Service Binding Operator odo uses [Service Binding Operator](https://operatorhub.io/operator/service-binding-operator) to provide the `odo link` feature which helps connect an odo component to a service or another component. +To install the Service Binding Operator from the OpenShift web console: 1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. 2. Make sure that the Project is set to All Projects. 3. Search for _**Service Binding Operator**_ in the search box under **All Items**. @@ -31,7 +33,8 @@ odo uses [Service Binding Operator](https://operatorhub.io/operator/service-bind 9. Once the Operator is installed, you should see **_Installed operator - ready for use_**, and a **View Operator** button appears on the page. 10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your Operator. -## Install an Operator +## Installing an Operator +To install an Operator from the OpenShift web console: 1. Login to the OpenShift web console with admin, and navigate to Operators > OperatorHub. 2. Make sure that the Project is set to All Projects. 3. Search for an Operator of your choice in the search box under **All Items**. @@ -43,7 +46,7 @@ odo uses [Service Binding Operator](https://operatorhub.io/operator/service-bind 9. Once the Operator is installed, you should see _**Installed operator - ready for use**_, and a **View Operator** button appears on the page. 10. Click on the **View Operator** button; this should take you to Operators > Installed Operators > Operator details page, and you should be able to see details of your Operator. -## Verify the Operator installation +## Verifying the Operator installation Once the Operator is successfully installed on the cluster, you can also use `odo` to verify the Operator installation and see the CRDs associated with it; run the following command: ```shell odo catalog list services From 80cc7e68e5a67e3de20c98b83efa227ecf37ca4d Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Fri, 20 Aug 2021 15:59:24 +0530 Subject: [PATCH 12/12] Add resources --- website/docs/getting-started/cluster-setup/kubernetes.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/website/docs/getting-started/cluster-setup/kubernetes.md b/website/docs/getting-started/cluster-setup/kubernetes.md index e2db1d1a713..b68a4d2c046 100644 --- a/website/docs/getting-started/cluster-setup/kubernetes.md +++ b/website/docs/getting-started/cluster-setup/kubernetes.md @@ -19,7 +19,7 @@ minikube addons enable ingress ```` To learn more about ingress addon, see [the documentation on Kubernetes website](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/). -*Other Kubernetes Cluster**: To enable the Ingress feature on a Kubernetes cluster _other than minikube_, using the NGINX Ingress controller see [the official NGINX Ingress controller installation documentation](https://kubernetes.github.io/ingress-nginx/deploy/). +**Other Kubernetes Cluster**: To enable the Ingress feature on a Kubernetes cluster _other than minikube_, using the NGINX Ingress controller see [the official NGINX Ingress controller installation documentation](https://kubernetes.github.io/ingress-nginx/deploy/). To use a different controller, see [the Ingress controller documentation](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). @@ -34,13 +34,14 @@ What are Operators? > >People who run workloads on Kubernetes often like to use automation to take care of repeatable tasks. The Operator pattern captures how you can write code to automate a task beyond what Kubernetes itself provides. > [(Source)](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#motivation) + [//]: # (Move until here) To install an Operator, we will first need to install OLM [(Operator Lifecycle Manager)](https://olm.operatorframework.io/) on the cluster. ```shell curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.3/install.sh | bash -s v0.18.3 ``` -Running the script will take some time to install all the necessary resources in the Kubernetes cluster including the `OperatorGroup` resource,.... +Running the script will take some time to install all the necessary resources in the Kubernetes cluster including the `OperatorGroup` resource. Note: Check the OLM [release page](https://github.com/operator-framework/operator-lifecycle-manager/releases/) to use the latest version.