Jenkins

Native plugin directly available in the Marketplace

As part of our CI/CD integration we provide a native plugin for Jenkins. You can install this plugin from the plugin marketplace directly into your pipeline. The full setup will be done from there. Connecting into your CI/CD pipeline allows developers to utilize existing tooling for their automatic documentation. Instead of tediously open a Web UI after a deployment, they can do all their changes in their IDE - and rely on LeanIX Microservice Intelligence to capture changes, make them transparent, and notify others.

The data that is synchronized is completely the same as for the generic CI/CD integration. If you, later on, wish to add additional information you can find our customization options here.

Setup

Prerequisites

  • The LeanIX plugin must be installed: https://www.jenkins.io/doc/book/managing/plugins/
    *You should have a valid LeanIX API token.
  • If you are using scripted pipelines in which the LeanIX plugin is to be integrated as a step, the "Credentials Binding" plugin must be installed: https://plugins.jenkins.io/credentials-binding/
  • For freestyle projects, in which the plugin can be added via UI as a build step, the plugin for injecting environment variables might be installed instead: https://plugins.jenkins.io/envinject/
  • An SCM provider (e.g. Git) must be configured for the pipeline to be used and the possibly necessary plug-in installed.
  • The manifest file made available by LeanIX should be filled with the appropriate values and should be located in the corresponding repository, so that it can be accessed by the plugin.

Configuration

The configuration of the LeanIX Plugin is divided into three parts:

  • Setting up secrets in the Jenkins administration,
  • Central configuration of the plugin,
  • Configuration of individual pipelines and jobs in which the plugin is to be used.

Setting up secrets in the Manage Jenkins area.

This section is only important if you want to use the LeanIX plugin in scripted pipelines. For this purpose, a new credentials record with the following parameters is created in Jenkins in the "Manage Jenkins" -> "Security" -> "Manage Credentials" area (a detailed description of how to create credentials can be found at the following link: https:www.jenkins.io/doc/book/using/using-credentials/):

  • Scope: It is best to select "global", unless security reasons or company guidelines speak against it.
  • Username: The host and thus the part of a URL that specifies the region of the LeanIX service in which the workspace is located, to which the data extracted by the plugin is to be sent (e.g. eu.leanix.net).
  • Password: A valid API token for the LeanIX workspace that matches the host.
  • ID: "LEANIX_CREDENTIALS" is suggested here, but any valid variable name can be selected. It just needs to be used accordingly in the pipeline.
  • Description: No value is needed here.
Storage of credentialsStorage of credentials

Storage of credentials

Central configuration of the plugin

The plugin offers the possibility to centrally configure important settings. After installation, there is an area on the basic level "Dashboard" of Jenkins with the title "LeanIX Microservice Intelligence" for these configurations.

Central settingsCentral settings

Central settings

When you open this page, you will find two areas in which settings can be made.

JSON settings

In the uppermost area with the title "Pipeline Configuration in JSON format" there is an input field in which configurations in JSON format can be inserted.
The structure of these configurations is as follows:

  • "leanIXConfigurations" contains all configurations, root of the file
  • "deploymentStageVarName": If you use environment variables for the configuration of the stage that your Jenkins job belongs to (e.g. test, production) you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the stage. The stage can also be set in the local configurations of the jobs.
  • "deploymentVersionVarName": If you use environment variables for the configuration of the version of the build that your Jenkins job is running, you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the version. It is mandatory to give a version, but it can also be given in the local configuration of the jobs.
  • "settings": In this array settings for several pipelines can be bundled.
  • "pipelines": This array is filled with the names of the pipelines/jobs, for which the following settings should apply
  • "path": The path to the LeanIX-manifest-YAML-file in your SCM (Git, SVN etc.) for the pipelines or jobs defined under "pipelines"

For Freestyle projects it is mandatory to add the path to manifest-file here!

This is an example of a configuration:

{
      "leanIXConfigurations": {
        "deploymentStageVarName": "stage",
        "deploymentVersionVarName": "version",
        "settings": [
          {
            "pipelines": [
              "pipeline1",
              "pipeline2",
              "job1"
            ],
            "path": "/other/lx-manifest.yml"
          },
          {
            "pipelines": [
              "pipeline3"
            ],
            "path": "/lx-manifest.yml"
          }
        ]
      }
    }
Job result settings

