From 8eba9ac94434e6aa011fe6f450f86a971fd99653 Mon Sep 17 00:00:00 2001 From: Joel Takvorian Date: Mon, 24 Mar 2025 14:50:02 +0100 Subject: [PATCH] README: getting started section with Krew - Put krew first (most people surely don't want to clone the repo in order to use the CLI) - For each "run" example, add a version with krew --- README.md | 125 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 100 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 92720f31..c9c95a5e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ network-observability-cli is a lightweight Flow, Packet and Metrics visualization tool. It deploys [NetObserv eBPF agent](https://github.com/netobserv/netobserv-ebpf-agent) on your k8s cluster to collect flows or packets from nodes network interfaces and streams data to a local collector for analysis and visualization. -Output files are generated under `output/flow` and `output/pcap` directories per host name +Output files are generated under `output/flow` and `output/pcap` directories per host name. On Openshift environments, you can also capture metrics in your monitoring stack and display a fully configured dashboard. @@ -14,40 +14,59 @@ To run this CLI, you will need: - either `oc` or `kubectl` command installed and connected to your cluster - Cluster admin rights -## Build +## Getting started with Krew -To build the project locally: +The CLI is available as a [Krew](https://krew.sigs.k8s.io/) plugin, which is the fastest way to get it up and running if you already use Krew. +If not, please refer to its [installation guide](https://krew.sigs.k8s.io/docs/user-guide/setup/install/). -### Install `shellcheck` package +To install the NetObserv CLI, run: ```bash -sudo dnf install -y shellcheck +kubectl krew install netobserv ``` -### Build the project +Or if you had an older version, to update it: ```bash -make build +kubectl krew update netobserv ``` -This will also copy resources and commands to the `build` directory. +Then, run it as a `kubectl` plugin, such as: -### Images +```bash +kubectl netobserv --version +# output example: +# Netobserv CLI version v0.0.8 +``` + +You can get detailed help using these commands: -To build your own images of CLI, run the following command replacing `USER` and `VERSION` accordingly: ```bash -USER=netobserv VERSION=dev make images +kubectl netobserv --help +kubectl netobserv flows --help +kubectl netobserv packets --help +kubectl netobserv metrics --help ``` ## Run ### Flow Capture -Run the following command to start capturing flows, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: +For instance, to capture all flows on the cluster that go through the `br-ex` network interface: -```bash -USER=netobserv VERSION=dev COMMAND_ARGS=--interfaces=br-ex make flows -``` +- As a `kubectl` plugin: + + ```bash + kubectl netobserv flows --interfaces=br-ex + ``` + +- Or from the repository `Makefile`: + + Run the following command to start capturing flows, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: + + ```bash + USER=netobserv VERSION=dev COMMAND_ARGS=--interfaces=br-ex make flows + ``` ![flows](./img/flow-table.png) @@ -106,11 +125,21 @@ or `dbeaver`: ### Packet Capture -Run the following command to start capturing packets, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: +For instance, to capture all TCP packets on the cluster that go through port 80: -```bash -USER=netobserv VERSION=dev COMMAND_ARGS="--protocol=TCP --port=80" make packets -``` +- As a `kubectl` plugin: + + ```bash + kubectl netobserv packets --protocol=TCP --port=80 + ``` + +- Or from the repository `Makefile`: + + Run the following command to start capturing packets, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: + + ```bash + USER=netobserv VERSION=dev COMMAND_ARGS="--protocol=TCP --port=80" make packets + ``` Similarly to flow capture, it will display a table view with latest flows. However, it will collect packets and write data under output/pcap directory. To stop capturing press Ctrl-C. @@ -119,12 +148,25 @@ This will write [pcapng](https://wiki.wireshark.org/Development/PcapNg) into a s ![wireshark](./img/wireshark.png) -### Metrics dashboard (OCP only) +We use the pcapng format to add contextual metadata, such as the k8s pods and service names. -Run the following command to start capturing metrics, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: -```bash -USER=netobserv VERSION=dev COMMAND_ARGS='--enable_pkt_drop --enable_dns --enable_rtt' make metrics -``` +### Metrics dashboard (OpenShift only) + +For instance, to capture many available metrics, including Packet drops, DNS stats and latenties: + +- As a `kubectl` plugin: + + ```bash + kubectl netobserv metrics --enable_pkt_drop --enable_dns --enable_rtt + ``` + +- Or from the repository `Makefile`: + + Run the following command to start capturing metrics, replacing `USER`, `VERSION` and `COMMAND_ARGS` accordingly: + + ```bash + USER=netobserv VERSION=dev COMMAND_ARGS='--enable_pkt_drop --enable_dns --enable_rtt' make metrics + ``` ![metrics](./img/metrics-dashboard.png) @@ -135,8 +177,41 @@ The url to access it is automatically generated from the CLI. Simply click on th The `cleanup` function will automatically remove the eBPF programs when the CLI exits. However you may need to run it manually if running in background or an error occurs. +- As a `kubectl` plugin: + + ```bash + kubectl netobserv cleanup + ``` + +- Or from the repository `Makefile`: + + ```bash + USER=netobserv VERSION=dev make cleanup + ``` + +## Build + +To build the project locally: + +### Install `shellcheck` package + ```bash -USER=netobserv VERSION=dev make cleanup +sudo dnf install -y shellcheck +``` + +### Build the project + +```bash +make build +``` + +This will also copy resources and commands to the `build` directory. + +### Images + +To build your own images of CLI, run the following command replacing `USER` and `VERSION` accordingly: +```bash +USER=netobserv VERSION=dev make images ``` ## Extending OpenShift or Kubernetes CLI with plugins