README.md

Jenkins Idler

• What is it?
• How to build
  • Prerequisites
  • Make usage
    • Compile the code
    • Build the container image
    • Run the tests
    • Format the code
    • Check commit message format
    • Clean up
  • Dependency management
  • Continuous Integration
  • Running locally
• Misc
• How to contribute?

What is it?

The Jenkins Idler is a service which idles perspectively unidles a tenant's Jenkins instance. In order to determine whether a Jenkins instance can be idled, the Idler monitors OpenShift Build and DeploymentConfig changes. It also keeps track of direct access to the UI as well as GitHub webhook deliveries.

1. Idler watches Build and DeploymentConfig changes in OpenShift
2. Idler controls the state of Jenkins DeploymentConfig in OpenShift
3. Idler is checking Jenkins Proxy for number of buffered webhook requests and last access to Jenkins UI
4. Proxy caches webhook requests while Jenkins is un-idling

Jenkins Idler is the sister project to fabric8-jenkins-proxy(Jenkins Proxy).

How to build

The following paragraphs describe how to build and work with the source.

Prerequisites

The project is written in Go, so you will need a working Go installation (Go version >= 1.8.3).

The build itself is driven by GNU Make which also needs to be installed on your systems.

Last but not least, you need a running Docker daemon, since the final build artifact is a Docker container. Also of the unit tests make use of Docker.

Make usage

Compile the code

$ make build

Build the container image

$ make image

Run the tests

$ make test

Format the code

$ make fmt

Check commit message format

$ make validate_commits

Clean up

$ make clean

More help is provided by make help.

Dependency management

The dependencies of the project are managed by Dep. To add or change the current dependencies you need to delete the Dep lock file (Gopkg.lock), update the dependency list (Gopkg.toml) and then regenerate the lock file. The process looks like this:

$ make clean
$ rm Gopkg.lock
# Update Gopkg.toml with the changes to the dependencies
$ make build
$ git add Gopkg.toml Gopkg.lock
$ git commit

Continuous Integration

At the moment Travis CI and CentOS CI are configured. Both CI systems build all merges to master as well as pull requests.

CI System
CentOS CI	master, pr
Travis CI	master, pr

Running locally

The repository contains a script setupLocalIdler.sh which can be used to run the Idler locally.

A prerequisite for this is to access the Red Hat OpenShift.io prodpreview infrastructure.

The internal documentation for how to set this up is located in this (private) document.

Misc

• The original problem statement.
• Service operations within OpenShift.io.

How to contribute?

If you want to contribute, make sure to follow the contribution guidelines when you open issues or submit pull requests.

APIs

Below area sample API requests

Task: Get API URL of all openshift clusters

Request: http://localhost:8080/api/idler/cluster

Response: 
[
  {
    "APIURL": "https://api.starter-us-east-2a.openshift.com/",
    "AppDNS": "b542.starter-us-east-2a.openshiftapps.com"
  },
  {
    "APIURL": "https://api.free-stg.openshift.com/",
    "AppDNS": "1b7d.free-stg.openshiftapps.com"
  }
]

Task: Get internal state of a specified namespace

Request: http://localhost:8080/api/idler/info/ksagathi-preview

Response:
{
  "Name": "ksagathi-preview",
  "ID": "7219a11c-f86a-4db1-ab3e-83216ff53009",
  "ActiveBuild": {
    "metadata": {
      "annotations": {
        
      },
      "Generation": 0
    },
    "status": {
      "phase": "New",
      "startTimestamp": "0001-01-01T00:00:00Z",
      "completionTimestamp": "0001-01-01T00:00:00Z"
    },
    "spec": {
      "replicas": 0,
      "Strategy": {
        "Type": ""
      }
    }
  },
  "DoneBuild": {
    "metadata": {
      "name": "sample1-1",
      "namespace": "ksagathi-preview",
      "annotations": {
        "openshift.io/build.number": "1",
        "openshift.io/jenkins-namespace": "ksagathi-preview-jenkins"
      },
      "Generation": 0
    },
    "status": {
      "phase": "Complete",
      "startTimestamp": "2018-04-11T08:27:15Z",
      "completionTimestamp": "2018-04-11T08:31:51Z"
    },
    "spec": {
      "replicas": 0,
      "Strategy": {
        "Type": "JenkinsPipeline"
      }
    }
  },
  "JenkinsLastUpdate": "2018-04-11T09:41:57Z"
}

Task: Check whether Jenkins pod is idle or not for a specific namespace

Request: curl http://localhost:8080/api/idler/isidle/ksagathi-preview-jenkins?openshift_api_url=https://api.starter-us-east-2a.openshift.com/

Response: {"is_idle":true}

Task: Unidle Jenkins Pod of the a specified namespace 

Request: curl http://localhost:8080/api/idler/unidle/ksagathi-preview-jenkins?openshift_api_url=https://api.starter-us-east-2a.openshift.com/

Response: (Empty response with 200 status code)

Task: Idle Jenkins Pod of a specified namespace

Request: curl -i http://localhost:8080/api/idler/idle/ksagathi-preview-jenkins?openshift_api_url=https://api.starter-us-east-2a.openshift.com/

Response: (Empty Response with 200 status code)