Command line interface for the Drove Container Orchestrator.
You can install the CLI from PyPI.
pip install drove-cliCreate virtual environment
mkdir -p ${HOME}/venvs
cd ${HOME}/venvs
python3 -m venv drove_cli
cd drove_cli
source bin/activate
pip install drove-cliTo activate in another shell:
source ${HOME}/venvs/drove_cli/bin/activateTo deactivate the venv (run when in activated environment):
deactivateThe cli is pushed as a docker for easy access. This also eliminates the need for having python etc setup on your system.
- Pull the image:
docker pull ghcr.io/phonepe/drove-cli:latest- Create a shell script called
drovewith the following content:
#! /bin/sh
docker run \
--rm --interactive --tty --network host \
--name drove-cli -v ${HOME}/.drove:/root/.drove:ro \
ghcr.io/phonepe/drove-cli:latest "$@"
- Make the script executable
chmod a+x drove- Put the path to this script in your
~/.bashrc.
export PATH="${PATH}:/path/to/your/script"-
Logout/login or run
. ~/.bashrcto load the new [path] -
Run drove cli
drove -hThe CLI is written in Python 3x
The arguments needed by the script are self documenting. Please use -h or --help in different sections and sub-sections of the CLI to get descriptions of commands, sub-commands, their arguments and options.
To see basic help:
$ drove -h
usage: drove [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]
{executor,cluster,apps,appinstances,tasks} ...
positional arguments:
{executor,cluster,apps,appinstances,tasks}
Available plugins
executor Drove cluster executor related commands
cluster Drove cluster related commands
apps Drove application related commands
appinstances Drove application instance related commands
tasks Drove task related commands
options:
-h, --help show this help message and exit
--file FILE, -f FILE Configuration file for drove client
--cluster CLUSTER, -c CLUSTER
Cluster name as specified in config file
--endpoint ENDPOINT, -e ENDPOINT
Drove endpoint. (For example: https://drove.test.com)
--auth-header AUTH_HEADER, -t AUTH_HEADER
Authorization header value for the provided drove endpoint
--insecure INSECURE, -i INSECURE
Do not verify SSL cert for server
--username USERNAME, -u USERNAME
Drove cluster username
--password PASSWORD, -p PASSWORD
Drove cluster password
--debug, -d Print details of errors
To see documentation for a command/section:
$ drove cluster -h
usage: drove cluster [-h] {ping,summary,leader,endpoints,events,maintenance-on,maintenance-off} ...
positional arguments:
{ping,summary,leader,endpoints,events,maintenance-on,maintenance-off}
Available commands for cluster management
ping Ping the cluster
summary Show cluster summary
leader Show leader for cluster
endpoints Show all exposed endpoints
events Events on the cluster
maintenance-on Set cluster to maintenance mode
maintenance-off Removed maintenance mode on cluster
options:
-h, --help show this help message and exit
To further drill down into options for a sub-command/subsection:
$ drove cluster events -h
usage: drove cluster events [-h] [--follow] [--type TYPE] [--count COUNT] [--textfmt TEXTFMT]
optional arguments:
-h, --help show this help message and exit
--follow, -f Follow events (Press CTRL-C to kill)
--type TYPE, -t TYPE Output events of only the matching type
--count COUNT, -c COUNT
Fetch <count> events at a time.
--textfmt TEXTFMT, -s TEXTFMT
Use the format string to print message
In order to use the CLI, we need to provide coordinates to the cluster to connect to. This can be done in the following manner:
The config file can be located in the following paths:
.drovefile in your home directory (Typically used for the default cluster you frequently connect to)- A file in any path that can be passed as a parameter to the CLI with the
-f FILEoption
This file is in ini format and is arranged in sections.
[DEFAULT]
...
stage_token = <token1>
prod_token = <token2>
[local]
endpoint = http://localhost:10000
username = admin
password = admin
[stage]
endpoint = https://stage.testdrove.io
auth_header = %(stage_token)s
[production]
endpoint = https://prod.testdrove.io
auth_header = %(prod_token)s
..The DEFAULT section can be used to define common variables like Insecure etc. The local, stage, production etc are names for individual clusters and these sections can be used to define configuration for individual clusters. Cluster name is referred to in the command line by using the -c command line option.
Interpolation of values is supported and can be achieved by using %(variable_name)s references.
- Note: The
DEFAULTsection is mandatory- Note: The
sat the end of%(var)sis mandatory for interpolation
endpoint = https://yourcluster.yourdomain.com # Endpoint for cluster
insecure = true
username = <your_username>
password = <your_password>
auth_header= <Authorization value here if using header based auth>
Authentication priority:
- If both
usernameandpasswordare provided, basic auth is used. - If a value is provided in the
auth_headerparameter, it is passed as the value for theAuthorizationheader in the upstream HTTP calls to the Drove server verbatim. - If neither, no auth is set
NOTE: Use the
insecureoption to skip certificate checks on the server endpoint (comes in handy for internal domains)
To use a custom config file, invoke drove in the following form:
$ drove -f custom.conf ...
This will connect to the cluster if an endpoint is mentioned in the DEFAULT section.
$ drove -f custom.conf -c stage ...
This will connect to the cluster whose config is mentioned in the [stage] config section.
$ drove -c stage ...
This will connect to the cluster whose config is mentioned in the [stage] config section in $HOME/.drove config file.
Pass the endpoint and other options using --endpoint|-e etc etc. Options can be obtained using -h as mentioned above. Invocation will be in the form:
$ drove -e http://localhost:10000 -u guest -p guest ...
The following CLI format is followed:
usage: drove [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]
{executor,cluster,apps,appinstances,tasks} ...
-h, --help show this help message and exit
--file FILE, -f FILE Configuration file for drove client
--cluster CLUSTER, -c CLUSTER
Cluster name as specified in config file
--endpoint ENDPOINT, -e ENDPOINT
Drove endpoint. (For example: https://drove.test.com)
--auth-header AUTH_HEADER, -t AUTH_HEADER
Authorization header value for the provided drove endpoint
--insecure INSECURE, -i INSECURE
Do not verify SSL cert for server
--username USERNAME, -u USERNAME
Drove cluster username
--password PASSWORD, -p PASSWORD
Drove cluster password
--debug, -d Print details of errors
Commands in drove are meant to address specific functionality. They can be summarized as follows:
list List all executors
info Show details about executor
appinstances Show app instances running on this executor
tasks Show tasks running on this executor
blacklist Blacklist executors
unblacklist Un-blacklist executors
Drove cluster executor related commands
drove executor [-h] {list,info,appinstances,tasks} ...List all executors
drove executor list [-h]Show details about executor
drove executor info [-h] executor-idexecutor-id - Executor id for which info is to be shown
Show app instances running on this executor
drove executor appinstances [-h] [--sort {0,1,2,3,4,5}] [--reverse] executor-idexecutor-id - Executor id for which info is to be shown
--sort {0,1,2,3,4,5}, -s {0,1,2,3,4,5}
Sort output by column
--reverse, -r Sort in reverse order
Show tasks running on this executor
drove executor tasks [-h] [--sort {0,1,2,3,4,5}] [--reverse] executor-idexecutor-id - Executor id for which info is to be shown
--sort {0,1,2,3,4,5}, -s {0,1,2,3,4,5}
Sort output by column
--reverse, -r Sort in reverse order
Take executors out of rotation.
drove executor blacklist executor-id [executor-id ...]executor-id - List of executor ids to be blacklisted. At least one is mandatory.
Bring blacklisted executors back into rotation.
drove executor blacklist executor-id [executor-id ...]executor-id - List of executor ids to be blacklisted. At least one is mandatory.
Drove cluster related commands
drove cluster [-h] {ping,summary,leader,endpoints,events} ...Ping the cluster
drove cluster ping [-h]Show cluster summary
drove cluster summary [-h]Show leader for cluster
drove cluster leader [-h]Show all exposed endpoints
drove cluster endpoints [-h] [--vhost VHOST] --vhost VHOST, -v VHOST
Show details only for the specific vhost
Events on the cluster
drove cluster events [-h] [--follow] [--type TYPE] [--count COUNT] [--textfmt TEXTFMT] --follow, -f Follow events (Press CTRL-C to kill)
--type TYPE, -t TYPE Output events of only the matching type
--count COUNT, -c COUNT
Fetch <count> events at a time.
--textfmt TEXTFMT, -s TEXTFMT
Use the format string to print message
Default: “{type: <25} | {id: <36} | {time: <20} | {metadata}”
Set cluster to maintenance mode.
drove cluster maintenance-onSet cluster to normal mode.
drove cluster maintenance-offDrove application related commands
drove apps [-h] {list,summary,spec,create,destroy,deploy,scale,suspend,restart,cancelop} ...List all applications
drove apps list [-h] [--sort {0,1,2,3,4,5,6,7,8}] [--reverse] --sort {0,1,2,3,4,5,6,7,8}, -s {0,1,2,3,4,5,6,7,8}
Sort output by column
--reverse, -r Sort in reverse order
Show a summary for an application
drove apps summary [-h] app-idapp-id - Application ID
Print the raw json spec for an application
drove apps spec [-h] app-idapp-id - Application ID
Create application on cluster
drove apps create [-h] spec-filespec-file - JSON spec file for the application
Destroy an app with zero instances
drove apps destroy [-h] app-idapp-id - Application ID
Deploy new app instances.
drove apps deploy [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-id instancesapp-id - Application ID
instances - Number of new instances to be created
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure instance count is reached
Scale app to required instances. Will increase or decrease instances on the cluster to match this number
drove apps scale [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-id instancesapp-id - Application ID
instances - Number of instances. Setting this to 0 will suspend the app
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure instance count is reached
Suspend the app
drove apps suspend [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-idPositional Arguments¶
app-id - Application ID
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure all instances are suspended
Restart am existing app instances.
drove apps restart [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-idapp-id - Application ID
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure all instances are replaced
Cancel current operation
drove apps cancelop [-h] app-idapp-id - Application ID
Drove application instance related commands
drove appinstances [-h] {list,info,logs,tail,download,replace,kill} ...List all application instances
drove appinstances list [-h] [--old] [--sort {0,1,2,3,4,5}] [--reverse] app-idapp-id - Application ID
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
Print details for an application instance
drove appinstances info [-h] app-id instance-idapp-id - Application ID
instance-id - Application Instance ID
Print list of logs for application instance
drove appinstances logs [-h] app-id instance-idapp-id - Application ID
instance-id - Application Instance ID
Tail log for application instance
drove appinstances tail [-h] [--file FILE] app-id instance-idapp-id - Application ID
instance-id - Application Instance ID
--log LOG, -l LOG Log filename to tail. Default is to tail output.log
Download log for application instance
drove appinstances download [-h] [--out OUT] app-id instance-id fileapp-id - Application ID
instance-id - Application Instance ID
file - Log filename to download
--out, -o Filename to download to. Default is the same filename as provided.
Replace specific app instances with fresh instances
drove appinstances replace [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-id instance-id [instance-id ...]app-id - Application ID
instance-id - Application Instance IDs
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation (default: 1)
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure all instances are replaced
Kill specific app instances
drove appinstances kill [-h] [--parallelism PARALLELISM] [--timeout TIMEOUT] app-id instance-id [instance-id ...]app-id - Application ID
instance-id - Application Instance IDs
--parallelism PARALLELISM, -p PARALLELISM
Number of parallel threads to be used to execute operation
--timeout TIMEOUT, -t TIMEOUT
Timeout for the operation on the cluster (default: 5 minutes)
--wait, -w Wait to ensure all instances are killed
Drove task related commands
drove tasks [-h] {create,kill,list,show,logs,tail,download} ...Create a task on cluster
drove tasks create [-h] spec-filespec-file - JSON spec file for the task
Kill a running task
drove tasks kill [-h] source-app-name task-idsource-app-name - Source app name as specified in spec
task-id - ID of the task as specified in the spec
List all active tasks
drove tasks list [-h] [--app APP] [--sort {0,1,2,3,4,5,6,7,8}] [--reverse] --app APP, -a APP Show tasks only for the given source app
--sort {0,1,2,3,4,5,6,7,8}, -s {0,1,2,3,4,5,6,7,8}
Sort output by column
--reverse, -r Sort in reverse order
Shows details about a task
drove tasks show [-h] source-app task-idsource-app - Name of the Drove application that started the task
task-id - Task ID
Print list of logs for task
drove tasks logs [-h] source-app task-idsource-app - Name of the Drove application that started the task
task-id - Task ID
Tail log for task
drove tasks tail [-h] [--file FILE] source-app task-idsource-app - Name of the Drove application that started the task
task-id - Task ID
--file FILE, -f FILE Log filename to tail. Default is to tail output.log
Download log for task
drove tasks download [-h] [--out OUT] source-app task-id filesource-app - Name of the Drove application that started the task
task-id - Task ID
file - Log filename to download
--out OUT, -o OUT Filename to download to. Default is the same filename as provided.
©2024, Santanu Sinha.