Deploying Eggplant Functional (Fusion Engine) in Containers

Intended Audience: Test developers familiar with using Git source control software workflows, automated pipelines, and containerized software.

tip

Eggplant Functional's script execution engine is also known as the Eggplant Fusion Engine. The Fusion Engine is essentially Eggplant Functional running in command-line mode. When we refer to Eggplant Functional running in a container, we usually refer to it as the "Fusion Engine." However, we refer to it as both on this page.

You can integrate Eggplant Functional (EPF) tests into your continuous integration/continuous delivery (CI/CD) pipelines by deploying EPF in a container. To run in a container, you launch EPF with its runscript command. The runscript command can run EPF without its graphical user interface (GUI) from a command-line interface (CLI), which allows it to run in a container.

This page covers following topics:

• Methods for Running EPF (Fusion Engine) in a Container

• Prerequisites for Running in a Container

• Using Prebuilt Containers

• Building Your Own Container

• Configuring Gitlab CI/CD to Use a Container Image

Methods for Running Eggplant Functional (Fusion Engine) in a Container

You can run Eggplant Functional (Fusion Engine) in a container in one of two ways:

• By passing a specific Eggplant SenseTalk test script to run as an argument with the runscript command. In this scenario, Eggplant Fusion Engine only runs for the duration of the specified script run. Below is an example runscript command for this scenario:

  runscript /tests/Demo.suite/Scripts/check_tutorial_sut.script

  For more information the runscript options available when you run the Eggplant Fusion Engine this way, see The Runscript Command, Running fron the Command Line, and Runscript Command Line Options.

• By running in Drive Mode, where you pass the drivemode yes -driveport <port> arguments with the runscript command to run Eggplant Fusion Engine as a background service. Drive Mode provides a simple XML-RPC interface that other applications, such as the Eggplant DAI Run Agent, can use to send messages to and from Eggplant Fusion Engine. In Drive Mode, Eggplant Fusion Engine runs continuously to receive and send messages until you or a process explicitly stops it. Below is an example runscript command for Drive Mode:

  runscript -driveport 5400 -CommandLineOutput yes

  For more information about the options available when you run Fusion Engine in Drive Mode, see About Eggdrive and Using Eggdrive with Eggplant Functional.

Container Image Options

To run Eggplant Functional (Fusion Engine) in a container (to containerize it), you have the following options:

• You can use the prebuilt images as described in Using the Prebuilt Eggplant Functional Container Images.

• You can build your own as described in Building Your Own Container Image.

Be sure to review the prerequisites below to ensure you have everything you need to run the Eggplant Fusion Engine in a container.

Container Prerequisites

To run Eggplant Functional (Fusion Engine) in a container, you need the following software:

General Requirements

Requirement	Notes
Git source control software	The latest version, if you plan to run your Fusion Engine container in a Gitlab pipeline.
Container software	Such as the pre-configured Eggplant Functional (Fusion Engine) container images, available in the Quay.io reository or Iron Bank repositories, Docker, Rancher, Ranger, or Podman.

Eggplant Functional (Fusion Engine) Requirements

Requirement	Notes
Supported Linux OSs running on Intel (x86_64) systems only	See the Eggplant Functional Prerequisites page for information about Eggplant Fusion Engine (Eggplant Functional) supported Linux operating systems and versions.
Eggplant Functional (Fusion Engine)	Launched using runscript.
Disable the BonJour Discovery option	You must set the Eggplant Fusion Engine (Eggplant Functional) BonjourDiscoveryEnabled option to false when you run it in a container. This option is unnecessary when you run a Fusion Engine container in a pipeline where it does not need the ability to poll for other VNC Servers.

Licensing Requirements for RLM

Containers must be used with a floating RLM license. In order to use RLM, you must meet the following requirements:

