Overview
Comprehensive automation can be quickly developed by using the RCTL Command Line Interface (RCTL) utility. RCTL enables users to script and automate reproducible workflows without having to interact with the Controller via the Web Console or the APIs or the Terraform provider.
Explore our blog for deeper insights on Declarative Cluster Lifecycle Management, available here!
Scope¶
The RCTL CLI can be embedded into your preferred "workflow automation platform" and be used to perform operations on ALL resources managed by the Controller.
Working Examples¶
RCTL can be embedded into any kind of workflow automation or CI platform such as Jenkins, CircleCI, GitHub Actions, GitLab etc. Review the CI Integrations Section for additional details and examples on how to embed RCTL into your preferred CI platform.
Important
Working examples of integrations are available on a public Github repository.
Platform Support¶
RCTL is supported on Windows, Mac, and Linux operating systems.
| Windows | Linux | macOS |
|---|---|---|
| 64-bit | 64-bit | 64-bit |
Note
Users can use the same macOS binary on ARM based Macs by enabling Rosetta 2.
Download RCTL¶
Manual¶
The Web console provides several conveniences for end users (developers etc) by making it intuitive for them to download the RCTL binaries.
- On the left panel of the admin console, click on "My Tools".
- Click on the "Download CLI" button and download the package for your operating system
- Unzip the downloaded package into a folder (for example: “rctl”).
Automated¶
Workflow automation systems and pipelines can embed the "download URLs" for RCTL binaries. Note that this download URL will always provide the "latest version" of the RCTL CLI.
Version¶
Use the following steps to check the version of RCTL. Users are encouraged to upgrade to the latest versions on a periodic basis (esp. with every release) to ensure they can leverage the latest functionality.
- Open Terminal (on macOS or Linux) or Command Prompt (on Windows).
- Navigate (i.e. change directory) to the folder where RCTL was unzipped.
- Type the following command.
./rctl version
VERSION: r1.21.0
BUILD: refs/tags/r1.21.0-43
BUILD-TIME: Fri 09 Dec 2022 11:02:14 AM UTC
ARCH: darwin/amd64
Embedded Help¶
RCTL can provide contextual help when requested.
./rctl --help
You should see output similar to the example shown below.
A CLI tool to manage resources.
Usage:
rctl [command]
Available Commands:
activate activate pipelines
apply apply for creating or updating resources in Rafay Console
completion Generate completion script
config Manage configuration of the CLI utility
convert2managed Convert various resources to managed.
create Create various resources in Console
deactivate deactivate pipelines
delete Delete various resources in Console
deploy deploy various resources in Console
download Download various resources in Console
drain Create various resources in Console
generate Generate various resources in Console
get get various resources in Console
help Help about any command
kubeconfig Generate kubeconfig
publish Publish workloads
scale Scale various resources in Console
set Set various resources in Console
share Share various resources in Console
start start pipelines
status Find out the status of resources like workloads
stop stop pipelines
uncordon Create various resources in Console
undeploy Undeploy
unpublish Unpublish resources like workloads
update update the details of various resource
upgrade Upgrade various resources in Console
validate Validate resources like workloads
version Displays version of the CLI utility
workload Manage workloads
Flags:
-c, --config string Customize cli config file
-d, --debug Enable debug logs
-h, --help help for rctl
-o, --output string Print json, yaml or table output. Default is table (default "table")
-p, --project string provide a specific project context
-v, --verbose Verbose mode. A lot more information output.
--wait Wait for the operation to complete
Use "rctl [command] --help" for more information about a command.
Usage Modes¶
The RCTL CLI can be used in both Interactive and Scripted modes.
Interactive Mode¶
This is the default mode and is primarily meant for human users that wish to view the results in a human-readable format.
Scripted Mode¶
This mode is useful when RCTL is embedded into a workflow such as an automation pipeline. The generated output will ideally be in a JSON or YAML format that can be consumed programmatically by the automation platform.
Exit Codes¶
The RCTL CLI returns an exit code (aka return code) for every command. The standard exit code is "0" for SUCCESS. Any other number for an exit code should be considered an ERROR.
To get the exit code, type "echo $?" at the command prompt after the command completes. Customers can use these exit codes to check for status of a CLI command when it is embedded into a workflow/pipeline.
#!/bin/bash
./rctl version
if [ $? -eq 0 ]
then
echo "The command ran OK"
exit 0
else
echo "The command failed"
exit 1
fi
Troubleshooting¶
RCTL can be configured to print detailed information via "verbose mode" to assist with troubleshooting. During a support call, support may request you to use the "debug" mode to assist with debugging.
Verbose Mode¶
For example, to enable "verbose" mode while retrieving the list of workloads
./rctl get workload --verbose
Debug Mode¶
For example, to enable "debug" mode while retrieving the list of workloads
./rctl get workload --debug
Auto Completion¶
RCTL can generate auto completion scripts for your target platform and shell.
./rctl completion -h
On Linux or macOS, you can use the following command to identify the current shell. In the example below, the current shell is "bash".
echo $SHELL
/bin/bash