moby/client
Albin Kerouanton 78479b1915
libnet: Make sure network names are unique
Fixes #18864, #20648, #33561, #40901.

[This GH comment][1] makes clear network name uniqueness has never been
enforced due to the eventually consistent nature of Classic Swarm
datastores:

> there is no guaranteed way to check for duplicates across a cluster of
> docker hosts.

And this is further confirmed by other comments made by @mrjana in that
same issue, eg. [this one][2]:

> we want to adopt a schema which can pave the way in the future for a
> completely decentralized cluster of docker hosts (if scalability is
> needed).

This decentralized model is what Classic Swarm was trying to be. It's
been superseded since then by Docker Swarm, which has a centralized
control plane.

To circumvent this drawback, the `NetworkCreate` endpoint accepts a
`CheckDuplicate` flag. However it's not perfectly reliable as it won't
catch concurrent requests.

Due to this design decision, API clients like Compose have to implement
workarounds to make sure names are really unique (eg.
docker/compose#9585). And the daemon itself has seen a string of issues
due to that decision, including some that aren't fixed to this day (for
instance moby/moby#40901):

> The problem is, that if you specify a network for a container using
> the ID, it will add that network to the container but it will then
> change it to reference the network by using the name.

To summarize, this "feature" is broken, has no practical use and is a
source of pain for Docker users and API consumers. So let's just remove
it for _all_ API versions.

[1]: https://github.com/moby/moby/issues/18864#issuecomment-167201414
[2]: https://github.com/moby/moby/issues/18864#issuecomment-167202589

Signed-off-by: Albin Kerouanton <albinker@gmail.com>
2023-09-12 10:40:13 +02:00
..
buildkit client/buildkit: ClientOpts: update docs to use doc-links, and inline 2023-08-01 16:19:36 +02:00
testdata Move engine-api client package 2016-09-07 11:05:58 -07:00
build_cancel.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
build_prune.go client: use strconv instead of fmt.Sprintf() 2022-10-08 17:41:39 +02:00
checkpoint_create.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_create_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_delete.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_delete_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_list.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_list_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
client.go Add otel support 2023-09-07 18:38:19 +00:00
client_deprecated.go client: deprecate NewClient properly 2023-03-31 16:15:01 -04:00
client_mock_test.go Add otel support 2023-09-07 18:38:19 +00:00
client_test.go Add otel support 2023-09-07 18:38:19 +00:00
client_unix.go remove pre-go1.17 build-tags 2023-05-19 20:38:51 +02:00
client_windows.go client: defaultHTTPClient() accept URL 2023-01-01 13:35:16 +01:00
config_create.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
config_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
config_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
config_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
config_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
config_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_attach.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
container_commit.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
container_commit_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_copy.go client: CopyToContainer(), CopyFromContainer(): remove status-code handling 2022-04-19 08:28:20 +02:00
container_copy_test.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
container_create.go Add health start interval 2023-07-05 23:44:17 +00:00
container_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_diff.go api/types/container: create type for changes endpoint 2023-05-03 21:23:42 +02:00
container_diff_test.go client: slightly improve ContainerDiff tests 2023-05-03 21:25:07 +02:00
container_exec.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
container_exec_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_export.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_export_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
container_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_kill.go client: ContainerKill(): don't send signal query-param if none was set 2022-04-19 17:40:33 +02:00
container_kill_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_list.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
container_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_logs.go gofmt GoDoc comments with go1.19 2022-07-08 19:56:23 +02:00
container_logs_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_pause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_pause_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
container_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_rename.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_rename_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_resize.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_resize_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_restart.go client: ContainerStop(), ContainerRestart(): support stop-signal 2022-04-20 21:29:34 +02:00
container_restart_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_start.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_start_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_stats.go client: return explicit "nil" for no errors, and remove nil check 2023-07-17 12:24:28 +02:00
container_stats_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_stop.go client: ContainerStop(), ContainerRestart(): support stop-signal 2022-04-20 21:29:34 +02:00
container_stop_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_top.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_top_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_unpause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_unpause_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_update.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
container_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_wait.go client: improve error messaging on crash 2023-01-26 15:52:01 -05:00
container_wait_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
disk_usage.go API,daemon: support type URL parameter to /system/df 2021-07-27 12:17:45 +02:00
disk_usage_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
distribution_inspect.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
distribution_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
envvars.go client: add const for environment variables, and document them 2022-03-07 12:35:55 +01:00
errors.go client: make IsErrNotFound an alias for errdefs.IsNotFound 2023-05-10 21:52:43 +02:00
events.go client: fix empty-lines (revive) 2022-09-28 01:58:52 +02:00
events_test.go api/types/events: define "Action" type and consts 2023-08-29 00:38:08 +02:00
hijack.go Add otel support 2023-09-07 18:38:19 +00:00
hijack_test.go refactor: move from io/ioutil to io and os package 2021-08-27 14:56:57 +08:00
image_build.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
image_build_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_create.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_history.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_history_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_import.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_import_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
image_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_list.go client/list: Handle SharedSize 2022-11-30 17:08:00 +01:00
image_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_load.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
image_load_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_pull.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_pull_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_push.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_push_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
image_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_save.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_save_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_search.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
image_search_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_tag.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_tag_test.go client: TestImageTagInvalidSourceImageName remove invalid test-case 2023-08-30 21:43:02 +02:00
info.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
info_test.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
interface.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
interface_experimental.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
interface_stable.go Add canonical import comment 2018-02-05 16:51:57 -05:00
login.go client: use types/registry.AuthConfig 2022-07-29 23:05:15 +02:00
network_connect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_connect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_create.go libnet: Make sure network names are unique 2023-09-12 10:40:13 +02:00
network_create_test.go libnet: Make sure network names are unique 2023-09-12 10:40:13 +02:00
network_disconnect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_disconnect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
network_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
network_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
network_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
network_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
node_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_list.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
node_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
node_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
node_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
options.go Add otel support 2023-09-07 18:38:19 +00:00
options_test.go client: add WithUserAgent() option 2023-06-09 09:59:29 +02:00
ping.go client: Client.buildRequest: use http.NewRequestWithContext 2023-08-09 20:30:25 +02:00
ping_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
plugin_disable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_disable_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_enable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_enable_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_install.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
plugin_list.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_push.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
plugin_push_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_set.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_set_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_upgrade.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
README.md Update example in README.md to close cli object 2023-08-26 19:55:45 +02:00
request.go client: Client.buildRequest: use http.NewRequestWithContext 2023-08-09 20:30:25 +02:00
request_test.go client: define a "dummy" hostname to use for local connections 2023-07-14 18:57:53 +02:00
secret_create.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
secret_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
secret_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
secret_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
secret_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
secret_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_create.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
service_create_test.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
service_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
service_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_list.go Add support for sending down service Running and Desired task counts 2019-10-14 10:43:00 -05:00
service_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
service_logs_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
service_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_update.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
service_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_get_unlock_key.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_get_unlock_key_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_init.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_init_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_join.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_join_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_leave.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_leave_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_unlock.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_unlock_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
swarm_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
task_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
task_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_logs.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
utils.go Add canonical import comment 2018-02-05 16:51:57 -05:00
version.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_create.go api: rename volume.VolumeCreateBody to volume.CreateOptions 2022-04-28 22:39:14 +02:00
volume_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_inspect.go api/types: replace uses of deprecated types.Volume with volume.Volume 2022-04-21 19:50:59 +02:00
volume_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_list.go api: add types/volume.ListOptions for a more consistent API 2022-08-03 23:30:28 +02:00
volume_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_prune.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
volume_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
volume_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00

Go client for the Docker Engine API

The docker command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does  running containers, pulling images, managing swarms, etc.

For example, to list running containers (the equivalent of docker ps):

package main

import (
	"context"
	"fmt"

	"github.com/docker/docker/api/types"
	"github.com/docker/docker/client"
)

func main() {
	cli, err := client.NewClientWithOpts(client.FromEnv)
	if err != nil {
		panic(err)
	}
	defer cli.Close()

	containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
	if err != nil {
		panic(err)
	}

	for _, container := range containers {
		fmt.Printf("%s %s\n", container.ID[:10], container.Image)
	}
}

Full documentation is available on GoDoc.