Document network diagnostic tool #5558
Conversation
| started to debug specific issues, and should not be left running all the time. | ||
|
|
||
| Information about networks is stored in a database, which can be examined using | ||
| the API. The database consists of one table per network. |
There was a problem hiding this comment.
The database consists of one table per network. would remove this, it is actually 2 per network so far, but not really of interest
There was a problem hiding this comment.
How are you supposed to know what the table name is that you want to dump? I couldn't figure this out.
There was a problem hiding this comment.
the idea is that the majority of the people will use the client that abstracts this detail and deserialize the structures of the database.
The tables are the endpoint_table and the overlay_peer_table
| started to debug specific issues, and should not be left running all the time. | ||
|
|
||
| Information about networks is stored in a database, which can be examined using | ||
| the API. The database consists of one table per network. |
There was a problem hiding this comment.
The database consists of one table per network. I would remove this, the number is actually 2 at the moment, but is not really relevant
| /join | ||
| ``` | ||
|
|
||
| ### Join or leave the swarm |
There was a problem hiding this comment.
Join leave the network database cluster
| The CLI is provided as a preview and is not yet stable. Commands or options may | ||
| change at any time. | ||
|
|
||
| The CLI executable is called `debugClient` and is made available using a |
There was a problem hiding this comment.
right now is called diagnosticClient
|
I think one of my questions got hidden addressing your feedback, @fcrisciani . I don't understand how the database tables are named. Can I give the user a clue, since they need to specify the table name in some of the commands? |
|
I think this is ready. PTAL again. |
| provides diagnostic information. The network debugging tool should only be | ||
| started to debug specific issues, and should not be left running all the time. | ||
|
|
||
| Information about networks is stored in a database, which can be examined using |
There was a problem hiding this comment.
stored in a database: how about a little more details around the networkdb:
- What kind of information is stored?
- Mention that the database is shared/clustered across all nodes.
| /networkpeers | ||
| / | ||
| /join | ||
| ``` |
There was a problem hiding this comment.
Shouldn't the leave endpoint be listed here too?
| ### Join or leave the network database cluster | ||
|
|
||
| ```bash | ||
| $ curl localhost:2000/join?members=ip1,ip2,... |
There was a problem hiding this comment.
It might be good to clarify ip1, ip2. Maybe add a note that they are the IPs of the nodes in the swarm? Ideal would be an example with a docker node ls and docker node inspect showing the IP addresses.
There was a problem hiding this comment.
Yes, I think that's useful (at least for one of the examples)
| 1. To run the container, use a command like the following: | ||
|
|
||
| ```bash | ||
| $ docker container run --name net-diagnostic -d --privileged --network host fcrisciani/network-diagnostic |
There was a problem hiding this comment.
How about we push the containerized tool to docker org in hub?
There was a problem hiding this comment.
Agreed; but that can be handled separate from this PR (and this reference updated in a follow-up)
|
Most of these are not really docs issues. @fcrisciani can you please provide some more info here? cc/ @thaJeztah |
|
|
||
| The Docker API exposes endpoints to query and control the network debugging | ||
| tool. CLI integration is provided as a preview, but the implementation is not | ||
| yet considered stable and commands and options may change without notice. |
There was a problem hiding this comment.
We should add a big fat warning that this tool should be used with care, as (IIUC) incorrect use of the tool can destroy/damage the network (it's not a read-only tool), and also expose information about your cluster's configuration that should be kept private (so don't expose this API outside of the host).
| the output, and is typically a number from 2 to 6 digits long. | ||
|
|
||
| ```bash | ||
| $ ps aux |grep dockerd | grep -v grep |
There was a problem hiding this comment.
If running with systemd (perhaps it's ok to assume that's the case), it's possible to use systemctl reload docker
| 1. To run the container, use a command like the following: | ||
|
|
||
| ```bash | ||
| $ docker container run --name net-diagnostic -d --privileged --network host fcrisciani/network-diagnostic |
There was a problem hiding this comment.
Agreed; but that can be handled separate from this PR (and this reference updated in a follow-up)
| ### Join or leave the network database cluster | ||
|
|
||
| ```bash | ||
| $ curl localhost:2000/join?members=ip1,ip2,... |
There was a problem hiding this comment.
Yes, I think that's useful (at least for one of the examples)
|
@fcrisciani We have decided not to doc this officially. Please use the contents of this PR to develop a README for https://github.com/docker/libnetwork/. After you have done so, please ping me to link to the readme from the |
|
@fcrisciani Please also include cautions about potential to harm the network, in the upstream |
Document the network diagnostic tool introduced in moby/moby#35677
Fixes #5555
cc/ @fcrisciani
Not sure if we should really be documenting the CLI at all. It's not great that the API isn't documented in Swagger.
I'm also not 💯 clear on the use case for this or the type of info you'd use it to get.