# Configuration

```{warning}
This project is still evolving, so these docs may be incomplete or out-of-date.
```

Jumpstarter can be configured as either a client, an exporter, or both depending
on your use case and deployment strategy.

By default, a local client and exporter session are automatically initialized when
running test scripts through `jmp start` or the `jmp shell` commands. This allows
for easy testing of new drivers, client libraries, or verifying that tests work
on your local bench.

When interacting with remote exporters in a CLI or CI environment, multiple clients
can be configured on the same system and used to interact with different devices
and different exporter instances.

Similarly, multiple exporters can be configured on a single host system to interact
with many different devices. However, each exporter instance is independent, making
it possible to stop, restart, and add new exporters while others are executing tests.

## User Configuration

Jumpstarter stores user-specific configs in the `~/.config/jumpstarter` directory
within the user's home folder.

The user config file defines the current client config and any user-specific
configurations for `jmp` CLI tool.

```yaml
# ~/.config/jumpstarter/config.yaml

apiVersion: jumpstarter.dev/v1alpha1
kind: UserConfig
config:
  current-client: ./clients/myclient.yaml
```

## System Configuration

Jumpstarter stores system configs in the `/etc/jumpstarter` directory.
This configuration directory is primarily used by the exporters as they often
run as daemon services on the host system.

The system config file defines the current exporter config and any system-level
configurations for the exporters.

```yaml
# /etc/jumpstarter/config.yaml

apiVersion: jumpstarter.dev/v1alpha1
kind: SystemConfig
config:
  current-exporter: ./exporters/myexporter/exporter.yaml
```

## Clients

Client configurations are stored in the Jumpstarter user configuration directory
`~/.config/jumpstarter/clients`. Each client config is a YAML file that contains
the client name, access token, and any configuration parameters.

### Client Config

```yaml
# ~/.config/jumpstarter/clients/myclient.yaml

apiVersion: jumpstarter.dev/v1alpha1
kind: Client
client:
  endpoint: "grpcs://jumpstarter.my-lab.com:1443"
  token: "dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz"
  drivers:
    # Wildcards are supported
    allow: ["jumpstarter.drivers.*", "vendorpackage.*"]
```

- `endpoint` - The gRPC endpoint of the Jumpstarter controller server.
- `token` - A client auth token generated by the controller.
- `drivers` - Driver client library configuration.
  - `allow` - A list of allowed driver namespaces to automatically load.
  - `unsafe: true` - Should all drivers be allowed to load?

### Multiple Clients

Multiple client configs can be added to the `~/.config/jumpstarter/clients` directory
manually or by using the Jumpstarter CLI.

Similar to kubectl, Jumpstarter allows you to switch between different client
configurations using the CLI tool. A `default` client is automatically configured
when installing the Jumpstarter Helm chart with `jmp install`.

### Client CLI Commands

To create a new client, the `jmp client create <name>` command can be used. When
`kubectl` is installed and the current context contains a Jumpstarter controller
instance, client tokens will be automatically generated using the controller endpoint.

```bash
$ jmp client create myclient
Using kubectl context 'my-cluster'
Generating client auth token
Created client config '/home/jdoe/.config/jumpstarter/clients/myclient.yaml'
```

To switch between different client configs, use the `jmp client use <name>` command:

```bash
$ jmp client use another
Using client config '/home/jdoe/.config/jumpstarter/clients/another.yaml'
```

All client configurations can be listed with `jmp client list`:

```bash
$ jmp client list
CURRENT   NAME       ENDPOINT                               PATH
*         default    grpcs://jumpstarter1.my-lab.com:1443   /home/jdoe/.config/jumpstarter/clients/default.yaml
          myclient   grpcs://jumpstarter2.my-lab.com:1443   /home/jdoe/.config/jumpstarter/clients/myclient.yaml
          another    grpcs://jumpstarter3.my-lab.com:1443   /home/jdoe/.config/jumpstarter/clients/another.yaml
```

Clients can also be removed using `jmp client delete <name>`:

```bash
$ jmp client delete myclient
Deleted client config '/home/jdoe/.config/jumpstarter/clients/myclient.yaml'
```

### Client Environment Variables

The client configuration may also be provided by environment variables which may
be useful in CI or when writing a script that uses Jumpstarter.

