From 6988fd29e1ac52a7e0e18533947f0f618976a8c9 Mon Sep 17 00:00:00 2001 From: Evan Baker Date: Tue, 12 Mar 2024 12:47:41 -0700 Subject: [PATCH] docs: fix broken links and markdown lints (#22) Signed-off-by: Evan Baker --- SECURITY.md | 18 +++++++++--------- SUPPORT.md | 8 +++----- deploy/grafana/dashboards/README.md | 2 ++ docs/captures/readme.md | 1 + docs/installation/grafana.md | 1 + docs/installation/prometheus-azure-managed.md | 2 +- docs/installation/prometheus-unmanaged.md | 2 +- docs/installation/setup.md | 1 + docs/intro.md | 3 +++ docs/metrics/advanced.md | 11 +++++++++++ docs/metrics/annotations.md | 1 + docs/metrics/basic.md | 13 +++++++++++++ docs/metrics/configuration.md | 1 + docs/metrics/plugins/linuxutil.md | 1 + docs/metrics/plugins/packetparser.md | 3 +++ docs/troubleshooting/basic-metrics.md | 2 +- site/README.md | 1 + 17 files changed, 54 insertions(+), 17 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b3c89efc8..d49d89e44 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ -## 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 [secure@microsoft.com](mailto:secure@microsoft.com). 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 index 2b2b9180b..4e1a42485 100644 --- 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 index 529e2ffe3..1dfbae4b4 100644 --- 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 index 04a699fff..557f7c8e5 100644 --- 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 index da3fecfec..127e11cda 100644 --- 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 index 214e07b39..ca5122c5a 100644 --- 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 index 490dc97d1..bf0edef23 100644 --- 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 index f7fccbc70..fe41a730f 100644 --- 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 index 2d9521ec7..fa96c47d9 100644 --- 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 index db4fb6f85..581a93659 100644 --- 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 index a8d41a4f8..5d635eafc 100644 --- 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 index 9c99a7dfc..d2568ec45 100644 --- 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 index 5574a574b..016772ae3 100644 --- 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 index 296487ee1..cbc7e266a 100644 --- 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 index 3e35c58eb..4df9ea24c 100644 --- 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 index 10a1b2742..8eca16511 100644 --- 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 index ff7cb7edb..ff9dd0e6a 100644 --- 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 ```