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:
|
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 In the meantime, a workaround is to directly delete the tenant from the cbsupport CLI configuration file (either under |
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
|
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.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
|
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 – CloudBees Support.
-
By default the configuration of the tool is persisted at
$HOME/.cbsupport/config.json. The environment variableCBSUPPORT_CONFIGmay 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.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 |
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,
cbsupportcannot 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
-
The cbsupport CLI makes use of jattach published under Apache License 2.0
-
The cbsupport CLI makes use of busybox published under the GNU General Public License, version 2. Sources are available here.