Set up on Chameleon Edge#

This guide covers how to configure Chameleon Edge (kind: chameleon-edge) as the testbed in a Kiso experiment.

Chameleon Edge uses a different OpenRC file from Chameleon Cloud. Both use the same Chameleon project allocation, but CHI@Edge requires its own site-specific OpenRC credentials file. A CHI@UC or CHI@TACC credential file will not work here. If you are looking for Chameleon bare-metal nodes, see Set up on Chameleon instead.

Chameleon Edge provisions containers on edge devices through CHI@Edge. For background on when to use it, see Components — Chameleon Edge.

Tip

Chameleon Edge containers are not accessible over SSH. Kiso communicates with them through the Chameleon Edge Python API instead. To inspect a running container, open the CHI@Edge Containers dashboard: select the container to view its status, access the interactive console, and retrieve stdout/stderr logs.

Prerequisites#

A Chameleon account at chameleoncloud.org
An active Chameleon project allocation — create a new project or join an existing one; the allocation must include CHI@Edge access
An OpenRC credentials file downloaded from the CHI@Edge site — switch to the CHI@Edge site in the dashboard, then create an application credential under Identity → Application Credentials. A CHI@UC or CHI@TACC credential file will not work here.
Kiso installed: pip install kiso[chameleon]

Config fields#

sites:
  - kind: chameleon-edge
    rc_file: ~/openrc-chameleon.sh   # Required — path to OpenRC credentials file
    lease_name: my-edge-lease        # Optional — lease name (default: EnOSlib)
    walltime: "02:00:00"             # Optional — lease duration in HH:MM format (default: 02:00)
    resources:
      machines:
        # Option A: DeviceCluster — select devices by board/model name
        - labels: [edge]             # Required
          machine_name: raspberrypi4 # Required — board type
          count: 2                   # Required — number of devices
          device_model: rpi4b-8gb    # Optional — specific device model
          container:                 # Optional — container to run on each device
            name: my-container       # Required
            image: ubuntu:22.04      # Required
            exposed_ports:           # Optional
              - "8080/tcp"
            start: true              # Optional
            start_timeout: 60        # Optional
            device_profiles:         # Optional
              - pi4

        # Option B: Device — select a specific device by name
        - labels: [specific-device]  # Required
          device_name: iot-jetson04  # Required — specific device hostname
          device_model: jetson-nano  # Optional
          container:
            name: jetson-container
            image: nvcr.io/nvidia/l4t-base:r32.6.1

Machine types#

DeviceCluster#

Selects a set of devices by board/machine type. Use this when you need multiple devices of the same kind.

Field	Required	Description
`labels`	Yes	Labels to assign
`machine_name`	Yes	Board/machine type name (e.g. `raspberrypi4`)
`count`	Yes	Number of devices to provision
`device_model`	No	Specific device model filter (e.g. `rpi4b-8gb`)
`container`	No	Container to deploy on the devices

Device#

Selects a specific named device. Use this when you need a particular piece of hardware.

Field	Required	Description
`labels`	Yes	Labels to assign
`device_name`	Yes	Specific device hostname (e.g. `iot-jetson04`)
`device_model`	No	Device model
`container`	No	Container to deploy

Container fields#

Field	Required	Description
`name`	Yes	Container name
`image`	Yes	Container image
`exposed_ports`	No	Ports to expose (e.g. `["8080/tcp"]`)
`start`	No	Whether to start the container immediately
`start_timeout`	No	Seconds to wait for container to start
`device_profiles`	No	Device profiles to apply (e.g. GPU access via `["pi4"]`)

Minimal working example#

name: chameleon-edge-test

sites:
  - kind: chameleon-edge
    rc_file: ~/openrc-chameleon.sh
    lease_name: kiso-edge-test
    resources:
      machines:
        - labels: [edge]
          machine_name: raspberrypi4
          count: 1
          container:
            name: test-container
            image: ubuntu:22.04
            start: true

experiments:
  - kind: shell
    name: check
    scripts:
      - labels: [edge]
        script: hostname && uname -r

Source the OpenRC file before running:

kiso up experiment.yml
kiso run experiment.yml
kiso down experiment.yml

Verifying the setup#

After kiso up, check the CHI@Edge dashboard:

Active lease under Reservations → Leases
Running containers under the CHI@Edge Container → Containers view

Common failure modes#

No edge devices available for lease

Edge devices at CHI@Edge are a shared resource. If none are available for the requested machine_name, try a different board type or a shorter walltime.

Missing or invalid RC file

If rc_file points to a file that does not exist or contains invalid credentials, kiso up will fail with an authentication error.

Warning

In your rc_file, do not use ' to quote the values. For e.g., export OS_AUTH_TYPE='v3applicationcredential' is invalid.

Lease expired during experiment

If the experiment runs longer than walltime, Chameleon terminates the lease. Set walltime generously. Leases can be extended from the Chameleon dashboard while active.

Command appears to hang or reports incorrect completion

The Chameleon Edge API has fixed timeouts that cannot be overridden. If a command takes too long, the API call terminates — but the command continues running on the container. Kiso handles this by polling the container for completion using an exit code file, so the command will eventually be detected as complete. If a script appears to hang, it is likely still running on the container; wait rather than interrupting.

File transfer times out on large directories

Chameleon Edge’s API compresses a directory before uploading or downloading it. For large directories this can exceed the API timeout. Kiso handles this automatically by falling back to transferring files individually when a bulk transfer times out. Expect slower transfer times for large experiment inputs or outputs on Chameleon Edge compared to other testbeds.

Set up on Chameleon Edge

Contents