Connecting DevOptics to a master automatically by using a plugin token

CloudBees encourages its customers to use operations center. Using plugin tokens is an advanced method that should be attempted only by experienced administrators.

Plugin tokens can be used with masters that use a proxy, and in both Free and Premium editions of DevOptics.

To enable a plugin token, do the following:

Create a plugin token and copy it to a file.
Define the environment variable DEVOPTICS_PLUGIN_TOKEN_FILE to enable your master to locate the file to which you copied the plugin token.
Verify the connection.

Prerequisites for using a plugin token

To use a plugin token, you must do the following:

Upgrade your DevOptics plugin. The plugin version must be 1.1700 or later.
Ensure your Primary Role in CloudBees GrandCentral is the Administrator role.

Creating a plugin token

To create a plugin token, your Primary Role in CloudBees GrandCentral must be the Administrator role.

In DevOptics, select Settings > Plugin tokens.
Click Create token.
Enter a token label to identify this token.
Click Create.
On the Your plugin token dialog box, click Copy token to copy the new token to a file that the Jenkins master can read. You can copy the token to any file in any location that you choose. Be sure to copy the token now because you cannot copy the token at any other time.
After you have created and copied a plugin, define the environment variable DEVOPTICS_PLUGIN_TOKEN_FILE to enable your master to locate the file to which you have copied your plugin token.

Verifying the plugin connection

From Jenkins, click Jenkins > DevOptics.
In the Connection Configuration via Plugin Token section, verify that Enabled appears. If Jenkins could not read the token, an error message indicates why the token could not be read. Be sure that the environment variable is set up correctly to point to the token file, and then try again.

Revoking plugin tokens

When you revoke a plugin token, you can no longer use that token to create connections to new masters. However, existing connections that use a connected token continue to be connected.

To revoke a token, your Primary Role in CloudBees GrandCentral must be the Administrator role.

In DevOptics, select Settings > Plugin tokens.
Do one of the following:
- To revoke a single token: Locate the token in the list, and then click Revoke on the row for that token.
- To revoke all tokens: Click Revoke all tokens.
Click Revoke to confirm that you want to revoke the tokens that you selected.

Viewing the plugin token for a Jenkins master

The Jenkins logs contain the plugin token that is used for each Jenkins master.

From Jenkins, click Jenkins > DevOptics.
In the Connection Configuration via Plugin Token section, the label assigned to the plugin token is displayed.

Viewing a list of plugin tokens in your organization

In DevOptics, select Settings > Plugin tokens.

Usage patterns for plugin tokens

Depending on the way you are running your Jenkins masters, there are a few different patterns you can follow for providing the plugin token to the DevOptics plugin. Below are just a few examples for widely used systems.

Docker at runtime

There are two main ways you could use plugin tokens to configure your Jenkins masters in docker. The first way is to mount the plugin token into your Jenkins docker container via a volume. This mechanism also works with Docker swarm and Docker compose. The folder you mount the plugin token into should also be defined as the environment variable DEVOPTICS_PLUGIN_TOKEN_FILE, to tell the DevOptics plugin to read the token from that location.

docker run -d --name jenkins-master -p 8080:8080 \
  -v /home/myuser/devoptics-plugin-token:/var/jenkins_home/devoptics-plugin-token \
  -e DEVOPTICS_PLUGIN_TOKEN_FILE=/var/jenkins_home/devoptics-plugin-token \
  jenkins/jenkins:latest▼

Then install the DevOptics plugin, and the plugin token will be automatically used to associate the Jenkins master to your DevOptics organization. You will see the label of the plugin token displayed in your DevOptics configuration page on Jenkins. 72 plugin token connected

Docker at build time

The second way to use plugin token association with docker is to include the plugin token into a custom built Jenkins docker image. This method requires less configuration at runtime, but also requires you to rebuild the docker image if you need to update the token. For example, your Dockerfile could be:

FROM jenkins/jenkins:latest
# Install the plugins
RUN /usr/local/bin/install-plugins.sh "cloudbees-devoptics-enabler" \
  "devoptics:latest:https://jenkins-updates.cloudbees.com/download/plugins/devoptics/latest/devoptics.hpi"
# Copy our DevOptics plugin token
COPY devoptics-plugin-token /var/jenkins_home/
# Tell DevOptics plugin where to find the token
ENV DEVOPTICS_PLUGIN_TOKEN_FILE=/var/jenkins_home/devoptics-plugin-token

When the Jenkins master starts up using an image built from this Dockerfile, it will automatically associate to your DevOptics organization.

Kubernetes via secrets

For Jenkins masters running within a Kubernetes environment, a good approach to providing the plugin token to DevOptics is to mount it as a secret.

kubectl create secret generic devoptics-secrets --from-file=./devoptics-plugin-token▼

Once the secret has been created, you would mount it into the Pod running Jenkins, and define the environment variable DEVOPTICS_PLUGIN_TOKEN_FILE, to tell the DevOptics plugin to read the token from the mounted location. An example Pod definition would be:

apiVersion: v1
kind: Pod
metadata:
  name: jenkins
spec:
  containers:
  - name: jenkins
    image: jenkins/jenkins:latest
    env:
    - name: DEVOPTICS_PLUGIN_TOKEN_FILE
      value: "/etc/devoptics-secrets/devoptics-plugin-token"
    volumeMounts:
    - name: devoptics-secrets
      mountPath: "/etc/devoptics-secrets"
      readOnly: true
  volumes:
  - name: devoptics-secrets
    secret:
      secretName: devoptics-secrets

Ansible via a playbook

If you do not use docker containers as your runtime environment for Jenkins, you can still automate using plugin tokens by using your preferred automation tooling. Below is an example Ansible role that installs a plugin token and configures it via systemd drop-in configuration for Fedora environments. Firstly the drop-in configuration defines the environment variable for Jenkins to read the file.

[Service]
Environment=DEVOPTICS_PLUGIN_TOKEN_FILE=/etc/sysconfig/devoptics-plugin-token

Then the role installs this drop-in configuration and the plugin token.

---
# tasks file for devoptics-plugin-token
- name: Copy DevOptics plugin token
  copy:
    content: "{{ devoptics_plugin_token }}"
    dest: "/etc/sysconfig/devoptics-plugin-token"
    owner: "jenkins"

- name: Create systemd drop-in directory for Jenkins
  file:
    path: "/etc/systemd/system/jenkins.service"
    state: directory

- name: Copy systemd drop-in to configure DevOptics plugin
  copy:
    src: "{{ role_path }}/files/10-devoptics.conf"
    dest: "/etc/systemd/system/jenkins.service/10-devoptics.conf"

This example assumes your DevOptics plugin token is defined in a variable in your Ansible inventory called devoptics_plugin_token.