documentation bugs couchbase-operator 0.8 release

05/01/2018

Changes for Overview page:

• In https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/overview.md

Change the following lines to reflect 0.8 release and add new features:

This is, however, our 0.7 Beta release, so not all features have been added yet. Below is a list of the management tasks we currently support:

* Cluster provisioning

* Elastic Scalability

* Auto Recovery

Will be adding more observations/findings to this bug as I am testing.

Eric Schneider (5/4): Removed the reference to 0.7. The main new feature is CRD check, which isn't really a management task. So I added a Getting Started section with links to prerequisites and release notes for more info.

05/02/2018

•  In https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/operatorConfig.md, if we change the number of replicas for the couchbase operator to more than 1, only one couchbase-operator pod comes up successfully. This will be addressed in 1.0 version. However, this can be mentioned in the release notes for 0.8. Please find the corresponding issue : https://issues.couchbase.com/browse/K8S-300

Eric Schneider (5/4): Sindhura Palakodety Can you provide a description for the release notes?

05/03/2018

• In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/prerequisiteAndSetup.html

The Bootstrapping OpenShift link is giving page not found error.

Eric Schneider (5/4): Issue is reported here: https://docs.google.com/spreadsheets/d/1olznXRuYWwJG0ikhiNJ1JEPq7NGWycPUmJSaGIdZJ_E/edit#gid=0

• In https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/bootstrapOpenshift.md

The line below should be changed

From:

 $ tar xzf openshift-bootstrap.zip

To

unzip openshift-bootstrap.zip

The lines below should be changed 

From (typo in bootstrap):

$ chmod +x openshift-bootsrap.sh

$ ./openshift-bootsrap.sh

To

$ chmod +x openshift-bootstrap.sh

$ ./openshift-bootstrap.sh

Eric Schneider (5/4): Changed

•  In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/cbopctl.html

The figure is missing. It is present in the github documentation: https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/images/cbopctl_figure_1.jpg

Eric Schneider (5/4): Issue is reported here: https://docs.google.com/spreadsheets/d/1olznXRuYWwJG0ikhiNJ1JEPq7NGWycPUmJSaGIdZJ_E/edit#gid=0

• The link https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/cbopctl.html needs to be updated with the latest content from https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/cbopctl.md

Eric Schneider (5/4): All changes will get pushed with the final update.

• The following commands in the links above should be changed:

From :

OS X:

$ curl https://packages.couchbase.com/kubernetes/0.8.0-beta2/darwin/cbopctl

Linux:

$ curl https://packages.couchbase.com/kubernetes/0.8.0-beta2/linux/cbopctl 

Windows:

$ curl https://packages.couchbase.com/kubernetes/0.8.0-beta2/windows/cbopctl 

To (Include Uppercase O to use curl to download the file)
 

OS X:

$ curl -O https://packages.couchbase.com/kubernetes/0.8.0-beta2/darwin/cbopctl 

Linux:

$ curl -O https://packages.couchbase.com/kubernetes/0.8.0-beta2/linux/cbopctl

Windows:

$ curl -O https://packages.couchbase.com/kubernetes/0.8.0-beta2/windows/cbopctl

 Why do we need the windows command? Not sure whether we need it

Eric Schneider (5/4): Changed

• In the link https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/clusterStatusGuide.html there are many places where the backtick from the github documentation is not translated properly.

For example in the screenshot below, observe the grey highlighted portion:

 Observe how it is translated to:

 Please fix the multiple areas in this documentation.

Eric Schneider (5/4): Fixed

• In the link : https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/accessingCouchbase.html

Fix formatting of the line:

Access it using one of the following: * the Couchbase Web Console * the Couchbase CLI

Eric Schneider (5/4): Potentially fixed. I think this was because there was not an empty line before the bulleted list.

• In the https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/runningCouchbase.html

Add the proper link for the Node Recovery section in the line :

A deployment blueprint also helps detect node failures, rebalance out bad nodes, and bring the cluster back to the desired capacity. The section on [Node Recovery] (nodeRecovery.html) provides further details.

Eric Schneider (5/4): Fixed.

Also a figure is missing:

https://github.com/couchbase/couchbase-operator/blob/beta2/docs/user/images/cb-operator-working.jpg

Eric Schneider (5/4): We are looking into why figures aren't getting pulled in, https://docs.google.com/spreadsheets/d/1olznXRuYWwJG0ikhiNJ1JEPq7NGWycPUmJSaGIdZJ_E/edit#gid=0

• In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/logsTroubleshooting.html

fix formatting in the line:

The following topics are also helpful to understand when troubleshooting the Operator: * Cluster Status and Conditions * Understanding Conditions and Events * Listing And Describing Resources * Node Recovery * Operator Configuration