- `JMP_CLIENT_CONFIG` - A path to a client configuration YAML file to use.
- `JMP_CLIENT` - The name of a registered client config to use.
- `JMP_ENDPOINT` - The gRPC endpoint of the Jumpstarter controller server
(overrides the config value).
- `JMP_TOKEN` - A client auth token generated by the controller
(overrides the config value).
- `JMP_DRIVERS_ALLOW` - A comma-separated list of allowed driver namespaces
to automatically load. Can be set to `UNSAFE` to allow unsafe loading of drivers.

## Exporters

Exporter configurations are by default stored globally in the Jumpstarter config
directory `/etc/jumpstarter/exporters`. Each exporter config is a YAML file and
optionally a Python script to initialize the exporter and its associated drivers.

### Exporter Config

Exporters can be configured using a pure-YAML format, which allows for the configuration
of built-in drivers and any additional driver packages registered by the user.

```yaml
# /etc/jumpstarter/exporters/myexporter.yaml

apiVersion: jumpstarter.dev/v1alpha1
kind: Exporter
endpoint: "grpcs://jumpstarter.my-lab.com:1443"
token: "dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz"
export:
  power:
    type: "jumpstarter.drivers.power.PduPower"
    config:
      host: "192.168.1.111"
      port: 1234
      username: "admin"
      password: "secret"
  serial:
    type: "jumpstarter.drivers.serial.Pyserial"
    config:
      port: "/dev/ttyUSB0"
      baudrate: 115200
  custom:
    type: "vendorpackage.CustomDriver"
    config:
      hello: "world"
```

- `endpoint` - The gRPC endpoint of the Jumpstarter controller server.
- `token` - An exporter auth token generated by the controller.
- `export` - Exporter driver configuration.

### Exporter CLI Commands

To create a new exporter, the `jmp exporter create <name>` command can be used.
When `kubectl` is installed and the current context contains a Jumpstarter controller
instance, exporter tokens will be automatically generated using the controller endpoint.
By default, a basic YAML config will be generated.

```bash
$ jmp exporter create myexporter
Using kubectl context 'my-cluster'
Generating exporter auth token
Created exporter config '/etc/jumpstarter/exporters/myexporter.yaml'
```

To switch between different exporter configs, use the `jmp exporter use <name>`
command:

```bash
$ jmp exporter use another
Using exporter config '/etc/jumpstarter/exporters/another/exporter.yaml'
```

To use a specific config when starting the exporter:

```bash
$ jmp exporter start another
Using exporter config '/etc/jumpstarter/exporters/another/exporter.yaml'
```

The path to a config can also be provided:

```bash
jmp exporter start --config /etc/jumpstarter/exporters/another/exporter.yaml
```

All exporter configurations can be listed with `jmp exporter list`:

```bash
$ jmp exporter list
CURRENT   NAME         ENDPOINT                               PATH                                           SCRIPT
*         default      grpcs://jumpstarter1.my-lab.com:1443   /etc/jumpstarter/exporters/default.yaml            N/A
          myexporter   grpcs://jumpstarter2.my-lab.com:1443   /etc/jumpstarter/exporters/myexporter.yaml         N/A
          another      grpcs://jumpstarter3.my-lab.com:1443   /etc/jumpstarter/exporters/another/exporter.yaml   /etc/jumpstarter/exporters/another/setup.py
```

Clients can also be removed using `jmp client delete <name>`:

```bash
$ jmp client delete myexporter
Deleted exporter config '/etc/jumpstarter/exporters/myexporter.yaml'
```

### Exporter Environment Variables

The exporter configuration may also be provided by environment variables which
may be useful in CI or when writing a script that uses Jumpstarter.

- `JMP_EXPORTER_CONFIG` - A path to a exporter configuration YAML file
to use.
- `JMP_EXPORTER` - The name of a registered exporter config to use.
- `JMP_ENDPOINT` - The gRPC endpoint of the Jumpstarter controller server
(overrides the config value).
- `JMP_TOKEN` - An exporter auth token generated by the controller
(overrides the config value).
- `JMP_DRIVERS` - A comma-separated list of allowed driver namespaces
to automatically load (overrides the config value).