Opstrace Command Line Interface (CLI) Reference

This document provides reference information about the Opstrace cluster management command line interface (CLI).

Commands

Note: please also use the --help switch to discover additional reference information that the CLI emits about itself.

create

Creates a new Opstrace cluster.

Example (for creating a cluster named testcluster in AWS):

./opstrace create aws testcluster -c config.yaml

Help text:

$ ./opstrace create --help
usage: opstrace create [-h] [--log-level LEVEL] [-c CONFIG_FILE_PATH] [--yes]
[--hold-controller]
PROVIDER CLUSTER_NAME
positional arguments:
PROVIDER The cloud provider to act on (aws, gcp).
CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no more than
13 characters).
optional arguments:
-h, --help show this help message and exit
--log-level LEVEL Set log level for output on stderr. One of: debug,
info, warning, error. Default: info
-c CONFIG_FILE_PATH, --cluster-config CONFIG_FILE_PATH
File path to cluster config document (YAML). Read
from stdin otherwise.
--yes Automatic yes to prompts; assume 'yes' as answer to
all prompts andrun non-interactively
--hold-controller Do not deploy controller into k8s cluster (for
development purposes).

Notes:

  • Cloud provider and cluster name are not part of the cluster configuration document. That means that the same cluster configuration document can be re-used across cloud providers and also across clusters with different names.
  • The create operation has internal timeout and retry logic. Unless you know better, it makes sense to keep this procedure running.
  • When the create operation detects a problem that needs to be resolved through human intervention then it does not necessarily error out immediately. Instead, it presents the problem through its logs, retries periodically, and waits for you to take action behind the scenes. For example, when a cloud resource can't be created as of a quota error then you can infer that from the CLI's log output and can take action while the CLI keeps retrying. If you do not take action, the create operation will time out eventually.
  • For some permanent, non-retryable errors the create operation will exit immediately, providing a clear error message.
  • When the create operation errors out expectedly or unexpectedly or when you interrupt it manually (for instance, by sending SIGINT via Ctrl+C) then you can safely re-run it. It is designed to pick up the work where it was left.

destroy

Tear down an existing Opstrace cluster.

Example (for tearing down a cluster named testcluster in AWS):

./opstrace destroy aws testcluster

In the happy case, no input beyond cloud provider and cluster name is needed. However, in certain ambiguous cases the CLI may ask for the --region argument

Help text:

$ ./opstrace destroy --help
usage: opstrace destroy [-h] [--log-level LEVEL] [--yes] [--region REGION]
PROVIDER CLUSTER_NAME
positional arguments:
PROVIDER The cloud provider to act on (aws, gcp).
CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no more than 13
characters).
optional arguments:
-h, --help show this help message and exit
--log-level LEVEL Set log level for output on stderr. One of: debug, info,
warning, error. Default: info
--yes Automatic yes to prompts; assume 'yes' as answer to all
prompts andrun non-interactively
--region REGION Set the AWS region to destroy in. Only needed when the
automatic region detection fails (when the corresponding
EKS cluster cannot be found or inspected). Not yet
supported for GCP.

Notes:

  • Cloud provider, cloud credentials and Opstrace cluster name are the fundamental input parameters for the destroy operation.
  • The destroy operation has internal timeout and retry logic. Unless you know better, it makes sense to keep this procedure running.
  • When the destroy operation errors out expectedly or unexpectedly or when you interrupt it manually (for instance, by sending SIGINT via Ctrl+C) then you can safely re-run it. It largely is designed to pick up the work where it was left. However, in some cases after partial teardown it may ask you to provide the cloud region via the --region argument

list

List existing Opstrace clusters (visible with the configured cloud credentials).

Example:

./opstrace list aws

Help text:

$ ./opstrace list --help
usage: opstrace list [-h] [--log-level LEVEL] PROVIDER
positional arguments:
PROVIDER The cloud provider to act on (aws, gcp).
optional arguments:
-h, --help show this help message and exit
--log-level LEVEL Set log level for output on stderr. One of: debug, info,
warning, error. Default: info

upgrade

Upgrade Opstrace from the version running in your account to the version defined by the current CLI you are using.

NOTE: GCP platform is not yet supported.

Example (to upgrade a cluster named testcluster in AWS):

./opstrace upgrade aws testcluster -c config.yaml

Help text:

$ ./opstrace upgrade --help
usage: opstrace upgrade [-h] [--log-level LEVEL] [-c CONFIG_FILE_PATH] [--yes] [--region REGION]
PROVIDER CLUSTER_NAME
positional arguments:
PROVIDER The cloud provider to act on (aws, gcp).
CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no more than 23 characters).
optional arguments:
optional arguments:
-h, --help show this help message and exit
--log-level LEVEL Set log level for output on stderr. One of: debug, info,
warning, error. Default: info
-c CONFIG_FILE_PATH, --cluster-config CONFIG_FILE_PATH
File path to cluster config document (YAML). Read
from stdin otherwise.
--yes Automatic yes to prompts; assume 'yes' as answer to all
prompts andrun non-interactively
--region REGION Set the AWS region. Only needed when the
automatic region detection fails (when the corresponding
EKS cluster cannot be found or inspected). Not yet
supported for GCP.

Notes:

  • The CLI version that executes the upgrade command defines the Opstrace target version.
  • The original config file used to create the cluster is required. However, changes to it are not yet supported. This requirement might change in the future.
  • The upgrade operation has internal timeout and retry logic. Unless you know better, it makes sense to keep this procedure running.
  • When the upgrade operation detects a problem that needs to be resolved through human intervention then it does not necessarily error out immediately. Instead, it presents the problem through its logs, retries periodically, and waits for you to take action behind the scenes. For example, when a cloud resource can't be upgraded as of a quota error then you can infer that from the CLI's log output and can take action while the CLI keeps retrying. If you do not take action, the upgrade operation will time out eventually.
  • For some permanent, non-retryable errors the upgrade operation will exit immediately, providing a clear error message.
  • When the upgrade operation errors out expectedly or unexpectedly or when you interrupt it manually (for instance, by sending SIGINT via Ctrl+C) then you can safely re-run it. It is designed to pick up the work where it was left.

Cloud credential discovery

If not specified otherwise, the Opstrace CLI tries to discover and use the AWS credentials from the default profile in the so-called shared AWS credentials file (~/.aws/credentials on Linux and Mac OS).

You can override this behavior by setting

  • the environment variable AWS_PROFILE (for choosing a different profile from said AWS credentials file)
  • the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (for not consulting the credentials file).

An more detailed specification can be found in the AWS SDK reference documentation here and here.