Issue

What is the best practice to collect data for CloudBees Support?

Environment

Resolution

The tool

cbsupport is a command line tool that allows to collect data about a CloudBees product.

Tool installation

Where to install

Depending on your installation type, the cbsupport tool needs to be installed in different locations.

CloudBees Core on modern cloud platforms
- The tool needs to be installed on a machine with access to the cluster running CloudBees Core via kubectl.
CloudBees Jenkins Enterprise version 1.x
- The tool needs to be installed on the bastion host (ie the machine where you run your cje commands).
Other installations
- The tool needs to be installed on the machine running either the Operations Center, or the master (in case you are running a single isolated master with no Operations Center).

NOTE: There is currently no multi cluster support.

How to install

From a directory in your PATH, simply run:

Mac OS X: curl -L -o cbsupport https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-darwin-amd64 && chmod +x cbsupport
Linux: curl -L -o cbsupport https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-linux-amd64 && chmod +x cbsupport
Windows: curl -L -o cbsupport https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport.exe

Feel free to use wget or simply your browser to retrieve the binary.

Tool prerequisites

All OSs

CloudBees Core on modern cloud platforms

You need kubectl installed and configured to point to the cluster running the product.
As a simple test, running kubectl get pods --all-namespaces |grep cjoc should at least return one result.

macOS specific

You’ll need docker-credential-osxkeychain.
Note that if you have docker installed, you most likely have the docker credential oskeychain installed.

This third party is used to interact with the macOS Keychain to securely store the credentials you provide to the tool.

Linux specific

On Linux, the tool uses pass to securely store the credentials you provide to the tool.

Installing `pass`

Follow the official guide for your distribution at Pass: Download

For example, here are simple instructions for Ubuntu / Debian:

sudo apt-get install pass

and here is for Fedora / RHEL / CentOS

sudo yum install pass

In case this is not available from your configured repositories, then you can install it from the tarball at https://www.passwordstore.org/ by running sudo make install

Setting `pass` up

You need a GPG key to encrypt secrets in the password store. If you do not have one you can generate it as follows:

gpg2 --gen-key

You might encounter an issue running this command.
If it appears to be hanging, most likely this is because your installation doesn’t generate enough entropy to generate the gpg key, in which case you want to install rngd-utils. For example on Ubuntu / Debina please run:

sudo apt-get install rng-tools

To initialize a password store run the following replacing <gpg_key_id> with your existing key or the one generated above.

pass init <gpg_key_id>

Finally, you want to setup this environment variable in your shell startup script (.bashrc, .zshrc…):

export GPG_TTY=$(tty)

This is required for the gpg-agent to work properly so that pass can access you GPG key.

NOTE: For more details, please refer to Pass: The Standard Unix Password Manager

Configure the tool using the wizard

Run cbsupport setup and follow the instructions. See below for an explanation of each configuration option for each installation type.

A few notes:

The Jenkins user should have admin privileges to be able to generate the bundle.
Do not use the password of the user, but generate a token as indicated in How to (re)generate my Jenkins user token.

All installation types

Working directory: Full path to directory where you would like to have all files generated by the tool stored. 
Operation Center URL (or Jenkins URL if single Jenkins): URL used to access the Operations Center or Master where this tool is installed. Include http(s):// in URL.
Jenkins User (should have admin privileges): The admin user on Jenkins that the tool will use to access the cluster and perform operations.
API Token: API token for authenticating as above user.

CloudBees Core on traditional platforms, CloudBees Jenkins Distribution, Jenkins LTS, CloudBees Jenkins Platform and CloudBees Jenkins Team

Path to JENKINS_HOME: Full path to the $JENKINS_HOME directory for either your Operations Center or Master, depending on where you installed the tool.
Jenkins (unix) user running the WAR: The name of the Unix user running the Jenkins WAR on the server.

CloudBees Core on modern cloud platforms

Kubernetes Namespace: The Namespace in your Kubernetes cluster that CloudBees Core is installed in.

Verify the installation

You can run the check command, that will make some basic smoke tests with the configuration you provided in the setup:

cbsupport check

Once the check is made, cbsupport is ready to be used.

CLI usage

CloudBees Support or the Knowledge Base article you are following should give you the command to run.
However here is an overview of some useful commands.

Check

Runs some smoke tests to make sure the tool is correctly installed and configured:

cbsupport check

Version

Dumps information about the running cbsupport binary and also will notify in case a new version is available:

cbsupport version

Update

Updates the cbsupport binary to the latest available version:

cbsupport update

Generating the default information

This command will generate the default information that support needs.
In case of doubt, just use this command:

cbsupport required-data default

The command is interactive and will ask for the tenant(s) on which the data gathering should happen.

Proxies are not supported
Self signed certificates are not supported
OpenShift is not supported
Multiple namespaces are not supported
When creating the working directory, cbsupport cannot create nested directories (ie the directory you provide should be located in an existing directory).
~ is not recognized as home by cbsupport therefore you shouldn’t use it when providing path to the CLI.
In case the targeted tenant is slow to generate a support bundle, the CLI will keep the connection up without any visual feedback making think it’s stuck.

Using cbsupport CLI to collect the requested data