Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

Files

This page describes configuration files used in Jumpstarter, including their format, location, related environment variables, and management commands.

Jumpstarter follows a specific hierarchy when loading configurations. See Loading Order for details on how configurations from different sources are prioritized.

User Configuration

File: config.yaml
Location: /home/<user>/.config/jumpstarter/config.yaml
Description: Defines global user settings including current client selection.

Format:

apiVersion: jumpstarter.dev/v1alpha1
kind: UserConfig
config:
  current-client: default # The currently selected client config to use (by local alias).

CLI Commands: The current client selection can be changed using: jmp config client use <alias>

Client Configuration

File: All valid client configuration files with a .yaml extension.
Location: /home/<user>/.config/jumpstarter/clients/*.yaml
Description: Stores client configurations including endpoints, access tokens, and driver settings.

Format:

apiVersion: jumpstarter.dev/v1alpha1
kind: ClientConfig
metadata:
  name: myclient # The name of the client in the cluster.
  namespace: jumpstarter-lab # The namespace of the client in the cluster.
tls:
  insecure: false # Enable insecure TLS for testing and development
  ca: "" # A CA certificate to use
endpoint: "jumpstarter.my-lab.com:1443" # The Jumpstarter service endpoint
token: "******************" # An authentication token
drivers:
  allow: ["jumpstarter_drivers_*", "vendorpackage.*"] # Driver packages the client can dynamically load
  unsafe: false # Allow any driver package to load dynamically

Environment Variables:

  • JUMPSTARTER_GRPC_INSECURE - Set to 1 to disable TLS verification globally

  • JMP_CLIENT_CONFIG - Path to a client configuration file

  • JMP_CLIENT - Name of a registered client config

  • JMP_NAMESPACE - Namespace in the controller

  • JMP_NAME - Client name

  • JMP_ENDPOINT - gRPC endpoint (overrides config file)

  • JMP_TOKEN - Auth token (overrides config file)

  • JMP_DRIVERS_ALLOW - Comma-separated list of allowed driver namespaces

  • JUMPSTARTER_FORCE_SYSTEM_CERTS - Set to 1 to force system CA certificates

CLI Commands:

$ jmp config client create <alias>  # Create new empty client config
$ jmp config client use <alias>     # Switch to a different client config
$ jmp config client list            # List available client configs
$ jmp config client delete <alias>  # Remove a client config locally

Exporter Configuration

File: All valid exporter configuration files with a .yaml extension
Location: /etc/jumpstarter/exporters/*.yaml
Description: Defines exporter settings including connection details and driver configurations.

Format:

apiVersion: jumpstarter.dev/v1alpha1
kind: ExporterConfig
metadata:
  name: myexporter # The name of the exporter in the cluster.
  namespace: jumpstarter-lab # The namespace of the exporter in the cluster.
tls:
  insecure: false # Enable insecure TLS for testing and development
  ca: "" # A CA certificate to use
endpoint: "jumpstarter.my-lab.com:1443" # The Jumpstarter service endpoint
token: "******************" # An authentication token
export: # Configure drivers to expose to the clients
  power:
    type: "jumpstarter_driver_power.driver.PduPower" # The driver Python class path and type
    config: # Dynamic configuration dict passed to the driver class
      host: "192.168.1.111"
      port: 1234
      username: "admin"
      password: "secret"
  serial:
    type: "jumpstarter_driver_pyserial.driver.PySerial"
    config:
      url: "/dev/ttyUSB0"
      baudrate: 115200

Environment Variables:

  • JUMPSTARTER_GRPC_INSECURE - Set to 1 to disable TLS verification

  • JMP_ENDPOINT - gRPC endpoint (overrides config file)

  • JMP_TOKEN - Auth token (overrides config file)

  • JMP_NAMESPACE - Namespace in the controller

  • JMP_NAME - Exporter name

CLI Commands:

$ jmp config exporter create <alias>  # Create new empty exporter config
$ jmp config exporter list            # List available exporter configs
$ jmp config exporter delete <alias>  # Remove a local exporter config

Running Exporters

Running from the CLI

Exporters can be run manually from the command line for testing:

# Run using the exporter config alias (the config file name)
# The exporter process will exit when the lease is released
$ jmp run --exporter my-exporter

# Run using the path to a specific exporter config file
$ jmp run --exporter-config /etc/jumpstarter/exporters/my-exporter.yaml

Running as a Service

For production deployments, it is recommended to use a service manager such as systemd to keep the exporter process alive and restart it after a lease ends or something goes wrong.

Containerized exporters can be installed as systemd services using podman-systemd.

Create a systemd service file at /etc/containers/systemd/my-exporter.container with the following content:

[Unit]
Description=My exporter

[Container]
ContainerName=my-exporter
Exec=/jumpstarter/bin/jmp run --exporter my-exporter # Command to run inside the container
Image=quay.io/jumpstarter-dev/jumpstarter:latest # The container image to use
Network=host # Use host networking
PodmanArgs=--privileged # Enable privileged mode to allow hardware access
Volume=/run/udev:/run/udev # Support devices within the container
Volume=/dev:/dev # Support devices within the container
Volume=/etc/jumpstarter:/etc/jumpstarter # Mount Jumpstarter configs directory

[Service]
Restart=always # Always restart the container after exit
StartLimitBurst=0

[Install]
WantedBy=multi-user.target default.target

Then enable and start the service:

$ sudo systemctl daemon-reload
$ sudo systemctl enable --now my-exporter