Skip to content

ligato/vpp-probe

Repository files navigation

vpp-probe

GitHub Releases Docker Image Version


Intro

VPP-probe is a command-line tool for inspecting and monitoring of VPP instances running in any kind of environment (Kubernetes, Docker, Local). It aims to help during debugging of issues that occur in the distributed systems containing several VPP instances.

Features

  • Instance Discovery - discover VPP instances in the target system environment
  • Packet Tracing - trace packets from multiple VPP instances while executing arbitrary command
  • Command Execution - execute commands on multiple VPP instances at once
  • Topology Auto-Correlation - automatic correlation of connections across VPP instances

Install

You can get vpp-probe by downloading a pre-compiled binary, using the official Docker image or building it from source.

Download a pre-compiled binary

Go to GitHub Releases and download a binary pre-compiled for your system.

Get Docker image

Go to DockerHub Tags for list of available tags.

Prerequisites
# Pull the latest image
docker pull ligato/vpp-probe

# Print version
docker run --rm -it ligato/vpp-probe version

Build from source

Go to GitHub to get the source code.

Prerequisites

To install vpp-probe from source simply run:

# Clone the repository
git clone https://github.com/ligato/vpp-probe.git
# if you use git with ssh: git clone [email protected]:ligato/vpp-probe.git

# Install the latest version
go install go.ligato.io/vpp-probe@latest
# if you have Go 1.15 and older: GO111MODULE=on go get go.ligato.io/vpp-probe

# Print version
vpp-probe version

Quick Start

Where is your VPP running?

Kubernetes

Basic commands for VPP running in a Kubernetes pod

# Discover VPP instances in a cluster
vpp-probe --env=kube discover

# Execute a command on all VPP instances
vpp-probe --env=kube exec -- "vppctl show counters"

# Trace packets on all VPP instances for the duration of ping command
vpp-probe --env=kube trace "kubectl exec -it mypod -- ping -c 1 10.10.1.1"

Specify target cluster(s) (kubeconfig/context)

# Run on different cluster by providing custom kubeconfig and/or context
vpp-probe --kubeconfig="my.kubeconfig" <command>
vpp-probe --kubecontext="kind-2"       <command>

# Run on multiple clusters by adding another kubeconfig/context separated by comma
vpp-probe --kubeconfig="kubeconfig1,kubeconfig2" <command>
vpp-probe --kubecontext="kind-2,kind-3"          <command>

When running vpp-probe from Docker image

# Run from Docker image
docker run -it --net=host --volume "$HOME/.kube/config:/.kube/config" ligato/vpp-probe --env=kube <command>

Docker

Basic commands for VPP running in a Docker container

# Discover VPP instances in Docker
vpp-probe --env=docker discover

# Execute a command on all VPP instances
vpp-probe --env=docker exec -- "vppctl show counters"

# Trace packets on all VPP instances for the duration of ping command
vpp-probe --env=docker trace "docker exec -it mycontainer ping -c 1 172.17.0.3"

Specify a different Docker daemon

# Run on different docker host
vpp-probe --dockerhost="/var/run/docker2.sock" <command>

When running vpp-probe from Docker image

# Run from Docker image
docker run -it --net=host --volume "/var/run/docker.sock:/var/run/docker.sock" ligato/vpp-probe --env=docker <command>

💻 Host

Basic commands for VPP running locally on the host

# Discover VPP instances running as local process
vpp-probe --env=local discover

# Execute a command on all VPP instances
vpp-probe --env=local exec -- "vppctl show counters"

# Trace packets on all VPP instances for the duration of ping command
vpp-probe --env=local trace "ping -c 1 192.168.1.1"

When running vpp-probe from Docker image

# Run from Docker image
docker run -it --net=host --pid=host --volume "/run/vpp:/run/vpp" ligato/vpp-probe --env=local <command>

For more detailed usage information, read docs/USAGE.md

Testing

# Run integration tests
go test ./test/integration

# Run e2e tests
go test ./test/e2e

For more information about testing, read docs/TESTING.m

Development

Read docs/DEVELOP.md for information about vpp-probe development.