Requirement	Notes
Reprise License Manager (RLM) Server	The currently supported version of the RLM Server as documented on the Eggplant Functional Prerequisites page.
Eggplant Functional Reprise License Manager (RLM) license(s)	1 Developer or Execution license for each instance of Eggplant Fusion Engine (Eggplant Functional) you want to run. You cannot use node-locked licenses when you run Eggplant Fusion Engine in a container. You can use a license key, it just cannot be for a node-locked license. You can also use floating licenses served by an RLM Server. For information about using the RLM Server for licenses, see Using RLM for Team License Management. You can create licenses through the Keysight Software Manager.
Network access to an RLM Server host	The Eggplant Fusion Engine in a container must have network access to the system running the RLM Server it from which it needs to check out a license.

Using Prebuilt Eggplant Functional (Fusion Engine) Container Images

We recommend using a prebuilt Eggplant Functional Container Image. Keysight provides container images with the Eggplant Functional script execution engine (Fusion Engine) that you can use. The entrypoint for these images is built around the Eggplant Functional runscript command. The container image can run on any Open Container Initiative (OCI) Runtime. Any runscript arguments you pass to the container will be passed to runscript. For information about OCI Runtime specifications, see the Linux Foundation Open Container Initiative site.

The containers are available from two repositories:

• Quay.io Eggplant Fusion Engine in a Container, which is also linked on our Eggplant Functional Software Downloads page.

• Iron Bank Eggplant Functional Container, which is Platform One's hardened container image repository. This repository provides a secure software supply chain for all software engineers in the greater United States Department of Defense (DoD) community. For more information, visit Platform One. You must be registered and logged in to Registry One in order to pull the container.

note

The prebuilt Eggplant Functional (Fusion Engine) container images can be customized if needed. To do this, create a Dockerfile/containerfile with the first line being FROM quay.io/eggplantsoftware/fusion-engine:latest, set USER root:root, make any adjustments needed (e.g. installing additional packages), and then add USER eggplant:eggplant back in.

Pulling the Prebuilt Container Images

Pull a copy of the prebuilt Eggplant Fusion Engine container image with either the podman command or the docker command depending on the container software you are using.

tip

You can copy sample commands in this guide by hovering over the command and then clicking the copy button (which looks like two pages stacked) when it appears on the right side of the code area.

For the Quay.io container:

Podman command:

podman pull quay.io/eggplantsoftware/fusion-engine:latest

Docker command:

docker pull quay.io/eggplantsoftware/fusion-engine:latest

For the Iron Bank container:

Use the below commands to pull the container from Registry One. You must be registered and logged in to Registry One in order for the pull command to work.

Podman command:

podman pull registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest

Docker command:

docker pull registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest

Running the Prebuilt Container Images

After you pull the Eggplant Fusion Engine container image, you need to configure it to run as shown in the following example podman run commands. The samples include ways to accept the EULA and Privacy agreements, either as variables or by passing those acceptances in a SenseTalk script. (This information is also provided in the Quay.io repository Description.)

As described above, the ENTRYPOINT for this container image is a wrapper around the Eggplant runscript command. This wrapper requires you to set the below environment variables:

EGGPLANT_ACCEPT_EULA=true
EGGPLANT_ACCEPT_PRIVACY_AGREEMENT=true

Depending on your setup, if you are using a license key, you also need to set the license key variable:

EGGPLANT_LICENSE_KEY=<your_license_key>

If you are using RLM to license, see Licensing with RLM.

Where the variables are:

• EGGPLANT_ACCEPT_EULA=true specifies to accept the End User License Agreement (EULA). For more information, see the EULA.
• EGGPLANT_ACCEPT_PRIVACY=true specifies to accept the Privacy Policy. For more information, see the Privacy Policy.
• EGGPLANT_LICENSE_KEY=<your_license_key> specifies the license key for running Eggplant Functional.

Licensing with RLM

In order to use a floating license served by a Reprise License Manager (RLM) in your container, you must specify the RLM host and password with the runscript command arguments at the end of the podman or docker command as shown in the podman example below.

• -licenserhost <RLM_Server_host_name>
• -licenserpassword <RLM_Server_password>

note

