leoverto/docker-network-graph

Quickly visualize docker networks with graphviz.

Docker Network Graph

Visualize the relationship between Docker networks and containers as a neat graphviz graph.

Example

Usage

usage: docker-net-graph.py [-h] [-v] [-o OUT]

Visualize docker networks.

optional arguments:
  -h, --help         show this help message and exit
  -v, --verbose      Verbose output
  -o OUT, --out OUT  Write output to file

In most cases what you want to run are the following couple commands:

git clone https://github.com/LeoVerto/docker-network-graph.git
cd docker-network-graph
pipenv install
pipenv run python docker-net-graph.py -o output.svg

This will generate an .svg file containing the graph.

Running inside docker

If you want to generate a graph for a remote system you can also easily run this script inside a pre-built docker container:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock leoverto/docker-network-graph

This will just generate and output the graph in the DOT Language. You can then paste that code into GraphvizOnline to render it. The recommended rendering engine is fdp.

Alternatively, if you prefer to render locally, you can run fdp -Tpng -o out.png on a system with graphviz installed, paste the previous output there, press enter and finally CTRL+C to generate the file.

For more advanced use cases you can append arguments to the docker run command as if you were running it in a local shell.

Development

If you'd like to contribute to this project, there is a sample docker-compose file using dummy containers in test.

You can deploy it using docker-compose -f test/docker-compose.yml up -d.

docker-network-graph's Issues

Exclude script container from graph

Detect if the script is running inside docker and if it is, exclude that container from the graph.

Add argument to automatically generate GraphvizOnline links

GraphvizOnline supports feeding graphs via a GET argument. Potentially this could be used to output a link that the user would just have to click to view the graph.

Use pre-generated colour palette

The current colour generation can result in some pretty ugly and dark colours. A pre-generated palette of around 20 colours could resolve this problem. Once the palette runs out the script can fall back to random colour generation.

Network aliases not shown

you can write something like this in docker-compose:

nginx:
    networks:
        webserver:
            aliases:
                - 'local.myapp'

It would be great to see the aliases per network (I currently have an issue using this and your tool might be very helpful !)

GraphViz not present in Docker image

When trying to render the dot output directly through the Docker image, it complaines about a missing dependency:

root@panda ~/.tmp # docker run --rm -v /var/run/docker.sock:/var/run/docker.sock:ro -v ${PWD}:/usr/src/app/.tmp leoverto/docker-network-graph -o .tmp/panda.svg                      
Traceback (most recent call last):
  File "/usr/local/lib/python3.9/site-packages/graphviz/backend.py", line 164, in run
    proc = subprocess.Popen(cmd, startupinfo=get_startupinfo(), **kwargs)
  File "/usr/local/lib/python3.9/subprocess.py", line 951, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "/usr/local/lib/python3.9/subprocess.py", line 1821, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'dot'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/src/app/docker-net-graph.py", line 211, in <module>
    generate_graph(args.verbose, args.out)
  File "/usr/src/app/docker-net-graph.py", line 193, in generate_graph
    g.render(base)
  File "/usr/local/lib/python3.9/site-packages/graphviz/files.py", line 243, in render
    rendered = backend.render(self._engine, format, filepath,
  File "/usr/local/lib/python3.9/site-packages/graphviz/backend.py", line 223, in render
    run(cmd, capture_output=True, cwd=cwd, check=True, quiet=quiet)
  File "/usr/local/lib/python3.9/site-packages/graphviz/backend.py", line 167, in run
    raise ExecutableNotFound(cmd)
graphviz.backend.ExecutableNotFound: failed to execute ['dot', '-Ksfdp', '-Tsvg', '-O', 'panda'], make sure the Graphviz executables are on your systems' PATH

Dependencies issues and fixes

@LeoVerto some dependency fixes that need to be added:

1. Mac users need to run an additional brew install graphviz after the instructions in the README to install Graphviz dependencies and add them to their path.
   if not, this is the error faced:

graphviz.backend.ExecutableNotFound: failed to execute ['sfdp', '-Tsvg', '-O', 'graph'], make sure the Graphviz executables are on your systems' PATH

2. This tool works with docker version 2.1.0. Hence, if using pip3 to install it, use pip3 install docker==2.1.0.
   The latest version of docker (4.1.x) is not compatible with some parts of the code.

Thanks!

Background colour

Heya,

Thanks for this project! I've been using it on and off for a few years to show how Docker infrastructure can work to others!

By adding [bgcolor=colour]; to the graph syntax, it's possible to make the diagrams a little less retina scarring white.

e.g.

// Docker Network Graph
graph {
	graph [splines=true] [bgcolor=black];

Is a custom background colour something that can be readily implemented at all?

Error With host network_mode ?

Traceback (most recent call last):
  File "docker-net-graph.py", line 191, in <module>
    generate_graph(args.verbose, args.out)
  File "docker-net-graph.py", line 170, in generate_graph
    draw_link(g, networks, link)
  File "docker-net-graph.py", line 147, in draw_link
    color=networks[link.network_name].color
KeyError: 'host'

I'm getting this error on running the tool.

Error when a service is not attached to any network

When a container declares no network, docker accepts it. But the tool fails with the following message:

Traceback (most recent call last):
  File "docker-net-graph.py", line 191, in <module>
    generate_graph(args.verbose, args.out)
  File "docker-net-graph.py", line 170, in generate_graph
    draw_link(g, networks, link)
  File "docker-net-graph.py", line 147, in draw_link
    color=networks[link.network_name].color
KeyError: 'none'

Swarm support

Supporting multi-host swarm networks would be a useful feature. Potentially different hosts could be visually grouped.

KeyError

When executing
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock leoverto/docker-network-graph
I get this:

Traceback (most recent call last):
  File "docker-net-graph.py", line 211, in <module>
    generate_graph(args.verbose, args.out)
  File "docker-net-graph.py", line 190, in generate_graph
    draw_link(g, networks, link)
  File "docker-net-graph.py", line 166, in draw_link
    color=networks[link.network_name].color
KeyError: 'mailcowdockerized_mailcow-network'

Here's the definition of the offending network (from https://github.com/mailcow/mailcow-dockerized/):

networks:
  mailcow-network:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br-mailcow
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: ${IPV4_NETWORK:-172.22.1}.0/24
        - subnet: ${IPV6_NETWORK:-fd4d:6169:6c63:6f77::/64}

Thanks for looking into this!

ARM image ??

It seems that there is no ARM image of docker-network-graph-poc for docker. I received a "exec user process caused: exec format error" response to the docker run command in the README.

uname -a: Linux jellynas 5.4.0-1025-raspi #28-Ubuntu SMP PREEMPT Wed Dec 9 17:10:53 UTC 2020 aarch64 aarch64 aarch64 GNU/Linux.

Many thanks if someone could provide one.

Import Errors and solution

I got it working recently on debian by:

Remove:
from graphviz.backend import FORMAT
and edit

def graphviz_output_file(filename: str):
    ext = os.path.splitext(filename)[1][1:]
    # if ext.lower() not in FORMATS:
    #     raise argparse.ArgumentTypeError("Must be valid graphviz output format")
    return filename

Attach edge anywhere on single-network containers