From d4b50bc59bae16fb978f588e21e936277fb9d91e Mon Sep 17 00:00:00 2001 From: Mahe Tardy Date: Tue, 11 Jul 2023 11:57:45 +0200 Subject: [PATCH] docs: reorganize the doc by creating new use cases section Signed-off-by: Mahe Tardy --- .../docs/concepts/generic-tracing/_index.md | 26 ------------------- .../en/docs/contribution-guide/_index.md | 2 +- docs/content/en/docs/faq/_index.md | 2 +- .../getting-started/try-tetragon-linux.md | 4 +-- docs/content/en/docs/reference/_index.md | 2 +- docs/content/en/docs/resources/_index.md | 2 +- docs/content/en/docs/use-cases/_index.md | 17 ++++++++++++ .../file-access.md | 4 +-- .../linux-process-credentials/_index.md | 8 +++--- .../linux-process-credentials/syscalls.md} | 2 +- .../network-observability.md | 6 ++--- .../process-lifecycle/_index.md | 2 +- .../process-lifecycle/privileged-execution.md | 4 +-- .../process-lifecycle/process-execution.md} | 2 +- 14 files changed, 37 insertions(+), 46 deletions(-) delete mode 100644 docs/content/en/docs/concepts/generic-tracing/_index.md create mode 100644 docs/content/en/docs/use-cases/_index.md rename docs/content/en/docs/{concepts/generic-tracing => use-cases}/file-access.md (99%) rename docs/content/en/docs/{concepts/generic-tracing => use-cases}/linux-process-credentials/_index.md (95%) rename docs/content/en/docs/{concepts/generic-tracing/linux-process-credentials/syscalls-monitoring.md => use-cases/linux-process-credentials/syscalls.md} (99%) rename docs/content/en/docs/{concepts/generic-tracing => use-cases}/network-observability.md (94%) rename docs/content/en/docs/{concepts => use-cases}/process-lifecycle/_index.md (98%) rename docs/content/en/docs/{concepts => use-cases}/process-lifecycle/privileged-execution.md (97%) rename docs/content/en/docs/{concepts/process-lifecycle/monitoring-process-execution.md => use-cases/process-lifecycle/process-execution.md} (99%) diff --git a/docs/content/en/docs/concepts/generic-tracing/_index.md b/docs/content/en/docs/concepts/generic-tracing/_index.md deleted file mode 100644 index 2c5ef704a64..00000000000 --- a/docs/content/en/docs/concepts/generic-tracing/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Generic tracing" -weight: 2 -icon: "reference" -description: "Tetragon can observe tracepoints and arbitrary kernel calls via kprobes" ---- - -For more advanced use cases, Tetragon can observe tracepoints and arbitrary -kernel calls via kprobes. For that, Tetragon must be extended and configured -with custom resources objects named TracingPolicy. It can then generates -`process_tracepoint` and `process_kprobes` events. - -TracingPolicy is a user-configurable Kubernetes custom resource that allows -users to trace arbitrary events in the kernel and optionally define actions to -take on a match. For example, a Sigkill signal can be sent to the process or -the return value of a system call can be overridden. - -For bare metal or VM use cases without Kubernetes, the same YAML configuration -can be passed via the `--tracing-policy` flag to the Tetragon binary or via the -`tetra` CLI to load the policies via gRPC. - -## What's next - -For more information on TracingPolicy and how to write them, see the -[documentation on TracingPolicy]({{< ref "docs/concepts/tracing-policy" >}}). - diff --git a/docs/content/en/docs/contribution-guide/_index.md b/docs/content/en/docs/contribution-guide/_index.md index af22604dc4a..8652197fb42 100644 --- a/docs/content/en/docs/contribution-guide/_index.md +++ b/docs/content/en/docs/contribution-guide/_index.md @@ -1,7 +1,7 @@ --- title: "Contribution Guide" linkTitle: "Contribution Guide" -weight: 6 +weight: 7 icon: "contribution" description: > How to contribute to the project diff --git a/docs/content/en/docs/faq/_index.md b/docs/content/en/docs/faq/_index.md index 9ef6cd5ff04..324b18ae4b0 100644 --- a/docs/content/en/docs/faq/_index.md +++ b/docs/content/en/docs/faq/_index.md @@ -1,6 +1,6 @@ --- title: "FAQ" -weight: 7 +weight: 8 icon: "faq" description: "List of frequently asked questions" --- diff --git a/docs/content/en/docs/getting-started/try-tetragon-linux.md b/docs/content/en/docs/getting-started/try-tetragon-linux.md index 7ec111db635..308ce8bdea0 100644 --- a/docs/content/en/docs/getting-started/try-tetragon-linux.md +++ b/docs/content/en/docs/getting-started/try-tetragon-linux.md @@ -57,7 +57,7 @@ Let's break down the previous command: ## Observe Tetragon base events With this default configuration, Tetragon already loaded its base sensors to -perform [process lifecycle observability]({{< ref "docs/concepts/process-lifecycle" >}}). +perform [process lifecycle observability]({{< ref "docs/use-cases/process-lifecycle" >}}). To quickly see the events, you can use the `tetra` CLI already shipped in the Tetragon container that was just started, it will connect to the Tetragon gRPC @@ -395,4 +395,4 @@ file using `cat ./tracing_policy.yaml` will bypass the policies presented here. - Try Tetragon in [Kubernetes environments]({{< ref "docs/getting-started/kubernetes-quickstart-guide" >}}). - Learn more about [TracingPolicy]({{< ref "docs/concepts/tracing-policy" >}}). -- See more use cases for observability in the [Concepts section]({{< ref "docs/concepts" >}}). +- See more use cases for observability in the [Use cases section]({{< ref "docs/use-cases" >}}). diff --git a/docs/content/en/docs/reference/_index.md b/docs/content/en/docs/reference/_index.md index 2106b5d185c..bd9221eccd1 100644 --- a/docs/content/en/docs/reference/_index.md +++ b/docs/content/en/docs/reference/_index.md @@ -1,7 +1,7 @@ --- title: "Reference" linkTitle: "Reference" -weight: 4 +weight: 6 icon: "reference" description: > Low level reference documentation for Tetragon diff --git a/docs/content/en/docs/resources/_index.md b/docs/content/en/docs/resources/_index.md index 09e314caabc..81b3418a742 100644 --- a/docs/content/en/docs/resources/_index.md +++ b/docs/content/en/docs/resources/_index.md @@ -1,6 +1,6 @@ --- title: "Resources" -weight: 8 +weight: 9 icon: "resources" description: "Additional resources to learn about Tetragon" --- diff --git a/docs/content/en/docs/use-cases/_index.md b/docs/content/en/docs/use-cases/_index.md new file mode 100644 index 00000000000..91c4eb86a29 --- /dev/null +++ b/docs/content/en/docs/use-cases/_index.md @@ -0,0 +1,17 @@ +--- +title: "Use Cases" +icon: "resources" +weight: 4 +description: > + This section presents various use cases on process, files, network and + security monitoring and enforcement. +--- + +By default, Tetragon monitors process lifecycle, learn more about that in the +[dedicated use cases]({{< ref "/docs/use-cases/process-lifecycle/" >}}). + +For more advanced use cases, Tetragon can observe tracepoints and arbitrary +kernel calls via kprobes. For that, Tetragon must be extended and configured +with custom resources objects named [TracingPolicy]({{< ref "/docs/concepts/tracing-policy" >}}). +It can then generates `process_tracepoint` and `process_kprobes` events. + diff --git a/docs/content/en/docs/concepts/generic-tracing/file-access.md b/docs/content/en/docs/use-cases/file-access.md similarity index 99% rename from docs/content/en/docs/concepts/generic-tracing/file-access.md rename to docs/content/en/docs/use-cases/file-access.md index c1d9684b0cf..a0f657e1a44 100644 --- a/docs/content/en/docs/concepts/generic-tracing/file-access.md +++ b/docs/content/en/docs/use-cases/file-access.md @@ -1,6 +1,6 @@ --- -title: "Use case: file access" -weight: 1 +title: "File access" +weight: 2 icon: "overview" description: "Monitor file access using kprobe hooks" --- diff --git a/docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/_index.md b/docs/content/en/docs/use-cases/linux-process-credentials/_index.md similarity index 95% rename from docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/_index.md rename to docs/content/en/docs/use-cases/linux-process-credentials/_index.md index 60fd914faae..9b82108604a 100644 --- a/docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/_index.md +++ b/docs/content/en/docs/use-cases/linux-process-credentials/_index.md @@ -1,8 +1,8 @@ --- -title: "Linux Process Credentials" -weight: 3 -icon: "reference" -description: "Monitor Linux Process Credentials" +title: "Linux process credentials" +weight: 4 +icon: "overview" +description: "Monitor Linux process credentials" --- On Linux each process has various associated user, group IDs, capabilities, diff --git a/docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/syscalls-monitoring.md b/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md similarity index 99% rename from docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/syscalls-monitoring.md rename to docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md index 4eaacfdb65a..c3ef7bd5f2e 100644 --- a/docs/content/en/docs/concepts/generic-tracing/linux-process-credentials/syscalls-monitoring.md +++ b/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md @@ -1,5 +1,5 @@ --- -title: "Use case: Monitor change Credentials system calls" +title: "Credentials change system calls" weight: 2 icon: "reference" description: "Monitor change Credentials System calls" diff --git a/docs/content/en/docs/concepts/generic-tracing/network-observability.md b/docs/content/en/docs/use-cases/network-observability.md similarity index 94% rename from docs/content/en/docs/concepts/generic-tracing/network-observability.md rename to docs/content/en/docs/use-cases/network-observability.md index a6fed5e50e5..22a6c1b80ce 100644 --- a/docs/content/en/docs/concepts/generic-tracing/network-observability.md +++ b/docs/content/en/docs/use-cases/network-observability.md @@ -1,7 +1,7 @@ --- -title: "Use case: network observability" -weight: 2 -icon: "reference" +title: "Network observability" +weight: 3 +icon: "overview" description: "Monitor TCP connect using kprobe hooks" --- diff --git a/docs/content/en/docs/concepts/process-lifecycle/_index.md b/docs/content/en/docs/use-cases/process-lifecycle/_index.md similarity index 98% rename from docs/content/en/docs/concepts/process-lifecycle/_index.md rename to docs/content/en/docs/use-cases/process-lifecycle/_index.md index a2bea9d869b..5a950eb2f1d 100644 --- a/docs/content/en/docs/concepts/process-lifecycle/_index.md +++ b/docs/content/en/docs/use-cases/process-lifecycle/_index.md @@ -2,7 +2,7 @@ title: "Process lifecycle" linkTitle: "Process lifecyle" weight: 1 -icon: "reference" +icon: "overview" description: "Tetragon observes by default the process lifecycle via exec and exit" --- diff --git a/docs/content/en/docs/concepts/process-lifecycle/privileged-execution.md b/docs/content/en/docs/use-cases/process-lifecycle/privileged-execution.md similarity index 97% rename from docs/content/en/docs/concepts/process-lifecycle/privileged-execution.md rename to docs/content/en/docs/use-cases/process-lifecycle/privileged-execution.md index e75455bcbef..9c063212aff 100644 --- a/docs/content/en/docs/concepts/process-lifecycle/privileged-execution.md +++ b/docs/content/en/docs/use-cases/process-lifecycle/privileged-execution.md @@ -1,7 +1,7 @@ --- -title: "Use case: privileged execution" +title: "Privileged execution" weight: 2 -icon: "reference" +icon: "overview" description: "Monitor process capabilities and kernel namespace access" --- diff --git a/docs/content/en/docs/concepts/process-lifecycle/monitoring-process-execution.md b/docs/content/en/docs/use-cases/process-lifecycle/process-execution.md similarity index 99% rename from docs/content/en/docs/concepts/process-lifecycle/monitoring-process-execution.md rename to docs/content/en/docs/use-cases/process-lifecycle/process-execution.md index 082fdabcd23..f6e91bd09ac 100644 --- a/docs/content/en/docs/concepts/process-lifecycle/monitoring-process-execution.md +++ b/docs/content/en/docs/use-cases/process-lifecycle/process-execution.md @@ -1,5 +1,5 @@ --- -title: "Use case: monitoring process execution" +title: "Process execution" weight: 1 icon: "overview" description: "Monitor process lifecycle with `process_exec` and `process_exit`"