CLI: sts

Overview

The SUSE® Observability sts CLI provides easy access to the functionality provided by the SUSE® Observability APIs. It can be used for automation using SUSE® Observability data, to configure SUSE® Observability and to develop StackPacks.

Prerequisites

  • SUSE® Observability URL - The URL of your SUSE® Observability instance (the same URL used to access the web interface).

  • API Token - A valid API token for authentication, which can be retrieved from the CLI page in your SUSE® Observability instance.

To obtain your API token:

  1. Log into your SUSE® Observability instance.

  2. Navigate to Main menu > CLI.

  3. Copy the API token displayed on the page.

Quick start

The fastest way to install and configure the sts CLI is to use the pre-filled commands available in your SUSE® Observability instance:

  1. Log into your SUSE® Observability instance.

  2. Navigate to Main menu > CLI.

  3. Copy the command for your OS and run it in a terminal.

These commands are pre-filled with the correct URL and API token for your specific SUSE® Observability instance, making installation and configuration a single step.

Download the CLI

  • Windows

  • macOS

  • Linux

  • Docker

Open a Powershell terminal (version 5.1 or later) and run the steps below. This can be done one step at a time, or joined together as a single script. After installation, the sts command will be available for the current user on both the Powershell terminal and the command prompt (cmd.exe).

  1. Set the source version and target path for the CLI:

    $CLI_PATH = $env:USERPROFILE +"\stackstate-cli"
If (!(test-path $CLI_PATH)) { md $CLI_PATH }
Invoke-WebRequest https://dl.stackstate.com/stackstate-cli/LATEST_VERSION -OutFile $CLI_PATH\VERSION
$VERSION=type $CLI_PATH\VERSION
$VERSION=$VERSION -replace "[v]"
$CLI_DL = "https://dl.stackstate.com/stackstate-cli/v$VERSION/stackstate-cli-$VERSION.windows-x86_64.zip"
echo "Installing {stackstate-product-name} CLI v$VERSION to: $CLI_PATH"

  2. Download and unpack the CLI to the target CLI path. Remove remaining artifacts:

    Invoke-WebRequest $CLI_DL -OutFile $CLI_PATH\stackstate-cli.zip
Expand-Archive -Path "$CLI_PATH\stackstate-cli.zip" -DestinationPath $CLI_PATH -Force
rm $CLI_PATH\stackstate-cli.zip, $CLI_PATH\VERSION

  3. Register the CLI path to the current user’s PATH. This will make the sts command available everywhere:

    $PATH = (Get-ItemProperty -Path "Registry::HKEY_CURRENT_USER\Environment" -Name PATH).Path
if ( $PATH -notlike "*$CLI_PATH*" ) {
  $PATH = "$PATH;$CLI_PATH"
  (Set-ItemProperty -Path "Registry::HKEY_CURRENT_USER\Environment" -Name PATH –Value $PATH)
  $MACHINE_PATH = (Get-ItemProperty -Path "Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment" -Name PATH).path
  $env:Path = "$PATH;$MACHINE_PATH"
}

  4. Verify that the CLI works:

    sts version

