Skip to content

Commit

Permalink
doc: document supported engines, improve w/ screenshots
Browse files Browse the repository at this point in the history
Signed-off-by: thediveo <[email protected]>
  • Loading branch information
thediveo committed Jan 9, 2024
1 parent c0c5936 commit 755dd66
Show file tree
Hide file tree
Showing 5 changed files with 35 additions and 17 deletions.
52 changes: 35 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@
![file descriptors](https://img.shields.io/badge/file%20descriptors-not%20leaking-success)
[![Go Report Card](https://goreportcard.com/badge/github.com/thediveo/lxkns)](https://goreportcard.com/report/github.com/thediveo/lxkns)

Discover how containers are using Linux kernel namespaces...

[![container namespaces](docs/_images/all-namespaces-with-containers-thumbnail.png)](docs/_images/all-namespaces-with-containers.png)

...or the mounts inside your containers, and how _over-mounts_ make other mounts
_invisible_.

[![container mounts](docs/_images/container-mounts-thumbnail.png)](docs/_images/container-mounts-containers.png)

## Quick Start

Expand All @@ -36,18 +44,18 @@ namespaces, as well as mount points with their hierarchies.
## Overview

`lxkns` discovers...
- Linux namespaces in almost every nook and cranny of your hosts (from open file
descriptors, bind-mounts, processes, and now even tasks and from open sockets)
– please see the table below,
- the mount points inside mount namespaces (correctly representing
- **Linux namespaces** in almost every nook and cranny of your hosts (from open
file descriptors, bind-mounts, processes, and now even tasks and from open
sockets) – please see the table below,
- the **mount points inside mount namespaces** (correctly representing
"overmounts").
- container workloads: these are then related to the underlying Linux
namespaces.
- **container workloads**: these are automatically related to the underlying
Linux namespaces.
- `lxkns` now leverages [(Siemens OSS) Turtlefinder
technology](https://github.com/siemens/turtlefinder) to autodetect container
engines even in hierarchical configurations, such as Kubernetes-in-Docker
and Docker Desktop on WSL2. Also, (socket-activated) podman detection has
finally landed in Turtlefinder, and in turn also in `lxkns`.
finally landed in turtlefinder, and in turn also in `lxkns`.


| | Where? | `lsns` | `lxkns` |
Expand All @@ -60,16 +68,6 @@ namespaces, as well as mount points with their hierarchies.
|| namespace hierarchy |||
|| owning user namespaces |||

The following container engine types are supported:
- Docker,
- plain containerd,
- CRI Evented PLEG: containerd, CRI-O,
- podman (via its Docker-compatible API only).

The `lxkns` discovery engine can be operated as a stand-alone REST service with
additional web UI. Alternatively, it can be embedded/integrated into other
system diagnosis tools.

For mount namespaces, lxkns finds mount points even in process-less mount
namespaces (for instance, as utilized in ["snap"
technology](https://snapcraft.io/docs)). Our discovery engine even determines
Expand All @@ -91,6 +89,26 @@ frontend:
[![lxkns web
app](https://img.youtube.com/vi/4e6_jGLM9JA/0.jpg)](https://www.youtube.com/watch?v=4e6_jGLM9JA)

## Detected/Supported Container Engines

The following container engine types are supported:
- [Docker](https://docker.com),
- plain [containerd](https://containerd.io/),
- via the [CRI Evented
PLEG API](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/3386-kubelet-evented-pleg/README.md):
[containerd](https://containerd.io/) and [CRI-O](https://cri-o.io/),
- [socket-activatable](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md)
[podman](https://podman.io/) – via the Docker-compatible API only. Please note
that there is no support for podman-proprietary pods (not to be confused with
Kubernetes pods).

## Deployment Options

The `lxkns` discovery engine can be operated as a stand-alone REST service with
additional web UI. Alternatively, it can be embedded/integrated into other
system diagnosis tools. A prominent example of embedding `lxkns` is
[@siemens/ghostwire](https://github.com/siemens/ghostwire).

## Notes

### Supported Go Versions
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/all-namespaces-with-containers.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/container-mounts-thumbnail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/container-mounts.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 755dd66

Please sign in to comment.