diff --git a/docs/source/cli/getting-started.md b/docs/source/cli/getting-started.md index e869cc6a4..77783d726 100644 --- a/docs/source/cli/getting-started.md +++ b/docs/source/cli/getting-started.md @@ -1,26 +1,21 @@ # Getting Started -Jumpstarter provides the following command line tools: +To simplify the management and operation of Jumpstarter, we provide several command-line tools for different use cases. These CLI tools can also be installed together through the `jmpstarter-cli` package and accessed using the `jmp` command for simplicity. -An **admin CLI** tool called `jmpctl`, which is useful for the administration of exporters and -clients in the distributed service. Installation instructions can be found [here](../installation/service-cli.md). +Each tool can also be installed separately for users who want to reduce the dependencies on their developer machine or an embedded exporter with limited available resources. -A **client CLI** called `jmp`, you can use it to interact with your connected -hardware, request leases, write tests, and develop custom drivers for your hardware. +## Admin CLI `jmp-admin` -A **exporter CLI** called `jmp-exporter`, you can use it to manage local exporter -configurations, and run transient or persistent exporter instances. +The `jmp-admin` or `jmp admin` CLI allows administration of exporters and clients +in a Kubernetes cluster. To use this CLI, you must have a valid `kubeconfig` and +access to the cluter/namespace where the Jumpstarter controller resides. -The `jmp` and `jmp-exporter` CLI tools are available as part of the `jumpstarter` Python package. -You can learn how to install this package [here](../installation/python-package.md), -but it is also available as a container image -```{code-block} -:substitutions: -quay.io/jumpstarter-dev/jumpstarter:{{version}} -``` +## Client CLI `jmp-client` -To check if you have the client CLI installed, run: +The `jmp-client` or `jmp client` CLI allows interaction with Jumpstarter clients +and the management of client configs. -```bash -$ jmp version -``` +## Exporter CLI `jmp-exporter` + +The `jmp-exporter` or `jmp exporter` CLI allows you to run Jumpstarter exporters +and management of exporter configs. diff --git a/docs/source/getting-started/index.md b/docs/source/getting-started/index.md index ca828c6a3..4866df629 100644 --- a/docs/source/getting-started/index.md +++ b/docs/source/getting-started/index.md @@ -4,7 +4,6 @@ This section provides getting started guide to help you set up Jumpstarter to test your software on real hardware. ```{toctree} -setup-local-client.md -setup-exporter.md -setup-controller.md +setup-local-exporter.md +setup-exporter-client.md ``` diff --git a/docs/source/getting-started/setup-controller.md b/docs/source/getting-started/setup-controller.md deleted file mode 100644 index 63a93cc5b..000000000 --- a/docs/source/getting-started/setup-controller.md +++ /dev/null @@ -1 +0,0 @@ -# Setup the Controller Service \ No newline at end of file diff --git a/docs/source/getting-started/setup-exporter-client.md b/docs/source/getting-started/setup-exporter-client.md new file mode 100644 index 000000000..09434d86c --- /dev/null +++ b/docs/source/getting-started/setup-exporter-client.md @@ -0,0 +1,172 @@ +# Setup a Remote Exporter/Client + +This guide walks you through the process of creating an exporter using the +controller service, configuring drivers, and running the exporter. + +## Prerequisites + +Make sure the following packages are installed in your Python environment: +- `jumpstarter-cli` - The core Jumpstarter CLI. +- `jumpstarter-driver-opendal` - The OpenDAL storage driver. +- `jumpstarter-driver-power` - The base power driver. + +You should also have the [Jumpstarter Service](../introduction/service.md) +running in a Kubernetes cluster you have admin access to. +For instructions on how to install Jumpstarter in a cluster, +refer to the [installation guide](../installation/service/index.md). + +```{tip} +Make sure you have the correct cluster in your `kubeconfig` file and the right +context selected. +``` + +## Create an Exporter + +First, we must create an exporter using the controller service API. +The `jmp admin` CLI provides methods to interact with the controller directly. + +To create an exporter and save the config locally, run the following command: + +```bash +# Creates an exporter called "testing" and saves the config +$ jmp admin create exporter testing --save + +# Usage for jmp admin create exporter +$ jmp admin create exporter + --help +Usage: jmp admin create exporter [OPTIONS] [NAME] + + Create an exporter object in the Kubernetes cluster + +Options: + -s, --save Save the config file for the created exporter. + -o, --out FILE Specify an output file for the exporter config. + -n, --namespace TEXT Kubernetes namespace to use + --kubeconfig FILENAME path to the kubeconfig file + --context TEXT Kubernetes context to use + --help Show this message and exit. +``` + +### Edit the Exporter Config + +Once the exporter has been created, a new config file will be saved to +`/etc/jumpstarter/exporters/testing.yaml`. + +To edit the config file with your default text editor, run the following command: + +```bash +# Opens the config for "testing" in your default editor +$ jmp exporter edit-config testing +``` + +Add the `storage` and `power` drivers under the `export` field in the config file. +The finished config should look like this: + +```yaml +# /etc/jumpstarter/exporters/testing.yaml +apiVersion: jumpstarter.dev/v1alpha1 +kind: ExporterConfig +# These values are automatically filled by the controller +endpoint: "..." +token: "..." +# Mock drivers for demo purpose +export: + storage: + type: jumpstarter_driver_opendal.driver.MockStorageMux + power: + type: jumpstarter_driver_power.driver.MockPower +``` + +## Run an Exporter + +To run the exporter locally, we can use the `jmp exporter` CLI tool. + +Run the following command to start the exporter locally using the config file: + +```bash +# Runs the exporter "testing" locally +$ jmp exporter run testing +``` + +The exporter will stay running until the process is exited via `^C` or the shell +is closed. + +## Create a Client + +To connect to the new exporter, a client must be created. We can also use the +`jmp admin` CLI tool to create a client using the controller. + +```bash +# This will create a client called "hello", allow unsafe drivers, and save the config +$ jmp admin create client hello --save --unsafe + +# Usage for jmp admin create client +jmp admin create client --help +Usage: jmp admin create client [OPTIONS] [NAME] + + Create a client object in the Kubernetes cluster + +Options: + -s, --save Save the config file for the created client. + -a, --allow TEXT A comma-separated list of driver client packages to + load. + --unsafe Should all driver client packages be allowed to load + (UNSAFE!). + -o, --out FILE Specify an output file for the client config. + -n, --namespace TEXT Kubernetes namespace to use + --kubeconfig FILENAME path to the kubeconfig file + --context TEXT Kubernetes context to use + --help Show this message and exit. +``` + +## Connect to the Exporter + +To interact with the exporter we created above, we can use the +"client shell" functionality within the `jmp` CLI. When a shell is spawned, +the client attempts to acquire a lease on an exporter. Once the lease is acquired, +the client can be interacted with through the magic `j` command or via the +Python API. + +```bash +# Spawn a shell using the "hello" client +$ jmp client shell hello + +# Usage for jmp client shell +$ jmp client shell --help +Usage: jmp client shell [OPTIONS] [NAME] + + Spawns a shell connecting to a leased remote exporter + +Options: + -l, --label ... + -n, --lease TEXT + --help Show this message and exit. +``` + +Once a lease is acquired, we can interact with the drivers hosted by the exporter +within the shell instance. + +```bash +# Spawn a shell using the "hello" client +$ jmp client shell hello + +# Running inside client shell +$ j +Usage: j [OPTIONS] COMMAND [ARGS]... + + Generic composite device + +Options: + --help Show this message and exit. + +Commands: + power Generic power + storage Generic storage mux + +# Simulate turning on the power +$ j power on +ok + +# Exit the shell +$ exit +``` diff --git a/docs/source/getting-started/setup-exporter.md b/docs/source/getting-started/setup-exporter.md deleted file mode 100644 index 96a89b61d..000000000 --- a/docs/source/getting-started/setup-exporter.md +++ /dev/null @@ -1 +0,0 @@ -# Setup an Exporter \ No newline at end of file diff --git a/docs/source/getting-started/setup-local-client.md b/docs/source/getting-started/setup-local-client.md deleted file mode 100644 index 11ef4c303..000000000 --- a/docs/source/getting-started/setup-local-client.md +++ /dev/null @@ -1,65 +0,0 @@ -# Setup a Local Exporter - -This guide walks you through the process of using Jumpstarter with a local exporter (the client and the exporter running on the same host) - -## Create Exporter Configuration -Create a text file with the following content -```yaml -# /etc/jumpstarter/exporters/demo.yaml -apiVersion: jumpstarter.dev/v1alpha1 -kind: ExporterConfig -metadata: - namespace: default - name: demo -# endpoint and token are intentionally left empty -endpoint: "" -token: "" -# mock drivers for demo purpose -export: - storage: - type: jumpstarter.drivers.storage.driver.MockStorageMux - power: - type: jumpstarter.drivers.power.driver.MockPower -``` -Once the exporter configuration is ready it should be placed at `/etc/jumpstarter/exporters/demo.yaml`. - -## Enter Exporter Shell -Now we can run the following command to enter the "Exporter Shell", inside which we can interact with the local exporter with Jumpstarter client. -```shell -$ jmp-exporter shell demo -``` - -## Use j Command -The `j` command is available in the exporter shell for controlling the exporter with shell commands. -```shell -# running inside exporter shell -$ j -Usage: j [OPTIONS] COMMAND [ARGS]... - - Generic composite device - -Options: - --help Show this message and exit. - -Commands: - power Generic power - storage Generic storage mux -$ j power on -ok -``` - -## Use Python API -Or we can use the Jumpstarter Python API to programmatically control the exporter. - -```shell -# running inside exporter shell -$ python - <