chore(docs): use autogenerate for site (#672)

# Description As title. Also rearranged some docs around. ## Related Issue If this pull request is related to any issue, please mention it here. Additionally, make sure that the issue is assigned to you before submitting this pull request. ## Checklist - [x] I have read the [contributing documentation](https://retina.sh/docs/contributing). - [x] I signed and signed-off the commits (`git commit -S -s ...`). See [this documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) on signing commits. - [x] I have correctly attributed the author(s) of the code. - [x] I have tested the changes locally. - [x] I have followed the project's style guidelines. - [x] I have updated the documentation, if necessary. - [x] I have added tests, if applicable. ## Screenshots (if applicable) or Testing Completed Please add any relevant screenshots or GIFs to showcase the changes made. ## Additional Notes Add any additional notes or context about the pull request here. --- Please refer to the [CONTRIBUTING.md](../CONTRIBUTING.md) file for more information on how to contribute to this project.
microsoft · Aug 27, 2024 · f77b2b4 · f77b2b4
1 parent df20875
commit f77b2b4
Show file tree

Hide file tree

Showing 55 changed files with 82 additions and 186 deletions.
diff --git a/docs/intro.md → docs/01-Intro.md b/docs/intro.md → docs/01-Intro.md
@@ -28,7 +28,7 @@ With Retina, you can **automate this process** with a **single CLI command** or
 - Run captures on all Nodes hosting the Pods of interest.
 - Upload each Node's results to a storage blob.
 
-To begin using the CLI, see [Quick Start Installation](./installation/cli.md).
+To begin using the CLI, see [Quick Start Installation](./02-Installation/02-CLI.md).
 
 ### Monitoring Network Health
 
@@ -59,13 +59,13 @@ Retina provides both:
 - **Basic metrics** (default, Node-Level metrics) and
 - **Advanced/Pod-Level metrics** (if enabled).
 
-For more info and a list of metrics, see [Metrics](metrics/modes.md).
+For more info and a list of metrics, see [Metrics](03-Metrics/modes/modes.md).
 
 ### Captures
 
 A Retina capture **logs network traffic** and metadata **for the specified Nodes/Pods**.
 
-Captures are **on-demand** and can be output to multiple destinations. For more info, see [Captures](captures/readme.md).
+Captures are **on-demand** and can be output to multiple destinations. For more info, see [Captures](04-Captures/readme.md).
 
 ## Extendable Architecture
 

diff --git a/docs/installation/setup.md → docs/02-Installation/01-Setup.md b/docs/installation/setup.md → docs/02-Installation/01-Setup.md
@@ -2,7 +2,7 @@
 
 Install the helm chart below for your scenario.
 
-Note: you can also run captures with just the [CLI](./cli.md).
+Note: you can also run captures with just the [CLI](./02-CLI.md).
 
 ## Installation
 
@@ -42,7 +42,7 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
 
 ### Advanced Mode with Remote Context (with Capture support)
 
-See [Metric Modes](../metrics/modes.md).
+See [Metric Modes](../03-Metrics/modes/modes.md).
 
 ```shell
 VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
@@ -64,7 +64,7 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
 
 ### Advanced Mode with Local Context (with Capture support)
 
-See [Metric Modes](../metrics/modes.md).
+See [Metric Modes](../03-Metrics/modes/modes.md).
 
 ```shell
 VERSION=$( curl -sL https://api.github.com/repos/microsoft/retina/releases/latest | jq -r .name)
@@ -86,4 +86,4 @@ helm upgrade --install retina oci://ghcr.io/microsoft/retina/charts/retina \
 
 ## Next Steps: Configuring Prometheus/Grafana
 
-- [Unmanaged Prometheus/Grafana](./prometheus-unmanaged.md)
+- [Unmanaged Prometheus/Grafana](./04-Grafana/prometheus-unmanaged.md)
diff --git a/docs/installation/cli.md → docs/02-Installation/02-CLI.md b/docs/installation/cli.md → docs/02-Installation/02-CLI.md
@@ -2,7 +2,7 @@
 
 Currently, Retina CLI supports Linux, Windows, and MacOS on x86_64 and ARM64 platforms.
 
-For CLI usage, see [Capture with Retina CLI](../captures/cli.md).
+For CLI usage, see [Capture with Retina CLI](../04-Captures/cli.md).
 
 ## Option 1: Install using Krew
 

diff --git a/docs/installation/config.md → docs/02-Installation/03-Config.md b/docs/installation/config.md → docs/02-Installation/03-Config.md
@@ -13,7 +13,7 @@ Defaults are specified for each component in *deploy/legacy/manifests/controller
 * `enabledPlugin_linux`: Array of enabled plugins for linux.
 * `enabledPlugin_win`: Array of enabled plugins for windows.
 * `metricsInterval`: the interval for which metrics will be gathered.
-* `dataAggregationLevel`: This config defines the level of data aggregation for Retina. See [Data Aggregation](../concepts/dataAggregation.md) for more details.
+* `dataAggregationLevel`: This config defines the level of data aggregation for Retina. See [Data Aggregation](../05-Concepts/data-aggregation.md) for more details.
 
 ## Operator Config
 

diff --git a/docs/installation/grafana.md → docs/02-Installation/04-Grafana/grafana.md b/docs/installation/grafana.md → docs/02-Installation/04-Grafana/grafana.md
@@ -12,17 +12,17 @@ Port-forward svc/prometheus-grafana to access from local browser.
 
 1. Check Grafana to make sure the managed Prometheus datasource exists:
 
-   ![alt text](img/portal-grafana.png)
+   ![alt text](../img/portal-grafana.png)
 
 2. Go to the dashboard page and select "import":
 
-   ![alt text](img/grafana-dashboard-import.png)
+   ![alt text](../img/grafana-dashboard-import.png)
 
 3. Import the [published dashboards](https://grafana.com/grafana/dashboards/) by ID [18814](https://grafana.com/grafana/dashboards/18814-kubernetes-networking-clusters/)
 
 4. The Grafana dashboard should now be visible.
 
-   ![alt text](img/grafana-dashboard.png)
+   ![alt text](../img/grafana-dashboard.png)
 
 ## Pre-Installed Dashboards
 

diff --git a/docs/installation/prometheus-unmanaged.md → ...lation/04-Grafana/prometheus-unmanaged.md b/docs/installation/prometheus-unmanaged.md → ...lation/04-Grafana/prometheus-unmanaged.md
@@ -4,7 +4,7 @@
 ## Pre-Requisites
 
 1. Create a Kubernetes cluster.
-2. Install Retina DaemonSet (see [Quick Installation](./setup.md)).
+2. Install Retina DaemonSet (see [Quick Installation](../01-Setup.md)).
 
 ## Configuring Prometheus
 
@@ -39,7 +39,7 @@ Note: Grafana and kube-state metrics may schedule on Windows nodes, the current
 
 7. Then go to [http://localhost:9090/targets](http://localhost:9090/targets) to see the Retina Pods being discovered and scraped:
 
-![alt text](img/prometheus-retina-pods.png)
+![alt text](../img/prometheus-retina-pods.png)
 
 ## Configuring Grafana
 
@@ -55,4 +55,4 @@ kubectl get secret -n kube-system prometheus-grafana -o jsonpath="{.data.admin-p
 
 10. Metrics should be visible:
 
-![alt text](img/grafana-dashboard-metrics.png)
+![alt text](../img/grafana-dashboard-metrics.png)
diff --git a/docs/unsorted/aks-setup.md → docs/02-Installation/aks-setup.md b/docs/unsorted/aks-setup.md → docs/02-Installation/aks-setup.md
diff --git a/...allation/img/grafana-dashboard-import.png → ...allation/img/grafana-dashboard-import.png b/...allation/img/grafana-dashboard-import.png → ...allation/img/grafana-dashboard-import.png
diff --git a/...llation/img/grafana-dashboard-metrics.png → ...llation/img/grafana-dashboard-metrics.png b/...llation/img/grafana-dashboard-metrics.png → ...llation/img/grafana-dashboard-metrics.png
diff --git a/docs/installation/img/grafana-dashboard.png → ...02-Installation/img/grafana-dashboard.png b/docs/installation/img/grafana-dashboard.png → ...02-Installation/img/grafana-dashboard.png
diff --git a/docs/installation/img/portal-grafana.png → docs/02-Installation/img/portal-grafana.png b/docs/installation/img/portal-grafana.png → docs/02-Installation/img/portal-grafana.png
diff --git a/...stallation/img/prometheus-retina-pods.png → ...stallation/img/prometheus-retina-pods.png b/...stallation/img/prometheus-retina-pods.png → ...stallation/img/prometheus-retina-pods.png
diff --git a/docs/installation/verify-signed-images.md → docs/02-Installation/verify-signed-images.md b/docs/installation/verify-signed-images.md → docs/02-Installation/verify-signed-images.md
diff --git a/docs/metrics/annotations.md → docs/03-Metrics/annotations.md b/docs/metrics/annotations.md → docs/03-Metrics/annotations.md
@@ -1,7 +1,7 @@
 # Annotations
 
 Annotations let you specify which Pods to observe (create metrics for).
-To configure this, specify `enableAnnotations=true` in Retina's [helm installation](../installation/setup.md) or [ConfigMap](../installation/config.md).
+To configure this, specify `enableAnnotations=true` in Retina's [helm installation](../02-Installation/01-Setup.md) or [ConfigMap](../02-Installation/03-Config.md).
 
 You can then add the annotation `retina.sh: observe` to either:
 

diff --git a/docs/metrics/configuration.md → docs/03-Metrics/configuration.md b/docs/metrics/configuration.md → docs/03-Metrics/configuration.md
@@ -1,8 +1,8 @@
 # Metrics Configuration
 
-You can enable/disable metrics by including/omitting their Plugin from `enabledPlugins` in either Retina's [helm installation](../installation/setup.md) or [ConfigMap](../installation/config.md).
+You can enable/disable metrics by including/omitting their Plugin from `enabledPlugins` in either Retina's [helm installation](../02-Installation/01-Setup.md) or [ConfigMap](../02-Installation/03-Config.md).
 
-Via [MetricsConfiguration CRD](../CRDs/MetricsConfiguration.md), you can further customize the following for your enabled plugins:
+Via [MetricsConfiguration CRD](../05-Concepts/CRDs/MetricsConfiguration.md), you can further customize the following for your enabled plugins:
 
 - Which metrics to include
 - Which metadata to include for a metric.
diff --git a/docs/metrics/advanced.md → docs/03-Metrics/modes/advanced.md b/docs/metrics/advanced.md → docs/03-Metrics/modes/advanced.md
@@ -3,7 +3,7 @@
 There are two Advanced modes (see [Metric Modes](./modes.md)) which include all [Basic Metrics](./basic.md) plus extra metrics providing Pod-Level context.
 
 The two Advanced modes are *remote context* and *local context*. The difference lies in the [Context Labels](#context-labels).
-Additionally, *local context* supports [Annotations](./annotations.md).
+Additionally, *local context* supports [Annotations](../annotations.md).
 
 ## Prefix
 
@@ -20,7 +20,7 @@ Node and Cluster metadata are included with the labels:
 
 There are Pod-Level context labels for metrics prepended with `adv_`.
 
-To customize context labels, see [MetricsConfiguration CRD](../CRDs/MetricsConfiguration.md).
+To customize context labels, see [MetricsConfiguration CRD](../../05-Concepts/CRDs/MetricsConfiguration.md).
 
 ### Remote Context
 
@@ -59,7 +59,7 @@ For *incoming* traffic:
 
 ### Plugin: `dropreason` (Linux)
 
-Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name             | Description                                    | Extra Labels          |
 | ----------------------- | ---------------------------------------------- | --------------------- |
@@ -93,7 +93,7 @@ Possible values for `reason`:
 
 ### Plugin: `dns` (Linux)
 
-Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name                  | Description                                                                                    | Extra Labels                                                                     |
 | ---------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
@@ -108,7 +108,7 @@ Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](./conf
 
 ### Plugin: `packetparser` (Linux)
 
-Metrics enabled when `packetparser` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `packetparser` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name                                | Description                                                                   | Extra Labels                |
 | ------------------------------------------ | ----------------------------------------------------------------------------- | --------------------------- |
@@ -152,7 +152,7 @@ Possible values for `le` (for API server metrics). Units are in *milliseconds*.
 
 ### Plugin: `tcpretrans` (Linux)
 
-Metrics enabled when `tcpretrans` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `tcpretrans` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name            | Description                                              | Extra Labels   |
 | ---------------------- | -------------------------------------------------------- | -------------- |

diff --git a/docs/metrics/basic.md → docs/03-Metrics/modes/basic.md b/docs/metrics/basic.md → docs/03-Metrics/modes/basic.md
@@ -1,3 +1,6 @@
+---
+sidebar_position: 2
+---
 # Basic Metrics
 
 These metrics are provided in all three modes (see [Metric Modes](./modes.md)).
@@ -17,7 +20,7 @@ All metrics include node and Cluster metadata with the labels:
 
 ### Plugin: `packetforward` (Linux)
 
-Metrics enabled when `packetforward` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `packetforward` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 |        Name             | Description              | Extra Labels  |
 | ----------------------- | -----------------------  | ------------- |
@@ -33,7 +36,7 @@ Possible values for `direction`:
 
 ### Plugin: `dropreason` (Linux)
 
-Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name             | Description              | Extra Labels          |
 | ----------------------- | ------------------------ | --------------------- |
@@ -59,7 +62,7 @@ Possible values for `reason`:
 
 ### Plugin: `linuxutil` (Linux)
 
-Metrics enabled when `linuxutil` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `linuxutil` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name             | Description                                                                     | Extra Labels                       |
 | ----------------------- | ------------------------------------------------------------------------------- | ---------------------------------- |
@@ -92,7 +95,7 @@ Possible values for `statistic_name` (for metric `tcp_connection_stats`):
 - `TCPTimeouts`
 - `TCPTSReorder`
 - `ResetCount`
-- and many others (full list [here](./plugins/linuxutil.md#label-values-for-tcp_connection_stats))
+- and many others (full list [here](../plugins/linuxutil.md#label-values-for-tcp_connection_stats))
 
 Possible values for `statistic_name` (for metric `ip_connection_stats`):
 
@@ -119,7 +122,7 @@ Possible values for `statistic_name` (for metric `interface_stats`):
 
 ### Plugin: `dns` (Linux)
 
-Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 | Metric Name                  | Description                                                      | Extra Labels                                                     |
 | ---------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- |
@@ -128,7 +131,7 @@ Metrics enabled when `dns` plugin is enabled (see [Metrics Configuration](./conf
 
 ### Plugin: `hnsstats` (Windows)
 
-Metrics enabled when `hnsstats` plugin is enabled (see [Metrics Configuration](./configuration.md)).
+Metrics enabled when `hnsstats` plugin is enabled (see [Metrics Configuration](../configuration.md)).
 
 |        Name             | Description                                   | Extra Labels          |
 | ----------------------- | ----------------------------------------------| --------------------- |

diff --git a/docs/metrics/modes.md → docs/03-Metrics/modes/modes.md b/docs/metrics/modes.md → docs/03-Metrics/modes/modes.md
@@ -1,3 +1,6 @@
+---
+sidebar_position: 1
+---
 # Metric Modes
 
 Retina provides **three modes** with their own metrics and scale capabilities.
@@ -8,9 +11,9 @@ The larger the cardinality, the more load induced on a Prometheus server for ins
 
 | Mode                                     | Description                                                                                                                                                                                                                        | Scale                                                                                                                                 | Metrics                          | Configuration                                                                                                |
 | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| *Basic*                                  | Metrics aggregated by Node.                                                                                                                                                                                                        | Metric cardinality proportional to number of nodes.                                                                                   | [Link to Metrics](./basic.md)    | [Link to Installation](../installation/setup.md#basic-mode)                                                  |
-| *Advanced/Pod-Level with remote context* | Basic metrics plus extra metrics aggregated by source and destination Pod.                                                                                                                                                         | Has scale limitations. Metric cardinality is unbounded (proportional to number of source/destination pairs, including external IPs).  | [Link to Metrics](./advanced.md) | [Link to Installation](../installation/setup.md#advanced-mode-with-remote-context-with-support-for-captures) |
-| *Advanced/Pod-Level with local context*  | Basic metrics plus extra metrics aggregated by "local" Pod (source for outgoing traffic, destination for incoming traffic). Also lets you specify which Pods to observe (create metrics for) with [Annotations](./annotations.md). | Designed for scale. Metric cardinality proportional to number of Pods observed.                                                       | [Link to Metrics](./advanced.md) | [Link to Installation](../installation/setup.md#advanced-mode-with-local-context-with-support-for-captures)  |
+| *Basic*                                  | Metrics aggregated by Node.                                                                                                                                                                                                        | Metric cardinality proportional to number of nodes.                                                                                   | [Link to Metrics](./basic.md)    | [Link to Installation](../../02-Installation/01-Setup.md#basic-mode)                                                  |
+| *Advanced/Pod-Level with remote context* | Basic metrics plus extra metrics aggregated by source and destination Pod.                                                                                                                                                         | Has scale limitations. Metric cardinality is unbounded (proportional to number of source/destination pairs, including external IPs).  | [Link to Metrics](./advanced.md) | [Link to Installation](../../02-Installation/01-Setup.md#advanced-mode-with-local-context-with-capture-support) |
+| *Advanced/Pod-Level with local context*  | Basic metrics plus extra metrics aggregated by "local" Pod (source for outgoing traffic, destination for incoming traffic). Also lets you specify which Pods to observe (create metrics for) with [Annotations](../annotations.md). | Designed for scale. Metric cardinality proportional to number of Pods observed.                                                       | [Link to Metrics](./advanced.md) | [Link to Installation](../../02-Installation/01-Setup.md#advanced-mode-with-local-context-with-capture-support)  |
 
 ## Where Do Metrics Come From?
 

diff --git a/docs/metrics/plugins/ciliumeventobserver.md → ...03-Metrics/plugins/ciliumeventobserver.md b/docs/metrics/plugins/ciliumeventobserver.md → ...03-Metrics/plugins/ciliumeventobserver.md
diff --git a/docs/metrics/plugins/dns.md → docs/03-Metrics/plugins/dns.md b/docs/metrics/plugins/dns.md → docs/03-Metrics/plugins/dns.md
@@ -4,7 +4,7 @@ Tracks incoming and outgoing DNS traffic, providing various metrics and details
 
 ## Metrics
 
-See metrics for [Basic Mode](../basic.md#plugin-dns-linux) or [Advanced Mode](../advanced.md#plugin-dns-linux).
+See metrics for [Basic Mode](../modes/basic.md#plugin-dns-linux) or [Advanced Mode](../modes/advanced.md#plugin-dns-linux).
 
 ## Architecture
 

diff --git a/docs/metrics/plugins/dropreason.md → docs/03-Metrics/plugins/dropreason.md b/docs/metrics/plugins/dropreason.md → docs/03-Metrics/plugins/dropreason.md
@@ -4,13 +4,13 @@ Counts number of packets/bytes dropped on a Node, along with the direction and r
 
 ## Metrics
 
-See metrics for [Basic Mode](../basic.md#plugin-dropreason-linux) or [Advanced Mode](../advanced.md#plugin-dropreason-linux).
+See metrics for [Basic Mode](../modes/basic.md#plugin-dropreason-linux) or [Advanced Mode](../modes/advanced.md#plugin-dropreason-linux).
 
 ## Architecture
 
 The plugin utilizes eBPF to gather data.
 The plugin generates Basic metrics from an eBPF result.
-In Advanced mode (see [Metric Modes](../modes.md)), the plugin turns this eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that a drops module can create extra Pod-Level metrics.
+In Advanced mode (see [Metric Modes](../modes/modes.md)), the plugin turns this eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that a drops module can create extra Pod-Level metrics.
 
 ### Code locations
 

diff --git a/docs/metrics/plugins/hnsstats.md → docs/03-Metrics/plugins/hnsstats.md b/docs/metrics/plugins/hnsstats.md → docs/03-Metrics/plugins/hnsstats.md
@@ -4,7 +4,7 @@ Gathers TCP statistics and counts number of packets/bytes forwarded or dropped i
 
 ## Metrics
 
-See metrics for [Basic Mode](../basic.md#plugin-hnsstats-windows) (Advanced modes have identical metrics).
+See metrics for [Basic Mode](../modes/basic.md#plugin-hnsstats-windows) (Advanced modes have identical metrics).
 
 ## Architecture
 

diff --git a/docs/metrics/plugins/infiniband.md → docs/03-Metrics/plugins/infiniband.md b/docs/metrics/plugins/infiniband.md → docs/03-Metrics/plugins/infiniband.md
diff --git a/docs/metrics/plugins/linuxutil.md → docs/03-Metrics/plugins/linuxutil.md b/docs/metrics/plugins/linuxutil.md → docs/03-Metrics/plugins/linuxutil.md
@@ -4,7 +4,7 @@ Gathers TCP/UDP statistics and network interface statistics from the `netstats`
 
 ## Metrics
 
-See metrics for [Basic Mode](../basic.md#plugin-linuxutil-linux) (Advanced modes have identical metrics).
+See metrics for [Basic Mode](../modes/basic.md#plugin-linuxutil-linux) (Advanced modes have identical metrics).
 
 ## Architecture
 

diff --git a/docs/metrics/plugins/packetforward.md → docs/03-Metrics/plugins/packetforward.md b/docs/metrics/plugins/packetforward.md → docs/03-Metrics/plugins/packetforward.md
@@ -4,7 +4,7 @@ Counts number of packets/bytes passing through the `eth0` interface of a Node, a
 
 ## Metrics
 
-See metrics for [Basic Mode](../basic.md#plugin-packetforward-linux) (Advanced modes have identical metrics).
+See metrics for [Basic Mode](../modes/basic.md#plugin-packetforward-linux) (Advanced modes have identical metrics).
 
 Note: `adv_forward_count` and `adv_forward_bytes` metrics are NOT associated with `packetforward` plugin despite similarities in name.
 These metrics are associated with [`packetparser` plugin](./packetparser.md).