cbsupport CLI documentation

7 minute read

cbsupport is a command-line tool that makes it easy to collect data commonly required for supporting CloudBees products.

Instead of having to follow detailed instructions to run several commands and collect the resulting files, cbsupport provides "one-liners" that automate those steps, reducing the effort required to collect these support data.

The cbsupport CLI can be installed on a shared jump box, the server running CloudBees software or your personal computer. You can install cbsupport in one place and configure it to work with multiple CloudBees products which may be installed elsewhere. By installing cbsupport today, you ensure that you are ready to collect required information, especially in an urgent situation when your CloudBees product is experiencing an issue.

1. Setup

1.1. Retrieving the library

The cbsupport CLI should be installed on a bastion host, ie a host having access to the cluster using http/https.

The cbsupport CLI does not support versions of the product older than 2.107.x (Jenkins weekly 2.96).

For CloudBees CI on modern cloud platforms, the bastion host should also have kubectl set up with the proper context to access the cluster where the product is installed. For other products, the bastion host should have ssh access to the components of the cluster: Operations Center and Controllers (formerly known as Masters).

From a directory in your PATH:

  • macOS:

curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-darwin-amd64 \ && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-darwin-amd64.sha256 \ && shasum -c cbsupport-darwin-amd64.sha256 \ && mv cbsupport-darwin-amd64 cbsupport \ && chmod +x cbsupport
  • Linux:

curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-linux-amd64 \ && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-linux-amd64.sha256 \ && sha256sum -c cbsupport-linux-amd64.sha256 \ && mv cbsupport-linux-amd64 cbsupport \ && chmod +x cbsupport
  • Windows:

curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport.exe \ && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport.exe.sha256 \ && shasum -c cbsupport.exe.sha256

1.2. Additional Setup

1.2.1. Self signed certificate support

The configuration needs to be done at the level of the bastion host. The cbsupport CLI is loading the certificates configured at OS level. The path to the certificate depends on the OS, find here the lookup path.

1.2.2. CloudBees CI on modern cloud platforms

You will need kubectl installed and configured to point to the cluster where CloudBees is installed. You can check that kubectl is properly configured by running:

kubectl get pods --all-namespaces |grep cjoc-0 |wc -l

Return should be at least one, proving that your kubectl installation is pointing to a cluster with an Operation Center running.

1.2.3. Other installations

About the ssh agent

For other installations, you will need to give the cbsupport CLI additional information about your setup. In order to do so, you will need the following information:

  • the hostname of each tenant of your cluster: if it’s a standalone tenant (ie you are not running an Operation Center) then the command will expect a single hostname. Otherwise, you will have to run the operation once per tenant.

  • the username used to run the Jenkins process on the tenant. Note that you should have the rights to connect using ssh with this username.

About the connection

Currently, the cbsupport CLI does not store any ssh credentials and relies on the ssh agent for connection. This means that you should:

  1. add the ssh key to the ssh agent

  2. unlock the key (if needed) on the ssh agent

  3. make sure you can connect directly to the tenant with: ssh ${USERNAME}@${HOSTNAME}

  4. At the moment, only port 22 is supported for the connection

Modifying a tenant

Once the ssh-agent is properly configured, you can add, update or remove a tenant by using:

cbsupport context edit

Then follow the on-screen instruction and choose the Manage the cluster information option. The setup will prompt you which Jenkins instance you wish to add the tenant for.

About the tenant removal

At the moment, you can only remove a tenant that matches an actual Jenkins instance. It means that if you remove the instance from the Operation Center before removing the tenant from the cbsupport CLI, you won’t be able to see the tenant when running cbsupport setup tenant remove. This issue is logged in our system and we hope to have a fix soon.

In the meantime, a workaround is to directly delete the tenant from the cbsupport CLI configuration file (either under ~/.cbsupport/config.json or $CBSUPPORT_CONFIG).

Checking the status of the cluster

Once the cluster is setup, you can check that the cbsupport CLI can properly connect to all the tenants by running:

cbsupport check cluster

In case one tenant has an issue, you should see the exact error message in the output.

1.2.4. Credential Storage

The cbsupport CLI encrypts credentials in a file on the machine. The file is itself protected by a primary password. This password (that you need to enter at each run of the cbsupport CLI) generates a SHA256 key using PBKDF2.

Primary password loss

If for some reason you lost the primary password, you can delete the secrets file. Next time you run the cbsupport CLI, it will ask for a new password (and consequently, will also ask you to input your credentials). To remove this file, run:

Removing the secret file
rm -f "${HOME}/.cbsupport/secrets.json"

1.3. Autocompletion

The cbsupport CLI provides completion script for bash, zsh and fish.

1.3.1. Prerequisite (bash)

For bash, the bash-completion package is a pre-requisite. Please follow the documentation of the bash-completion package to properly install it.

1.3.2. Installing the script

Once the prerequisite is installed, run cbsupport completion help and follow the instructions.

1.4. Configuration

The cbsupport CLI does not need any other configuration. It will ask for the information it needs when it needs it, then save them for later reuse. It also tries to automatically find the data it needs, but always asks for a confirmation.

