docs: fix broken links and markdown lints (#22)

Signed-off-by: Evan Baker <[email protected]>
microsoft · Mar 12, 2024 · 6988fd2 · 6988fd2
1 parent b64e6cb
commit 6988fd2
Show file tree

Hide file tree

Showing 17 changed files with 54 additions and 17 deletions.
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,6 +1,6 @@
 <!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->
 
-## Security
+# Security
 
 Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet) and [Xamarin](https://github.com/xamarin).
 
@@ -14,17 +14,17 @@ Instead, please report them to the Microsoft Security Response Center (MSRC) at
 
 If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp).
 
-You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
 
 Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
 
- * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
- * Full paths of source file(s) related to the manifestation of the issue
- * The location of the affected source code (tag/branch/commit or direct URL)
- * Any special configuration required to reproduce the issue
- * Step-by-step instructions to reproduce the issue
- * Proof-of-concept or exploit code (if possible)
- * Impact of the issue, including how an attacker might exploit the issue
+* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+* Full paths of source file(s) related to the manifestation of the issue
+* The location of the affected source code (tag/branch/commit or direct URL)
+* Any special configuration required to reproduce the issue
+* Step-by-step instructions to reproduce the issue
+* Proof-of-concept or exploit code (if possible)
+* Impact of the issue, including how an attacker might exploit the issue
 
 This information will help us triage your report more quickly.
 

diff --git a/SUPPORT.md b/SUPPORT.md
@@ -1,11 +1,9 @@
 # Support
 
-## How to file issues and get help 
+## How to file issues and get help
 
-This project uses GitHub Issues to track bugs and feature requests. Please search the existing 
-issues before filing new issues to avoid duplicates. For new issues, file your bug or 
-feature request as a new Issue.
+This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new Issue.
 
-## Microsoft Support Policy 
+## Microsoft Support Policy
 
 Support for this project is limited to the resources listed above.
diff --git a/deploy/grafana/dashboards/README.md b/deploy/grafana/dashboards/README.md
@@ -1 +1,3 @@
+# README
+
 Dashboards here are a copy of dashboards published in Retina organization on grafana.com
diff --git a/docs/captures/readme.md b/docs/captures/readme.md
@@ -9,6 +9,7 @@ Captures are on-demand and can be output to the host filesystem, a storage blob,
 ## Usage
 
 There are two methods for triggering a Capture:
