You have access to an OpenShift user that has cluster-admin privileges (system:admin in this guide)

You have access to a standard OpenShift user without cluster-admin privileges (developer in this guide)

If you have an OpenShift environment that already has a custom setup (non-default), you should be able to modify a few of the parameters in the various commands and configuration files mentioned in this guide in order to fit your requirements.

This guide makes certain assumptions about the role-based access control (RBAC) settings in your OpenShift environment. Refer to the RBAC documentation before you install the Operator, as your OpenShift environment may differ from the environment upon which this guide is based.

Prerequisites

Download the Operator package and unpack it on the same computer where you normally run oc.

The Operator package contains YAML configuration files and command-line tools that you will use to install the Operator.

After you unpack the download, the resulting directory will be titled something like couchbase-autonomous-operator-openshift.x.x-linux_x86_64. Make sure to cd into this directory before you run the commands in this guide.

Create an OpenShift Project

The first thing that you need to do is use a standard OpenShift user to create a project where the Operator will reside:

oc login -u developer

oc new-project operator-example-namespace

oc logout

In this example, the standard user is developer, and the project is operator-example-namespace. Later in this guide you will give developer the ability to manage the Operator and the Couchbase Server clusters in operator-example-namespace.

Install the Custom Resource Definition

The next step in setting up the Operator is to install the CouchbaseCluster custom resource definition (CRD). The Operator can do this for you automatically (as it does when installing on open source Kubernetes), but in OpenShift it’s better to do it manually because installing a CRD is a cluster-level operation and requires cluster-level permissions that should not be given to typical users.

To install the CRD, log in as an OpenShift user that has cluster-admin privileges (in this case system:admin) and run the following commands:

oc login -u system:admin

oc create -f crd.yaml

You only need to install the CRD once. After that, you can create the Operator in any OpenShift project.

Create an imagePullSecret

Red Hat recommends that all containers that run in OpenShift be built with Red Hat Enterprise Linux. Couchbase provides these images to users through the Red Hat Container Catalog. Using this catalog requires creating an imagePullSecret so that Docker knows where to look for images. To create an imagePullSecret for the Red Hat Container Catalog, run the following command:

Create a Role and Service Account for the Operator

You need to create a role in OpenShift that allows the Operator to access the resources that it needs to run.

If you plan to run the Operator in more than one project, it may be preferable to create a cluster role because you can assign that role to a service account in any OpenShift project.
Note that if you chose to to use a cluster role, making modifications to it will affect all instances of the Operator that use it.
This has the potential to cause adverse affects in production environments, such as removing required premissions used by older instances of the Operator.

If you want to create role bindings for multiple users either at the cluster or namespace level, they will need to have unique names. In the previous examples, if you were to create a role binding for user alice, you’d use the name couchbasecluster-alice in place of couchbasecluster-developer.

Create the Operator

At this point you can now use the developer user to create the Operator in the operator-example-namespace project. To create and start the Operator, run the following command:

Running this command downloads the Operator Docker image (specified in the operator-deployment.yaml file) and creates a deployment, which manages a single instance of the Operator. The Operator uses a deployment so that it can restart if the pod it’s running in dies.

After you run the oc create command, it generally takes less than a minute for OpenShift to deploy the Operator and for the Operator to be ready to run.

If you encounter a ErrImagePull or ImagePullBackOff event associated with the Operator pod, check that the container image URL in operator-deployment.yaml is reachable, and that the specified image is available.

The images that are specified in the provided YAML files are hosted in common public container registries.
Couchbase regularly publishes new container images that incorporate the latest security updates and patches.
In rare cases, a registry’s security policy may force the removal of older container images, causing the provided YAML definitions to become invalid.
It’s recommended that you check the registry for new and discontinued container images, and update your deployment accordingly.

To use a newer container image, simply update the container image URL in operator-deployment.yaml with the new image name, and then push the definition to your OpenShift environment.
Container images are available in the following repository:

Check the Status of the Deployment

You can use the following command to check on the status of the deployment:

oc get deployments

If you run the previous command immediately after the Operator is deployed, the output will look something like the following:

NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
couchbase-operator 1 1 1 0 10s

In this case, the deployment is called couchbase-operator. The DESIRED field in the output shows that this deployment will create one pod running the Operator. The CURRENT field shows that one Operator pod has been created. However, the AVAILABLE field indicates that the pod is not ready yet since its value is 0 and not 1. That means that the Operator is still establishing a connection to the Kubernetes master node to allow it to get updates on CouchbaseCluster objects. Once the Operator has completed this task, it will be able to start managing Couchbase Server clusters and the status will be shown as AVAILABLE.

You should continue to poll the status of the Operator until the output looks similar to the following:

NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
couchbase-operator 1 1 1 1 47s

Check the Status of the Operator

You can use the following command to verify that the Operator has started successfully:

oc get pods -l app=couchbase-operator

If the Operator is up and running, the command returns an output where the READY field shows 1/1, such as:

Next Steps

Quick Start Script

The script below has been parameterized for clarity and relies on a set of environment variables that may be tailored to the individual OpenShift environment being deployed in. These variables correspond to the resources being created and used in order to deploy the Operator. These are explained below:

NAMESPACE

The Kubernetes namespace/OpenShift project to run the Operator in. This can be changed to any project you have access to.

ADMIN_ACCOUNT

The administrator account which has the ability to install custom resource definitions and create role bindings which grant privilege escalation.

OPERATOR_SERVICE_ACCOUNT

The service account the Operator should run as. This can be changed to any valid Kubernetes name, however, is scoped to the namespace it is deployed in so it must be unique in that context.