Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add operator hub documentation #3158

Merged
merged 1 commit into from
May 14, 2020
Merged

Add operator hub documentation #3158

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 68 additions & 203 deletions docs/public/operator-hub.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,271 +1,136 @@
:source-highlighter: pygments
== Introduction to Operators

# odo integration with Operator Hub
---
What is an Operator?

When working in experimental mode, odo provides the ability to work with
link:https://www.openshift.com/learn/topics/operators[Operators] installed on
the cluster. It allows listing of Operators, creation of services from CRD
(Custom Resource Definitions) provided by the Operators, printing the YAML
definition and providing custom YAML definition to start the service from a
CRD.
An Operator is essentially a link:https://www.openshift.com/learn/topics/operators[custom controller]. It is a method of packaging, deploying and managing a Kubernetes-native application.

[NOTE]
====
Installation of Operators is not a part of odo workflow. It is something that
your OpenShift/Kubernetes cluster administrator should be able to do for you.
====
With Operators, odo allows you to create a service as defined by a Custom Resource Definition (CRD).

=== Prerequisites
Odo utilizes Operators and link:https://operatorhub.io/[Operator Hub] in order to provide a seamless method for custom controller service installation.

- `odo` is installed.
- Required Operators are installed in the project/namespace by cluster
administrator.
- Experimental mode is enabled. For every command (other than those for
<<create-project,project creation>>) mentioned in this document to work, we
first need to enable the experimental mode. This can be done in
different ways. Make sure that you have installed latest version of odo and
perform any one of the following actions.
== Deploying your first Operator

* Enable experimental mode in odo preferences:
+
[source,shell]
----
$ odo prefrence set Experimental true
----
==== Prerequisites

* You must have cluster permissions to install an Operator on either link:https://docs.openshift.com/container-platform/4.3/operators/olm-adding-operators-to-cluster.html[OpenShift] or link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/install/install.md[Kubernetes].
* Enable experimental mode for odo. This can be done by: `odo preference set experimental true`

* Export the environment variable `ODO_EXPERIMENTAL`:
+
[source,shell]
----
$ export ODO_EXPERIMENTAL=true
----
== Creating a project

* Prefix every command mentioned below with `ODO_EXPERIMENTAL=true`. For
example, to list the Operators installed in current project:
+
[source,shell]
----
$ ODO_EXPERIMENTAL=true odo catalog list services
----

=== [[create-project]]Creating a project
Create a project to keep your source code, tests, and libraries organized in a
separate single unit.
Create a project to keep your source code, tests, and libraries
organized in a separate single unit.

1. Log in to the Kubernetes/OpenShift cluster:
. Log in to your cluster:
+
[source,shell]
[source,sh]
----
$ odo login -u developer -p developer
$ odo login -u developer -p developer
----

2. Create a project:
. Create a project:
+
[source,shell]
[source,sh]
----
$ odo project create myproject
✓ Project 'myproject' is ready for use
✓ New project created and now using project : myproject
$ odo project create myproject
✓ Project 'myproject' is ready for use
✓ New project created and now using project : myproject
----

=== [[list-operators]]Listing the Operators
== Installing an Operator

To list the Operators installed in current project, execute below command:
In our examples, we install link:https://etcd.io/[etcd], a distributed key-value store from link:https://operatorhub.io/operator/etcd[Operator Hub].

[source,shell]
----
$ odo catalog list services
----

It will list the
link:https://docs.openshift.com/container-platform/4.3/operators/olm-what-operators-are.html[Operators]
and the services, or
link:https://docs.openshift.com/container-platform/4.3/operators/crds/crd-extending-api-with-crds.html#crd-custom-resource-definitions_crd-extending-api-with-crds[CRD
(Custom Resource Definitions)], provided by these Operators. For example, we
have installed etcd and MongoDB Operators and the output we get is like below:

[source,shell]
----
$ odo catalog list services
Operators available in the cluster
NAME CRDs
etcdoperator.v0.9.4 EtcdCluster, EtcdBackup, EtcdRestore
mongodb-enterprise.v1.4.5 MongoDB, MongoDBUser, MongoDBOpsManager
----

