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

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:

# 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:

# 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:

# /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:

# 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.

# 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.

# 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.

# 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