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.
--out FILE Specify an output file for the exporter
config.
-n, --namespace TEXT Kubernetes namespace to use
-l, --label <TEXT TEXT>... Labels
--kubeconfig FILENAME path to the kubeconfig file
--context TEXT Kubernetes context to use
--oidc-username TEXT OIDC username
--nointeractive Disable interactive prompts (for use in
scripts).
-o, --output [json|yaml|name] Output mode. Use "-o name" for shorter output
(resource/name).
--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 config exporter edit 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 CLI tool.
Run the following command to start the exporter locally using the config file:
# Runs the exporter "testing" locally
$ jmp run --exporter 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!).
--out FILE Specify an output file for the client config.
-n, --namespace TEXT Kubernetes namespace to use
-l, --label <TEXT TEXT>... Labels
--kubeconfig FILENAME path to the kubeconfig file
--context TEXT Kubernetes context to use
--oidc-username TEXT OIDC username
--nointeractive Disable interactive prompts (for use in
scripts).
-o, --output [json|yaml|name] Output mode. Use "-o name" for shorter output
(resource/name).
--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 shell --client hello --selector example.com/board=foo
Usage for jmp shell¶
$ jmp shell --help
Usage: jmp shell [OPTIONS] [COMMAND]...
Spawns a shell (or custom command) connecting to a local or remote exporter
COMMAND is the custom command to run instead of shell.
Example:
.. code-block:: bash
$ jmp shell --exporter foo -- python bar.py
Options:
--exporter-config PATH Path of exporter config
--exporter TEXT Alias of exporter config
--client-config PATH Path to client config
--client TEXT Alias of client config
--lease TEXT
-l, --selector TEXT Selector (label query) to filter on, supports '=',
'==', and '!=' (e.g. -l key1=value1,key2=value2).
Matching objects must satisfy all of the specified
label constraints.
--duration DURATION Accepted duration formats:
PnYnMnDTnHnMnS - ISO 8601 duration format
HH:MM:SS - time in hours, minutes, seconds
D days, HH:MM:SS - time prefixed by X days
D d, HH:MM:SS - time prefixed by X d
See https://docs.rs/speedate/latest/speedate/ for
details [default: (00:30:00)]
--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 shell --client hello --selector example.com/board=foo
# 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