Support `docker system`-related API endpoints

[rtfpessoa]

Description

Add support for docker system as described in the docs

I looked but could not find any reference to it neither in the code or in any issue. If this is duplicated let me know. If this is the first time it is referenced, I would be interested in contributing this feature and would like to know if it would make sense and if there are any things I might need to check besides README etc.

[johnflavin]

TL;DR It isn't possible to support most of the docker system commands directly, but you could add some things to docker-client that would help get us closer.

Here's a long explanation. docker-client doesn't use the docker command-line directly, it uses the docker API. You can read all the API endpoints that docker exposes in their swagger.yaml file, or a formatted web page in their docs: https://docs.docker.com/develop/sdk/#api-version-matrix. Each of the 1.xx versions on the latter page is a link to a full run-down of every API endpoint in that version. The good news is that everything that the docker command-line does is also done through the API, so everything they do is possible for us to support. The bad news is that sometimes they sometimes expose a single command that wraps up multiple API calls, whereas the style of docker-client is more to just expose the API directly and let the users mix and match those API endpoints however they like.

In the case of docker system, almost all of those functions are the tricky multiple-API-calls-wrapped-up-in-one-command kind. The only one exposed directly in the API is docker system df; you can see it in the swagger.yaml on line 7059. So you could easily add that one directly to docker-client and we would be better for it.

However, there is more you could do that would be even more helpful. There are plenty of other API endpoints we do not have (because docker adds them a lot faster than we do), including several that are used under the covers by docker system commands. You could spend plenty of time adding additional APIs of all sorts and it would be super helpful. There are APIs all over that swagger.yaml that we don't have yet, or properties that got added to existing APIs that we don't have, or options or flags or whatever. It could be a full-time job just keeping docker-client up-to-date with the docker API.

But instead of just searching swagger.yaml for what we don't have, I can point you in a direction that will get you closer to what you asked for originally, which is supporting the docker system commands. You can read the source code for the various docker system commands inside the docker CLI here: https://github.com/docker/cli/tree/master/cli/command/system. (It's in go, which I don't write, but I find it pretty readable even so. If you don't know go, still give it a shot.) All of the docker system subcommands are the various source files here. If you look through, for instance, prune.go you can see what the docker CLI does when you run docker system prune. It separately prunes containers, volumes, images, networks, and the build cache. You would have to track down the source code for those to know exactly what they do too, but, spoilers, those are exposed in the remote API. So if you added to docker-client all those separate APIs that we don't yet support—/images/prune, /containers/prune, etc.—then you could write some code in your application to run all of those together in the same way that the docker system prune function does.

[mattnworb]

@johnflavin awesome writeup. +1 that the intention of this library is to be a client for the docker API as opposed to the docker CLI.

[davidxia]

@johnflavin Thanks for the explanation.

@mattnworb @johnflavin Do you think docker-client should just stick to the API or provide CLI functionality? I lean towards former to keep it more focused.

[mattnworb]

Right, this library is meant to be a client for the API. I don't see the point of a client for the CLI, when the CLI already exists.

[davidxia]

I can close this issue then if no one objects.

[rtfpessoa]

I guess you can close it, but would be nice to link @johnflavin answer to future work on the missing apis for prune etc.

[mattnworb]

I think it is a fair request to add API methods related to the docker system CLI as mentioned above

However, there is more you could do that would be even more helpful. There are plenty of other API endpoints we do not have (because docker adds them a lot faster than we do), including several that are used under the covers by docker system commands. You could spend plenty of time adding additional APIs of all sorts and it would be super helpful. There are APIs all over that swagger.yaml that we don't have yet, or properties that got added to existing APIs that we don't have, or options or flags or whatever.

Whether you keep this issue open for it or create another, I don't think it matters much. But I do think it is useful to keep "help-wanted" issues like this open for newcomers/interested contributors to find.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[dmandalidis]

Hi @rtfpessoa ,

Since this project went on mature status, please re-open this issue (if it still stands) to https://github.com/dmandalidis/docker-client. Thanks