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 in order to provide a seamless method for custom controller service installation. These Operators could be installed using Operator Hub or you could install a custom Operator developed within your organization.

Deploying your first Operator

Prerequisites

You must have cluster permissions to install an Operator on either OpenShift or Kubernetes.

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 install the Operator Lifecycle Manager and etcd from the etcd installation guide on Operator Hub.

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.

For example, once you link an EtcdCluster service with your nodejs 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.

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