Merge pull request #240 from jumpstarter-dev/update-docs

Update Documentation to Reflect Refactoring

Author: NickCao

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.

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
 ```

docs/source/getting-started/setup-controller.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 <TEXT TEXT>...
+  -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
+```