Open a terminal and run the steps below. This can be done one step at a time, or all together as a single script. After installation, the sts command will be available for the current user.

  1. Download the latest CLI version for x86_64 (Intel) or arm64 (M1).

    (VERSION=`curl https://dl.stackstate.com/stackstate-cli/LATEST_VERSION` &&
  VERSION=${VERSION#v} &&
  ARCH=`uname -m` &&
  curl https://dl.stackstate.com/stackstate-cli/v$VERSION/stackstate-cli-$VERSION.darwin-$ARCH.tar.gz | tar xz --directory /usr/local/bin)

  2. Verify that the CLI works:

    sts version

Open a terminal and run the steps below. This can be done one step at a time, or all together as a single script. After installation, the sts command will be available for the current user.

  1. Download and unpack the latest version for x86_64:

    (VERSION=`curl https://dl.stackstate.com/stackstate-cli/LATEST_VERSION` && VERSION=${VERSION#v} &&
curl https://dl.stackstate.com/stackstate-cli/v$VERSION/stackstate-cli-$VERSION.linux-x86_64.tar.gz | tar xz --directory /usr/local/bin)

  2. Verify that the CLI works:

    sts version

To run the latest version of the CLI using Docker execute:

docker run stackstate/stackstate-cli2

Alternatively, go to the CLI page in the SUSE® Observability UI and copy the Quick installation command for Docker - this is pre-filled with the correct <URL> and <API-TOKEN> required to configure the CLI for your SUSE® Observability instance.

You can now run CLI commands by appending them to the end of the docker run command (for example, docker run stackstate/stackstate-cli2 version).

Configure the CLI

Authentication

API token

By default, the CLI will authenticate using the API token that you provided when the CLI configuration was saved.

The most secure way to use your API token is through an environment variable. You can store the API token with a secrets manager and inject it as an environment variable into your shell.

  • Windows / macOS / Linux

  • Docker

  1. In the SUSE® Observability UI, go to Main menu > CLI and copy your API token.

  2. Run the command below, where <URL> is the URL to your SUSE® Observability instance and <API-TOKEN> is the API token you copied from the CLI page in the SUSE® Observability UI:

    sts context save --name <NAME> --url <URL> --api-token <API-TOKEN>

  3. The connection to your SUSE® Observability instance will be tested and a configuration file stored at ~/.config/stackstate-cli/config.yaml.

The Docker version of the CLI can’t be configured with a config file. Specify the configuration of your SUSE® Observability instance using environment variables and pass these to Docker:

  • STS_CLI_URL - the URL to your SUSE® Observability instance.

  • STS_CLI_API_TOKEN - the API token taken from the SUSE® Observability UI Main menu > CLI page.

  • STS_CA_CERT_PATH - path to a PEM-encoded CA certificate file for servers using self-signed certificates. The directory containing the certificate must be mounted into the Docker container.

  • STS_CA_CERT_BASE64_DATA - base64-encoded CA certificate data for servers using self-signed certificates (ignored if STS_CA_CERT_PATH is specified).

  • STS_SKIP_SSL - disables SSL certificate validation (ignores certificate configurations, use with caution).

For example:

docker run \
   -v /path/to/certs:/certs \
   -e STS_CLI_URL \
   -e STS_CLI_API_TOKEN \
   -e STS_CA_CERT_PATH=/certs/ca.crt \
   stackstate/stackstate-cli2 settings list --type Layer

Service tokens

You can optionally use the CLI to create one or more service tokens to authenticate with the SUSE® Observability Base and Admin APIs. For example, a service token can be used to authenticate in CI (Continuous Integration) scenarios where no real user is doing the operations on the SUSE® Observability instance.

To create a service token, run the command below:

sts service-token create --name <NAME> --roles <ROLE(s)> [--expiration <yyyy-MM-dd>]

This will create a new service token and print it. The --expiration parameter is optional and can be used to set the expiration date of the service token.

Once you have this, you can configure the CLI to use it:

sts context save --name <NAME> --service-token <TOKEN> --url <URL>

Manage multiple contexts

The sts CLI supports configuration and management of different (authentication) contexts. This enables you to easily switch between an administrative and regular user, or to switch between different SUSE® Observability instances. For example, you could use a different context for a test and production instance of SUSE® Observability. You can list, save, delete, set and validate contexts in the sts CLI. Run sts context -h for details of the available commands and their usage.

Configuration options

You don’t need a configuration file to run the sts CLI. You can also configure the CLI through a combination of environment variables and flags.

If multiple types of configuration are presented to the CLI the order of processing will be:

  1. Flags

  2. Environment variables

  3. Config file

Environment variable Flag Description

STS_CLI_URL

--url

URL to your SUSE® Observability instance.

STS_CLI_API_TOKEN

--api-token

API token to your SUSE® Observability instance. The most secure way to use your API token is through an environment variable. You can store the API token with a secrets manager and inject it as an environment variable into your shell.

STS_CLI_SERVICE_TOKEN

--service-token

A service token to your SUSE® Observability instance. The most secure way to use your service token is through an environment variable. You can store the service token with a secrets manager and inject it as an environment variable into your shell.

STS_CA_CERT_PATH

--ca-cert-path

Path to a PEM-encoded CA certificate file for servers using self-signed certificates or certificates from a private CA.

STS_CA_CERT_BASE64_DATA

--ca-cert-base64-data

Base64-encoded CA certificate data for servers using self-signed certificates or certificates from a private CA. Ignored if STS_CA_CERT_PATH is specified.

STS_SKIP_SSL

--skip-ssl

Disables SSL certificate validation. When set to true, the CLI will not validate SSL certificates and will ignore STS_CA_CERT_PATH and STS_CA_CERT_BASE64_DATA settings. Use with caution as this reduces security.

STS_CLI_API_PATH

n/a

The path appended to the end of the URL to get the API endpoint. (Defaults to /api)

STS_CLI_CONTEXT

--context

The name of the context to use.

Next to overriding specific parts of the config file, it’s also possible to override the default config file location. This is done through the --config <PATH> flag.

Available Commands

The sts CLI provides the following top-level commands:

Command Description

agent

Manage SUSE® Observability agents

completion

Generate autocompletion scripts for shells

context

Manage the CLI contexts and configurations

dashboard

Manage dashboards

health

Health synchronization related commands

license

Manage SUSE® Observability license information

monitor

Manage monitors and monitoring configurations

rbac

Manage RBAC

service-token

Manage service tokens.

settings

Manage instance settings and configurations

stackpack

Manage and upload StackPacks

topic

Manage Kafka topics

topology-sync

Manage topology synchronization

user-session

Inspect user sessions

version

Display version information

All commands accept the --help flag, which documents each command’s usage.

For detailed information about any command and its subcommands, run:

sts [command] --help

Upgrade

To upgrade to the latest version of the sts CLI, run the install command again.

You can check the version of the sts CLI that you are currently running with the command sts version.

Uninstall

  • Windows

  • macOS

  • Linux

  • Docker

Quick uninstall

Open a Powershell terminal and run:

. { iwr -useb https://dl.stackstate.com/stackstate-cli/install.ps1 } | iex; uninstall

The sts CLI and all associated configuration are now removed for the current user.

Manual uninstall

Open a Powershell terminal and run each step one-by-one or all at once. The sts CLI and all associated configuration will be removed for the current user.

  1. Remove binary:

    $CLI_PATH = $env:USERPROFILE+"\stackstate-cli"
rm -R $CLI_PATH 2>1  > $null

  2. Remove config:

    rm -R $env:USERPROFILE+"\.config\stackstate-cli" 2>1  > $null

  3. Remove the CLI from the environment path:

    $PATH = (Get-ItemProperty -Path 'Registry::HKEY_CURRENT_USER\Environment' -Name PATH).Path
$i = $PATH.IndexOf(";$CLI_PATH")
if ($i -ne -1) {
  $PATH = $PATH.Remove($i, $CLI_PATH.Length+1)
  (Set-ItemProperty -Path 'Registry::HKEY_CURRENT_USER\Environment' -Name PATH –Value $PATH)
}

Quick uninstall

Open a terminal and run:

curl -o- https://dl.stackstate.com/stackstate-cli/uninstall.sh | bash

The sts CLI and all associated configuration are now removed for the current user.

Manual uninstall

  1. Open a terminal.

  2. To remove the sts CLI, run the command:

    rm -r /usr/local/bin/sts

  3. To remove configuration for the sts CLI, run the command:

    rm -r ~/.config/stackstate-cli

The sts CLI and all associated configuration are now removed for the current user.

Quick uninstall

Open a terminal and run:

curl -o- https://dl.stackstate.com/stackstate-cli/uninstall.sh | bash

The sts CLI and all associated configuration are now removed for the current user.

Manual uninstall

  1. Open a terminal.

  2. To remove the sts CLI, run the command:

    rm -r /usr/local/bin/sts

  3. To remove configuration for the sts CLI, run the command:

    rm -r ~/.config/stackstate-cli

The sts CLI and all associated configuration are now removed for the current user.

To remove the CLI image and containers run:

docker rmi -f stackstate/stackstate-cli2

Open source

The SUSE® Observability sts CLI is open source and can be found on GitHub at: