sloctl

README

Sloctl is a command-line interface (CLI) for Nobl9. You can use sloctl to manage multiple Nobl9 configuration objects such as SLOs, Projects or Alert Policies.

The web user interface is available to give you an easy way to create and update SLOs and other resources, while sloctl aims to provide a systematic and automated approach to maintaining SLOs as code.

You can use it in CI/CD or your terminal power-user workflows 🔥

Usage

Sloctl includes built-in documentation for each command, to access it, run:

sloctl <command> --help

For more details check out sloctl user guide.

If you want to learn how to fully tame the sloctl's potential, see recipes section below.

Install

Script

The script requires bash and a minimal set of GNU utilities. On Windows it will work with either MinGW or Cygwin. You can either pipe it directly into bash or download the file and run it manually.

# Using curl:
curl -fsSL https://raw.githubusercontent.com/nobl9/sloctl/main/install.bash | bash

# On systems where curl is not available:
wget -O - -q https://raw.githubusercontent.com/nobl9/sloctl/main/install.bash | bash

# If you prefer to first download the script, inspect it and then run it:
curl -fsSL -o install.bash https://raw.githubusercontent.com/nobl9/sloctl/main/install.bash
# Or with wget:
wget -O install.bash -q https://raw.githubusercontent.com/nobl9/sloctl/main/install.bash
# Once downloaded, set execution permissions:
chmod 700 install.bash
# The script is well documented and comes with additional options.
# You can display the help message by running:
./install.bash --help

Prebuilt Binaries

The binaries are available at Releases page.

Go install

go install github.com/nobl9/sloctl/cmd/sloctl@latest

Homebrew

brew tap nobl9/sloctl
brew install sloctl

Docker

Sloctl official images are hosted on hub.docker.com.

Here's an example workflow for managing Project object:

1. Export sloctl access keys through environment variables.

   export SLOCTL_CLIENT_ID=<your-client-id>
   export SLOCTL_CLIENT_SECRET=<your-client-secret>
   

2. Create a sample Project object and save it to project.yaml file.

   cat << EOF > project.yaml
   apiVersion: n9/v1alpha
   kind: Project
   metadata:
     displayName: My Project
     name: my-project
   spec:
     description: Just and example Project :)
   EOF
   

3. Apply the project from project.yaml. To keep STDIN open and allow piping the contents of project.yaml into the docker run command, use interactive mode with docker run.

   cat project.yaml | docker run --rm -i \
     -e SLOCTL_CLIENT_ID=${SLOCTL_CLIENT_ID} \
     -e SLOCTL_CLIENT_SECRET=${SLOCTL_CLIENT_SECRET} \
     nobl9/sloctl apply -f -
   

4. Fetch the applied Project.

   docker run --rm \
     -e SLOCTL_CLIENT_ID=${SLOCTL_CLIENT_ID} \
     -e SLOCTL_CLIENT_SECRET=${SLOCTL_CLIENT_SECRET} \
     nobl9/sloctl get project my-project
   

5. Remove the Project.

   docker run --rm \
     -e SLOCTL_CLIENT_ID=${SLOCTL_CLIENT_ID} \
     -e SLOCTL_CLIENT_SECRET=${SLOCTL_CLIENT_SECRET} \
     nobl9/sloctl delete project my-project
   

Build Docker image locally

1. Download Dockerfile and latest linux sloctl binary from the Releases page. Make sure they are in your working directory.

2. Build the image:

   docker build -t <NAME_YOUR_IMAGE> .
   

3. Set environment variables if you plan to use them for authenticating with SLOCTL. Reference the sloctl environment variables Doc.

4. Run the image:

   docker run
   -e SLOCTL_CLIENT_ID=$SLOCTL_CLIENT_ID \
   -e SLOCTL_CLIENT_SECRET=$SLOCTL_CLIENT_SECRET \
   <YOUR_IMAGE_NAME> get slos --no-config-file
   

Recipes

Prerequisites:

• jq, a popular command-line JSON processor.
• yq is wrapper over jq, it extends jq's capabilities with YAML support.

1. Filter out SLOs with specific integration (prometheus in this example):

sloctl get slos -A |
  yq -Y \
  --arg source_type "prometheus" \
  '[ .[] | select(
    .spec.objectives[] |
      (.rawMetric and .rawMetric.query[$source_type])
      or
      (.countMetrics and .countMetrics.total[$source_type])
  )]'