OSM Health

osm-health is a CLI tool for troubleshooting issues with Open Service Mesh. It can be used to:

  • Gather diagnostic information on the state of the control plane and the mesh components
  • Ensure that everything is running as expected
  • Triage the state of the mesh when an issue is encountered

Get started

  1. Clone the repo

  2. Checkout the tag for the latest release. For example:

    git checkout v0.0.1
  3. From root, build the binary

    make build-osm-health
  4. Add it to your $PATH to get started. For example:

    sudo cp ./bin/osm-health /usr/local/bin/osm-health

You can now use the CLI with:

osm-health <command>


To check the status of the osm control plane, run:

osm-health control-plane status

osm-health can check the connectivity between two pods by running a series of diagnostic checks on the meshed namespaces and pods, Envoy, SMI policies and core OSM control plane components. To run these checks, use:

osm-health connectivity pod-to-pod <SOURCE_POD> <DESTINATION_POD>


A command runs a series of checks associated with that command.

Each check can return one of 4 outcomes:

  1. Pass: indicates the check was successful and its result was as expected

  2. Fail: indicates the check failed and returns the error that could be causing the failure. Failed checks highlight components that could require further investigation

  3. Info: this is returned when the check is not generally expected to pass or fail, but rather the purpose of the check is to simply provide information to the user. An info check prints out general diagnostic information generated by the check.

    For example, when SMI TrafficTarget checks are run, they may return an info outcome that says that permissive traffic policy mode is enabled, so SMI access policies do not apply. Such an outcome cannot be categorized as a pass or a fail outcome because it is not an unexpected behavior

  4. Unknown: this indicates the check could not come to a clear conclusion