backplane-cli is a CLI tool to interact with backplane api.
Go should be installed in your local system with version 1.19
Download the latest binary from the GitHub releases page.
For example, to download the binary on Linux:
$ wget https://github.com/openshift/backplane-cli/releases/download/v0.1.1/ocm-backplane_0.1.1_Linux_x86_64.tar.gz
$ tar -xvzf ocm-backplane_0.1.1_Linux_x86_64.tar.gz
$ chmod +x ocm-backplane
$ mv ocm-backplane $GOBIN
First clone the repository somewhere in your $PATH. A common place would be within your $GOPATH.
Example:
$ mkdir $GOPATH/src/github.com/openshift
$ cd $GOPATH/src/github.com/openshift
$ git clone git@github.com/openshift/backplane-cli.git
$ make build
This command will build the backplane-cli binary, named ocm-backplane. This binary will be placed in $PATH.
As the binary has prefix ocm-, it becomes a plugin of ocm, and can be invoked by ocm backplane.
For more information about ocm plugins, please refer https://github.com/openshift-online/ocm-cli#extend-ocm-with-plugins
The configuration file of backplane-cli is expected to be located at $HOME/.config/backplane/config.json.
To setup the PS1(prompt) for bash/zsh, please follow these instructions.
| Command | Description |
|---|---|
ocm backplane login <CLUSTERID/EXTERNAL_ID/CLUSTER_NAME> |
Login to the target cluster |
ocm backplane logout <CLUSTERID/EXTERNAL_ID/CLUSTER_NAME> |
Logout from the target cluster |
ocm backplane config get [flags] |
Retrieve Backplane CLI configuration variables |
ocm backplane config set [flags] |
Set Backplane CLI configuration variables |
ocm backplane console [flags] |
Launch the OpenShift console of the current logged in cluster |
ocm backplane cloud console |
Launch the current logged in cluster's cloud provider console |
ocm backplane cloud credentials [flags] |
Retrieve a set of temporary cloud credentials for the cluster's cloud provider |
ocm backplane elevate <reason> -- <command> |
Elevate privileges to backplane-cluster-admin and add a reason to the api request, this reason will be stored for 20min for future usage |
ocm backplane monitoring <prometheus/alertmanager/thanos/grafana> [flags] |
Launch the specified monitoring UI (Deprecated following v4.11 for cluster monitoring stack) |
ocm backplane script describe <script> [flags] |
Describe the given backplane script |
ocm backplane script list [flags] |
List available backplane scripts |
ocm backplane session [flags] |
Create a new session and log into the cluster |
ocm backplane status |
Print essential cluster info |
ocm backplane managedJob create <script> [flags] |
Create a backplane managed job resource |
ocm backplane managedJob get <job_name> [flags] |
Retrieve a backplane managed job resource |
ocm backplane managedJob list [flags] |
Retrieve a list of backplane managed job resources |
ocm backplane managedJob logs <job_name> [flags] |
Retrieve logs of the specified managed job resource |
ocm backplane managedJob delete <job_name> [flags] |
Delete the specified managed job resource |
ocm backplane testJob create <script> [flags] |
Create a backplane test managed job on a non-production cluster for testing. To use with bash libraries, make sure the libraries are in the scripts directory in the format source /managed-scripts/<path-from-managed-scripts-scripts-dir> |
ocm backplane testJob get <job_name> [flags] |
Retrieve a backplane test job resource |
ocm backplane testJob list [flags] |
Retrieve a list of backplane test job resources |
ocm backplane testJob logs <job_name> [flags] |
Retrieve logs of the specified test job resource |
ocm backplane upgrade |
Upgrade backplane-cli to the latest version |
ocm backplane version |
Display the installed backplane-cli version |
ocm backplane healthcheck |
Check the VPN and Proxy connectivity on the host network when experiencing isssues accessing the backplane API |
In this example, we will login to a cluster with id 123456abcdef in production environment, and we have the OCM client environment setup like this.
-
Run backplane login in another terminal.
$ ocm backplane login <cluster> -
Run
occommand to access the target cluster.$ oc whoami system:serviceaccount:default:1234567 -
To login to the Management cluster for HyperShift (or) the managing Hive shard of normal OSD/ROSA cluster
$ ocm backplane login <cluster> --manager -
To login to the Service Cluster of a HyperShift hosted cluster or the Management Cluster
$ ocm backplane login <cluster> --service
- Login to the target cluster via backplane and add --cluster-info flag
$ ocm backplane cluster login <cluster> --cluster-info
Logging into multiple clusters via different terminal instances.
-
How to log into the first cluster
$ ocm backplane login <cluster-id-1> --multi $ export KUBECONFIG= <cluster-id-1-kube-config-path>you can also directly run
$ source <(ocm backplane login <cluster-id-1> --multi) -
How to log into the second cluster
$ ocm backplane login <cluster-id-2> --multi $ export KUBECONFIG= <cluster-id-2-kube-config-path>
-
Generate a User Token REST API Key and save it into backplane config file.
$ ocm backplane config set pd-key <api-key>Replace
<api-key>with the actual User Token REST API Key obtained from PagerDuty. -
To log in using the PagerDuty incident link, use the following command:
$ ocm backplane login --pd https://{your-pd-domain}.pagerduty.com/incidents/<incident-id>Replace
<incident-id>with the specific incident ID you want to access. -
Alternatively, if you have the incident ID, you can use the following command:
$ ocm backplane login --pd <incident-id>Replace
<incident-id>with the specific incident ID you want to access.
-
Login to the target cluster via backplane as the above.
-
Run the below command and it will launch the console of the current logged in cluster.
$ ocm backplane console --> Console will be available at http://127.0.x.x:xxxx -
Follow the above link
http://127.0.x.x:xxxxto access console.You can directly open the console in browser by adding flag -b or setting environment variable
BACKPLANE_DEFAULT_OPEN_BROWSER=true. Example,When running this command, it will open the console in the browser automatically.
$ ocm backplane console -bOr set the environment variable
$ export BACKPLANE_DEFAULT_OPEN_BROWSER=true $ ocm backplane consoleOptionally, you can also load the enabled console plugin
$ ocm backplane console -pluginsNote: Load the console plugin from backplane-cli is not sufficient to access the console plugin, backplane-api to expose the console plugin service explicitly is needed.
-
Login to the target cluster via backplane as the above.
-
Run the below command and it will launch the cloud console of the current logged in cluster.
$ ocm backplane cloud console Console Link: Link: https://xxxxx -
Follow the above link to access the console.
You can directly open the console in the browser by adding flag
-bor setting the environment variableBACKPLANE_DEFAULT_OPEN_BROWSER=true.When running this command, it will open the console in the browser automatically.
$ ocm backplane cloud console -bOr set the environment variable
$ export BACKPLANE_DEFAULT_OPEN_BROWSER=true $ ocm backplane cloud console `
Monitoring command can be used to launch the specified monitoring UI.
Run this command from within a cluster :
ocm backplane monitoring <prometheus/alertmanager/thanos/grafana> [flags]
Note: Following version 4.11, Prometheus, AlertManager and Grafana monitoring UIs are deprecated for openshift-monitoring stack, please use 'ocm backplane console' and use the observe tab for the same. Other monitoring stacks remain unaffected.
Backplane session command will create an isolated environment to interact with a cluster in its own directory. The default location for this is ~/backplane.
The default session save path can be configured via the backplane config file.
{
"url": "your-bp-url"
"proxy-url": "your-proxy-url"
"session-dir":"your-session-dir"
}
The following command will create a new session and log in to the cluster.
## with intractive session name
ocm backplane session <session-name> -c <cluster-id>
## only with cluster id
ocm backplane session <cluster-id>
Backplane session keeps the session history commands in /session-name/.history file.
[ <session-name> (<cluster-info-PS1>)]$ history
1 2023-05-08 15:06:05 oc get nodes
2 2023-05-08 15:06:13 oc get co
3 2023-05-08 15:06:40 history
Backplane session setup following environment variables.
HISTFILE = <your-session-path>/<session-name>/.history
PATH = <your-os-path>
KUBECONFIG = <your-session-path>/<session-name>/<cluster-id>/config
CLUSTERID = <cluster-id>
CLUSTERNAME = <cluster-name>
Folowing command delete the session
ocm backplane session --delete <session-name>
If you need to run some oc command(s) with elevation using backplane-cluster-admin user, you can use the elevate command for this.
Backplane elevate takes as first positional argument the reason for this elevation. If the first argument is an empty string, then it will be considered as an empty reason, but you cannot just skip the reason argument if you provide also other positional argument(s). If you want to not provide an empty string as reason, you can use the -n/--no-reason option and oc command will start at first positional argument.
The elevate command requires a none empty reason for the elevation. When a reason is provided it will be used for future usage, in order you do not have to provide a reason for each elevation commands. The reasons are stored in the kubeconfig context, so it is valid only for the cluster for which it has been provided. When a reason is created/used, the last used reason timestamp is updated in the context, and the reason will be kept for 20min after its last usage, in order to avoid bad usage.
When you use the elevate command with an empty reason, it will look if a non expired reason is stored in the current context for this server, and if there is one it will use it. If there is no reason stored in current context, then if the stdin and stderr are not redirected to pipe or file, a prompt will be done to ask for the reason.
$ ocm-backplane evate 'OHSS-xxxxxx' -- get secret xxx
The provided reason will be used for elevation, but also stored for future elevation on this cluster. If a reason was already stored in the current_context, then this provided reason will be added to it.
If you run the elevate command with an empty reason for the first time (or after the expiration), then you will be prompt for the reason if possible
$ ocm-backplane elevate '' -- get secret xxx
Please enter a reason for elevation, it will be stored in current context for 20 minutes : <here you can enter your reason>
or
$ ocm-backplane elevate -n -- get secret xxx
Please enter a reason for elevation, it will be stored in current context for 20 minutes : <here you can enter your reason>
If then you rerun an elevate command, for the same cluster, before the expiration delay, no prompt will be done and previous reason will be used for elevation.
You can initialize the reson context for a cluster without running a command, then the reason will be used for future commands
$ ocm-backplane elevate 'OHSS-xxxxxx'
or you can not provide the reason and will be prompt for it if needed
$ ocm-backplane elevate
Please enter a reason for elevation, it will be stored in current context for 20 minutes : <here you can enter your reason>
If a prompt is required but that stdin and/or stderr are redirected to file or output, then an error will be generated.
$ cat patch.json | ocm-backplane elevate -n -- patch -f -
ERRO[0000] please enter a reason for elevation
$ ocm-backplane elevate -n -- get secret xxx 2> error.txt
ERRO[0000] please enter a reason for elevation
In order to avoid those errors, you can either run the the elevate without command before or provide a none empty reason.
No issue if only stdout is redirected.
$ ocm-backplane elevate -n -- get secret xxx | grep xxx
Please enter a reason for elevation, it will be stored in current context for 20 minutes : <here you can enter your reason>
The backplane health check can be used to verify VPN and proxy connectivity on the host network as a troubleshooting approach when experiencing issues accessing the backplane API.
The end-user needs to set the VPN and Proxy check-endpoints in the local backplane configuration first:
cat ~/.config/backplane/config.json
{
"proxy-url": ["http://proxy1.example.com:3128", "http://proxy2.example.com:3128"],
"vpn-check-endpoint": "http://your-vpn-endpoint.example.com",
"proxy-check-endpoint": "http://your-proxy-endpoint.example.com"
}
vpn-check-endpoint:To specify this test endpoint to check if it can be accessed with the currently connected VPN.proxy-check-endpoint:To specify this test endpoint to check if it can be accssed with the currently working proxy.
NOTE: The vpn-check-endpoint and proxy-check-endpoint mentioned above are just examples, the end-user can customize them as needed.
- Running healthcheck by default
./ocm-backplane healthcheck
Checking VPN connectivity...
VPN connectivity check passed!
Checking proxy connectivity...
Getting the working proxy URL ['http://proxy1.example.com:3128'] from local backplane configuration.
Testing connectivity to the pre-defined test endpoint ['https://your-proxy-endpoint.example.com'] with the proxy.
Proxy connectivity check passed!
Checking backplane API connectivity...
Successfully connected to the backplane API!
Backplane API connectivity check passed!
- Specify the healthcheck flags to run
vpnorproxycheck only
./ocm-backplane healthcheck --vpn
Checking VPN connectivity...
VPN connectivity check passed!
./ocm-backplane healthcheck --proxy
Checking proxy connectivity...
Proxy connectivity check passed!
Note: VPN connection check is a pre-requisite (The example below demonstrates checking proxy connectivity with VPN disconnected.)
./ocm-backplane healthcheck --proxy
WARN[0000] No VPN interfaces found: [tun tap ppp wg]
VPN connectivity check failed: No VPN interfaces found: [tun tap ppp wg]
Note: Proxy connectivity check requires VPN to be connected. Please ensure VPN is connected and try again.
Backplane CLI has a default release cycle of every 2 weeks
In case of you have changes that have immediate impact and would need an immediate promotion, please reach out to:
Backplane team (alias : @backplane-team) in #sd-ims-backplane slack channel
To help diagnose any issues, you can modify the default verbosity of the logger. Use -v for info level or explicitly setting the logging level by using --verbosity=debug flag.
For further information on logging levels refer to the in-built help.
$ ocm backplane help
See design.md.
Please help us to improve. To contact the backplane team:
- @backplane-team in slack channel #sd-ims-backplane (CoreOS workspace)
- Or reach out OWNERS
As part of our continuous integration (CI) process, we've incorporated govulncheck to identify known vulnerabilities in the backplane-cli codebase.
Following each CI execution, especially when PRs are submitted, a detailed vulnerability report can be found in build-log.txt. This is nested within
the artifacts/test/ directory of the ci/prow/scan-optional test. To retrieve the report:
- Click on
Detailsnext toci/prow/scan-optionalin a specific PR. - Click
Artifactsat the top-right corner of the page. - Navigate to
artifacts/test/to view thebuild-log.txtcontaining vulnerability information.
While some detected vulnerabilities might be non-blocking at the moment, they are still reported. We encourage both users and developers to thoroughly review these reports. If any Go packages are flagged, consider updating them to their fixed versions.
To manually execute a vulnerability scan locally, run the following command:
make scan