In the second area, "Job result", you can make the basic setting for all jobs / pipelines, which impact a failure of the LeanIX build step will have for the entire job or the entire pipeline. One of the five options that Jenkins offers as a result can be selected here. If the plugin fails, the selected result is set as the end result of the executed job. The default value for the result is "SUCCESS" which means that a failure of the LeanIX-Plugin does not make the pipeline/job fail.

Job result setting in case of failureJob result setting in case of failure

Job result setting in case of failure

Individual configuration of pipelines and jobs

Configuring Freestyle Projects

To configure a freestyle project, the stage and version of the job must be defined in environment variables. If you have a way to configure this, the name of the variables you use can be set via the central configuration of the plugin, see above. Otherwise the plugin "Environment Injector" (https://plugins.jenkins.io/envinject/) available for Jenkins can be used. The stage and version must be defined in such a way that the names used match those used in the central configuration. In the following example in the central configuration "deploymentStageVarName" was
defined with "stage" and "deploymentVersionVarName" with "version":

Set your version and stage attributesSet your version and stage attributes

Set your version and stage attributes

In addition, an SCM provider (e.g. Git) must be set up correctly for the project and the LeanIX manifest file must be located there under the path that is specified in the central configuration for this job.

In order to add the LeanIX plugin to the project, a corresponding build step must be created. To do this, click in the configuration of the Freestyle project under "Build" on "Add build step" and select "LeanIX Microservice Intelligence".

Choose the right build stepChoose the right build step

Choose the right build step

In the input mask with the title "LeanIX Microservice Intelligence" that then appears, fill in the appropriate values ​​or select from the drop-down menus:

  • LeanIX-Manifest-Path -readonly- : This field is readonly, it will be filled automatically after the first run of the plugin. This is the path to the manifest file that is specified in the central configuration. If it is not specified, the default will be "/lx-manifest.yml".
  • Hostname: Enter the host name for the appropriate LeanIX region in which your workspace is located.
  • Apitoken: Enter the API token that matches the host name or your workspace in this protected field.
  • Result in case of failure: Indicate what influence a failure of the LeanIX plugin should have on EXACTLY THIS JOB. If you do not make a selection, the selection of the central configuration is used. If you make a selection, the entry for the central configuration for this job will be overwritten.
  • Dependency manager of the SCM: Select which DependencyManager you use for your project. This information is important so that the correct dependencies can be generated from your SCM and integrated into the appropriate factsheet. The LeanIX plugin currently supports NPM, MAVEN and GRADLE.
  • Use this LeanIX Build Step: This checkbox indicates whether the LeanIX Build step should be executed or skipped. You can use this to switch it on and off as per job.
Freestyle project configuration.Freestyle project configuration.

Freestyle project configuration.

Configuring Pipeline projects

In your pipeline definition, the variables for stage and version of the build must be set as environment variables. Define the variable names used in the central configuration (see above), otherwise "stage" is assumed for the stage variable and "version" for the version variable. If you don't have your own way of defining it, you can define these variables in the pipeline as follows:

     environment {
        stage = "dev"
        version = "1.3.0"
    }

Before adding the LeanIX build step to the pipeline, add a secured credentials environment with the Credentials Binding Plugin, as indicated under Prerequisites. The corresponding line looks like this:

     withCredentials ([usernamePassword (credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]{}

The step in which the LeanIX plug-in is executed must be within the scope of "withCredentials" so that it can securely access the LeanIX API token and the other information.
To configure the LeanIX plugin step you can use the "pipeline Syntax" generator of Jenkins.
A pipeline step with a built-in LeanIX plugin looks like this:

    steps {
        withCredentials([usernamePassword(credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]) {
            leanIXMicroserviceIntelligence hostname: host, useleanixconnector: true, dependencymanager: 'GRADLE'
        }
    }

Usage

When the configuration of the project or pipeline is complete, the start of a build (Build now) will include the execution of the LeanIX plugin. After execution and if the LeanIX plugin step has been reached, there is a menu item called "LeanIX Microservice Intelligence Log" in the monitoring area of each build (click on the build number in the Pipeline or Project area). In this area you will find the information which values were used for the build by the LeanIX plugin as well as information on the result of the step in the "Status" section. Possible errors will be mentioned here.

Logs of the LeanIX MI PluginLogs of the LeanIX MI Plugin

Logs of the LeanIX MI Plugin

The plugin also logs information in the "Console Output" section, which is present with every build.


Did this page help you?