Skip to content

Overview

Comprehensive automation can be quickly developed by using either the Command Line Interface (RCTL) utility or REST APIs. RCTL enables users to script and automate reproducible workflows without having to interact with the Controller via the Web Console GUI.

RCTL can be embedded into any kind of workflow automation or CI platform such as Jenkins etc. We have developed integrations with popular CI platforms. Review detailed documentation describing Integrations with CI Platforms.


Scope

The RCTL CLI Utility can be embedded into your preferred workflow automation platform and be used to perform operations on the following resources managed by the Controller.

Resource Create Get Update Delete Publish Unpublish
Addon YES YES YES YES N/A N/A
Blueprint YES YES YES YES N/A N/A
Cluster YES YES YES YES N/A N/A
Credential YES YES No YES N/A N/A
Namespace YES YES NO YES N/A N/A
Workload YES YES YES YES YES YES
Pipeline YES YES YES YES Activate Deactivate
Repository YES YES YES YES N/A N/A
Trigger YES YES YES YES N/A N/A

Users are recommended to use the Controller's REST APIs for privileged resources such as "Projects".


Examples

We develop and maintain illustrative examples of integrations with "CI platforms". These are available on a public Github repository.

Review the CI Integrations Section for additional details and examples on how to embed RCTL into your preferred CI platform.


Platform Support

RCTL is supported on Windows, Mac, and Linux operating systems.

Windows Linux macOS
64-bit 64-bit 64-bit

Downloads

Manual Download

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”).

Tools Page

Download CLI


Automated Download

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

OS RCTL Download URL
Linux https://s3-us-west-2.amazonaws.com/rafay-prod-cli/publish/rctl-linux-amd64.tar.bz2
macOS https://s3-us-west-2.amazonaws.com/rafay-prod-cli/publish/rctl-darwin-amd64.tar.bz2
Windows https://s3-us-west-2.amazonaws.com/rafay-prod-cli/publish/rctl-windows-amd64.zip

Check 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.3.4
BUILD: tags/r1.3.4-99
BUILD-TIME: Wed Sep 23 01:52:31 UTC 2020
ARCH: darwin/amd64

Embedded Help

RCTL can provide contextual help when requested.

./rctl -h
A CLI tool to manage resources.

Usage:
  rctl [command]

Available Commands:
  activate    activate pipelines in the Controller
  apply       apply for creating or updating resources(pipeline) in the Controller
  completion  Generate completion script
  config      Manage configuration of the CLI utility
  create      Create various resources in Controller
  deactivate  deactivate pipelines in the Controller
  delete      Delete various resources in Controller
  download    Download various resources in Controller
  get         get various resources in Controller
  help        Help about any command
  kubeconfig  Generate kubeconfig
  namespace   Manage namespaces
  publish     Publish workloads
  start       start pipelines in the Controller
  status      Find out the status of resources like workloads
  stop        stop pipelines in the Controller
  unpublish   Unpublish resources like workloads
  update      update the details of various resource
  validate    Validate resources like workloads
  version     Displays version of the CLI utility
  workload    Manage workloads

OR

./rctl --help

Usage Modes

RCTL supports both Interactive and Scripted usage modes.

Interactive Mode

This is the default mode. This is aimed at human users that wish to interact directly with the Controller and view the results in a human-readable format.

Scripted Mode

This mode is useful when RCTL is embedded into a workflow such as a CI/CD pipeline. The generated output will ideally be in a JSON or YAML format that can be consumed programmatically by the pipeline.


Exit Codes

The 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

Deprecated Commands

Early versions of RCTL were limited to lifecycle operations for "workloads" and "namespaces". In an effort to enable full end to end automation, the scope of RCTL has dramatically increased to cater for lifecycle management of multiple resource types. Upcoming, future versions of RCTL will continue to expand scope further.

Resource Prior Version Current Version
Addon NO YES
Blueprint NO YES
Cluster NO YES
Blueprint NO YES
Namespace YES YES
Workload YES YES

To accommodate this significant change, RCTL commands are now "action centric" instead of "resource centric". Although, previous "resource" centric commands will continue to work, they should be considered as deprecated and will be removed in the near future.

# Operation Deprecated
1 Kubeconfig YES. Use Download
2 Namespace YES. Use Create, Get, Update, Delete
3 Workload YES. Use Create, Get, Update, Delete