step-by-step.rst

Step by step

Checklist

Setting up ETOS is a daunting task when you are doing it the first time around. But it is also easy to miss a few steps that are required for it to work.

For this reason we have created a checklist in order to keep track of what needs to be done so that no steps are forgotten.

• Set up a Kubernetes cluster (ETOS runs in Kubernetes)
• Set up an execution_space (Execute test runner containers)
• Set up a log_area (Storing logs after execution)
• Deploy MongoDB (Event storage DB)
• Deploy Redis Sentinel (ETOS internal communications)
• Deploy RabbitMQ (must be accessible outside of kubernetes as well)
• Deploy Eiffel GraphQL API
  • Deploy an Eiffel event storage tool. Example
• Deploy ETOS helm chart: index:Installation

• Configure etos-environment-provider

  • services/etos_environment_provider:IUT Provider
  • services/etos_environment_provider:Execution Space Provider
  • services/etos_environment_provider:Log Area Provider

• Create an tercc

  • Upload the tercc to an area with no required authorization.

• Generate an ArtC
• Generate an ArtP
• Verify that the ArtC and ArtP events exist in the Eiffel GraphQL API.
• Install getting_started/step-by-step:Installing ETOS Client on a workstation
• Set services/etos_client:Environment variables for ETOS Client
• Test ETOS deployment using ETOS Client <services/etos_client:General Syntax>

Installing ETOS Client on a workstation

This section will guide you through the process of setting up etos-client.

etos-client is the default tool for executing the test suites with. We always recommend using the client.

Requirements

• Python 3.6 (or higher)

Installation

etos-client can be found on PyPi and is installable with pip.

pip install etos_client

CLI Usage

etos_client --help

More on usage can be found here<services/etos_client:General Syntax>

Setting up a Jenkins delegation job

This page describes how to set up delegation jobs for ETOS. A delegation job's function is described here <services/etos_environment_provider:Execution Space Provider>

Note that a delegation job can be created just the way you want to (as long as it follows the instructions from the execution space), this is just a sample of how you could implement it.

Prerequisites

• Jenkins
• Jenkins Pipelines

Example setup

1. Create a pipeline job.
2. Recommended to set cleanup policy for the job.
3. Add multi-line string parameter named 'docker'.
4. Configure Execution Space <services/etos_environment_provider:Execution Space Provider> to send the 'docker' parameter to Jenkins.
5. Add script to delegation

node() {
    stage('ETOS') {
        def jsonslurper = new groovy.json.JsonSlurper()
        def json = params.docker
        def dockerJSON = jsonslurper.parseText(json)

        def environmentJSON = dockerJSON["environment"]
        def parametersJSON = dockerJSON["parameters"]
        def dockerName
        if (parametersJSON.containsKey("--name")) {
            dockerName = parametersJSON["--name"]
        } else {
            dockerName = UUID.randomUUID().toString()
            parametersJSON["--name"] = dockerName
        }
        env.DOCKERNAME = dockerName
        def environment = ""
        def parameters = ""
        environmentJSON.each{entry -> environment += "-e $entry.key=$entry.value "}
        parametersJSON.each{entry -> parameters += "$entry.key $entry.value "}
        def image = dockerJSON["image"]
        def command = "docker run --rm " + environment + parameters + image + " &"
        /*
          Write a bash file which will trap interrupts so that the docker container
          is properly removed when canceling a build.
        */
        writeFile file: 'run.sh', text: (
            '_terminate() {\n'
            + '    echo "Stopping container"\n'
            + "    docker stop $dockerName\n"
            + '}\n'
            + 'trap _terminate SIGTERM\n'
            + "$command \n"
            + 'child=$!\n'
            + 'wait "$child"\n'
        )
        sh "docker pull $image || true"
        sh """
        bash run.sh
        docker rm $dockerName || true
        """
        sh "rm run.sh"
    }
}

Example execution space provider

Checkout any number of static execution spaces. More information about execution space providers here <services/etos_environment_provider:Execution Space Provider>

{
  "execution_space": {
        "id": "jenkins",
        "list": {
            "possible": {
                "$expand": {
                    "value": {
                        "request": {
                            "url": "https://jenkins/job/DELEGATION/build",
                            "method": "POST",
                            "headers": {
                                "Accept": "application/json"
                            },
                            "data": {
                                "json": {
                                    "$json_dumps": {
                                        "parameter": [
                                            { "name": "docker", "value": {
                                                "$json_dumps": "$execution_space_instructions"
                                              }
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "to": "$amount"
                }
            },
            "available": "$this.possible"
        }
    }
}