Pre configuration

In case you are an administrator deploying the cbsupport CLI for other users, you can configure the tool ahead of time by running cbsupport setup and following the instructions.

A few notes:

  1. The Jenkins user should have admin privileges to be able to generate the bundle.

  2. Do not use the password of the user, but generate a token as indicated in How to (re)generate my Jenkins user token – CloudBees Support.

  3. By default the configuration of the tool is persisted at $HOME/.cbsupport/config.json. The environment variable CBSUPPORT_CONFIG may be used to specify the location of the configuration file.

2. Usage

2.1. Check

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

cbsupport check

2.2. Version

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

cbsupport version

2.3. Update

Updates the cbsupport CLI binary to the latest available version:

cbsupport update

2.4. Health Check

Examines your environment to determine if it meets the known requirements for CloudBees CI.

It can not guarantee that CloudBees CI will run successfully on an examined environment, but it will point out known problems.

cbsupport health-check

This command can be used before installing the product to validate that the target environment will meet the requirements. In such scenario the only pre-requisite is to configure kubectl to access to the target environment.

Output sample:

----- Kubernetes Client:Validates the Kubernetes client (kubectl) ----- OK kubectl can run OK kubectl returns a version OK Kubernetes client version is valid ----- Kubernetes Server:Validates the Kubernetes Server ----- OK Kubernetes server is accessible OK Kubernetes server version is valid OK Client and Server run the same major version OK Client and server have less than 1 minor version difference ----- Default Storage class:Test the Default Storage class ----- OK Has a default Storage class KO Storage provisioner is supported ○ Details: Change the default storage to one of these: [[ssd-core-sstng-31-sstng-31 ssd-storage]]. Or configure a supported storage class in the product ○ More details: https://docs.cloudbees.com/d/hc-default-storage-class/#storage_provisioner_is_supported ----- SUMMARY: ----- * Total 9 (✓ 8, ⚠ 0, ✗ 1)

2.5. Context

Manage your context. A context is bound to a given setup. For instance, you could have a production and a staging context pointing respectively to your production and staging clusters. By default, you should not have to worry about context, your first setup is automatically pushed into a context called default. You can then choose to delete it, or create a new new one, or update it. The commands available commands are below:

cbsupport context create|delete|describe|edit|get|set

2.6. 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.

2.7. Generating specific information

In case of a specific issue, Support will ask you to gather more specific data.

2.7.1. Generating information for Performance issues

The following command will generate the information that Support needs for diagnosing performance issues.

cbsupport required-data performance

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

2.7.2. Generating information for I/O Performance issues

The following command will generate the information that Support needs for diagnosing I/O performance issues.

cbsupport required-data io

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

2.7.3. Generating information for a Jenkins Build issue

The following command will generate the information (a specific build root directory) that Support needs for diagnosing Build issues.

cbsupport required-data build

The command is interactive and will ask for the tenant containing the build, the item full name and the build number. It also asks for options such as maxDepth, the maximum number of levels to descend from the build directory.

2.7.4. Generating information for a Jenkins Item (Job / Folders) issue

The following command will generate the information (a specific item root directory) that Support needs for diagnosing Item issues.

cbsupport required-data item

The command is interactive and will ask for the tenant containing the item and the item full name. It also asks for options such as maxDepth, the maximum number of levels to descend from the item directory.

2.7.5. Generating information for Ingress issues (CloudBees CI on modern cloud platforms)

The following command will generate the information that Support needs for diagnosing Ingress issues.

cbsupport required-data ingress

The command is interactive and will ask for the namespace in which the Ingress Controller is deployed

2.7.6. Generating information for Sidecar Injector issues (CloudBees CI on modern cloud platforms)

The following command will generate the information that Support needs for diagnosing Sidecar injector issues.

cbsupport required-data sidecar-injector

The command is interactive and will ask for the namespace in which the Sidecar Injector is deployed

2.7.7. Generating information for Jenkins Memory issues

The following command will generate the information that Support needs for diagnosing Memory related issues.

cbsupport required-data memory [–-heapdump=true|false]

The heapdump flag is optional (defaults to false) and drives whether a heapdump will be generated or not. Be aware that, depending on the size of the Heap, heapdumps can be huge and greatly increase the size of generated data. In case of doubt, do not generate the heapdump, Support will ask you specifically to activate the option.

3. Features (matrix per installation type)

Given the previous section, the feature section gives:

Command/Install type Kubernetes Other

check

check cluster

version

update

health-check

1

required-data default

2

required-data performance

required-data io

required-data ingress

required-data build

required-data item

required-data sidecar-injector

required-data memory

help

context create

context delete

context describe

context edit

context get

context set

1 Health checks will depend on the type of product. 2 Will only generate a bundle and jenkins cluster information but no infrastructure info.

4. Known issues and limitations

  • Proxies are not supported

  • On CloudBees CI on modern cloud platforms, Multicluster is not supported

  • On other installation types, an ssh agent is needed

  • On other installation types, only port 22 is allowed for ssh connections

  • When creating the working directory, cbsupport cannot create nested directories (ie the directory you provide should be located in an existing directory).

  • 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.

5. Licenses