Eden

Eden is the simplest way to setup & test EVE and Adam.

Eden is a management harness that provides two layers of management.

infrastructure: deploy and/or delete nodes running EVE, controller Adam and software-defined networks between EVE and the controller
tasks: execute on EVE, via the controller, one or more tasks

Eden is particularly suited to running tests and test suites. These tests must meet eden's test API. This repository also includes a framework for simplify running the tests on the managed EVE via Adam, and reporting on results.

Eden is inspired by Kubernetes workflows and CLI

Note that EVE by itself without a controller is useless in practice. It retrieves its entire configuration from the controller, and has no console commands that can be used standalone, like general-purpose Linux distributions. You use the controller to tell EVE which workloads you want to run. EVE, in turn, runs those workloads in containers or VMs.

EVE supports the following workload formats:

OCI image from any OCI compliant registry
OS image in qcow2 format
OS image in raw format

Eden is controlled by a single (secretly-named) command eden. It has multiple sub-commands and options. Run eden help to see sub-commands.

Running Eden

You need at least two devices, either or both of which can be virtual:

Edge: this is the device on which you will run EVE, and launch tasks such as tests.
Manager: this is where you will run Eden and, optionally, all of the management components.

A typical eden workflow is:

install the prerequisites
create a named context to store all of your configuration - eden config add <name>
(optional) set options for the context - eden config set <name> [options...]
run setup - eden setup, which extracts an eve-os qcow2 disk image from the docker image named in the context
start Eden's components - eden start
- if running EVE as qemu, entirely under eden control, it will start automatically
- if running EVE as a separate EVE device:
  1. create or download the EVE image you want
  2. flash the image to the device's storage
  3. start the device
onboard EVE - eden eve onboard, explicitly allowing it to connect to the controller
use the Eden CLI to perform tasks, such as install apps or run tests
terminate Eden's components and, optionally, EVE - eden stop
clean up - eden clean

To customize the device on which EVE is running, or the image launched, see docs/eve-images.md.

Prerequisites

On the manager, you need:

the eden binary
docker, to run eden's components, including the ability to execute commands. For Linux:

sudo usermod -aG docker $USER
newgrp docker

test binaries - eden ships with pre-compiled ones
a text editor to configure the system and create test scenarios and scripts using eden

Eden itself -- the main executable file eden, components, and tests -- ships as stand-alone applications or docker images. You do not need to install and configure the development environment on your computer.

The manager hosts:

Eden - control layer CLI
Adam - the controller, running as a daemon process
SDN - software-defined networking between EVE (in Qemu) and the controller (to emulate various connectivity scenarios)
Redis - the log database, running as a daemon process
Eserver - the image/file database to expose http and ftp content for downloading to the edge device
Registry - an OCI-compliant registry to expose images for downloading to the edge device

Eden currently does not support interfacing with a commercial controller, although it is planned for the future.

As the manager hosts the controller, which the edge device must connect to, the edge device must be able to connect via network to port 3333.

For the edge device, you need an EVE OS image to install.

Important Note: EVE's strong security model allows it to only connect to one controller, during onboarding. Once onboarded EVE will not switch its allegiance to any other controller. You simply cannot change the registered certificates or controller IP for an onboarded device. This requires that you be specify the right IP of the target controller when creating the EVE image.

There are additional requirements for certain use cases:

Local Virtual Device

If you intend to run EVE in a virtual local device, you also will need:

qemu version 4.x or higher
Linux: KVM, including the ability to execute commands. For Linux:

  sudo usermod -aG kvm $USER
  newgrp kvm

macOS: machyve or Parallels
telnet
squashfs tools, available, depending on your OS, as squashfs or squashfs-tools

EVE uses virtualization; to run in VM-based environments, see the cloud document.

Raspberry Pi

If you want to use Eden with Raspberry Pi on Linux, you also need to install binfmt-support and qemu-user-static.

Quickstart Guides