Eric Schneider (5/4): Potentially fixed. I think this was because there was not an empty line before the bulleted list.

•  In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/logsTroubleshooting.html

The script cb_k8s_support.sh is not linked.

Eric Schneider (5/4): This is likely because the file was not published yet.

• In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/logsTroubleshooting.html

Change the label from -lname=couchbase-operator to -lapp=couchbase-operator to keep it consistent through out the documentation:

Get name of operator pod

$ kubectl get po -lname=couchbase-operator NAME READY STATUS RESTARTS AGE couchbase-operator-1917615544-h20bm 1/1 Running 0 20h

 Similarly:

On OpenShift:

# Get name of operator pod $ oc get po -lname=couchbase-operator 

Eric Schneider (5/4): Changed

 
 Fix formatting in the line:

Watch for the following messages which indicate that the Operator is unable to reconcile your cluster into a desired state: * Logs with level=error * Operator is unable to get cluster state after N retries

Eric Schneider (5/4): Potentially fixed. I think this was because there was not an empty line before the bulleted list.

The section below has to be removed (since we no longer hard code the cluster name)
 

Note: If you are not using the default namespace, you must download and update the couchbase-cli-collect-logs.yaml file to reflect your namespace. For example, if your namespace is myproject, edit the command field in the YAML file to replace cb-example-0000.cb-example.default.svc with cb-example-0000.cb-example.myproject.svc. The updated field will now look like the following:

--- command: [""/bin/sh"", ""-c"", ""couchbase-cli-secure collect-logs-start -c cb-example-0000.cb-example.myproject.svc -u {auth.admin.username} -p {auth.admin.password} --all-nodes""] ---

Once the log collection is complete, you can view the log location for each node from the Couchbase Server Web Console by going to Logs > Collect Information and clicking Show Current Collection. You can then run a command like the following for each node in the cluster to collect their logs.

Eric Schneider (5/4): Mike Wiederhold [X] said this should be kept in an email he sent me.

Also mention that the commands (mentioned below) collect the logs from all the nodes in the cluster. The logs (when default configuration is used) are found under /opt/couchbase/var/lib/couchbase/tmp location.

On Kubernetes:
kubectl create -f https://packages.couchbase.com/kubernetes/0.8.0-beta2/couchbase-cli-collect-logs.yaml
On OpenShift:
oc create -f https://packages.couchbase.com/kubernetes/0.8.0-beta2/couchbase-cli-collect-logs.yaml

Eric Schneider *(5/4): Changed*

• In https://www.couchbaseinc.acct.us.onehippo.com/developers/documentation/server/5.5/operator/demo.html

1. Fix the formatting and numbering

Eric Schneider (5/4): Fixed

1. ** Remove the line " See Accessing the Couchbase CLI for details. ". It is confusing.
   RBAC users can be created by directly using the CLI, or as a job within the Kubernetes cluster. See Accessing the Couchbase CLI for details.
   Instead add the link as a hyperlink for the word "job".

Eric Schneider (5/4): Will leave this the same, but altered formatting slightly to make more clear.

1. **Remove the section below, since the cluster name is no longer hard-coded:

   Note: If you are not using the default namespace, you must download and update the couchbase-cli-create-user.yaml file to reflect your namespace. For example, if your namespace is myproject, edit the command field in the YAML file to replace cb-example-0000.cb-example.default.svc with cb-example-0000.cb-example.myproject.svc. The updated field will now look like the following snippet

   command: ["/bin/sh", "-c", "/couchbase-cli-secure user-manage                      -c cb-example-0000.cb-example.myproject.svc                      -u {auth.admin.username}                      -p {auth.admin.password}                      --rbac-username {auth.users.default_user}                      --rbac-password {auth.users.default_password}                      --roles admin --auth-domain local --set"]

   Eric Schneider (5/4): Mike Wiederhold [X] said this should be kept in an email he sent me.

1. Instead put the disclaimer below right above the statement "To deploy the pillowfight data loader, run the following command:" since the pillowfight-data-loader.yaml has hardcoded cluster name string.

Note: If you are not using the default namespace, you must download and update the pillowfight-data-loader.yaml file to reflect your namespace. For example, if your namespace is myproject, edit the command field in the YAML file to replace cb-example-0000.cb-example.default.svc with cb-example-0000.cb-example.myproject.svc. The updated field will now look like the following snippet:

  command: ["cbc-pillowfight",

                  "-U", "couchbase://cb-example-0000.cb-example.myproject.svc/default?select_bucket=true",

                  "-I", "10000", "-B", "1000", "-c", "10", "-t", "1", "-P", "password"]

Eric Schneider (5/4): Added, but Mike Wiederhold [X] should review