From 8fc0b1f98e1c5720eaf3caecb19f0168ea9f3cd8 Mon Sep 17 00:00:00 2001 From: Aleksandr Nogikh Date: Tue, 2 Dec 2025 11:57:31 +0100 Subject: syz-cluster: update README Include more details about the system. --- syz-cluster/README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) (limited to 'syz-cluster') diff --git a/syz-cluster/README.md b/syz-cluster/README.md index f4cd8168b..d87473942 100644 --- a/syz-cluster/README.md +++ b/syz-cluster/README.md @@ -1,3 +1,40 @@ +`syz-cluster` is a distributed patch series fuzzing that is relying on syzkaller. +It's deployed at https://ci.syzbot.org. + +## Overview + +The system is to be deployed on a K8S cluster. The main services are: +* `dashboard`: the web interface, read-only. +* `controller`: manages the state of the system, provides + [API](./pkg/api/client.go) for other components, schedules fuzzing sessions. +* `series-tracker`: polls LKML git archives for the new series. +* `reporter-server`: generates new reports, provides API for actual reporter + implementations. +* `email-reporter`: sends reports over email, handles incoming email commands. + +The actual patch processing is orchestrated by Argo Workflows: see [the +template](./pkg/workflow/template.yaml). It relies on the following processing +steps: +* `workflow/triage-step` +* `workflow/build-step` +* `workflow/boot-step` +* `workflow/fuzz-step` + +Triage and build steps need the actual kernel checkouts. The base kernel repo is +hosted on a shared network disk and is regularly updated by the scripts in +`kernel-disk`. + +The system can be deployed in multiple environments, which is achieved with the +help of Kustomize. Depending on the actual deployment target, different pieces of +configuration are applied: +* `overlays/minikube`: the local dev environment. +* `overlays/gke/staging`: the staging prod environment. +* `overlays/gke/prod`: https://ci.syzbot.org. + +`global-config.yaml` is the main configuration file of the system - it +determines the mailing lists to poll, configures resource usage and the actual +reporting. + ## Local installation steps 1. Install and start minikube: https://minikube.sigs.k8s.io/docs/start/ @@ -26,11 +63,14 @@ $ make k8s-config-argo-wait $ make k8s-config-dev | kubectl apply -f - $ make migrate-job.yaml | kubectl create -f - ``` -5. (Optional) Pre-fetch the kernel git repository: +5. Pre-fetch the kernel git repository: ``` $ make fetch-kernels-once.yaml | kubectl create -f - ``` +Note that actual series processing won't start until the job created in (5) +finishes. + ## Developmental tips 1. Install Argo Workflows client: https://github.com/argoproj/argo-workflows/releases -- cgit mrf-deployment