Logo

Sloctl User Guide

sloctl, a command-line tool from Nobl9 to configure and manage SLO resources

Back to Nobl9 Documentation

Sloctl User Guide

Sloctl is the command-line interface (CLI) for Nobl9 you can use the sloctl CLI when creating or updating multiple SLOs at once, creating or updating multiple objectives, or when updating SLOs as part of CI/CD.

The web user interface is available to give you an easy way to create and update SLOs, and to familiarize you with the features available in Nobl9, while sloctl aims to provide a systematic and/or automated approach to maintaining SLOs as code.

Setting Up Sloctl

Use the following steps to install and configure Nobl9 command-line interface, sloctl.

Binary Installation

When installing files in protected folders, the operating system occasionally requires copy or file permissions. When this happens, give the installed files executable permissions (Linux and Mac) or confirm the file copy operation (Windows).

Use the following steps to download the Nobl9 CLI.

  1. Download the appropriate binary executable zip file from https://github.com/nobl9/sloctl/releases .
  2. Extract the binary. The following are platform-specific instructions:

Mac OS
For Mac OS, we recommend using brew:

  1. Install Homebrew.

  2. Use Terminal to complete the installation:

     brew tap nobl9/sloctl
     brew install sloctl
    

Note: The Mac OS occasionally requires file permissions. When this happens, give the file executable permission. For further details, see Mac Users instructions.

Linux
We recommend manual installation from the binary executable zip file to /usr/local/bin.

💡 Note: The Linux operating system occasionally requires file permissions. When this happens, give the file executable permission. For further details, see Linux instructions.

Windows
We recommend manual installation from the binary executable zip file to C:\Windows\System32

💡 Note: The Windows operating system occasionally requires file permissions. When this happens, give the file executable permission. For further details on copying to system folders and executable permissions, see Windows instructions.

Configuration

Follow the steps below to configure your sloctl connection.

  1. Create a Client ID and Client Secret pair for use in sloctl.

    • Navigate to Settings → Access Keys in the web UI.

    • Click Create Access Key.

  2. Follow UI instructions to configure sloctl to use the provided credentials. Use one of the available set-up flows:

    • Click the Download credentials file in the web UI and put downloaded file in ~/.config/nobl9/config.toml (Linux and macOS) or %UserProfile%\.config\nobl9\config.toml (Windows).

    or

    • Run sloctl add-context, name the context, and paste the Client ID and Client Secret from the web UI when prompted.
  3. Test the configuration by entering sloctl get slos into the command line.

Note: If there are no SLOs created in your account or in the selected project, you might see this message: No resources found in default project. The message means the configuration is correct. The command line will return a 401 error if the configuration does not work.

General Usage

The following is a general structure of sloctl commands:

  sloctl [command] [object] [--flags]

To get a list of all possible commands and flags, use one of the following forms:

  sloctl -h
  sloctl --help

To get details about a specific command and its objects and flags, use one of the following forms:

Summary of sloctl Commands

The following are the available commands in sloctl.

All commands start with sloctl. For example stoctl delete

Command Description
add-context Add new sloctl configuration context.
apply Apply resource definition in YAML or JSON format.
completion Generate the autocompletion script for sloctl for the specified shell.
delete Delete resource definition by name or definition file.
get Display one or more resources.
help Help about any command.
use-context Set the default context.
version Print the sloctl version.

Common Objects

These are the API objects that you can manipulate with sloctl with different commands.

For details about each object, see the YAML Guide.

Objects arguments follow the command argument in the sloctl command line.

For example:

Object Description
agents Provide a solution to metrics collection from external sources. In this solution users deploy the agents
alertmethods When an incident is triggered, Nobl9 enables you to send the alert to a notification engine or tool
alertpolicies A policy defining a set of conditions that when met, cause an alert to be a sent to a predefined list of integrations
alerts Notifications for SLOs when certain conditions are met
dataexports The configuration to export your data from Nobl9
directs Provide a SaaS solution to metrics collection from external sources
projects Serve as workspaces for resources and provide a layer of isolation for resources in different projects
services High-level groupings of SLOs
rolebindings Assign a user the permissions indicated in a role
slos A set of target values for a service level objective

Caution: If you are using sloctl version older than 0.0.56, you will not be able to use the kind: Project and kind: RoleBinding.

Flags

Common Flags pass data to a command or parameter.

Flag Long Form Description
-h --help Help for sloctl
-o --output string output format: one of table|yaml|json (default yaml)

Certain sloctl commands have other specific flags. Hence, Global Flags define the scope of the current command, such as the project, context, or location of the configuration file:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-p --project string Overrides the default project from active context for the duration of the selected command.

Command References

Add-context

The add-context command adds a new sloctl configuration context. It is an interactive command, that collects parameters in a wizard mode.