In above output, `etcdoperator.v0.9.4` is the Operator while `EtcdCluster`,
`EtcdBackup` and `EtcdRestore` are the CRDs provided by this Operator.

To start a service from an Operator, we need the Operator name and name of the
service (CRD) to start. Note that these name values are case-sensitive.

=== [[dry-run]]Print the YAML used to start a service

odo provides the feature to print the YAML definition of the service (Custom
Resource or CR) provided by the Operator before starting a service off it. This
can be done by:

[source,shell]
----
$ odo service create <operator-name> --crd <cr-name> --dry-run
----
[IMPORTANT]
====
Each Operator we install refers to the built-in `metadata.annotations.alm-examples` annotation in order to correctly deploy. If the Operator does not contain the correct metadata, you will not be able to correctly deploy. For more information, see the the link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md#crd-templates[upstream CRD documentation].
====

For example, to print YAML definition of `EtcdCluster` provided by
`etcdoperator.v0.9.4` Operator, you would do:

[source,shell]
----
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster --dry-run
----
=== Kubernetes installation

You can also redirect the output generated above and modify it before starting
a service. We will see this in <<create-from-yaml,creating service from YAML
section>>.
For Kubernetes installation, you must install the Operator Lifecycle Manager and etcd from the link:https://operatorhub.io/operator/etcd[etcd installation guide on Operator Hub].

=== [[create-service]]Create a service from an Operator
=== OpenShift installation

[NOTE]
====
For the commands mentioned in this section to work properly, you need to make
sure that the Operator has a valid definition in its `metadata` to start the
requested service. The commands mentioned here refer the
`metadata.annotations.alm-examples` of an Operator and use it as-is to start
the service. If this YAML has placeholder values or sample values that are not
meant to aid in starting a real service, you will not be able to see a service
start from it.
====
For OpenShift installation, the etcd Operator can be installed through the link:https://docs.openshift.com/container-platform/4.3/operators/olm-adding-operators-to-cluster.html[administrative console].

To start an `EtcdCluster` service from `etcdoperator.v0.9.4` Operator, you need
to execute:
=== Listing all available Operators

[source,shell]
Before deploying your first Operator, have a look at what is available:
[source,sh]
----
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster
$ odo catalog list services
Operators available in the cluster
NAME CRDs
etcdoperator.v0.9.4 EtcdCluster, EtcdBackup, EtcdRestore
----

This is exactly same command as that shown in <<dry-run,printing the YAML of
service>> section above but without the `--dry-run` flag.
In above output, `etcdoperator.v0.9.4` is the Operator while `EtcdCluster`,
`EtcdBackup` and `EtcdRestore` are the CRDs provided by this Operator.

At the moment, `odo` is unable to list services started from an Operator. To
check if the above command succeeded in starting a service, use `kubectl` or
`oc`:

[source,shell]
----
$ kubectl get EtcdCluster
----

At the time of writing this document, above command worked out of the box
because, as mentioned in the note, `etcdoperator.v0.9.4` 's definition has a
valid example for `EtcdCluster` embedded into it. This can be checked by doing:
=== Deploying etcd to a cluster

In this example, we will be deploying our link:https://operatorhub.io/operator/etcd[installed etcd Operator] to an OpenShift / Kubernetes cluster.

[source,shell]
. Create a etcd service from the `etcdoperator.v0.9.4` Operator:
+
[source,sh]
----
$ kubectl get csv/etcdoperator.v0.9.4 -o yaml
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster
----

and referring to the `alm-examples` section under `annotations` in the
`metadata` of the `etcdoperator.v0.9.4` Operator.

If you're using OpenShift, you can replace `kubectl` with `oc` in above
command.

If there is placeholder/invalid data or no data in the aforementioned section
of the Operator's definition, `odo` won't be able to start the service. As an
example, refer to the YAML definition of `EtcdBackup` in the
`etcdoperator.v0.9.4` 's `metadata`:

