diff --git a/README.md b/README.md index 40c4c3e..f738687 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,43 @@ This project was created by [@lburgazzoli in this repository](https://github.com/lburgazzoli/dapr-operator-ng) and donated to the Dapr Sandbox organization. -## Setup +## Installation -TBD \ No newline at end of file +The `Dapr Kubernetes Operator` was created with the intention of running through the [Operator Lifecycle Manager][olm_home], +specifically on [OpenShift 4][openshift_home]. This is where the operator shines most, as it leverages the powerful +features built into the latest version of OpenShift. + +That being said, the operator can be installed and provide the same functionality on any Kubernetes cluster. The +following methods are provided for installing the operator. + +### OpenShift + +The operator is published as part of the built-in Community Operators in the Operator Hub on OpenShift 4. See the +[OpenShift Install Guide][install_openshift] for more information on installing on the OpenShift platorm. + +### Operator Lifecycle Manager + +Using the Operator Lifecycle Manager to install and manage the `Dapr Kubernetes Operator` is the preferred method. The operator +is published to [operatorhub.io][operatorhub_link]. Following the installation process there should work for most OLM +installations. + +Look at the [OLM Install Guide][install_olm] for an example using this approach with minikube. + +### Manual Installation + +The operator can be installed manually if desired. + +!!! info + The manual installation method requires cluster credentials that provide the `cluster-admin` ClusterRole or + equivalent. + +The [Manual Installation Guide][install_manual] provides the steps needed to manually install the operator on any +Kubernetes cluster. + + +[install_manual]:./docs/install/manual.md +[install_olm]:./docs/install/olm.md +[install_openshift]:./docs/install/openshift.md +[olm_home]:https://github.com/operator-framework/operator-lifecycle-manager +[openshift_home]:https://try.openshift.com +[operatorhub_link]:https://operatorhub.io/operator/dapr-kubernetes-operator \ No newline at end of file diff --git a/config/samples/olm/catalog.yaml b/config/samples/olm/catalog.yaml index 4b04140..ed0f551 100644 --- a/config/samples/olm/catalog.yaml +++ b/config/samples/olm/catalog.yaml @@ -2,10 +2,10 @@ apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: daprio-catalog - namespace: openshift-marketplace + namespace: olm spec: sourceType: grpc - image: docker.io/daprio/dapr-kubernetes-operator-catalog:latest + image: ghcr.io/dapr-sandbox/dapr-kubernetes-operator-catalog:latest displayName: dapr.io catalog grpcPodConfig: securityContextConfig: restricted diff --git a/config/samples/olm/kustomization.yaml b/config/samples/olm/kustomization.yaml new file mode 100644 index 0000000..712062c --- /dev/null +++ b/config/samples/olm/kustomization.yaml @@ -0,0 +1,5 @@ +resources: + - namespace.yaml + - catalog.yaml + - operator_group.yaml + - subscription.yaml \ No newline at end of file diff --git a/config/samples/olm/namespace.yaml b/config/samples/olm/namespace.yaml new file mode 100644 index 0000000..690a4a1 --- /dev/null +++ b/config/samples/olm/namespace.yaml @@ -0,0 +1,4 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: dapr-system \ No newline at end of file diff --git a/config/samples/olm/operator_group.yaml b/config/samples/olm/operator_group.yaml new file mode 100644 index 0000000..d531c1e --- /dev/null +++ b/config/samples/olm/operator_group.yaml @@ -0,0 +1,5 @@ +apiVersion: operators.coreos.com/v1 +kind: OperatorGroup +metadata: + name: dapr-operator + namespace: dapr-system \ No newline at end of file diff --git a/config/samples/olm/subscription.yaml b/config/samples/olm/subscription.yaml index 82d4c1e..975133c 100644 --- a/config/samples/olm/subscription.yaml +++ b/config/samples/olm/subscription.yaml @@ -2,10 +2,10 @@ apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: dapr-control-plane - namespace: openshift-operators + namespace: dapr-system spec: channel: alpha name: dapr-kubernetes-operator installPlanApproval: Automatic source: daprio-catalog - sourceNamespace: openshift-marketplace + sourceNamespace: olm diff --git a/docs/install/manual.md b/docs/install/manual.md new file mode 100644 index 0000000..82499ce --- /dev/null +++ b/docs/install/manual.md @@ -0,0 +1,8 @@ + Manual Installation using kustomize + +The following steps can be used to manually install the operator on any Kubernetes environment with minimal overhead. + +!!! info + Several of the steps in this process require the `cluster-admin` ClusterRole or equivalent. + +TBD \ No newline at end of file diff --git a/docs/install/olm.md b/docs/install/olm.md new file mode 100644 index 0000000..f287beb --- /dev/null +++ b/docs/install/olm.md @@ -0,0 +1,113 @@ +# OLM Install + +The following steps can be used to install the operator using the [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager) on any Kubernetes +environment. + +## Cluster Setup + +This guide uses [minikube](https://minikube.sigs.k8s.io/) to deploy a Kubernetes cluster locally, follow the +instructions for your platform to install. If you already have a Kubernetes cluster ready to go, skip to +the [OLM](#operator-lifecycle-manager) section. + +Run minikube with a dedicated profile. Adjust the system resources as needed for your platform. + +```bash +minikube start -p dapr +``` + +## Operator Lifecycle Manager + +Install the OLM components manually. If you already have OLM installed, skip to the [Operator](#operator-install) section. + +Either + +- install OLM from here: https://github.com/operator-framework/operator-lifecycle-manager/releases + +or + +- install using the `operator-sdk` command +```bash +operator-sdk olm install +``` + +Verify that OLM is installed. There should be two new namespaces, `olm` and `operators` created as a result. + +```bash +kubectl get ns +``` + +``` +NAME STATUS AGE +kube-system Active 7d1h +default Active 7d1h +kube-public Active 7d1h +kube-node-lease Active 7d1h +operators Active 94s +olm Active 94s +``` + +Verify that the OLM Pods are running in the `olm` namespace. + +```bash +kubectl get pods -n olm +``` + +``` +NAME READY STATUS RESTARTS AGE +catalog-operator-569cd6998d-h5cbp 1/1 Running 0 39s +olm-operator-6fbbcd8c8b-qzv47 1/1 Running 0 39s +operatorhubio-catalog-m7qxq 1/1 Running 0 31s +packageserver-6cb8b48df4-wp89m 1/1 Running 0 30s +packageserver-6cb8b48df4-ww62h 1/1 Running 0 30s +``` + +That's it, OLM should be installed and availble to manage the Dapr Operator. + +## Operator Install + +The [dapr-kubernetes-operator](https://github.com/dapr-sandbox/dapr-kubernetes-operator/) provides a pre-made kustomization file to deploy the Dapr Kubernetes Operator with OLM: + +```bash +kubectl apply -k https://github.com/dapr-sandbox/dapr-kubernetes-operator//config/samples/olm +``` + +This command should: + +- Create a `dapr-system` namespace +- Create a `CatalogSource` in the `olm` namespace + ```bash + ➜ kubectl get catalogsources -n olm + NAME DISPLAY TYPE PUBLISHER AGE + daprio-catalog dapr.io catalog grpc dapr.io 11m + operatorhubio-catalog Community Operators grpc OperatorHub.io 18m + ``` +- Create an `OperatorGroup` in the `dapr-system` namespace + ```bash + ➜ kubectl get operatorgroups -n dapr-system + NAME AGE + dapr-operator 12m + ``` +- Create a new `Subscription` for theDapr Kubernetes Operator in the new `dapr-system` namespace. + ```bash + ➜ kubectl get subscriptions.operators.coreos.com -n dapr-system + NAME PACKAGE SOURCE CHANNEL + dapr-control-plane dapr-kubernetes-operator daprio-catalog alpha + ``` + The subscription should result in an `InstallPlan` being created in the `dapr-system` namespace which finally result in the `dapr-control-plane` Pod running + ```bash + ➜ kubectl get pods -n dapr-system + NAME READY STATUS RESTARTS AGE + dapr-control-plane-66866765b9-nzb6t 1/1 Running 0 13m + ``` + +## Usage + +Once the operator is installed and running, new `DaprControlPlane` resources can be created. + +## Cleanup + +You can clean up the operator resources by running the following commands. + +```bash +kubectl delete -k https://github.com/dapr-sandbox/dapr-kubernetes-operator//config/samples/olm +``` diff --git a/docs/install/openshift.md b/docs/install/openshift.md new file mode 100644 index 0000000..0bd36ea --- /dev/null +++ b/docs/install/openshift.md @@ -0,0 +1,14 @@ +# OpenShift Install + +This guide uses [OpenShift 4](https://try.openshift.com/), follow the guide for your platform to install. + +Once the OpenShift cluster is up and running, the operator can be deployed. +The preferred method to install the operator is using the OpenShift console. +The operator can also be installed manually if desired. + +## Console Install + +The operator is published in the Operator Hub with the OpenShift console. Log into the console using the URL for your +cluster and select the Operators link, then select the OperatorHub link to display the list of operators. + +Select the operator named `Dapr Kubernetes Operator` and click the **Install** button.