k8s.io/test-infra@v0.0.0-20240520184403-27c6b4c223d8/gubernator/README.md (about)

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