From feb61e03fa5ebc3f7f4c409c3c048988c10628c1 Mon Sep 17 00:00:00 2001 From: "gcp-cherry-pick-bot[bot]" <98988430+gcp-cherry-pick-bot[bot]@users.noreply.github.com> Date: Tue, 21 May 2024 18:03:36 +0200 Subject: [PATCH] docs: add cleanup docs (#1368) (#1371) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché Co-authored-by: Charles-Edouard Brétéché --- testdata/e2e/examples/CATALOG.md | 1 + testdata/e2e/examples/quick-start/README.md | 23 +++++ .../examples/quick-start/chainsaw-test.yaml | 15 +++ .../e2e/examples/quick-start/configmap.yaml | 6 ++ website/docs/quick-start/cleanup.md | 97 +++++++++++++++++++ website/docs/quick-start/timeouts.md | 4 +- website/mkdocs.base.yaml | 8 +- website/mkdocs.yaml | 1 + 8 files changed, 151 insertions(+), 4 deletions(-) create mode 100644 testdata/e2e/examples/quick-start/README.md create mode 100644 testdata/e2e/examples/quick-start/chainsaw-test.yaml create mode 100644 testdata/e2e/examples/quick-start/configmap.yaml create mode 100644 website/docs/quick-start/cleanup.md diff --git a/testdata/e2e/examples/CATALOG.md b/testdata/e2e/examples/CATALOG.md index fa88b7fa9..0232defac 100644 --- a/testdata/e2e/examples/CATALOG.md +++ b/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) diff --git a/testdata/e2e/examples/quick-start/README.md b/testdata/e2e/examples/quick-start/README.md new file mode 100644 index 000000000..faf256f1a --- /dev/null +++ b/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* | + +--- + diff --git a/testdata/e2e/examples/quick-start/chainsaw-test.yaml b/testdata/e2e/examples/quick-start/chainsaw-test.yaml new file mode 100644 index 000000000..a73214233 --- /dev/null +++ b/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 diff --git a/testdata/e2e/examples/quick-start/configmap.yaml b/testdata/e2e/examples/quick-start/configmap.yaml new file mode 100644 index 000000000..381941858 --- /dev/null +++ b/testdata/e2e/examples/quick-start/configmap.yaml @@ -0,0 +1,6 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: chainsaw-quick-start +data: + foo: bar diff --git a/website/docs/quick-start/cleanup.md b/website/docs/quick-start/cleanup.md new file mode 100644 index 000000000..c86a2e9a5 --- /dev/null +++ b/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. diff --git a/website/docs/quick-start/timeouts.md b/website/docs/quick-start/timeouts.md index bd03f718d..fa84ee76e 100644 --- a/website/docs/quick-start/timeouts.md +++ b/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). diff --git a/website/mkdocs.base.yaml b/website/mkdocs.base.yaml index 8c61c393b..04ed420ec 100644 --- a/website/mkdocs.base.yaml +++ b/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 diff --git a/website/mkdocs.yaml b/website/mkdocs.yaml index 21a345c3b..b6b12a77f 100644 --- a/website/mkdocs.yaml +++ b/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