All of the quickstart guides get you running quickly, and assume you already have eden installed. They start the official nginx image as a container, serving the content of ./data/helloeve/ on port 8028. You will be able to access it via http://<EVE IP>:8028. Note that if you are running EVE as virtual device in Qemu with SDN enabled, you will not be able to access EVE IP and your apps directly, instead eden sdn fwd command must be used (run with no arguments to print help). Feel free to change the content in ./data/helloeve/ and redeploy the pod.

At any time, to get the status of what is running and where, including <EVE IP>, run:

eden status

Quickstart Local (PC in qemu)

eden config add default
eden setup
eden start
eden eve onboard
eden pod deploy docker://nginx -p 8028:80 --mount=src=./data/helloeve,dst=/usr/share/nginx/html
eden status

# if SDN is disabled (sdn.disable=true)
curl http://<EVE IP>:8028
# if SDN is enabled (sdn.disable=false)
eden sdn fwd eth0 8028 curl http://FWD_IP:FWD_PORT

When done be sure to clean up:

make clean
# OR
eden stop && eden clean --current-context=false

Quickstart Hardware (Build an image for real x86)

eden config add default --devmodel general
eden config set default --key adam.eve-ip --value <IP of Manager>
eden setup

Burn the image that was displayed to a the proper storage for you device, e.g. SD card or USB drive. There are many utilities and tools to do so, from the venerable dd to balena etcher.

Boot your device from the storage medium.

Then on eden:

eden start
eden eve onboard
eden pod deploy docker://nginx -p 8028:80 --mount=src=./data/helloeve,dst=/usr/share/nginx/html
eden status
curl http://<EVE IP>:8028

When done be sure to clean up:

make clean
# OR
eden stop && eden clean --current-context=false

Target Platforms

EVE can run on most platforms. However, there are some considerations when running on certain platforms. See docs/eve-platforms.md.

Eden shell settings

For more ease of use of Eden, you can use the automatically generated setup files for your shell:

for BASH/ZSH -- source ~/.eden/activate.sh
for TCSH -- source ~/.eden/activate.csh

These settings add the Eden's binaries directory to the PATH environment variable and add the "EDEN_<current_config>_" label to the command prompt.

In setup files defined some functions (BASH/ZSH) and aliases (TCSH) for work with configs:

eden+config <config_name> -- add new config for Eden
eden-config <config_name> -- remove config from Eden and switch to 'default'
eden_config <config_name> -- switch Eden to config and change prompt

To deactivate this settings call eden_deactivate function.

You may configure Bash/Zsh/Fish shell completions for Eden by command eden utils completion.

Eden Configurations

Eden's config is controlled via a yaml file, overriddable using command-line options. In most cases, the defaults will work just fine for you. If you want to change the configuration of any of the services, or use multiple stored setups, see docs/config.md.

Remote access to eve

To get a shell on the EVE device, once the device is fully registered to its controller:

eden eve ssh

You can run a single command remotely by passing it as argument:

eden eve ssh "ls -la"

If you need access to the actual device console, run:

eden eve console

Applications on EVE

Applications are controlled on an EVE device with the eden pod commands. For details, see applications.

Tests

Running tests is simple:

eden test <test folder>

For example -- to run the reboot test:

eden test tests/reboot/

Or to run the workflow tests:

EDEN_TEST=small eden test tests/workflow -v debug

Because most workflow tests already contain a setup phase you only need minimal preparation before running them - here is an example of running smoke test workflow (as done in .github/actions/setup-environment/action.yml and .github/actions/run-eden-test/action.yml):

(optional) make clean
make build
make build-tests
eden config add default
eden setup
eden test tests/workflow/ -s smoke.tests.txt

Here it is important not to do the setup with make run, because it doesn't include a call to eden+ports.sh that sets up port forwarding for the tests.

For tests that accept parameters, simply pass them after the test path. For example, to run Log/Metrics/Info test in debug mode with timeout of 600 seconds and requiring 3 messages of each type:

eden test tests/lim/ -v debug -a '-timewait 600 -number 3'

As of this writing, you must build the tests before running them:

make build-tests

For more information about running tests, as well as creating your own, start here.

Help

You can get more information about make actions by running make help.

More information can be found at the wiki or in the #eve-help channel in slack.

lf-edge/eden