From 91f3263227ee22900e4ee157a52b50330457be3e Mon Sep 17 00:00:00 2001 From: Evan Baker Date: Tue, 12 Mar 2024 15:56:52 +0000 Subject: [PATCH] fix markdown lints 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/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 +++ site/README.md | 1 + 14 files changed, 51 insertions(+), 14 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b3c89efc85..d49d89e441 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 2b2b9180b8..4e1a424853 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 529e2ffe3e..1dfbae4b40 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 04a699ffff..557f7c8e53 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 da3fecfec0..127e11cda0 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/setup.md b/docs/installation/setup.md index f7fccbc70d..fe41a730f3 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 2d9521ec72..fa96c47d97 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 db4fb6f85c..581a936592 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 a8d41a4f8b..5d635eafc3 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 9c99a7dfcc..d2568ec45b 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 5574a574b6..016772ae3e 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 296487ee18..cbc7e266aa 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 3e35c58ebc..4df9ea24c6 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/site/README.md b/site/README.md index ff7cb7edb7..ff9dd0e6ac 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 ```