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

Documentation for Odo integration with Operator Hub #3029

Merged
merged 6 commits into from
May 11, 2020
Merged

Documentation for Odo integration with Operator Hub #3029

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b2d8b9e
Documentation for Odo integration with Operator Hub
dharmit Apr 23, 2020
852bbb1
Changes based on PR review
dharmit Apr 28, 2020
f485730
It's odo, not Odo
dharmit May 1, 2020
ab0b7c9
Changes as suggested in PR review
dharmit May 6, 2020
ac5c657
Accommodate PR review and change case where required
dharmit May 8, 2020
22d9114
Move from docs/user to docs/public
dharmit May 11, 2020
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: 271 additions & 0 deletions docs/public/operator-hub.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,271 @@
:source-highlighter: pygments

# odo integration with Operator Hub
---

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.

[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.
====

=== Prerequisites

- `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.

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


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

* 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.

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

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

=== [[list-operators]]Listing the Operators

To list the Operators installed in current project, execute below command:

[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
----

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
----

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>>.

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

[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.
====

To start an `EtcdCluster` service from `etcdoperator.v0.9.4` Operator, you need
to execute:

[source,shell]
----
$ odo service create etcdoperator.v0.9.4 --crd EtcdCluster
----

This is exactly same command as that shown in <<dry-run,printing the YAML of
service>> section above but without the `--dry-run` flag.

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:


[source,shell]
----
$ kubectl get csv/etcdoperator.v0.9.4 -o yaml
----

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]
----
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
----

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.

On the other hand, `EtcdCluster` 's definition looks like below:

[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.

=== [[create-service-from-yaml]]Create service from a YAML file

[NOTE]
====
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.
====

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:

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

and then modify the YAML to below:

[source,yaml]
.etcd.yaml
----
apiVersion: etcd.database.coreos.com/v1beta2
kind: EtcdCluster
metadata:
name: my-etcd-cluster // <1>
spec:
size: 1 // <2>
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:

[source,shell]
----
$ 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:

[source,shell]
----
$ kubectl get pods | grep my-etcd-cluster
----