# Epoch CLI
Command line interface for the Epoch Container Orchestrator.
# Getting Started
## Installation
You can install the cli from from PyPI.
```bash
pip install epoch-cli
```
Reactivate/deactivate virtual environment based on the need to utilize epoch cli.
## Requirements
The CLI is written in Python 3x
## Accessing the Documentation
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:
```
$ epoch -h
usage: epoch [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]
{cluster,runs,topology} ...
positional arguments:
{cluster,runs,topology}
Available plugins
cluster Epoch cluster related commands
runs Epoch runs related commands
topology Epoch topology related commands
options:
-h, --help show this help message and exit
--file FILE, -f FILE Configuration file for epoch client
--cluster CLUSTER, -c CLUSTER
Cluster name as specified in config file
--endpoint ENDPOINT, -e ENDPOINT
Epoch endpoint. (For example: https://epoch.test.com)
--auth-header AUTH_HEADER, -t AUTH_HEADER
Authorization header value for the provided epoch endpoint
--insecure INSECURE, -i INSECURE
Do not verify SSL cert for server
--username USERNAME, -u USERNAME
Epoch cluster username
--password PASSWORD, -p PASSWORD
Epoch cluster password
--debug, -d Print details of errors
```
# Connecting to the Epoch cluster
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:
## Epoch CLI config file
The config file can be located in the following paths:
* `.epoch` file 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 FILE` option
### Config File format
This file is in ini format and is arranged in sections.
```ini
[DEFAULT]
...
stage_token = <token1>
prod_token = <token2>
[local]
endpoint = http://localhost:10000
username = admin
password = admin
[stage]
endpoint = https://stage.testepoch.io
auth_header = %(stage_token)s
[production]
endpoint = https://prod.testepoch.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 inidividual 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 acieved by using `%(variable_name)s` references.
> * Note: The `DEFAULT` section is mandatory
> * Note: The `s` at the end of `%(var)s` is mandatory for interpolation
### Contents of a Section
```
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 `username` and `password` are provided, basic auth is used.
* If a value is provided in the `auth_header` parameter, it is passed as the value for the `Authorization` header in the upstream HTTP calls to the Epoch server verbatim.
* If neither, no auth is set
> NOTE: Use the `insecure` option to skip certificate checks on the server endpoint (comes in handy for internal domains)
To use a custom config file, invoke epoch in the following form:
```
$ epoch -f custom.conf ...
```
This will connect to the cluster if an endpoint is mentioned in the `DEFAULT` section.
```
$ epoch -f custom.conf -c stage ...
```
This will connect to the cluster whose config is mentioned in the `[stage]` config section.
```
$ epoch -c stage ...
```
This will connect to the cluster whose config is mentioned in the `[stage]` config section in `$HOME/.epoch` config file.
## Command line options
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:
```
$ epoch -e http://localhost:10000 -u guest -p guest ...
```
## CLI format
The following cli format is followed:
```
usage: epoch [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]
{cluster,runs,topology} ...
```
### Basic Arguments
```
-h, --help show this help message and exit
--file FILE, -f FILE Configuration file for epoch client
--cluster CLUSTER, -c CLUSTER
Cluster name as specified in config file
--endpoint ENDPOINT, -e ENDPOINT
Epoch endpoint. (For example: https://epoch.test.com)
--auth-header AUTH_HEADER, -t AUTH_HEADER
Authorization header value for the provided epoch endpoint
--insecure INSECURE, -i INSECURE
Do not verify SSL cert for server
--username USERNAME, -u USERNAME
Epoch cluster username
--password PASSWORD, -p PASSWORD
Epoch cluster password
--debug, -d Print details of errors
```
## Commands
Commands in epoch are meant to address specific functionality. They can be summarized as follows:
```
cluster Epoch cluster related commands
runs Epoch runs related commands
topology Epoch topology related commands
```
---
Topology
---
Epoch topology executor related commands
```
epoch topology [-h] {list,get,create,update,delete,pause,unpause,run} ...
```
#### Sub-commands
##### list
List all executors
```
epoch topology list [-h]
```
##### get
Show details about topology-id
```
epoch topology get [-h] topology-id
```
###### Positional Arguments
`topology-id` - Topology-id to be shown
##### run
Run the given topology-id
```
epoch topology run [-h] topology-id
```
###### Positional Arguments
`topology-id` - Topology-id to be run
##### create
Create a task on cluster
```
epoch topology create [-h] spec-file
```
###### Positional Arguments
`spec-file` - JSON spec file for the topology
##### update
Update topology running on this cluster
```
epoch topology update [-h] spec-file
```
###### Positional Arguments
`spec-file` - JSON spec file for the topology
##### pause
Pause the given topology-id
```
epoch topology pause [-h] topology-id
```
###### Positional Arguments
`topology-id` - Topology-id to be paused
##### unpause
Unpause the given topology-id
```
epoch topology unpause [-h] topology-id
```
###### Positional Arguments
`topology-id` - Topology-id to be unpaused
##### delete
Delete the given topology-id
```
epoch topology delete [-h] topology-id
```
###### Positional Arguments
`topology-id` - Topology-id to be deleted
---
Cluster
---
Epoch cluster related commands
```
epoch cluster [-h] {leader} ...
```
#### Sub-commands
##### leader
Show leader for cluster
```
epoch cluster leader [-h]
```
---
Runs
---
Epoch application related commands
```
epoch runs [-h] {list,get,kill,log} ...
```
#### Sub-commands
##### list
List all runs
```
epoch runs list [-h]
```
##### get
get the details for the given Topology's runId
```
epoch runs get [-h] topology-id run-id
```
###### Positional Arguments
`topology-id` - Topology-id
`run-id` - Run-id to be fetched
##### kill
Kills the given taskid.
```
epoch runs kill [-h] topology-id run-id task-name
```
###### Positional Arguments
`topology-id` - Topology-id
`run-id` - Run-id
`task-name` - Task-name to be killed
##### log
gets the log the given taskid.
```
epoch runs log [-h] topology-id run-id task-name
```
###### Positional Arguments
`topology-id` - Topology-id
`run-id` - Run-id
`task-name` - Task-name to be fetched
©2024, Shubhransh Jagota.
Raw data
{
"_id": null,
"home_page": "https://github.com/PhonePe/epoch-cli",
"name": "epoch-cli",
"maintainer": "Tushar Naik",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "tushar.knaik@gmail.com",
"keywords": "container, docker, podman, distributed-systems, container-orchestrator",
"author": "Shubhransh Jagota",
"author_email": "mailtoshubhransh@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1a/53/245a52639f555904a9ce9c8171a03493ba674488f5eae781eb188dd3af5b/epoch_cli-0.0.2.tar.gz",
"platform": null,
"description": "# Epoch CLI\n\nCommand line interface for the Epoch Container Orchestrator.\n\n# Getting Started\n\n## Installation\n\nYou can install the cli from from PyPI.\n\n```bash\npip install epoch-cli\n```\n\nReactivate/deactivate virtual environment based on the need to utilize epoch cli.\n\n## Requirements\nThe CLI is written in Python 3x\n\n\n## Accessing the Documentation\nThe 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.\n\nTo see basic help:\n```\n\n$ epoch -h\n\nusage: epoch [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]\n {cluster,runs,topology} ...\n\npositional arguments:\n {cluster,runs,topology}\n Available plugins\n cluster Epoch cluster related commands\n runs Epoch runs related commands\n topology Epoch topology related commands\n\noptions:\n -h, --help show this help message and exit\n --file FILE, -f FILE Configuration file for epoch client\n --cluster CLUSTER, -c CLUSTER\n Cluster name as specified in config file\n --endpoint ENDPOINT, -e ENDPOINT\n Epoch endpoint. (For example: https://epoch.test.com)\n --auth-header AUTH_HEADER, -t AUTH_HEADER\n Authorization header value for the provided epoch endpoint\n --insecure INSECURE, -i INSECURE\n Do not verify SSL cert for server\n --username USERNAME, -u USERNAME\n Epoch cluster username\n --password PASSWORD, -p PASSWORD\n Epoch cluster password\n --debug, -d Print details of errors\n\n```\n\n# Connecting to the Epoch cluster\n\nIn order to use the CLI, we need to provide coordinates to the cluster to connect to. This can be done in the following manner:\n\n## Epoch CLI config file\nThe config file can be located in the following paths:\n* `.epoch` file in your home directory (Typically used for the default cluster you frequently connect to)\n* A file in any path that can be passed as a parameter to the CLI with the `-f FILE` option\n\n### Config File format\nThis file is in ini format and is arranged in sections.\n\n```ini\n[DEFAULT]\n...\nstage_token = <token1>\nprod_token = <token2>\n\n[local]\nendpoint = http://localhost:10000\nusername = admin\npassword = admin\n\n[stage]\nendpoint = https://stage.testepoch.io\nauth_header = %(stage_token)s\n\n[production]\nendpoint = https://prod.testepoch.io\nauth_header = %(prod_token)s\n\n..\n```\n\nThe `DEFAULT` section can be used to define common variables like Insecure etc. The `local`, `stage`, `production` etc are names for inidividual 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.\\\n*Interpolation* of values is supported and can be acieved by using `%(variable_name)s` references.\n\n> * Note: The `DEFAULT` section is mandatory\n> * Note: The `s` at the end of `%(var)s` is mandatory for interpolation\n\n### Contents of a Section\n```\nendpoint = https://yourcluster.yourdomain.com # Endpoint for cluster\ninsecure = true\nusername = <your_username>\npassword = <your_password>\nauth_header= <Authorization value here if using header based auth>\n```\n\nAuthentication priority:\n* If both `username` and `password` are provided, basic auth is used.\n* If a value is provided in the `auth_header` parameter, it is passed as the value for the `Authorization` header in the upstream HTTP calls to the Epoch server verbatim.\n* If neither, no auth is set\n\n> NOTE: Use the `insecure` option to skip certificate checks on the server endpoint (comes in handy for internal domains)\n\nTo use a custom config file, invoke epoch in the following form:\n\n```\n$ epoch -f custom.conf ...\n```\n\nThis will connect to the cluster if an endpoint is mentioned in the `DEFAULT` section.\n\n```\n$ epoch -f custom.conf -c stage ...\n```\n\nThis will connect to the cluster whose config is mentioned in the `[stage]` config section.\n\n```\n$ epoch -c stage ...\n```\n\nThis will connect to the cluster whose config is mentioned in the `[stage]` config section in `$HOME/.epoch` config file.\n\n\n## Command line options\nPass 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:\n\n```\n$ epoch -e http://localhost:10000 -u guest -p guest ...\n```\n\n## CLI format\nThe following cli format is followed:\n\n```\nusage: epoch [-h] [--file FILE] [--cluster CLUSTER] [--endpoint ENDPOINT] [--auth-header AUTH_HEADER] [--insecure INSECURE] [--username USERNAME] [--password PASSWORD] [--debug]\n {cluster,runs,topology} ...\n```\n### Basic Arguments\n```\n -h, --help show this help message and exit\n --file FILE, -f FILE Configuration file for epoch client\n --cluster CLUSTER, -c CLUSTER\n Cluster name as specified in config file\n --endpoint ENDPOINT, -e ENDPOINT\n Epoch endpoint. (For example: https://epoch.test.com)\n --auth-header AUTH_HEADER, -t AUTH_HEADER\n Authorization header value for the provided epoch endpoint\n --insecure INSECURE, -i INSECURE\n Do not verify SSL cert for server\n --username USERNAME, -u USERNAME\n Epoch cluster username\n --password PASSWORD, -p PASSWORD\n Epoch cluster password\n --debug, -d Print details of errors\n\n```\n\n## Commands\nCommands in epoch are meant to address specific functionality. They can be summarized as follows:\n```\n cluster Epoch cluster related commands\n runs Epoch runs related commands\n topology Epoch topology related commands\n```\n---\n Topology\n---\nEpoch topology executor related commands\n\n```\nepoch topology [-h] {list,get,create,update,delete,pause,unpause,run} ...\n```\n\n#### Sub-commands\n\n##### list\n\nList all executors\n\n```\nepoch topology list [-h]\n```\n\n##### get\n\nShow details about topology-id\n\n```\nepoch topology get [-h] topology-id\n```\n\n###### Positional Arguments\n\n`topology-id` - Topology-id to be shown\n\n##### run\n\nRun the given topology-id\n\n```\nepoch topology run [-h] topology-id\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id to be run\n\n##### create\n\nCreate a task on cluster\n```\nepoch topology create [-h] spec-file\n```\n###### Positional Arguments\n\n`spec-file` - JSON spec file for the topology\n\n##### update\n\nUpdate topology running on this cluster\n\n```\nepoch topology update [-h] spec-file\n```\n\n###### Positional Arguments\n\n`spec-file` - JSON spec file for the topology\n\n##### pause\n\nPause the given topology-id\n\n```\nepoch topology pause [-h] topology-id\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id to be paused\n\n##### unpause\n\nUnpause the given topology-id\n\n```\nepoch topology unpause [-h] topology-id\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id to be unpaused\n\n##### delete\n\nDelete the given topology-id\n\n```\nepoch topology delete [-h] topology-id\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id to be deleted\n\n---\n\nCluster\n---\nEpoch cluster related commands\n\n```\nepoch cluster [-h] {leader} ...\n```\n\n#### Sub-commands\n\n\n##### leader\n\nShow leader for cluster\n```\nepoch cluster leader [-h]\n```\n\n---\n\nRuns\n---\nEpoch application related commands\n\n```\nepoch runs [-h] {list,get,kill,log} ...\n```\n#### Sub-commands\n\n##### list\n\nList all runs\n\n```\nepoch runs list [-h]\n```\n\n##### get\n\nget the details for the given Topology's runId\n```\nepoch runs get [-h] topology-id run-id\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id\n`run-id` - Run-id to be fetched\n\n##### kill\n\nKills the given taskid.\n```\nepoch runs kill [-h] topology-id run-id task-name\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id \n`run-id` - Run-id \n`task-name` - Task-name to be killed\n\n##### log\n\ngets the log the given taskid.\n```\nepoch runs log [-h] topology-id run-id task-name\n```\n###### Positional Arguments\n\n`topology-id` - Topology-id \n`run-id` - Run-id \n`task-name` - Task-name to be fetched\n\n\n\u00a92024, Shubhransh Jagota.",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Command line interface for Epoch task scheduler",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/PhonePe/epoch-cli",
"Repository": "https://github.com/PhonePe/epoch-cli"
},
"split_keywords": [
"container",
" docker",
" podman",
" distributed-systems",
" container-orchestrator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "746a7a6843ab29f62d4854f782ee4d45bf9731c5f31535c332ff00e14cd27699",
"md5": "1866857cdaf3161b6952d90e760c4a91",
"sha256": "ae847a1af203b2761714495b86a7df1e1d94340e3a6d6d13b8250227854eb6aa"
},
"downloads": -1,
"filename": "epoch_cli-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1866857cdaf3161b6952d90e760c4a91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 11126,
"upload_time": "2024-05-22T14:17:07",
"upload_time_iso_8601": "2024-05-22T14:17:07.731555Z",
"url": "https://files.pythonhosted.org/packages/74/6a/7a6843ab29f62d4854f782ee4d45bf9731c5f31535c332ff00e14cd27699/epoch_cli-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a53245a52639f555904a9ce9c8171a03493ba674488f5eae781eb188dd3af5b",
"md5": "a2b7572e9710f57cbf094a2022345f99",
"sha256": "a1233a3dab69159702e65424d45fc0a6ce973ee6da61c69958c7bd58f1fdb4eb"
},
"downloads": -1,
"filename": "epoch_cli-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a2b7572e9710f57cbf094a2022345f99",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10516,
"upload_time": "2024-05-22T14:17:09",
"upload_time_iso_8601": "2024-05-22T14:17:09.091643Z",
"url": "https://files.pythonhosted.org/packages/1a/53/245a52639f555904a9ce9c8171a03493ba674488f5eae781eb188dd3af5b/epoch_cli-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-22 14:17:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PhonePe",
"github_project": "epoch-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "epoch-cli"
}
JSON
