docs: add cleanup docs (#1368) (#1371)

Signed-off-by: Charles-Edouard Brétéché <[email protected]>
Co-authored-by: Charles-Edouard Brétéché <[email protected]>

testdata/e2e/examples/CATALOG.md

@@ -21,6 +21,7 @@
 - [delete-test](orphan/README.md)
 - [outputs](outputs/README.md)
 - [patch](patch/README.md)
+- [quick-start](quick-start/README.md)
 - [script-env](script-env/README.md)
 - [sleep](sleep/README.md)
 - [template](template/README.md)

testdata/e2e/examples/quick-start/README.md

@@ -0,0 +1,23 @@
+# Test: `quick-start`
+
+*No description*
+
+## Steps
+
+| # | Name | Bindings | Try | Catch | Finally |
+|:-:|---|:-:|:-:|:-:|:-:|
+| 1 | [step-1](#step-step-1) | 0 | 2 | 0 | 0 |
+
+### Step: `step-1`
+
+*No description*
+
+#### Try
+
+| # | Operation | Bindings | Outputs | Description |
+|:-:|---|:-:|:-:|---|
+| 1 | `apply` | 0 | 0 | *No description* |
+| 2 | `assert` | 0 | 0 | *No description* |
+
+---
+

testdata/e2e/examples/quick-start/chainsaw-test.yaml

@@ -0,0 +1,15 @@
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: quick-start
+spec:
+  steps:
+  - try:
+    # first operation: create the config map
+    - apply:
+        # file is relative to the test folder
+        file: configmap.yaml
+    # second operation: verify the config map exists and contains the expected data
+    - assert:
+        # file is relative to the test folder
+        file: configmap.yaml

testdata/e2e/examples/quick-start/configmap.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: chainsaw-quick-start
+data:
+  foo: bar

website/docs/quick-start/cleanup.md

@@ -0,0 +1,97 @@
+# Control your cleanup
+
+Unless configured differently, by default Chainsaw will **automatically remove the resources it created** after a test finishes.
+
+Cleanup happens in reverse order of creation (created last, cleaned up first).
+This is important, especially when the controller being tested makes use of `finalizers`.
+
+!!! tip "Overriding cleanup timeout"
+    Note that Chainsaw performs a blocking deletion, that is, it will wait until the resource is not present anymore in the cluster before proceeding with the next resource cleanup.
+
+## Timeout
+
+A global cleanup timeout can be defined at the configuration level or using command line flags.
+
+It can also be overridden on a per-test or per-step basis but not at the operation level.
+
+```yaml
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: example
+spec:
+  timeouts:
+    # cleanup timeout at the test level
+    cleanup: 30s
+  steps:
+  - timeouts:
+      # cleanup timeout at the step level
+      cleanup: 2m
+    try: ...
+```
+
+## Automatic cleanup
+
+After a test, every resource created by Chainsaw will be automatically deleted. This applies to `create` and `apply` operations.
+
+In the logs below we can see Chainsaw deletes the previously created resource:
+
+```
+    | 15:21:29 | quick-start | @setup   | CREATE    | OK    | v1/Namespace @ chainsaw-cute-cod
+    | 15:21:29 | quick-start | step-1   | TRY       | RUN   |
+    | 15:21:29 | quick-start | step-1   | APPLY     | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | CREATE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | APPLY     | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | ASSERT    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | ASSERT    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | TRY       | DONE  |
+    === step cleanup process start ===
+    | 15:21:29 | quick-start | step-1   | CLEANUP   | RUN   |
+    | 15:21:29 | quick-start | step-1   | DELETE    | RUN   | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | DELETE    | OK    | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | DELETE    | DONE  | v1/ConfigMap @ chainsaw-cute-cod/chainsaw-quick-start
+    | 15:21:29 | quick-start | step-1   | CLEANUP   | DONE  |
+    === step cleanup process end ===
+    === test cleanup process start ===
+    | 15:21:29 | quick-start | @cleanup | DELETE    | RUN   | v1/Namespace @ chainsaw-cute-cod
+    | 15:21:29 | quick-start | @cleanup | DELETE    | OK    | v1/Namespace @ chainsaw-cute-cod
+    | 15:21:34 | quick-start | @cleanup | DELETE    | DONE  | v1/Namespace @ chainsaw-cute-cod
+    === test cleanup process end ===
+```
+
+## Manual cleanup
+
+Under certain circumstances, automatic cleanup is not enough and we want to execute custom operations.
+
+Chainsaw allows registering cleanup operations that will be run after automatic cleanup.
+Custom cleanup operations live at the test step level:
+
+```yaml
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: example
+spec:
+  steps:
+    # this step will create a local cluster
+  - try:
+    - script:
+        timeout: 1m
+        content: |
+          kind create cluster --name dynamic --kubeconfig ./dynamic
+    # at cleanup time, we want to delete the local cluster we created
+    # and remove the associated kubeconfig
+    cleanup:
+    - script:
+        content: |
+          kind delete cluster --name dynamic
+    - script:
+        content: |
+          rm -f ./dynamic
+```
+
+## Next step
+
+At this point, we covered the main Chainsaw features.
+
+Look at the [next steps](./next-steps.md) section to find out what to do next.

website/docs/quick-start/timeouts.md

@@ -144,6 +144,4 @@ spec:
 
 ## Next step
 
-At this point, we covered the main Chainsaw features.
-
-Look at the [next steps](./next-steps.md) section to find out what to do next.
+In the next section, we will see how Chainsaw [manages cleanup](./cleanup.md).

website/mkdocs.base.yaml

@@ -107,12 +107,18 @@ markdown_extensions:
     emoji_index: !!python/name:material.extensions.emoji.twemoji
     emoji_generator: !!python/name:material.extensions.emoji.to_svg
 - admonition
-- codehilite
 - meta
+- md_in_html
 - toc:
     permalink: true
 - pymdownx.tabbed:
     alternate_style: true
+- pymdownx.highlight:
+    anchor_linenums: true
+    line_spans: __span
+    pygments_lang_class: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
 - pymdownx.superfences
 - pymdownx.tasklist:
     custom_checkbox: true

website/mkdocs.yaml

@@ -14,6 +14,7 @@ nav:
   - quick-start/operation-outputs.md
   - quick-start/try-catch.md
   - quick-start/timeouts.md
+  - quick-start/cleanup.md
   - quick-start/next-steps.md
   - Advanced use cases:
     - quick-start/advanced/index.md