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.
-
Log in to your cluster:
$ odo login -u developer -p developer
-
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 theetcdoperator.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 deployed 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 doingodo catalog list services
orkubectl 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