casactl CLI

The casactl CLI is a tool that helps you manage self-hosted CloudCasa. It is especially useful for collecting logs. Note that you can use --help option at any level to get detailed usage information.

Installation

There are three different ways in which you can get access to casactl.

  1. Using docker image.

  2. Run it in one of “amds-apiserver” pods (starting from release 1.4.4).

  3. Install in a virtual env.

Using Docker

Users will need to do “docker login” first using their ACR credentials as the image is not publicly available. These are the same credentials used while installing CloudCasa.:

docker login --username <USER> --password <PASSWORD>

Since casactl needs to be able to run kubectl against the cloudcasa server cluster, kubeconfig needs to be accessible from within the container. For example, if the current directory has “kubeconfig” file, it can be mounted, as follows:

docker run --rm -it -v `pwd`:/data cloudcasa.azurecr.io/catalogicsoftware/casactl:latest -- bash
> export CASACTL_CC_SERVER_KUBECONFIG_OPTIONS="--kubeconfig /data/kubeconfig"
> casactl server info

Note that with this method, any files created by the tool (log archives for example) may need to be copied outside the container unless options are passed to the tool to place them in a mounted directory. Check specific commands for info on such options.

Running in api server pods

Starting from the release 1.4.4, casactl is packaged with “amds-apiserver” image so you can just exec into one of the “amds-apiserver” pods and run it, like so:

$ kubectl -n cloudcasa-server exec -it amds-apiserver-84bbd959c5-mb9w4 -- bash

bash-5.1$ casactl server info

Installing in a virtual env

casactl requires Python 3.9 or later and is distributed as a “wheel” file. E.g. “casactl-0.42-py3-none-any.whl”. It is available in CloudCasa support portal under “Resources” section. Please contact CloudCasa support if your access is not already set up.

It is best to install casactl in a Python virtual environment. Here is one way of doing it (on Linux):

$ python3 -m venv ~/venv/casactl
$ ~/venv/casactl/bin/pip install pip --upgrade
$ ~/venv/casactl/bin/pip install <WHEEL-FILE>

You can then either add ~/venv/ccmanage/bin to the PATH environment variable, or use the absolute path to run casactl.

See also

For more details, see Creating virtual environments.

For upgrading to a newer version, run:

$ ~/venv/casactl/bin/pip install <WHEEL-FILE> --upgrade

Usage

Run casactl --help to see all available commands.

casactl uses kubectl command to access the cluster running CloudCasa server, so kubectl should be properly set up. In most cases, if you can run kubectl to manage the server cluster, you can run casactl without any further configuration. However, if you need to pass extra parameters to “kubectl”, see Passing kubectl options.

If CloudCasa is configured with self-signed certificate, you need to pass the -k option to casactl to ignore SSL validation errors.

Every run of the casactl command creates a unique log file in the system temp directory. In case of any errors, check the log file. An example log file (on Linux):

/tmp/casactl-2024-03-06-15-40-52-_a6njvmf.txt

Commands

Collecting server logs

To collect logs from CloudCasa server components, run the command:

casactl server logs

This will collect logs from all CloudCasa pods, and creates an archive (zip file for the most part). In order to collect logs for a particular component, pass the name of the component using “-c” option.:

casactl server logs -c apiserver

To collect logs for multiple components, use the “-c” option multiple times. Example:

casactl server logs -c apiserver -c mongo

Run casactl server logs --help to find all the available components.

Finally, to skip creation of the archive file, use the “–no-zip” option.

Collecting job logs

To collect logs for a job:

casactl job logs <JOB-ID>

This will download logs for the job (similar to downloading from UI) but will also collect some additional information.

Note

Starting from 1.4.4 version, “Download logs” in UI will automatically use this command to generate job logs, so you don’t need to run this command explicitly in most cases.

Scrape metrics

To see what metrics CloudCasa publishes, run the command:

casactl server metrics

Catalog restore

The casactl catalog command performs a catalog restore. This may be needed if CloudCasa has to be reinstalled for some reason. For details, see Catalog backup/restore.

Passing kubectl options

In rare cases, additional parameters may need to be passed to kubectl to access the server cluster. casactl supports this use case with the option “–server-kcopts”. Using this option, you can pass any kubectl parameters that need to be used to access the CloudCasa cluster. For example, if the kubeconfig file is at location “/tmp/cloudcasa.kubeconfig”, you can run the script as follows:

casactl --server-kcopts "--kubeconfig /tmp/cloudcasa.kubeconfig" ...

Here is another example:

casactl --server-kcopts "--kubeconfig /tmp/cloudcasa.kubeconfig --cluster cloudcasa" ...

kubectl parameters can also be passed in an environment variable instead of as a command line parameter. To do this, set the environment variable “CASACTL_CC_SERVER_KUBECONFIG_OPTIONS”. Here is an example using bash:

export CASACTL_CC_SERVER_KUBECONFIG_OPTIONS="--kubeconfig /tmp/cloudcasa.kubeconfig"

Once the variable is set, you can simply run “casactl” without passing “–server-kcopts”.