Appel au Squash Orchestrator depuis un pipeline Jenkins

Configuration d'un Squash orchestrator dans Jenkins

Pour accéder à l'espace de configuration du Squash Orchestrator, il faut tout d'abord se rendre dans l'espace Configurer le système du System Configuration, accessible par l'onglet Administrer Jenkins :

Configuration système

Un bloc nommé OpenTestFactory Orchestrator servers sera ensuite disponible :

Déclaration Orchestrateur OpenTestFactory

Server id : Cet ID est généré automatiquement et ne peut être modifié. Il n'est pas utilisé par l'utilisateur.
Server name : Ce nom est défini par l'utilisateur. C'est celui qui sera mentionné dans le script du pipeline lors d'une exécution de workflow.
Receptionist endpoint URL : L'adresse du micro-service receptionist de l'orchestrateur, avec son port tel que défini au lancement de l'orchestrateur.
Reportez-vous à la documentation de Squash Orchestrator pour plus de détails.
Workflow Status endpoint URL : L'adresse du micro-service observer de l'orchestrateur, avec son port tel que défini au lancement de l'orchestrateur.
Reportez-vous à la documentation de documentation de Squash Orchestrator pour plus de détails.
Credential : Identifiant Jenkins de type Secret text contenant un JWT Token permettant de s'authentifier auprès de l'orchestrateur.
Reportez-vous à la documentation de l'OpenTestFactory Orchestrator pour plus de détails sur l'accès sécurisé à l'orchestrateur.
Workflow Status poll interval : Ce paramètre correspond au temps de mise à jour du statut du workflow.
Workflow creation timeout : Timeout utilisé pour attendre que l'état du workflow soit disponible auprès de l'observer après réception par le receptionist.

Intégration de l'appel à Squash Orchestrator dans un pipeline Jenkins

Une fois qu'il y a au moins un Squash Orchestrator configuré dans Jenkins, il est possible de faire appel à l'orchestrateur depuis un job Jenkins de type pipeline grâce à une méthode de pipeline dédiée.

Ci-dessous, un exemple de pipeline simple utilisant la méthode d'appel à l'orchestrateur :

node {
   stage 'Stage 1: sanity check'
   echo 'OK pipelines work in the test instance'
   stage 'Stage 2: steps check'
   configFileProvider([configFile(
       fileId: '600492a8-8312-44dc-ac18-b5d6d30857b4',
       targetLocation: 'testWorkflow.json'
    )]) {
    def workflow_id = runOTFWorkflow(
        workflowPathName:'testWorkflow.json',
        workflowTimeout: '300S',
        serverName:'defaultServer',
        jobDepth: 2,
        stepDepth: 3,
        dumpOnError: true
    )
    echo "We just ran The Squash Orchestrator workflow $workflow_id"
   }
}

La méthode runOTFWorkflow permet de transmettre un workflow à l'orchestrateur pour exécution. Elle dispose de 6 paramètres :

workflowPathName : Le chemin vers le fichier contenant le workflow. Dans le cas présent, le fichier est injecté via le plugin Config File Provider, mais il est également possible de l'obtenir par d'autres moyens (récupération depuis un SCM, génération à la volée dans un fichier, …).
workflowTimeout : Timeout sur l'exécution des actions. Ce délai d'attente se déclenchera si l'exécution du workflow prend plus de temps que prévu, pour quelque raison que ce soit. Son objectif est de stopper les flux de travail bloqués (par exemple en raison d'environnements inaccessibles ou d'appels à l'action non pris en charge). Il est à adapter en fonction de la durée d'exécution attendue des différents tests du workflow.
serverName : Nom du serveur Squash Orchestrator à utiliser. Ce nom est celui défini dans l'espace de configuration OpenTestFactory Orchestrator servers de Jenkins.
jobDepth : Profondeur des jobs imbriqués dont les logs sont à afficher dans la console Jenkins.
Ce paramètre est optionnel. Sa valeur par défaut est 1.
La valeur 0 permet de d'afficher tous les jobs quelles que soient leurs profondeurs.
stepDepth : Profondeur des steps imbriquées dont les logs sont à afficher dans la console Jenkins.
Ce paramètre est optionnel. Sa valeur par défaut est 1.
La valeur 0 permet de d'afficher toutes les steps quelles que soient leurs profondeurs.
dumpOnError : Quand sa valeur est true, réaffiche l'intégralité des logs avec la profondeur maximale de job et de step lorsqu'un workflow échoue.
Ce paramètre est optionnel. Sa valeur par défaut est true.