+
 - [CLI command](#option-1-retina-cli) or
 - [CRD/YAML configuration](#option-2-capture-crd-custom-resource-definition).
 

diff --git a/docs/installation/grafana.md b/docs/installation/grafana.md
@@ -30,5 +30,6 @@ FIXME add published dashboard links
 ## Pre-Installed Dashboards
 
 If you're using [Azure-Hosted Prometheus/Grafana](prometheus-azure-managed.md), versions of these dashbaords are pre-installed under:
+
 - Dashboards > Managed Prometheus > Kubernetes / Networking / Clusters
 - Dashboards > Managed Prometheus > Kubernetes / Networking / DNS
diff --git a/docs/installation/prometheus-azure-managed.md b/docs/installation/prometheus-azure-managed.md
@@ -78,4 +78,4 @@
 
 ## Configuring Grafana
 
-In the Azure Portal, find your Grafana instance. Click on the Grafana Endpoint URL, then follow [Configuring Grafana](./configuring-grafana.md).
+In the Azure Portal, find your Grafana instance. Click on the Grafana Endpoint URL, then follow [Configuring Grafana](./grafana.md).
diff --git a/docs/installation/prometheus-unmanaged.md b/docs/installation/prometheus-unmanaged.md
@@ -74,4 +74,4 @@
 
 ## Configuring Grafana
 
-Create a Grafana instance at [grafana.com](https://www.grafana.com) and follow [Configuring Grafana](./configuring-grafana.md).
+Create a Grafana instance at [grafana.com](https://www.grafana.com) and follow [Configuring Grafana](./grafana.md).
diff --git a/docs/installation/setup.md b/docs/installation/setup.md
@@ -37,6 +37,7 @@ make helm-install-advanced-local-context
 ## Next Steps: Configuring Prometheus/Grafana
 
 Follow the guide relevant to your setup:
+
 - [Unmanaged Prometheus/Grafana](./prometheus-unmanaged.md)
 - [Azure-Hosted Prometheus/Grafana](./prometheus-azure-managed.md)
 

diff --git a/docs/intro.md b/docs/intro.md
@@ -24,6 +24,7 @@ Retina lets you **investigate network issues on-demand** and **continuously moni
 *Why can't my Pods connect to each other any more?* **Typical investigation is time-intensive** and involves performing packet captures, where one must identify the Nodes involved, gain access to each Node, run `tcpdump` commands, and export the results off of each Node.
 
 With Retina, you can **automate this process** with a **single CLI command** or CRD/YAML that can:
+
 - Run captures on all Nodes hosting the Pods of interest.
 - Upload each Node's results to a storage blob.
 
@@ -45,6 +46,7 @@ Retina uses two types of telemetry: metrics and captures.
 ### Metrics
 
 Retina metrics provide **continuous observability** into:
+
 - Incoming/outcoming traffic
 - Dropped packets
 - TCP/UDP
@@ -53,6 +55,7 @@ Retina metrics provide **continuous observability** into:
 - Node/interface statistics
 
 Retina provides both:
+
 - **Basic metrics** (default, Node-Level metrics) and
 - **Advanced/Pod-Level metrics** (if enabled).
 

diff --git a/docs/metrics/advanced.md b/docs/metrics/advanced.md
@@ -12,6 +12,7 @@ All metrics have the prefix `networkobservability_`.
 ## Universal Labels
 
 Node and Cluster metadata are included with the labels:
+
 - `cluster`
 - `instance` (Node name)
 
@@ -24,6 +25,7 @@ To customize context labels, see [MetricsConfiguration CRD](../CRDs/MetricsConfi
 ### Remote Context
 
 For Advanced mode with *remote context*, default context labels are the following:
+
 - `source_ip`
 - `source_namespace`
 - `source_pod`
@@ -36,12 +38,14 @@ For Advanced mode with *remote context*, default context labels are the followin
 ### Local Context
 
 For Advanced mode with *local context*, default context labels are the following for *outgoing* traffic:
+
 - `source_ip`
 - `source_namespace`
 - `source_pod`
 - `source_workload`
 
 For *incoming* traffic:
+
 - `destination_ip`
 - `destination_namespace`
 - `destination_pod`
@@ -65,13 +69,16 @@ Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration]
 | `adv_drop_bytes` | ***Advanced/Pod-Level***: dropped byte count | `direction`, `reason`, context labels |
 
 #### Label Values
+
 See [Context Labels](#context-labels).
 
 Possible values for `direction`:
+
 - `ingress` (incoming traffic)
 - `egress` (outgoing traffic)
 
 Possible values for `reason`:
+
 - `IPTABLE_RULE_DROP`
 - `IPTABLE_NAT_DROP`
 - `TCP_CONNECT_BASIC`
@@ -120,10 +127,12 @@ The metrics were born out of a real-life incident, where Node-to-API-server late
 See [Context Labels](#context-labels).
 
 Possible values for `direction`:
+
 - `ingress` (incoming traffic)
 - `egress` (outgoing traffic)
 
 Possible values for `flag`:
+
 - `FIN`
 - `SYN`
 - `RST`
@@ -135,6 +144,7 @@ Possible values for `flag`:
 - `NS`
 
 Possible values for `le` (for API server metrics). Units are in *milliseconds*. `le` stands for "less than or equal". See [Prometheus histogram documentation](https://prometheus.io/docs/concepts/metric_types/#histogram) for more info.
+
 - `0`
 - `0.5`
 - `1` through `4.5` in increments of 0.5
@@ -149,4 +159,5 @@ Metrics enabled when `tcpretrans` plugin is enabled (see [Metrics Configuration]
 | `adv_tcpretrans_count` | ***Advanced/Pod-Level***: TCP retransmitted packet count | context labels |
 
 #### Label Values
+
 See [Context Labels](#context-labels).
diff --git a/docs/metrics/annotations.md b/docs/metrics/annotations.md
@@ -4,6 +4,7 @@ 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).
 
 You can then add the annotation `retina.sh/v1alpha1: observe` to either:
+
 - individual Pods
 - Namespaces (to observe all the Pods in the namespace).
 

diff --git a/docs/metrics/basic.md b/docs/metrics/basic.md
@@ -9,6 +9,7 @@ All metrics have the prefix `networkobservability_`.
 ## Universal Labels
 
 All metrics include node and Cluster metadata with the labels:
+
 - `cluster`
 - `instance` (Node name)
 
@@ -26,6 +27,7 @@ Metrics enabled when `packetforward` plugin is enabled (see [Metrics Configurati
 #### Label Values
 
 Possible values for `direction`:
+
 - `ingress` (incoming traffic)
 - `egress` (outgoing traffic)
 
@@ -41,10 +43,12 @@ Metrics enabled when `dropreason` plugin is enabled (see [Metrics Configuration]
 #### Label Values
 
 Possible values for `direction`:
+
 - `ingress` (incoming traffic)
 - `egress` (outgoing traffic)
 
 Possible values for `reason`:
+
 - `IPTABLE_RULE_DROP`
 - `IPTABLE_NAT_DROP`
 - `TCP_CONNECT_BASIC`
@@ -69,6 +73,7 @@ Metrics enabled when `linuxutil` plugin is enabled (see [Metrics Configuration](
 #### Label Values
 
 Possible values for TCP `state`:
+
 - `UNKNOWN`
 - `ESTABLISHED`
 - `SYN_SENT`
@@ -83,21 +88,25 @@ Possible values for TCP `state`:
 - `CLOSING`
 
 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))
 
 Possible values for `statistic_name` (for metric `ip_connection_stats`):
+
 - `InNoECTPkts`
 - `InNoRoutes`
 - `InOctets`
 - `OutOctets`
 
 Possible values for `statistic_name` (for metric `udp_connection_stats`):
+
 - `ACTIVE` (currently active socket count)
 
 Possible values for `statistic_name` (for metric `interface_stats`):
+
 - `tx_packets`
 - `rx_packets`
 - `rx0_cache_full` (or `rx1_`, etc.)
@@ -133,14 +142,17 @@ Metrics enabled when `hnsstats` plugin is enabled (see [Metrics Configuration](.
 #### Label Values
 
 Possible values for `direction`:
+
 - `ingress` (incoming traffic)
 - `egress` (outgoing traffic)
 
 Possible values for `reason`:
+
 - `endpoint` (dropped by HNS endpoint)
 - `aclrule` (dropped by ACL firewall rule in VFP)
 
 Possible values for `statistic_name` (for metric `tcp_connection_stats`):
+
 - `ResetCount`
 - `ClosedFin`
 - `ResetSyn`
@@ -150,6 +162,7 @@ Possible values for `statistic_name` (for metric `tcp_connection_stats`):
 - `TimeWaitExpiredCount`
 
 Possible values for TCP `flag`:
+
 - `SYN`
 - `SYNACK`
 - `FIN`

diff --git a/docs/metrics/configuration.md b/docs/metrics/configuration.md
@@ -3,5 +3,6 @@
 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).
 
 Via [MetricsConfiguration CRD](../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/plugins/linuxutil.md b/docs/metrics/plugins/linuxutil.md
@@ -53,6 +53,7 @@ These are initialized in the linuxutil.go file.
 ## Label Values for `tcp_connection_stats`
 
 Below is a running list of all statistics for the metric `tcp_connection_stats`, captured from the `netstats` utility:
+
 - `DelayedACKLocked`
 - `DelayedACKLost`
 - `DelayedACKs`

diff --git a/docs/metrics/plugins/packetparser.md b/docs/metrics/plugins/packetparser.md
@@ -24,6 +24,7 @@ In Advanced mode (see [Metric Modes](../modes.md)), the plugin turns an eBPF res
 Code path: *pkg/module/metrics/forward.go*
 
 Metrics produced:
+
 - `adv_forward_count`
 - `adv_forward_bytes`
 
@@ -32,6 +33,7 @@ Metrics produced:
 Code path: *pkg/module/metrics/tcpflags.go*
 
 Metrics produced:
+
 - `adv_forward_count`
 - `adv_forward_bytes`
 
@@ -40,6 +42,7 @@ Metrics produced:
 Code path: *pkg/module/metrics/latency.go*
 
 Metrics produced:
+
 - `adv_node_apiserver_latency`
 - `adv_node_apiserver_no_response`
 - `adv_node_apiserver_tcp_handshake_latency`
diff --git a/docs/troubleshooting/basic-metrics.md b/docs/troubleshooting/basic-metrics.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-Basic metrics is covered by the [Metrics](../metrics/intro.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](../metrics/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/site/README.md b/site/README.md
@@ -15,6 +15,7 @@ To test, run `make docs` to spin up local webserver and view changes with hot re
 Install `yarn` (e.g. for Ubuntu, try [this guide](https://www.linuxcapable.com/how-to-install-yarn-on-ubuntu-linux/#install-yarn-on-ubuntu-2204-or-2004-via-nodesource)).
 
 In this directory (*retina/site/*), run:
+
 ```bash
 yarn
 ```