About cbopctl

cbopctl is a command-line tool that is provided in the Couchbase Autonomous Operator package. It implements a custom subset of the kubectl and oc commands to ensure that CouchbaseCluster objects are valid configurations before they are uploaded to Kubernetes.

It’s important to check that a configuration is valid before uploading it, because once a configuration is uploaded to Kubernetes, the Couchbase Operator is unable to handle configuration errors. Therefore, you must use cbopctl whenever you load or modify a CouchbaseCluster configuration.

Installation

Make sure that you have downloaded the Operator package and unpacked it on the same computer where you normally run kubectl or oc.

After you unpack the download, the resulting directory will be titled something like couchbase-autonomous-operator-kubernetes_x.x.x-linux_x86_64.

macOS
Linux
Windows

Open a Terminal window and go to the directory where the cbopctl binary is located:
```
cd couchbase-autonomous-operator-kubernetes_x.x.x-macos_x86_64/bin/
```
Make the cbopctl binary executable:
```
chmod +x ./cbopctl
```

Move the binary into your PATH:

sudo mv ./cbopctl /usr/local/bin/cbopctl

Open a command prompt and go to the directory where the cbopctl binary is located:
```
cd couchbase-autonomous-operator-kubernetes_x.x.x-linux_x86_64/bin/
```
Make the cbopctl binary executable:
```
chmod +x ./cbopctl
```

Move the binary into your PATH:

sudo mv ./cbopctl /usr/local/bin/cbopctl

Open a command prompt and go to the directory where the cbopctl binary is located:
```
cd couchbase-autonomous-operator-kubernetes_x.x.x-windows_x86_64\bin\
```
Add the cbopctl binary into your PATH.

Syntax

cbopctl implements the create, delete, and apply commands in a similar way to kubectl and oc.

cbopctl [option] [args]

  apply    Update a Couchbase Cluster
  create   Create a new Couchbase Cluster
  delete   Delete a new Couchbase Cluster

Optional Flags:

     --version                Prints version information
  -h,--help                   Prints the help message

Options

create

This option should be used when pushing new CouchbaseCluster configurations to Kubernetes.
apply

This option should be used when updating a CouchbaseCluster configuration that is already in Kubernetes.
delete

This option can be used to delete a CouchbaseCluster. (This option is more for completeness, since no validation takes place during a delete.)

Flags

Each option has three flags — one that is required and two that are optional.

Required Flags:

  -f,--filename               Filename or the resource to create

Optional Flags:

     --dry-run                If true, only print the object that would be sent,
                              without sending it
     --kubeconfig             The path to your kubernetes configuration
  -h,--help                   Prints the help message

Specifying the filename of a CouchbaseCluster configuration is required for all commands. The dry-run flag can be used to run validation on the specified configuration file without uploading it to Kubernetes. This is particularly useful if you want to use features in kubectl that are not in cbopctl, but you still want to validate the configuration before pushing it to Kubernetes. The kubeconfig flag is also available in case the configuration to your Kubernetes cluster is located on a non-default path.

How it Works

The following diagram shows the process of uploading a CouchbaseCluster configuration to Kubernetes using just kubectl:

The kubectl command is run and the CouchbaseCluster configuration is sent to the Kubernetes API Server.
The CouchbaseCluster configuration undergoes partial validation by Kubernetes.
If the CouchbaseCluster configuration is found to be valid by Kubernetes, it is inserted into etcd. If it is not valid, an error is returned to kubectl.
etcd acknowledges to the API Server that the CouchbaseCluster object was persisted.
A success message is returned to kubectl.
The CouchbaseCluster object is sent to the Couchbase Operator.

Since Kubernetes can only do a partial validation, the only place to do full validation is in the API Server, because errors in the configuration must be caught before the CouchbaseCluster configuration makes it to etcd.

Until Kubernetes provides full native validation, you must use cbopctl whenever you load or modify a CouchbaseCluster configuration. The cbopctl command contains all of Couchbase’s validation code in one command line tool and is the only way to ensure that invalid configurations don’t make it into Kubernetes.