Creating and linking with Operator backed services

In this document we will go through what Operators are, how to create and delete services from the installed Operators, and how to link an odo component with an Operator backed service. We do this walking through an example Node.js application and linking it with an etcd key-value store.

Note

We will be updating our documentation with more examples of linking components to different kinds of Operator backed services in future.

Introduction to Operators

What is an Operator?

An Operator is essentially a custom controller. It is a method of packaging, deploying and managing a Kubernetes-native application.

With Operators, odo allows you to create a service as defined by a Custom Resource Definition (CRD).

odo utilizes Operators and Operator Hub in order to provide a seamless method for custom controller service installation.

Warning

You cannot install Operators with odo on your cluster.

To install Operators on a Kubernetes cluster, contact your cluster administrator or see the Kubernetes documentation.

To install Operators on an OpenShift cluster, contact your cluster administrator or see the OpenShift documentation.

Deploying your first Operator

Prerequisites

You must have cluster permissions to install an Operator on either OpenShift or Kubernetes. If you’re running a minikube cluster, you can refer this guide to install Operators required to run example mentioned in this document.

Creating a project

Create a project to keep your source code, tests, and libraries organized in a separate single unit.

Create a project:

$ odo project create myproject
 ✓  Project 'myproject' is ready for use
 ✓  New project created and now using project : myproject

Installing an Operator

In our examples, we install etcd, a distributed key-value store from Operator Hub.

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 upstream CRD documentation.

Kubernetes installation

For Kubernetes installation, you must need to install the Operator Lifecycle Manager and etcd Operator from the etcd installation guide on Operator Hub. You can refer this document for steps setup Operator Lifecycle Manager and etcd Operator on a minikube cluster.

OpenShift installation

For OpenShift installation, the etcd Operator can be installed through the administrative console.

Listing all available Operators

Before deploying your first Operator, have a look at what is available:

$ odo catalog list services
Operators available in the cluster
NAME                          CRDs
etcdoperator.v0.9.4           EtcdCluster, EtcdBackup, EtcdRestore

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

Creating an Operator backed service

In this example, we will be deploying EtcdCluster service from etcd Operator to an OpenShift / Kubernetes cluster. This service is provided by the Operator etcdoperator. Please ensure that this Operator is installed on your OpenShift / Kubernetes cluster before trying to create EtcdCluster service from it. If it’s not installed, please install it by logging into your OpenShift / Kubernetes cluster as kube:admin user.

Create an EtcdCluster service from the etcdoperator.v0.9.4 Operator:
```
$ odo service create etcdoperator.v0.9.4/EtcdCluster
```
Confirm the Operator backed service was deployed:
```
$ odo service list
```

It is important to note that EtcdBackup and EtcdRestore cannot be deploymeed the same way as we deployed EtcdCluster as they require configuring other parameters in their YAML definition.

Deploying Operator backed service to a cluster via YAML

In this example, we will be deploying our installed etcd Operator to an OpenShift / Kubernetes cluster.

However, we will be using the YAML definition where we modify the metadata.name and spec.size.

Important

Deploying via YAML is a temporary feature as we add support for passing parameters on the command line and interactive mode.

Retrieve the YAML output of the operator:

$ odo service create etcdoperator.v0.9.4/EtcdCluster --dry-run > etcd.yaml

Modify the YAML file by redefining the name and size:

apiVersion: etcd.database.coreos.com/v1beta2
kind: EtcdCluster
metadata:
  name: my-etcd-cluster // Change the name
spec:
  size: 1 // Reduce the size from 3 to 1
  version: 3.2.13

Create the service from the YAML file:

$ odo service create --from-file etcd.yaml

Confirm that the service has been created:
```
$ odo service list
```

Linking an odo component with an Operator backed service

Linking a component to a service means, in simplest terms, to make a service usable from the component. odo uses Service Binding Operator v0.3.0 to provide the linking feature. Please refer this document to install it on OpenShift or Kubernetes.

For example, once you link an EtcdCluster service with your Node.js application, you can use (or, interact with) the EtcdCluster from within your node app. The way odo facilitates linking is by making sure that specific environment variables from the pod in which the service is running are configured in the pod of the component as well.

After having created a service using either of the two approaches discussed above, we can now connect an odo component with the service thus created.

Make sure you are executing the command for a component that’s pushed (odo push) to the cluster.

Link the component with the service:

$ odo service list
NAME                    AGE
EtcdCluster/example     46m2s
    
$ odo link EtcdCluster/example
 ✓  Successfully created link between component "node-todo" and service "EtcdCluster/example"
    
To apply the link, please use `odo push`
    
$ odo push

Important

For the link between a component and Operator Hub backed service to take effect, make sure you do odo push. The link won’t be effective otherwise.

Unlinking an odo component from an Operator backed service

Unlinking unsets the environment variables that were set by linking. This would cause your application to cease being able to communicate with the service linked using odo link.

Important

odo unlink doesn’t work on a cluster other than OpenShift (that is, minikube, or vanilla Kubernetes, etc.) because Service Binding Operator cannot be setup the OLM way (that is, we cannot list it by doing odo catalog list services or kubectl get csv like we can do for etcd Operator in this document). We are working making this possible.

Make sure you are executing the command for a component that’s pushed (odo push) to the cluster.

Unlink the component from the service it is connected to:

$ odo unlink EtcdCluster/example
✓  Successfully unlinked component "node-todo" from service "EtcdCluster/example"
    
To apply the changes, please use `odo push`
    
$ odo push

Important

For unlinking to take effect, make sure you do odo push. It won’t be effective otherwise.

Deleting an Operator backed service

To delete an Operator backed service, provide full name of the service that you see in the output of odo service list. For example:

$ odo service list
NAME                    AGE
EtcdCluster/example     2s

$ odo service delete EtcdCluster/example

To forcefully delete a service without being prompted for confirmation, use the -f flag like below:

$ odo service delete EtcdCluster/example -f