Opstrace Command Line Interface (CLI) Reference
This document provides reference information about the Opstrace command line interface (CLI).
Commands
Please use the --help
switch to discover additional reference information that the CLI emits about itself.
create
Creates a new Opstrace instance with a configuration document.
Example (for creating an instance named test
in AWS):
./opstrace create aws test -c config.yaml
Help text:
$ ./opstrace create --helpusage: opstrace create [-h] [--log-level LEVEL] [-c CONFIG_FILE_PATH] [--yes][--hold-controller] [--write-kubeconfig-file PATH]PROVIDER CLUSTER_NAMEpositional arguments:PROVIDER The cloud provider to act on (aws, gcp).CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no more than23 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_PATHFile path to cluster config document (YAML). Readfrom stdin otherwise.--yes Automatic yes to prompts; assume 'yes' as answer toall prompts andrun non-interactively--hold-controller Do not deploy controller into k8s cluster (fordevelopment purposes).--write-kubeconfig-file PATHWrite kubectl config file (for KUBECONFIG env var)as soon as data is available (right after K8s clusterhas been set up).
Notes:
- Cloud provider and instance name are not part of the configuration document. That means that the same configuration document can be re-used across cloud providers and also across instances with different names.
- The
create
operation has internal timeout and retry logic. Unless you know better, it makes sense to keep this operation 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, thecreate
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 sendingSIGINT
viaCtrl+C
) then you can safely re-run it. It is designed to pick up the work where it was left.
destroy
Remove an existing Opstrace instance and all its supporting cloud resources.
Example (for tearing down an instance named test
in AWS):
./opstrace destroy aws test
In the happy path no input beyond cloud provider and instance name is needed.
However, in certain ambiguous cases where the CLI can not automatically detect the region your instance is in, it will ask for the --region
argument.
Once provided, the CLI will remove all resources created for that instance name in the given region.
Help text:
$ ./opstrace destroy --helpusage: opstrace destroy [-h] [--log-level LEVEL] [--yes] [--region REGION]PROVIDER CLUSTER_NAMEpositional arguments:PROVIDER The cloud provider to act on (aws, gcp).CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no more than 23characters).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 allprompts andrun non-interactively--region REGION Set the AWS region to destroy in. Only needed when theautomatic region detection fails (when the correspondingEKS cluster cannot be found or inspected). Not yetsupported for GCP.
Notes:
- Cloud provider, cloud credentials and Opstrace instance name are the fundamental input parameters for the
destroy
operation. - The
destroy
operation has internal timeout and retry logic, similar to thecreate
operation. 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 sendingSIGINT
viaCtrl+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 --helpusage: opstrace list [-h] [--log-level LEVEL] PROVIDERpositional 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.
Example (to upgrade an instance named test
in AWS):
./opstrace upgrade aws test -c config.yaml
Help text:
$ ./opstrace upgrade --helpusage: opstrace upgrade [-h] [--log-level LEVEL] [-c CONFIG_FILE_PATH][--yes] [--region REGION] PROVIDER CLUSTER_NAMEpositional arguments:PROVIDER The cloud provider to act on (aws, gcp).CLUSTER_NAME The Opstrace cluster name ([a-z0-9-_], no morethan 23 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_PATHFile path to cluster config document (YAML). Readfrom stdin otherwise.--yes Automatic yes to prompts; assume 'yes' as answer to allprompts andrun non-interactively--region REGION Set the AWS region. Only needed when theautomatic region detection fails (when the correspondingEKS cluster cannot be found or inspected). Not yetsupported for GCP.
Notes:
- The CLI version that executes the upgrade command defines the Opstrace target version.
- The original config file used to create the instance 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, similar to thecreate
operation. 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, theupgrade
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 sendingSIGINT
viaCtrl+C
) then you can safely re-run it. It is designed to pick up the work where it was left.
Tenant API Authentication with ta-*
Commands
The ta-
prefix represents the idea of "tenant API authentication."
See our upcoming Tenant Guide for usage examples.
$ ./opstrace --helpusage: opstrace [-h] [--version] [--log-level LEVEL]{create,destroy,list,status,upgrade,ta-create-keypair,ta-create-token,ta-pubkeys-add,ta-pubkeys-list,ta-pubkeys-remove}...ta-create-keypair Tenant authentication: create a new RSA key pair.ta-create-token Tenant authentication: create a tenant API authentication token signed with a custom private key.Write token to stdout.ta-pubkeys-add Tenant authentication: add public key to a running Opstrace cluster so that it accepts tokenssigned with the corresponding private key.ta-pubkeys-list Tenant authentication: list public keys for a running Opstrace cluster, i.e. the set of trustanchors for signed authentication tokens.ta-pubkeys-remove Tenant authentication: remove a specific public key from the set of trust anchors, i.e. do notaccept corresponding authentication tokens anymore.
All ta-*
commands offered by the Opstrace CLI are new and should be thought of as experimental (command names and signatures are subject to potentially big changes in the future).
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
andAWS_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.