github.com/shashidharatd/test-infra@v0.0.0-20171006011030-71304e1ca560/gubernator/README.md (about)

     1  Gubernator is a frontend for displaying Kubernetes test results stored in GCS.
     2  
     3  It runs on Google App Engine, and parses JSON and junit.xml results for display.
     4  
     5  https://k8s-gubernator.appspot.com/
     6  
     7  # Adding a repository to the PR Dashboard
     8  
     9  To make Gubernator's [PR Dashboard](https://k8s-gubernator.appspot.com/pr) work
    10  on another repository, it needs to receive webhook events.
    11  
    12  Go to Settings -> Webhooks on the repository (or organization) you want to add.
    13  
    14  Add a new webhook with these options:
    15  
    16  Payload URL: https://github-dot-k8s-gubernator.appspot.com/webhook
    17  Secret: Ask test-infra oncall.
    18  Select: "Send me everything"
    19  
    20  Gubernator will use the events it receives to build information about PRs, so
    21  only updates after the webhook is added will be shown on the dashboard.
    22  
    23  # Development
    24  
    25  - Install the Google Cloud SDK: https://cloud.google.com/sdk/
    26  - Run locally using `dev_appserver.py` and visit http://localhost:8080
    27  - Test and lint using `./test-gubernator.sh`
    28  - Deploy with `make deploy` followed by `make migrate`
    29  
    30  # Deployment
    31  
    32  - Get the "Gubernator Github Webhook Secret" (ask test-infra for help) and write
    33    it to `github/webhook_secret`.
    34  - Set up `secrets.json` to support Github [OAuth logins](https://github.com/settings/applications).
    35    The skeleton might look like:
    36  
    37  ```json
    38      {
    39          "k8s-gubernator.appspot.com": {
    40              "session": "(128+  bits of entropy for signing secure cookies)",
    41              "github_client": {
    42                  "id": "(client_id for the oauth application)",
    43                  "secret": "(client_secret for the oauth application)"
    44              }
    45          }
    46      }
    47  ```
    48  
    49  # GCS Layout
    50  
    51  In order to correctly interpret jobs results, in GCS, Gubernator expects that
    52  any one job directory is laid out in a specific manner, and that job directories
    53  are laid out in a specific manner relative to each other.
    54  
    55  ## Job Artifact GCS Layout
    56  
    57  Every run should upload `started.json`, `finished.json`, and `build-log.txt`, and
    58  can optionally upload jUnit XML and/or other files to the `artifacts/` directory.
    59  For a single build of a job, Gubernator expects the following layout in GCS:
    60  
    61  ```
    62  .
    63  ├── artifacts         # all artifacts must be placed under this directory
    64  │   └── junit_00.xml  # jUnit XML reports from the build
    65  ├── build-log.txt     # std{out,err} from the build
    66  ├── finished.json     # metadata uploaded once the build finishes
    67  └── started.json      # metadata uploaded once the build starts
    68  ```
    69  
    70  The following fields in `started.json` are honored:
    71  
    72  ```json
    73  {
    74      "timestamp": "seconds after UNIX epoch that the build started",
    75      "pull": "$PULL_REFS from the run",
    76      "repos": {
    77          "org/repo": "git version of the repo used in the test",
    78      },
    79  }
    80  ```
    81  
    82  The following fields in `finished.json` are honored:
    83  
    84  ```json
    85  {
    86      "timestamp": "seconds after UNIX epoch that the build finished",
    87      "result": "SUCCESS or FAILURE, the result of the build",
    88      "metadata": "dictionary of additional key-value pairs that will be displayed to the user",
    89  }
    90  ```
    91  
    92  Any artifacts from the build should be placed under `./artifacts/`. Any jUnit
    93  XML reports should be named `junit_*.xml` and placed under `./artifacts` as well.
    94  
    95  ## GCS Bucket Layout
    96  
    97  In your bucket, a number of directories are required to store the output of all
    98  the different types of jobs:
    99  
   100  ```
   101  .
   102  ├── logs                 # periodic and postsubmit jobs live here
   103  │   └── other_job_name   # contains all the builds of a job
   104  │       └── build_number # contains job artifacts, as above
   105  └── pr-logs
   106      ├── directory                # symlinks for builds live here
   107      │   └── job_name             # contains all symlinks for a job
   108      │       └── build_number.txt # contains one line: location of artifacts for the build
   109      └── pull
   110          ├── batch                # batch jobs live here
   111          │   └── job_name         # contains all the builds of a job
   112          │       └── build_number # contains job artifacts, as above
   113          └── org_repo                 # jobs testing PRs for org/repo live here
   114              └── pull_number          # jobs running for a PR with pull_number live here
   115                  └── job_name         # all builds for the job for this pr live here
   116                      └── build_number # contains job artifacts, as above
   117  ```