github twitter linkedin 500px
Install Kubernetes operators in OpenShift using only the CLI
Apr 24, 2020
5 minutes read

OpenShift 4 went all-in on Kubernetes operators: they are used for installation of the platform itself but also to install databases, middlewares, etc. There are more and more operators available on the Operator Hub. Most software now provide an operator and describe how to use it.

Nevertheless, almost every software documentation I read so far, includes the steps to install the operator using the nice GUI of OpenShift 4. But since my OpenShift environments are provisioned by a playbook, I want to be able to install operators using the CLI only!

The OpenShift official documentation covers this part but I did not find it very clear. So, this article tries to make it clearer: how to install Kubernetes operators in OpenShift using only the CLI.

Discover the available operators from the CLI

Discover the operators available on your platform.

oc get packagemanifests -n openshift-marketplace --sort-by=.metadata.name

This should give you a very long list of operators. You can filter it to retain only the ones you need.

For instance, to discover the operators required to install Red Hat Service Mesh / Istio:

$ oc get packagemanifests -n openshift-marketplace |egrep -i '(elastic|jaeger|kiali|service.*mesh)'
elasticsearch-operator                       Red Hat Operators     47h
jaeger-product                               Red Hat Operators     47h
jaeger                                       Community Operators   47h
kiali                                        Community Operators   47h
kiali-ossm                                   Red Hat Operators     47h
servicemeshoperator                          Red Hat Operators     47h

The second column is the display name of the operator source. Later in the procedure, we will need the identifier of the operator source.

Query it programmatically for a specific operator using the following command.

oc get packagemanifests -n openshift-marketplace -o jsonpath='{.status.catalogSource}{"\n"}' elasticsearch-operator

In the rest of this article, we will install Elastic Search using the elasticsearch-operator coming from the redhat-operators source using the CLI.

Query the available channels for this operator using the follwing command.

oc get packagemanifest -o jsonpath='{range .status.channels[*]}{.name}{"\n"}{end}{"\n"}' -n openshift-marketplace elasticsearch-operator

When this article was written, the Elastic Search operator had four channels:

4.2
4.2-s390x
4.3
preview

In the rest of this article we will install version 4.3 using the CLI.

Finally discover whether the operator can be installed cluster-wide or in a single namespace.

oc get packagemanifest -o jsonpath='{range .status.channels[*]}{.name}{" => cluster-wide: "}{.currentCSVDesc.installModes[?(@.type=="AllNamespaces")].supported}{"\n"}{end}{"\n"}' -n openshift-marketplace elasticsearch-operator

You will discover that the Elastic Search operator can be installed cluster-wide for all of its four channels.

4.2 => cluster-wide: true
4.2-s390x => cluster-wide: true
4.3 => cluster-wide: true
preview => cluster-wide: true

The rest of the procedure varies slightly depending if the operator supports cluster-wide installation or not.

Install an operator cluster-wide using the CLI

To install an operator cluster-wide using the CLI, create a Subscription object in the openshift-operators namespace.

oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: elasticsearch-operator
  namespace: openshift-operators
spec:
  channel: "4.3"
  name: elasticsearch-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

The outstanding fields of the Subscription object are:

  • metadata.name: name of your subscription. free choice
  • metadata.namespace: for a cluster-wide installation, the value is fixed: openshift-operators
  • spec.channel: the channel to install (see above the output of the oc get packagemanifest command)
  • spec.name: the name of the operator to install
  • spec.source: the id of the operator source (currently there are three operator sources: certified-operators, community-operators and redhat-operators)
  • spec.sourceNamespace: fixed value (openshift-marketplace)

Ensure the Elastic Search operator has been deployed successfully in the openshift-operators namespace.

$ oc get pods -n openshift-operators -l name=elasticsearch-operator
NAME                                      READY   STATUS    RESTARTS   AGE
elasticsearch-operator-6697867687-x7r6t   1/1     Running   0          3d6h

Install an operator in a namespace using the CLI

To install an operator in a specific project, you need to create first an OperatorGroup in the target namespace. An OperatorGroup is an OLM resource that selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the OperatorGroup.

Create a new project.

oc new-project my-project

Create an OperatorGroup object in your project.

oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: my-project
  namespace: my-project
spec:
  targetNamespaces:
  - my-project
EOF

The outstanding fields of the OperatorGroup object are:

  • metadata.name: name of your OperatorGroup. free choice
  • metadata.namespace: the namespace in which you want to deploy your operator.
  • spec.targetNamespaces[0]: the namespace in which you want to deploy your operator (again).

Once the subscription is created, the OLM should create a CSV (ClusterServiceVersion):

$ oc get csv
NAME                                         DISPLAY                  VERSION               REPLACES                                     PHASE
elasticsearch-operator.4.3.13-202004131016   Elasticsearch Operator   4.3.13-202004131016   elasticsearch-operator.4.3.10-202003311428   Succeeded

If the CSV is not created, it might be because there are multiple OperatorGroup object in the namespace. Delete them all before recreating the one you need.

You can then create the Subscription object in your project.

oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: elasticsearch-operator
  namespace: my-project
spec:
  channel: "4.3"
  name: elasticsearch-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

The meaning of each field is the same as described above in the section Install an operator cluster-wide using the CLI.

Use the installed operator

Once installed, you will want to use the operator to perform something useful. All the capabilities of your newly installed operator are described in the ClusterServiceVersion (CSV) created automatically by the Operator Lifecycle Manager (OLM).

$ oc get csv
NAME                                         DISPLAY                  VERSION               REPLACES                                     PHASE
elasticsearch-operator.4.3.13-202004131016   Elasticsearch Operator   4.3.13-202004131016   elasticsearch-operator.4.3.10-202003311428   Succeeded

You can get details about the Custom Resource Definitions (CRD) supported by the operator or retrieve some sample CRDs.

Get the CSV name of the installed Elastic Search operator.

CSV=$(oc get csv -o name |grep /elasticsearch-operator.)

Now you can query the CRDs enabled by your operator.

oc get $CSV -o json |jq -r '.spec.customresourcedefinitions.owned[]|.name'

This will return a list of fully qualified CRDs:

elasticsearches.logging.openshift.io

You can also retrieve the sample CRDs if you need some help to get started.

oc get $CSV -o json |jq -r '.metadata.annotations["alm-examples"]'

For example, you can create an Elastic Search instance by using the provided sample CRD.

oc get $CSV -o json |jq -r '.metadata.annotations["alm-examples"]' |jq '.[0]' |oc apply -f -

And then retrieve all the created objects belonging to the operator.

oc get $(oc get $CSV -o json |jq -r '[.spec.customresourcedefinitions.owned[]|.name]|join(",")')

Conclusion

This article explained how to install Kubernetes operators in OpenShift using only the CLI and also how to use them afterwards without having to use to the OpenShift console!


Back to posts