From 2e43212720fed54d5dc8003962a2c8fb26aac24f Mon Sep 17 00:00:00 2001
From: Jop Zitman <jop.zitman@secura.com>
Date: Mon, 11 Oct 2021 17:14:37 +0200
Subject: [PATCH] Add hook priority docs

Signed-off-by: Jop Zitman <jop.zitman@secura.com>
---
 docs/api/crds/scan-completion-hook.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/api/crds/scan-completion-hook.md b/docs/api/crds/scan-completion-hook.md
index 7eb4dc6e..f6bfa2bf 100644
--- a/docs/api/crds/scan-completion-hook.md
+++ b/docs/api/crds/scan-completion-hook.md
@@ -20,6 +20,31 @@ The `type` field can be either `ReadOnly` or `ReadAndWrite`.
 
 `ReadAndWrite` hooks have the ability to update both the findings and raw scan reports. This can be used to attach additional metadata to the findings by comparing the findings to external inventory systems or APIs of cloud providers.
 
+### Priority (Optional)
+
+The `priority` field helps determine the execution order of the hook.
+Hooks with a higher priority will be scheduled before hooks with a lower priority.
+By default, hooks are given a priority of 0.
+Hooks with equal priority are scheduled according to the default schedule:
+
+1. Run ReadAndWrite hooks one by one (undefined order).
+2. Once all ReadAndWrite hooks are completed, ReadOnly hooks are scheduled in parallel.
+
+The following diagram shows an example run:
+
+```text
+                                 Priority 2                                          Priority 1                    Priority 0
+    +-------------------------------------------------------------------+     +----------------------+      +----------------------+
+    |    +--------------+       +--------------+       +--------------+ |     |    +--------------+  |      |    +--------------+  | 
+    | -> | ReadAndWrite |------>| ReadAndWrite |------>|   ReadOnly   | |     | -> |   ReadOnly   |  | ---> | -> | ReadAndWrite |  |
+    |    +--------------+       +--------------+  |    +--------------+ |     |    +--------------+  |      |    +--------------+  |
+--> |                                             |                     | --> |                      |      +----------------------+
+    |                                             |    +--------------+ |     |    +--------------+  |
+    |                                             +--->|   ReadOnly   | |     | -> |   ReadOnly   |  |
+    |                                                  +--------------+ |     |    +--------------+  |
+    +-----------+-------------------------------------------------------+     +----------------------+
+```
+
 ### Image (Required)
 
 The `image` field contains a container image reference for the image supposed to run as the hook.
@@ -53,6 +78,7 @@ metadata:
   name: elastic-persistence-hook
 spec:
   type: ReadOnly
+  priority: 2
   image: docker.io/securecodebox/persistence-elastic:latest
   imagePullSecrets:
   - name: image-pull-secret