github.com/google/syzkaller@v0.0.0-20251211124644-a066d2bc4b02/syz-cluster/README.md (about)

     1  `syz-cluster` is a distributed patch series fuzzing that is relying on syzkaller.
     2  It's deployed at https://ci.syzbot.org.
     3  
     4  ## Overview
     5  
     6  The system is to be deployed on a K8S cluster. The main services are:
     7  * `dashboard`: the web interface, read-only.
     8  * `controller`: manages the state of the system, provides
     9    [API](./pkg/api/client.go) for other components, schedules fuzzing sessions.
    10  * `series-tracker`: polls LKML git archives for the new series.
    11  * `reporter-server`: generates new reports, provides API for actual reporter
    12    implementations.
    13  * `email-reporter`: sends reports over email, handles incoming email commands.
    14  
    15  The actual patch processing is orchestrated by Argo Workflows: see [the
    16  template](./pkg/workflow/template.yaml). It relies on the following processing
    17  steps:
    18  * `workflow/triage-step`
    19  * `workflow/build-step`
    20  * `workflow/boot-step`
    21  * `workflow/fuzz-step`
    22  
    23  Triage and build steps need the actual kernel checkouts. The base kernel repo is
    24  hosted on a shared network disk and is regularly updated by the scripts in
    25  `kernel-disk`.
    26  
    27  The system can be deployed in multiple environments, which is achieved with the
    28  help of Kustomize. Depending on the actual deployment target, different pieces of
    29  configuration are applied:
    30  * `overlays/minikube`: the local dev environment.
    31  * `overlays/gke/staging`: the staging prod environment.
    32  * `overlays/gke/prod`: https://ci.syzbot.org.
    33  
    34  `global-config.yaml` is the main configuration file of the system - it
    35  determines the mailing lists to poll, configures resource usage and the actual
    36  reporting.
    37  
    38  ## Local installation steps
    39  
    40  1. Install and start minikube: https://minikube.sigs.k8s.io/docs/start/
    41  ```
    42  $ minikube start --cni=cilium
    43  ```
    44  
    45  `--cni=cilium` enables the use of a more advanced Network plugin that supports
    46  the emulation of network policies.
    47  
    48  2. Add a Spanner Add-on: https://minikube.sigs.k8s.io/docs/handbook/addons/cloud-spanner/
    49  ```
    50  $ minikube addons enable cloud-spanner
    51  ```
    52  3. Build all docker containers (might take a while):
    53  ```
    54  $ eval $(minikube docker-env)
    55  $ make build-all
    56  ```
    57  4. Deploy the cluster:
    58  ```
    59  $ make restart-spanner
    60  $ kubectl create namespace argo
    61  $ make k8s-config-argo | kubectl apply -f -
    62  $ make k8s-config-argo-wait
    63  $ make k8s-config-dev | kubectl apply -f -
    64  $ make migrate-job.yaml | kubectl create -f -
    65  ```
    66  5. Pre-fetch the kernel git repository:
    67  ```
    68  $ make fetch-kernels-once.yaml | kubectl create -f -
    69  ```
    70  
    71  Note that actual series processing won't start until the job created in (5)
    72  finishes.
    73  
    74  ## Developmental tips
    75  
    76  1. Install Argo Workflows client: https://github.com/argoproj/argo-workflows/releases
    77  
    78  Then you can use the `argo` tool like this:
    79  
    80  ```
    81  $ argo list
    82  ```
    83  
    84  2. Forward the dashboard port:
    85  
    86  ```
    87  $ kubectl port-forward service/web-dashboard-service --address 0.0.0.0 50123:80
    88  ```