Usage:

  sloctl add-context
  1. Set the context name:

    New context name: Enter the context name and press Enter

  2. Set the Client ID:

    In the Nobl9 application, the Client ID is generated by navigating to Settings -> Access Keys -> Create Access Key:

    * Client ID:Enter the Client ID and press Enter

  3. Set Client Secret:

    • Client Secret: Enter the Client Secret and press Enter
  4. Set a default Project:

    The project can be overridden with the -p (--project) flag in any command:

    • Project [default]: Enter the default project name and press Enter
  5. You are asked if newly created context should be set as default now:

    • Set 'context name from Step 1' as a default context? [y/N]: type y (for Yes) or n (for No)

    Note: Hitting Enter without selecting y or n would default to No.

Apply

The apply command commits the changes by sending the updates to the application.

Usage:

  sloctl apply [flags]

Examples:

Flags:

Flag Long Form Description
-f --file []string Provides a file path or a URL to the configuration in YAML or JSON format. This option can be used multiple times.
-h --help Help for sloctl

Global Flags:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-p --project string Overrides the default project from active context for the duration of the selected command.

Use sloctl apply [object] --help for more information about the delete command and different objects.

When the specified changes were applied successfully, a confirmation message is shown:

sloctl apply -f ./samples/sample.yaml

Resources successfully created.

Completion

The completion command generates the autocompletion script for sloctl for the specified shell.

Usage:

  sloctl completion [command]

Available commands

Command Description
bash Generate the autocompletion script for bash.
fish Generate the autocompletion script for fish.
powershell Generate the autocompletion script for powershell.
zsh Generate the autocompletion script for zsh.

Flags:

Flag Long Form Description
-h --help Help for completion.

Global Flags:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-p --project string Overrides the default project from active context for the duration of the selected command.

Delete

The delete command allows users to delete different resources.

Usage:

  sloctl delete [flags]
  sloctl delete [command]

Examples:

Available objects:

For details, see Common Objects

Flags:

Flag Long Form Description
-f --file string Provides a file path or a URL to the configuration in YAML or JSON format. This option can be used multiple times.
-h --help Help for sloctl.

Global Flags:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-p --project string Overrides the default project from active context for the duration of the selected command.

Use sloctl delete [object] --help for more information about the delete command and different objects.

When the specified objects were deleted successfully, sloctl shows the following confirmation message:

sloctl delete -f example.yaml

The resources were successfully deleted.

Get

The get command prints a table of the most important information about the specified resources.

Usage:

  sloctl get [object]

Available objects:

For details, see Common Objects

Flags:

Flag Long Form Description
-h --help Help for sloctl.
-o --output string output format: one of table|yaml|json (default yaml)

Global Flags:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-p --project string Overrides the default project from active context for the duration of the selected command.

Use sloctl get [object] --help for more information about the get command and different objects.

Notes:

Help (Start screen)

sloctl
sloctl -h
sloctl --help

All available commands for execution are listed below.

Use this tool to work with definitions of SLO in YAML files.

For every command more detailed help is available.

Usage:

sloctl [command]

Available Commands:

Command Description
add-context Add new sloctl configuration context.
apply Apply resource definition in YAML or JSON format.
completion Generate the autocompletion script for sloctl for the specified shell.
delete Delete resource definition by name or definition file.
get Display one or more than one resource.
help Help about any command.
use-context Set the default context.
version Print the sloctl version.

Flags:

Flag Long Form Description
-A --all-projects Displays the objects from all of the projects.
  --config string Config file path (without this flag checks for %UserProfile%\.config\nobl9\config.toml on Windows and ~/.config/nobl9/config.toml on other operating systems).
-c --context string Overrides the default context for the duration of the selected command.
-h --help Help for sloctl
-p --project string Overrides the default project from active context for the duration of the selected command.

Use sloctl [command] --help for more information about a command.

Use-context

You can define multiple contexts and the use-context command allows you to choose the default context. It is helpful if the user belongs to multiple organizations or if the user wants to switch between different default projects.

Usage

  sloctl use-context context-name # non-interactive mode
  sloctl use-context # interactive mode

When sloctl use-context is used in interactive mode and some contexts are already defined, the user is asked to select the context from the list.

For example:

When no context is defined yet, sloctl returns the following error:

Version

The version command prints the installed version of sloctl.

Usage

  sloctl version

The output includes product version and architecture. For example,

Common Errors / Warnings

The following are common errors/warnings that users can experience.

Use Cases of SLO Configurations

For detailed examples of how to create SLOs for sample services using sloctl, refer to the Getting Started Guide.

Deprecated

With the 0.0.58 release kind: Integration has been deprecated and kind: AlertMethod has been introduced instead.

During the transition period, users can still apply their YAML files that use kind: Integration. Nobl9 will no longer return it, but it will return AlertMethod. The sloctl get command will not return any results for integrations.