CloudBees Docker Traceability

This plugin allows the tracking of the creation and use of Docker containers in Jenkins and their future use.

Plugin Summary

Container deployments summary page
Tracking of Docker image and container deployments produced in Jenkins
Tracking of Docker container events
Tracking of Docker container states being retrieved from docker inspect calls
Advanced API for Docker reports analysis
Submission of events from Docker and Docker Swarm installations
Data polling from Jenkins (including Docker API-compatible JSONs)
Support of search queries

Figure 1. Docker Traceability root page

The current version of the plugin has several limitations, which may affect common use cases. See Known Issues for more info.

Installation Guidelines

Plugin setup

Install CloudBees Docker Traceability plugin from Jenkins Update Center
Install other Jenkins plugins, which produce image fingerprints to be traced by the plugin (see Integrations)
Configure security. This step is highly recommended, because the plugin can store raw JSON, which may contain sensitive info like passwords
- The plugin introduces new permissions, which allow to restrict the access
  - Read - Allows to retrieve details like full container/info dumps. Web interfaces are being managed by the global Jenkins.Read permission, so they won’t be affected
  - Submit - Allows the submission deployment records from the remote API
  - Delete - Allows the deletion deployment records or entire fingerprints
- It is recommended to restrict the access to the deployments records submission to a limited group of users
Optional: Edit plugin settings on the Jenkins configuration page to adjust the behavior. Main options are listed below:
1. Docker Traceability link on the main panel
  1. By default, Jenkins does not display the Docker Traceability link on the main left panel. This link can be enabled on the configuration page
  2. Even if the root action is disabled, the plugin remains fully operational. The main action can be accessed using the direct $JENKINS_URL/docker-traceability link.
2. Image fingerprints creation mode
  1. By default, the plugin expects image fingerprints to be created by other Docker plugins based on Docker Commons plugin.
  2. The behavior can be adjusted on the plugin’s global configuration page

Client-side configuration

The CloudBees team is working on a specialized fault-tolerant client, which will monitor events on Docker and Docker Swarm servers and then submit reports to Docker CloudBees Traceability plugin. This client will become available soon. Currently the reports can be submitted using the plugin’s remote API commands.

Use cases

Submitting deployment records

The plugin does not support an automatic polling of events from external Docker servers. The events should be submitted by external clients or other Jenkins plugins.

Warning! Currently the plugin accepts the info for previously registered fingerprints only. Other submissions will be ignored. Initial image records should be created by other plugins using (Integrations)

From external items using REST API

The plugin’s API provides several commands, which allow to submit new events from remote client applications.

If you use a secured instance, in addition to credentials clients must be aware aware about Cross-Site Request Forgery Protection on Jenkins. Otherwise the requests may be rejected . See the configuration guidelines on Remote access API Wiki page.

submitContainerStatus is a simple call, which may be used from user scripts without a generation of additional JSON files.

Examples:

curl http://localhost:8080/jenkins/docker-traceability/submitContainerStatus
    --data-urlencode inspectData="$(docker inspect CONTAINER_ID)"▼

curl http://localhost:8080/jenkins/docker-traceability/submitContainerStatus
    --data-urlencode status=create
    --data-urlencode imageName=jenkinsci/workflow-demo
    --data-urlencode hostName=dev-server-1
    --data-urlencode hostName=development
    --data-urlencode inspectData="$(docker inspect CONTAINER_ID)"▼

submitEvent is a more complex call, which allows submit the all available data about a Docker container via a single REST API call. This call can be used from external plugins.

From other plugins

The plugin provides the DockerEventListener extension point, which is being used to notify listeners about new records.

Docker Traceability functionality also listens to these endpoints, so it is possible to notify the plugin about new records using DockerEventListener#fire()` method.

Getting info from the plugin

For each container record the plugin publishes the info on the container summary page. A summary status about deployments is being also added to the parent image page.

Figure 2. Container info and deployment events on the container page

Figure 3. Container deployments summary on the image page

If an external client submits information about the image (which can be retrieved using docker inspect imageId command), the plugin captures this image and adds a new facet to the image fingerprint page.

Figure 4. Docker image info facet

Raw data is accessible via the plugin’s API or via hyperlinks on info pages.

Search

You can search deployments by container IDs using the "Search" control on the Docker Traceability page. You can also query containers using the plugin’s API.

Integrations

CloudBees Docker Traceability plugin is based on fingerprints provided by Docker Commons plugin. The plugin just adds additional facets to main fingerprint pages, so any other plugin can contribute to the UI by adding additional facets to the fingerprint.

CloudBees Docker Pipeline and Docker Build and Publish plugins can create such fingerprints. See Docker Commons plugin Wiki page to get an info about other existing fingerprint contributors.

API

The detailed description of API endpoints is available in the "api" page of the Docker Traceability page (see $(JENKINS_URL)/docker-traceability/api)

Known issues

Below you can find a list of the issues, which may affect the plugins usage. CloudBees team is working on these issues in order to resolve them soon.

Fingerprints automatic cleanup by Jenkins (JENKINS-28655)

If CloudBees Docker Traceability plugin creates a new container or image fingerprint from a client’s request, it cannot reference its original build due to the missing info
Jenkins has a garbage collector, which removes fingerprints without build references every 24 hours

Impact:

If the created fingerprint is not referenced by a build, it may be deleted within 24 hours
If any other plugin references a fingerprint during the build, it will be retained till the build gets deleted

Workaround:

You can disable the fingerprint cleanup thread from the $JENKINS_HOME/init.groovy script, which will be launched every time Jenkins starts up
In such case Jenkins will retain all fingerprints, so be aware about possible disk overflows

Sample script:

import hudson.*;
import hudson.model.*;

ExtensionList.lookup(AsyncPeriodicWork.class).get(FingerprintCleanupThread.class).cancel()▼