diff --git a/docs/intro.md b/docs/01-Intro.md similarity index 90% rename from docs/intro.md rename to docs/01-Intro.md index 0f8f1783e0..75840256fe 100644 --- a/docs/intro.md +++ b/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 b/docs/02-Installation/01-Setup.md similarity index 91% rename from docs/installation/setup.md rename to docs/02-Installation/01-Setup.md index d83960f750..208c338544 100644 --- a/docs/installation/setup.md +++ b/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 b/docs/02-Installation/02-CLI.md similarity index 93% rename from docs/installation/cli.md rename to docs/02-Installation/02-CLI.md index 613340497d..0d00540888 100644 --- a/docs/installation/cli.md +++ b/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 b/docs/02-Installation/03-Config.md similarity index 92% rename from docs/installation/config.md rename to docs/02-Installation/03-Config.md index ffd140df0b..ea54a032e8 100644 --- a/docs/installation/config.md +++ b/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 b/docs/02-Installation/04-Grafana/grafana.md similarity index 87% rename from docs/installation/grafana.md rename to docs/02-Installation/04-Grafana/grafana.md index 0ea730cea9..ccb7d216b9 100644 --- a/docs/installation/grafana.md +++ b/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 b/docs/02-Installation/04-Grafana/prometheus-unmanaged.md similarity index 92% rename from docs/installation/prometheus-unmanaged.md rename to docs/02-Installation/04-Grafana/prometheus-unmanaged.md index 33b6e52338..de0fb7200b 100644 --- a/docs/installation/prometheus-unmanaged.md +++ b/docs/02-Installation/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 b/docs/02-Installation/aks-setup.md similarity index 100% rename from docs/unsorted/aks-setup.md rename to docs/02-Installation/aks-setup.md diff --git a/docs/installation/img/grafana-dashboard-import.png b/docs/02-Installation/img/grafana-dashboard-import.png similarity index 100% rename from docs/installation/img/grafana-dashboard-import.png rename to docs/02-Installation/img/grafana-dashboard-import.png diff --git a/docs/installation/img/grafana-dashboard-metrics.png b/docs/02-Installation/img/grafana-dashboard-metrics.png similarity index 100% rename from docs/installation/img/grafana-dashboard-metrics.png rename to docs/02-Installation/img/grafana-dashboard-metrics.png diff --git a/docs/installation/img/grafana-dashboard.png b/docs/02-Installation/img/grafana-dashboard.png similarity index 100% rename from docs/installation/img/grafana-dashboard.png rename to docs/02-Installation/img/grafana-dashboard.png diff --git a/docs/installation/img/portal-grafana.png b/docs/02-Installation/img/portal-grafana.png similarity index 100% rename from docs/installation/img/portal-grafana.png rename to docs/02-Installation/img/portal-grafana.png diff --git a/docs/installation/img/prometheus-retina-pods.png b/docs/02-Installation/img/prometheus-retina-pods.png similarity index 100% rename from docs/installation/img/prometheus-retina-pods.png rename to docs/02-Installation/img/prometheus-retina-pods.png diff --git a/docs/installation/verify-signed-images.md b/docs/02-Installation/verify-signed-images.md similarity index 100% rename from docs/installation/verify-signed-images.md rename to docs/02-Installation/verify-signed-images.md diff --git a/docs/metrics/annotations.md b/docs/03-Metrics/annotations.md similarity index 78% rename from docs/metrics/annotations.md rename to docs/03-Metrics/annotations.md index ea7b0d3891..fa171020ea 100644 --- a/docs/metrics/annotations.md +++ b/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 b/docs/03-Metrics/configuration.md similarity index 50% rename from docs/metrics/configuration.md rename to docs/03-Metrics/configuration.md index 016772ae3e..d562a339fc 100644 --- a/docs/metrics/configuration.md +++ b/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 b/docs/03-Metrics/modes/advanced.md similarity index 95% rename from docs/metrics/advanced.md rename to docs/03-Metrics/modes/advanced.md index 581a936592..268f9ea6ae 100644 --- a/docs/metrics/advanced.md +++ b/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 b/docs/03-Metrics/modes/basic.md similarity index 94% rename from docs/metrics/basic.md rename to docs/03-Metrics/modes/basic.md index d2568ec45b..f4c38258fb 100644 --- a/docs/metrics/basic.md +++ b/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 b/docs/03-Metrics/modes/modes.md similarity index 81% rename from docs/metrics/modes.md rename to docs/03-Metrics/modes/modes.md index 87e16f6374..11eb3ac720 100644 --- a/docs/metrics/modes.md +++ b/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 b/docs/03-Metrics/plugins/ciliumeventobserver.md similarity index 100% rename from docs/metrics/plugins/ciliumeventobserver.md rename to docs/03-Metrics/plugins/ciliumeventobserver.md diff --git a/docs/metrics/plugins/dns.md b/docs/03-Metrics/plugins/dns.md similarity index 86% rename from docs/metrics/plugins/dns.md rename to docs/03-Metrics/plugins/dns.md index 4690c5db02..031438f982 100644 --- a/docs/metrics/plugins/dns.md +++ b/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 b/docs/03-Metrics/plugins/dropreason.md similarity index 81% rename from docs/metrics/plugins/dropreason.md rename to docs/03-Metrics/plugins/dropreason.md index f175a2c425..c5baad45e7 100644 --- a/docs/metrics/plugins/dropreason.md +++ b/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 b/docs/03-Metrics/plugins/hnsstats.md similarity index 75% rename from docs/metrics/plugins/hnsstats.md rename to docs/03-Metrics/plugins/hnsstats.md index fe4e1a66cc..2336678291 100644 --- a/docs/metrics/plugins/hnsstats.md +++ b/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 b/docs/03-Metrics/plugins/infiniband.md similarity index 100% rename from docs/metrics/plugins/infiniband.md rename to docs/03-Metrics/plugins/infiniband.md diff --git a/docs/metrics/plugins/linuxutil.md b/docs/03-Metrics/plugins/linuxutil.md similarity index 95% rename from docs/metrics/plugins/linuxutil.md rename to docs/03-Metrics/plugins/linuxutil.md index cbc7e266aa..2e16280d12 100644 --- a/docs/metrics/plugins/linuxutil.md +++ b/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 b/docs/03-Metrics/plugins/packetforward.md similarity index 82% rename from docs/metrics/plugins/packetforward.md rename to docs/03-Metrics/plugins/packetforward.md index f8e6d07a2b..df60170e03 100644 --- a/docs/metrics/plugins/packetforward.md +++ b/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). diff --git a/docs/metrics/plugins/packetparser.md b/docs/03-Metrics/plugins/packetparser.md similarity index 69% rename from docs/metrics/plugins/packetparser.md rename to docs/03-Metrics/plugins/packetparser.md index 4df9ea24c6..e22607919f 100644 --- a/docs/metrics/plugins/packetparser.md +++ b/docs/03-Metrics/plugins/packetparser.md @@ -4,13 +4,13 @@ Measures TCP packets passing through `eth0`, providing the ability to calculate ## Metrics -See metrics for [Advanced Mode](../advanced.md#plugin-packetparser-linux). For module information, see [below](#modules). +See metrics for [Advanced Mode](../modes/advanced.md#plugin-packetparser-linux). For module information, see [below](#modules). ## Architecture The plugin utilizes eBPF to gather data. The plugin does not generate Basic metrics. -In Advanced mode (see [Metric Modes](../modes.md)), the plugin turns an eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that *several modules* can create Pod-Level metrics. +In Advanced mode (see [Metric Modes](../modes/modes.md)), the plugin turns an eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that *several modules* can create Pod-Level metrics. ### Code locations diff --git a/docs/metrics/plugins/readme.md b/docs/03-Metrics/plugins/readme.md similarity index 63% rename from docs/metrics/plugins/readme.md rename to docs/03-Metrics/plugins/readme.md index b39ab61099..6149a56345 100644 --- a/docs/metrics/plugins/readme.md +++ b/docs/03-Metrics/plugins/readme.md @@ -6,10 +6,10 @@ See [Metrics Configuration](../configuration.md) for info on configuration. | Name | Description | Metrics in Basic Mode | Metrics in Advanced Mode | Development Guide | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------- | -| `packetforward` (Linux) | Counts number of packets/bytes passing through the `eth0` interface of a Node, along with the direction of the packets. | [Basic Mode](../basic.md#plugin-packetforward-linux) | Same metrics as Basic mode | [Dev Guide](./packetforward.md) | -| `dropreason` (Linux) | Counts number of packets/bytes dropped on a Node, along with the direction and reason for drop. | [Basic Mode](../basic.md#plugin-dropreason-linux) | [Advanced Mode](../advanced.md#plugin-dropreason-linux) | [Dev Guide](./dropreason.md) | -| `linuxutil` (Linux) | Gathers TCP/UDP statistics and network interface statistics from the `netstats` and `ethtool` Node utilities (respectively). | [Basic Mode](../basic.md#plugin-linuxutil-linux) | Same metrics as Basic mode | [Dev Guide](./linuxutil.md) | -| `dns` (Linux) | Counts DNS requests/responses by query, including error codes, response IPs, and other metadata. | [Basic Mode](../basic.md#plugin-dns-linux) | [Advanced Mode](../advanced.md#plugin-dns-linux) | [Dev Guide](./dns.md) | -| `hnstats` (Windows) | Gathers TCP statistics and counts number of packets/bytes forwarded or dropped in HNS and VFP. | [Basic Mode](../basic.md#plugin-hnsstats-windows) | Same metrics as Basic mode | [Dev Guide](./hnsstats.md) | -| `packetparser` (Linux) | Measures TCP packets passing through `eth0`, providing the ability to calculate TCP-handshake latencies, etc. | No basic metrics | [Advanced Mode](../advanced.md#plugin-packetparser-linux) | [Dev Guide](./packetparser.md) | +| `packetforward` (Linux) | Counts number of packets/bytes passing through the `eth0` interface of a Node, along with the direction of the packets. | [Basic Mode](../modes/basic.md#plugin-packetforward-linux) | Same metrics as Basic mode | [Dev Guide](./packetforward.md) | +| `dropreason` (Linux) | Counts number of packets/bytes dropped on a Node, along with the direction and reason for drop. | [Basic Mode](../modes/basic.md#plugin-dropreason-linux) | [Advanced Mode](../modes/advanced.md#plugin-dropreason-linux) | [Dev Guide](./dropreason.md) | +| `linuxutil` (Linux) | Gathers TCP/UDP statistics and network interface statistics from the `netstats` and `ethtool` Node utilities (respectively). | [Basic Mode](../modes/basic.md#plugin-linuxutil-linux) | Same metrics as Basic mode | [Dev Guide](./linuxutil.md) | +| `dns` (Linux) | Counts DNS requests/responses by query, including error codes, response IPs, and other metadata. | [Basic Mode](../modes/basic.md#plugin-dns-linux) | [Advanced Mode](../modes/advanced.md#plugin-dns-linux) | [Dev Guide](./dns.md) | +| `hnstats` (Windows) | Gathers TCP statistics and counts number of packets/bytes forwarded or dropped in HNS and VFP. | [Basic Mode](../modes/basic.md#plugin-hnsstats-windows) | Same metrics as Basic mode | [Dev Guide](./hnsstats.md) | +| `packetparser` (Linux) | Measures TCP packets passing through `eth0`, providing the ability to calculate TCP-handshake latencies, etc. | No basic metrics | [Advanced Mode](../modes/advanced.md#plugin-packetparser-linux) | [Dev Guide](./packetparser.md) | | `cilium` (Linux) | Collect agent and perf events from cilium via monitor1_2 socket and process flows in our hubble observer | [Metrics](./ciliumeventobserver.md#metrics) | Same metrics as Basic mode | [Dev Guide](./ciliumeventobserver.md) | diff --git a/docs/03-Metrics/plugins/tcpretrans.md b/docs/03-Metrics/plugins/tcpretrans.md new file mode 100644 index 0000000000..4bd1d8010e --- /dev/null +++ b/docs/03-Metrics/plugins/tcpretrans.md @@ -0,0 +1,18 @@ +# `tcpretrans` (Linux) + +Measures retransmitted TCP packets. + +## Metrics + +See metrics for [Advanced Mode](../modes/advanced.md#plugin-tcpretrans-linux). + +## Architecture + +The plugin utilizes eBPF to gather data. +The plugin does not generate Basic metrics. +In Advanced mode (see [Metric Modes](../modes/modes.md)), the plugin turns an eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that a tcpretrans module can create Pod-Level metrics. + +### Code locations + +- Plugin and eBPF code: *pkg/plugin/tcpretrans/* +- Module for extra Advanced metrics: *pkg/module/metrics/tcpretrans.go* diff --git a/docs/captures/cli.md b/docs/04-Captures/cli.md similarity index 98% rename from docs/captures/cli.md rename to docs/04-Captures/cli.md index 235bfc46c9..83a5a949f3 100644 --- a/docs/captures/cli.md +++ b/docs/04-Captures/cli.md @@ -2,7 +2,7 @@ Retina capture command allows the user to capture network traffic and metadata for the capture target, and then send the capture file to the location by Output Configuration. -Note: captures can also be performed with a [Capture CRD](../CRDs/Capture.md) after [installing Retina](../installation/setup.md) with capture support. +Note: captures can also be performed with a [Capture CRD](../05-Concepts/CRDs/Capture.md) after [installing Retina](../02-Installation/01-Setup.md) with capture support. ## Retina capture create diff --git a/docs/captures/img/capture-architecture-with-operator.png b/docs/04-Captures/img/capture-architecture-with-operator.png similarity index 100% rename from docs/captures/img/capture-architecture-with-operator.png rename to docs/04-Captures/img/capture-architecture-with-operator.png diff --git a/docs/captures/img/capture-architecture-without-operator.png b/docs/04-Captures/img/capture-architecture-without-operator.png similarity index 100% rename from docs/captures/img/capture-architecture-without-operator.png rename to docs/04-Captures/img/capture-architecture-without-operator.png diff --git a/docs/captures/img/capture-managed-storage-account.png b/docs/04-Captures/img/capture-managed-storage-account.png similarity index 100% rename from docs/captures/img/capture-managed-storage-account.png rename to docs/04-Captures/img/capture-managed-storage-account.png diff --git a/docs/captures/img/retina-release.png b/docs/04-Captures/img/retina-release.png similarity index 100% rename from docs/captures/img/retina-release.png rename to docs/04-Captures/img/retina-release.png diff --git a/docs/captures/managed-storage-account.md b/docs/04-Captures/managed-storage-account.md similarity index 100% rename from docs/captures/managed-storage-account.md rename to docs/04-Captures/managed-storage-account.md diff --git a/docs/captures/readme.md b/docs/04-Captures/readme.md similarity index 90% rename from docs/captures/readme.md rename to docs/04-Captures/readme.md index 5a3a1b1d5c..558590e7f9 100644 --- a/docs/captures/readme.md +++ b/docs/04-Captures/readme.md @@ -15,9 +15,9 @@ There are two methods for triggering a Capture: ### Option 1: Retina CLI -Available after [Installing Retina CLI](../installation/cli.md). +Available after [Installing Retina CLI](../02-Installation/02-CLI.md). -See [Capture Command](../captures/cli.md) for more details. +See [Capture Command](](../04-Captures/02-CLI.md) for more details. #### Example @@ -39,9 +39,9 @@ A random hashed name is assigned to each Retina Capture to uniquely label it. ### Option 2: Capture CRD (Custom Resource Definition) -Available after after [installing Retina](../installation/setup.md) with capture support. +Available after after [installing Retina](../02-Installation/01-Setup.md) with capture support. -See [Capture CRD](../CRDs/Capture.md) for more details. +See [Capture CRD](../05-Concepts/CRDs/Capture.md) for more details. #### Managed Storage Account diff --git a/docs/CRDs/Capture.md b/docs/05-Concepts/CRDs/Capture.md similarity index 97% rename from docs/CRDs/Capture.md rename to docs/05-Concepts/CRDs/Capture.md index 7cbf2410f2..4ebeabfca2 100644 --- a/docs/CRDs/Capture.md +++ b/docs/05-Concepts/CRDs/Capture.md @@ -5,7 +5,7 @@ The `Capture` CustomResourceDefinition (CRD) defines a custom resource called `Capture`, which represents the settings of a network trace. This CRD allows users to specify the configurations for capturing network packets and storing the captured data. -To use the `Capture` CRD, [install Retina](../installation/setup.md) with capture support. +To use the `Capture` CRD, [install Retina](../../02-Installation/01-Setup.md) with capture support. ## CRD Specification diff --git a/docs/CRDs/MetricsConfiguration.md b/docs/05-Concepts/CRDs/MetricsConfiguration.md similarity index 100% rename from docs/CRDs/MetricsConfiguration.md rename to docs/05-Concepts/CRDs/MetricsConfiguration.md diff --git a/docs/CRDs/RetinaEndpoint.md b/docs/05-Concepts/CRDs/RetinaEndpoint.md similarity index 100% rename from docs/CRDs/RetinaEndpoint.md rename to docs/05-Concepts/CRDs/RetinaEndpoint.md diff --git a/docs/concepts/dataAggregation.md b/docs/05-Concepts/data-aggregation.md similarity index 100% rename from docs/concepts/dataAggregation.md rename to docs/05-Concepts/data-aggregation.md diff --git a/docs/troubleshooting/basic-metrics.md b/docs/06-Troubleshooting/basic-metrics.md similarity index 97% rename from docs/troubleshooting/basic-metrics.md rename to docs/06-Troubleshooting/basic-metrics.md index aa9c8b700d..83e6fe054e 100644 --- a/docs/troubleshooting/basic-metrics.md +++ b/docs/06-Troubleshooting/basic-metrics.md @@ -2,7 +2,7 @@ ## Overview -Basic metrics is covered by the [Metrics](../metrics/basic.md) section of the Retina documentation. This guide is intended to help you troubleshoot issues with basic metrics. +Basic metrics is covered by the [Metrics](../03-Metrics/modes/basic.md) section of the Retina documentation. This guide is intended to help you troubleshoot issues with basic metrics. ## Metrics are not being generated or showing up in Grafana dashboards diff --git a/docs/troubleshooting/capture.md b/docs/06-Troubleshooting/capture.md similarity index 95% rename from docs/troubleshooting/capture.md rename to docs/06-Troubleshooting/capture.md index b7474f4de4..aa63370e82 100644 --- a/docs/troubleshooting/capture.md +++ b/docs/06-Troubleshooting/capture.md @@ -24,7 +24,7 @@ kubectl get pod -n --seletor job-name= ## Capture Pod ImagePullBackOff -By default, kubectl retina plugin will eventually create Capture Pods from the [GHCR](https://github.com/microsoft/retina) image with the same version as the kubectl plugin. If the kubectl plugin is built from a local environment, the GHCR image cannot be found. Check [capture CLI Debug Mode](../captures/cli.md#Debug_mode) for local development and testing. +By default, kubectl retina plugin will eventually create Capture Pods from the [GHCR](https://github.com/microsoft/retina) image with the same version as the kubectl plugin. If the kubectl plugin is built from a local environment, the GHCR image cannot be found. Check [capture CLI Debug Mode](](../04-Captures/02-CLI.md#Debug_mode) for local development and testing. ## Windows node allows only one capture job running at one time diff --git a/docs/troubleshooting/imgs/prom-retina-config.png b/docs/06-Troubleshooting/imgs/prom-retina-config.png similarity index 100% rename from docs/troubleshooting/imgs/prom-retina-config.png rename to docs/06-Troubleshooting/imgs/prom-retina-config.png diff --git a/docs/troubleshooting/imgs/prom-retina-service-discovery1.png b/docs/06-Troubleshooting/imgs/prom-retina-service-discovery1.png similarity index 100% rename from docs/troubleshooting/imgs/prom-retina-service-discovery1.png rename to docs/06-Troubleshooting/imgs/prom-retina-service-discovery1.png diff --git a/docs/troubleshooting/imgs/prom-retina-service-discovery2.png b/docs/06-Troubleshooting/imgs/prom-retina-service-discovery2.png similarity index 100% rename from docs/troubleshooting/imgs/prom-retina-service-discovery2.png rename to docs/06-Troubleshooting/imgs/prom-retina-service-discovery2.png diff --git a/docs/troubleshooting/imgs/prometheus-retina-targets.png b/docs/06-Troubleshooting/imgs/prometheus-retina-targets.png similarity index 100% rename from docs/troubleshooting/imgs/prometheus-retina-targets.png rename to docs/06-Troubleshooting/imgs/prometheus-retina-targets.png diff --git a/docs/contributing/developing.md b/docs/07-Contributing/developing.md similarity index 100% rename from docs/contributing/developing.md rename to docs/07-Contributing/developing.md diff --git a/docs/contributing/readme.md b/docs/07-Contributing/readme.md similarity index 100% rename from docs/contributing/readme.md rename to docs/07-Contributing/readme.md diff --git a/docs/metrics/_category_.json b/docs/metrics/_category_.json deleted file mode 100644 index 16a6dd251c..0000000000 --- a/docs/metrics/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Metrics", - "position": 2, - "link": { - "type": "generated-index", - "description": "Currently supported Retina plugins." - } -} diff --git a/docs/metrics/plugins/_category_.json b/docs/metrics/plugins/_category_.json deleted file mode 100644 index 862399be14..0000000000 --- a/docs/metrics/plugins/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Plugins", - "position": 4, - "link": { - "type": "generated-index", - "description": "Currently supported Retina plugins." - } -} diff --git a/docs/metrics/plugins/tcpretrans.md b/docs/metrics/plugins/tcpretrans.md deleted file mode 100644 index d409a310b1..0000000000 --- a/docs/metrics/plugins/tcpretrans.md +++ /dev/null @@ -1,18 +0,0 @@ -# `tcpretrans` (Linux) - -Measures retransmitted TCP packets. - -## Metrics - -See metrics for [Advanced Mode](../advanced.md#plugin-tcpretrans-linux). - -## Architecture - -The plugin utilizes eBPF to gather data. -The plugin does not generate Basic metrics. -In Advanced mode (see [Metric Modes](../modes.md)), the plugin turns an eBPF result into an enriched `Flow` (adding Pod information based on IP), then sends the `Flow` to an external channel so that a tcpretrans module can create Pod-Level metrics. - -### Code locations - -- Plugin and eBPF code: *pkg/plugin/tcpretrans/* -- Module for extra Advanced metrics: *pkg/module/metrics/tcpretrans.go* diff --git a/docs/troubleshooting/_category_.json b/docs/troubleshooting/_category_.json deleted file mode 100644 index 0c201161a6..0000000000 --- a/docs/troubleshooting/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Troubleshooting", - "position": 4, - "link": { - "type": "generated-index", - "description": "Troubleshooting for Retina." - } -} diff --git a/docs/unsorted/README.md b/docs/unsorted/README.md deleted file mode 100644 index d972012f3f..0000000000 --- a/docs/unsorted/README.md +++ /dev/null @@ -1 +0,0 @@ -# Unsorted diff --git a/site/docusaurus.config.js b/site/docusaurus.config.js index afa0cd686d..54a39bd4fc 100644 --- a/site/docusaurus.config.js +++ b/site/docusaurus.config.js @@ -67,7 +67,7 @@ const config = { items: [ { type: 'doc', - docId: 'intro', + docId: 'Intro', position: 'left', label: 'Docs', }, diff --git a/site/sidebars.js b/site/sidebars.js index 5ed65d77e8..185043f56e 100644 --- a/site/sidebars.js +++ b/site/sidebars.js @@ -14,94 +14,9 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure - //tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // But you can create a sidebar manually - - tutorialSidebar: [ - 'intro', - { - type: 'category', - label: 'Quick Installation', - items: [ - 'installation/setup', - 'installation/prometheus-unmanaged', - 'installation/grafana', - 'installation/cli', - 'installation/config', - 'installation/verify-signed-images' - ], - }, - { - type: 'category', - label: 'Metrics', - items: [ - 'metrics/modes', - 'metrics/basic', - 'metrics/advanced', - 'metrics/configuration', - 'metrics/annotations', - { - type: 'category', - label: 'Plugins', - items: [ - 'metrics/plugins/readme', - 'metrics/plugins/packetforward', - 'metrics/plugins/dropreason', - 'metrics/plugins/linuxutil', - 'metrics/plugins/infiniband', - 'metrics/plugins/dns', - 'metrics/plugins/hnsstats', - 'metrics/plugins/packetparser', - 'metrics/plugins/tcpretrans', - `metrics/plugins/ciliumeventobserver`, - ], - }, - ], - }, - { - type: 'category', - label: 'Captures', - items: [ - 'captures/readme', - 'captures/cli', - 'captures/managed-storage-account', - ], - }, - { - type: 'category', - label: 'CRDs', - items: [ - 'CRDs/Capture', - 'CRDs/RetinaEndpoint', - 'CRDs/MetricsConfiguration', - ], - }, - { - type: 'category', - label: 'Concepts', - items: [ - 'concepts/dataAggregation', - ], - }, - { - type: 'category', - label: 'Troubleshooting Guides', - items: [ - 'troubleshooting/capture', - 'troubleshooting/basic-metrics', - ], - }, - { - type: 'category', - label: 'Contributing', - items: [ - 'contributing/readme', - 'contributing/developing', - ], - } - ], - }; module.exports = sidebars; diff --git a/site/src/pages/index.js b/site/src/pages/index.js index a0a249b0f4..fd2c4aa8af 100644 --- a/site/src/pages/index.js +++ b/site/src/pages/index.js @@ -17,7 +17,7 @@ function HomepageHeader() {
+ to="/docs/Intro"> Get Started