Pour faciliter la lecture des logs et le débogage, les logs issus des environnements d'exécution des tests sont toujours affichés, quelle que soit la profondeur des logs demandée.

Passage de variables d'environnement ou de fichiers

Dans certains cas, il est nécessaire de transmettre des variables d'environnement ou des fichiers au workflow.

Pour les variables, il suffit de les déclarer dans la section environment de la définition du pipeline. Ces variables doivent être préfixées par OPENTF_. Elles seront utilisables dans le workflow sans ce préfixe.

Pour les fichiers, ils doivent être déclarés à l'aide du paramètre fileResources de la méthode runOTFWorkflow. Ce paramètre se compose d'un tableau d'éléments ref qui sont composés de deux attributs :

name : correspond au nom du fichier tel qu'utilisé dans le workflow.
path : le chemin du fichier au sein du workspace du job Jenkins.

L'exemple suivant exécute un workflow workflows/my_workflow_2.yaml en lui fournissant un fichier file (dont le contenu sera celui du fichier my_data/file.xml) et deux variables d'environnement FOO et TARGET :

pipeline {
  agent any
  environment {
    OPENTF_FOO = 12
    OPENTF_TARGET = 'https://example.com/target'
  }
  stages {
    stage('Greetings'){
      steps {
        echo 'Hello!'
      }
    }
    stage('QA') {
      steps {
        runOTFWorkflow(
          workflowPathName: 'workflows/my_workflow_2.yaml',
          workflowTimeout: '200S',
          serverName: 'orchestrator',
          jobDepth: 2,
          stepDepth: 3,
          dumpOnError: true,      
          fileResources: [ref('name': 'file', 'path': 'my_data/file.xml')]
        )
      }
    }
  }
}

Appel pour le déclenchement d'un workflow exploitant l'environnement d'exécution `inception`

Lorsque le but est de faire appel à Squash Orchestrator pour l'exécution d'un workflow utilisant l'environnement d'exécution inception, tel que décrit dans la documentation, le pipeline est à adapter suivant le modèle ci-dessous :

node {
   stage 'Stage 1: sanity check'
   echo 'OK pipelines work in the test instance'
   stage 'Stage 2: steps check'
   configFileProvider([
       configFile(fileId: 'inception_workflow.yaml', targetLocation: 'testWorkflow.yaml'),
       configFile(fileId: 'TEST-ForecastSuite.xml', targetLocation: 'TEST-ForecastSuite.xml')
    ]) {
       def workflow_id = runSquashWorkflow(
           workflowPathName:'testWorkflow.yaml',
           workflowTimeout: '300S',
           serverName:'defaultServer',
           jobDepth: 2,
           stepDepth: 3,
           dumpOnError: true, 
           fileResources: [ref('name':'myfile','path':'TEST-ForecastSuite.xml')]
       )

       echo "We just ran The Squash Orchestrator workflow $workflow_id"
   }
}

Le paramètre fileResources permet de renseigner les fichiers à transmettre à l'orchestrateur, ces fichiers correspondant à ceux renseignés dans la section files du workflow. Ce paramètre doit être défini comme indiqué dans le paragraphe précédent.

Rétrocompatibilité avec le plugin squash-devops.hpi

Pour accompagner son passage à l'open-source, ce plugin a changé depuis sa version 1.3.1 On est ainsi passé de squash-devops-1.3.0.hpi à opentestfactory-orchestrator-1.3.1.hpi. Afin de faciliter la transition des utilisateurs, les rétrocompatibilités suivantes sont assurées dans la version 1.3.1 :

Si vous désinstallez le plugin squash-devops.hpi et installez le plugin opentestfactory-orchestrator.hpi, vos serveurs installés avec le plugin legacy seront restaurés.
Les pipelines utilisant la méthode runSquashWorkflow sont toujours pris en charge. Cependant, cette méthode est dépréciée et ne sera plus supportée dans les futures versions ; utilisez dès à présent la méthode runOTFWorkflow à la place.
Les variables d'environnement utilisant le préfixe SQUASHTF_ sont toujours supportées. Cependant, elles sont dépréciées et ne seront plus supportées dans les futures versions, utilisez dès à présent le préfixe OPENTF_ à la place.

Cette rétrocompatibilité est toujours disponible pour la version actuelle : opentestfactory-orchestrator-2.2.0.hpi