fabric8-jenkins-proxy

README

fabric8-jenkins-proxy

• What is it?
• Data flow diagrams
• 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
  • Testing webhooks

What is it?

fabric8-jenkins-proxy (Jenkins Proxy) is the sister project to fabric8-jenkins-idler(Jenkins Idler). Its task is to run a HTTP Proxy which sits in between an openshift.io user and its Jenkins instance within openshift.io. For more information refer to the Idler README.

Data flow diagrams

The following diagrams describe the data flow within the proxy for a received GitHub webhook respectively a direct user interaction with the Jenkins service:

How to build?

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

Prerequisites

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

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.

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 setupLocalProxy.sh which can be used to run the Proxy locally. A prerequisite for this is access to https://console.dsaas-stg.openshift.com/. To run the script you need to export your OpenShift access token for console.dsaas-stg.openshift.com as DSAAS_PREVIEW_TOKEN. Note, In order to port forward you need to edit permissions on the dsaas-preview namespace. You need to have jq installed to run these commands. For fedora use sudo dnf install jq

Usage: ./scripts/setupLocalProxy.sh [start|stop|env|unset]

This script is used to run the Jenkins Proxy on localhost. As a prerequisite OPENSHIFT_API_TOKEN needs to be exported. In your shell (from the root of fabric8-jenkins-proxy):

To start proxy and other required services

[user@localhost ~]$ export DSAAS_PREVIEW_TOKEN=<dsaas-preview-token>
[user@localhost ~]$ ./scripts/setupLocalProxy.sh start

Run command below this in a separate terminal so that we can see logs of the above command.

[user@localhost ~]$ export DSAAS_PREVIEW_TOKEN=<dsaas-preview-token>
[user@localhost ~]$ eval $(./scripts/setupLocalProxy.sh env)
[user@localhost ~]$ fabric8-jenkins-proxy

After you stop fabric8-jenkins-proxy, you would want to stop all the dependency services as well To remove postgres container and stop port-forwarding to prod-preview's idler service and tenant service

[user@localhost ~]$ ./scripts/setupLocalProxy.sh stop

Services running as a part of this local setup:

• idler on 9001
• tenant service on 9002
• postgres on 5432

This will run proxy over HTTPS on port 8080.

Testing webhooks

You can trigger local webhook delivery like so. Go to a GitHub repository generated by the OpenShift.io launcher. Find the webhook settings under Settings->Webhooks. There you can see the recent deliveries. Copy the payload of a webhook delivery into a file webhook-payload.json. Then execute the following curl command:

$ curl https://localhost:8080/github-webhook/ \
-H "Content-Type: application/json" \
-H "User-Agent: GitHub-Hookshot/c494ff1" \
-H "X-GitHub-Event: status" \
-d @webhook-payload.json

Testing Through UI

Any request that is made to proxy(i.e., port 8080) regardless of the path, proxy will send a request to idler to unidle jenkins, if it is idled.

curl https://localhost:8080/*

This would show a spinning wheel until jenkins is idle. On running locally the html page might not exist so, it will show a message on not finding the html page.

APIs

This project opens three ports 9091, 9092 and 8080. Proxy service running on 8080 is exposed at route https://jenkins.openshift.io and Jenkins API router running on 9092 is exposed on https://jenkins.api.openshift.io. API router running on 9091 is not exposed.

9091

The unexposed API router(9091) has only one API, which is info API. An example is as follows

Request: GET https://localhost:9091/api/info/ksagathi-preview

Response: {"namespace":"ksagathi-preview","requests":0,"last_visit":0,"last_request":0}

Apart from this we have Prometheus running at /metrics

9092

Jenkins API has only one API, which gets us current state of the Jenkins instance and triggers its unidling.

Request: curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" https://jenkins.api.openshift.io/api/jenkins/start -k

Response: {
                Data: { State: idled|starting|running},
                Errors : []ResponseError {
                                Code: httpStatusCode,
                                Description: "Description",
                                }
        }