[source,yaml]
. Confirm the Operator backed service was deployed:
+
[source,sh]
----
apiVersion: etcd.database.coreos.com/v1beta2
kind: EtcdBackup
metadata:
name: example-etcd-cluster-backup
spec:
etcdEndpoints:
- <etcd-cluster-endpoints>
s3:
awsSecret: <aws-secret>
path: <full-s3-path>
storageType: S3
$ odo service list
----

Here we can see some placeholder data in the form of `<etcd-cluster-endpoints>`
, `<aws-secret>` and `<full-s3-path>` that the user is expected to set to
appropriate value for the service to start.
It is important to note that `EtcdBackup` and `EtcdRestore` are **not** available for deployment as they require interactive parameters.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not entirely correct. I mean, one can't do odo service create etcdoperator.v0.9.4 --crd EtcdBackup or odo service create etcdoperator.v0.9.4 --crd EtcdRestore and expect it to work OOTB. They must redirect its alm-example to a yaml, modify the yaml to contain correct values and then use the --dry-run flag.

But, it's not worth holding this PR for that reason since --dry-run is properly documented already.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not entirely correct, but still a valid statement that they don't work out of the box. I don't think we should be encouraging users to have to modify a YAML, copy over metadata annotations and then try again.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that we shouldn't be encouraging yaml modificatoin, but we're allowing them to pipe and edit a yaml while we get around to working on #2799 and #2785.


On the other hand, `EtcdCluster` 's definition looks like below:
=== Deploying etcd to a cluster via YAML

[source,yaml]
----
apiVersion: etcd.database.coreos.com/v1beta2
kind: EtcdCluster
metadata:
name: example
spec:
size: 3
version: 3.2.13
----

There's no placeholder data here and it can thus be used to spin a working
service from the Operator.
In this example, we will be deploying our link:https://operatorhub.io/operator/etcd[installed etcd Operator] to an OpenShift / Kubernetes cluster.

=== [[create-service-from-yaml]]Create service from a YAML file
However, we will be using the YAML definition where we modify the `metadata.name` and `spec.size`.

[NOTE]
[IMPORTANT]
====
This feature is provided on temporary basis while we work on adding support for
link:https://github.com/openshift/odo/issues/2785[passing parameters on the
command line] and link:https://github.com/openshift/odo/issues/2799[using
interactive mode] to create Operator backed services.
Deploying via YAML is a **temporary** feature as we add support for link:https://github.com/openshift/odo/issues/2785[passing parameters on the command line] and link:https://github.com/openshift/odo/issues/2799[interactive mode].
====

If the YAML definition of the service (or Custom Resource) that you want to
start has placeholder data in its Operator's `metadata`, you can use
<<dry-run,`--dry-run` feature>> explained above to get the YAML definition,
replace the placeholder values with correct values and start the service
using the corrected YAML definition.

For example, if you would like start an `EtcdCluster` service but of a smaller
size than what's configured by default, you could first fetch the YAML
definition of the service:

. Retrieve the YAML output of the operator:
+
[source,shell]
----
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster --dry-run
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster --dry-run > etcd.yaml
----

and then modify the YAML to below:

. Modify the YAML file by redefining the name and size:
+
[source,yaml]
.etcd.yaml
----
apiVersion: etcd.database.coreos.com/v1beta2
kind: EtcdCluster
metadata:
name: my-etcd-cluster // <1>
name: my-etcd-cluster // Change the name
spec:
size: 1 // <2>
size: 1 // Reduce the size from 3 to 1
version: 3.2.13
----
<1> We changed the name from `example` to `my-etcd-cluster`
<2> We reduced the size from `3` to `1`

Now we can use the `etcd.yaml` file above to create a service:

. Create the service from the YAML file:
+
[source,shell]
----
$ odo service create --from-file etcd.yaml
$ odo service create --from-file etcd.yaml
----

This will result in a `EtcdCluster` service with only one pod instead of the
three pods that it's originally configured to create. This can be checked by
doing:

. Confirm that the service has been created:
+
[source,shell]
----
$ kubectl get pods | grep my-etcd-cluster
$ odo service list
----