You should always secure your RLM Server with a password. However, if a password is not set for your RLM Server, you can omit the -LicenserPassword argument."

Example: This example shows licensing RLM when running in Drive Mode:

podman run -d  \
       -e EGGPLANT_ACCEPT_EULA=true \
       -e EGGPLANT_ACCEPT_PRIVACY_AGREEMENT=true \
       -P \
       quay.io/eggplantsoftware/fusion-engine:latest \ //Replace this line with registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest for the Iron Bank container
       -driveport 5400 -CommandLineOutput yes -licenserhost <RLM_Server_host_name> -licenserpassword <RLM_Server_password>

note

If the RLM license host is localhost, and RLM is not running on an externally resolvable hostname, use the following instead of the local host address:

• On Windows, use: host.docker.internal
• On Linux and Mac use: 172.17.0.1

Running a SenseTalk Script with Eggplant Fusion Engine

You can configure your Eggplant Fusion Engine container to run a SenseTalk script as shown in the following example podman run command.

This example shows the commands for the Eggplant Fusion Engine container in the Quay.io repository. You can also use the sample command below for the Iron Bank container when you replace the Quay.io repository path with the Iron Bank repository path.

podman run --rm \
       -e EGGPLANT_ACCEPT_EULA=true \
       -e EGGPLANT_ACCEPT_PRIVACY_AGREEMENT=true \
       -e EGGPLANT_LICENSE_KEY=<your_license_key> \
       --volume $HOME/suites:/home/eggplant/suites \
       quay.io/eggplantsoftware/fusion-engine:latest \ //Replace this line with registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest for the Iron Bank container
       -CommandLineOutput yes /path/to/script

Where -CommandLineOutput yes /path/to/script is the line to replace with the path to the specific script you want to run.

note

The bind mount in the above example (--volume $HOME/suites:/home/eggplant/suites) is required to make local scripts available in the container.

Running Eggplant Fusion Engine in Drive Mode

Alternatively, you can run Eggplant Fusion Engine in Drive Mode as shown in the following sample podman run command. This example is for the Eggplant Fusion Engine container in the Quay.io repository.

The sample command below can also apply to the Iron Bank container when you replace the Quay.io repository path with the Iron Bank repository path.

podman run -d  \
       -e EGGPLANT_ACCEPT_EULA=true \
       -e EGGPLANT_ACCEPT_PRIVACY_AGREEMENT=true \
       -e EGGPLANT_LICENSE_KEY=<your_license_key> \
       -P \
       quay.io/eggplantsoftware/fusion-engine:latest \ //Replace this line with registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest for the Iron Bank container
       -driveport 5400 -CommandLineOutput yes

Where the -driveport 5400 -CommandLineOutput yes is the line that specifies to run Eggplant Functional in Drive Mode

Next step: For information about integrating your prebuilt container into your Gitlab pipelines, see Configuring Gitlab CI to Use Your Container Image.

Building Your Own Container Image

It is recommended to use a prebuilt Eggplant Functional (Fusion Engine) container image. However, if you are familiar with building containers, you can either customize the Eggplant Functional container image, or build your own container to run Eggplant Functional (Fusion Engine). Following are the things you need to know to successfully build a container that runs Fusion Engine.

note

In order to customize the existing prebuilt Eggplant Functional (Fusion Engine) Container Images, you can create a Dockerfile/Containerfile with the first line being FROM quay.io/eggplantsoftware/fusion-engine:latest, set USER root:root, make any adjustments needed (e.g. installing additional packages), and then add USER eggplant:eggplant back in.

Installing Eggplant Fusion Engine in a Container

To run an Eggplant Fusion Engine instance in a container, you need to configure the container to perform a command-line installation. See Installing Eggplant Functional for the installation instructions for your Linux container platform.

Configure Defaults (After installation)

Prior to running Eggplant Fusion Engine in a container, you must configure the instance in the container to accept the End User License Agreement (EULA) and Privacy Policy, as well as obtain a license.

Example:

In your Dockerfile or containerfile, set up the container for headless operation and accept agreements during the image build:

RUN defaults write Eggplant GSBackend libgnustep-headless \
    && defaults write Eggplant AcceptEULA YES \
    && defaults write Eggplant AcceptPrivacyAgreement YES

Launching Eggplant Fusion Engine in a Container

As mentioned in Methods for Running Eggplant Functional/Fusion Engine in Container there are two ways to run the Fusion Engine in a container: you can configure it to run a specific script, or you can configure it to run as a persistent service in Drive Mode. Examples of both methods follow.

Launching to Run a Script in Drive Mode

You can run Eggplant Fusion Engine in Drive Mode using the -driveport parameter, as shown in the following sample podman run command.

Important

Be sure the port you specify in the -driveport argument is exposed.

Example:

Running in Drive Mode using podman run might look like the example below. This example accepts the EULA (Eggplant User License Agreement) and Privacy Agreement, and also licenses EPF before launching the fusion engine container in Drive Mode:

podman run -d  \
       -e EGGPLANT_ACCEPT_EULA=true \
       -e EGGPLANT_ACCEPT_PRIVACY_AGREEMENT=true \
       -e EGGPLANT_LICENSE_KEY=<your_license_key> \
       -P \
       quay.io/eggplantsoftware/fusion-engine:latest \ //Replace this line with registry1.dso.mil/ironbank/keysight/eggplant/fusion-engine:latest for the Iron Bank container
       -driveport 5400 -CommandLineOutput yes

Examples:

To run from Docker directly, running a script would look like the below example. In this case, the runscript -drivemode 5400 -CommandLineOutput yes is the line that launches Fusion Engine in Drive Mode:

docker run <container-image-name> runscript -driveport 5400 -CommandLineOutput yes

Alternately, you could use runscript like so:

docker run <container-image-name> runscript <script-path>

Please note that you must configure defaults and license Eggplant Functional prior to running commands like the above examples.

Configuring Gitlab CI/CD to Use a Container Image

To integrate an Eggplant Fusion Engine container into a GitLab Continuous Integration/Continuous Delivery (CI/CD) pipeline, you must specify the container information in the pipeline configuration. Gitlab pipeline configurations are specified in the .gitlab-ci.yml file as shown in the following example.

For more information about Gitlab CI/CD, See Get Started with Gitlab CI/CD.

Example gitlab-ci.yml File for Pipeline Configuration

The example gitlab-ci.yml file below shows how you can configure a Gitlab pipeline to run a SenseTalk script with the prebuilt Quay.io Eggplant Functional container on Red Hat Enterprise Linux 8 (Rocky). Information about using this container is provided in Pulling the Prebuilt Container Images.

stages:
  - tests

run-rocky-epf-test:
  stage: test
  image:
    name: quay.io/eggplantsoftware/fusion-engine:latest
    entrypoint:
      - "" # restore default entrypoint
  script: 
     - defaults write Eggplant AcceptEULA YES 
     - defaults write Eggplant AcceptPrivacyAgreement YES 
     - runscript -LicenserHost ${EGGPLANT_LICENSE_HOST}
     - runscript -CommandLineOutput YES Demo.suite/Scripts/check_tutorial_sut.script
  artifacts:
     when: always
     paths:
       - Demo.suite/Results
      reports:
        junit: Demo.suite/Results/**/LogFile.xml

Upgrading and Uninstalling Eggplant Functional (Fusion Engine) in a Container

Because most containers are destroyed after they run, you do not uninstall Eggplant Functional (Fusion Engine) from a container.

For the same reason, you do not upgrade Eggplant Fusion Engine in an existing container. Upgrading Eggplant Fusion Engine in a container consists of specifying the URL for the new Eggplant Functional version you want in your container configuration so that your container launches with the new version. For example, this would be the URL specified in the image name field in the Example gilab-ci.yml file above, or in line 8 on the Iron Bank Dockerfile.

Need More Information?

Contact Eggplant Customer Support if you require further assistance.