Description
The Topology type in the swagger spec is defined as a flat additionalProperties: string, but the actual Go implementation has a Segments field. Client code generated from the swagger spec produces the wrong type and cannot deserialise Docker output for AccessibleTopology and related fields.
The swagger spec defines:
|
Topology: |
|
description: | |
|
A map of topological domains to topological segments. For in depth |
|
details, see documentation for the Topology object in the CSI |
|
specification. |
|
type: "object" |
|
additionalProperties: |
|
type: "string" |
But the Go type in api/types/volume/cluster_volume.go is:
|
type Topology struct { |
|
Segments map[string]string `json:",omitempty"` |
|
} |
The Go struct serializes as {"Segments": {"key": "value"}}, not {"key": "value"}.
Reproduce
I've confirmed this end-to-end by installing the democratic-csi local-hostpath plugin as a Docker plugin (docker plugin create from exported rootfs), initialising a single-node Swarm, creating a cluster volume with driver: csi-local-path, and calling GET /volumes/{name} using Bollard. An integration test will link to this ticket shortly.
The actual Docker daemon output for ClusterVolume.Info is:
{
"VolumeContext": {
"node_attach_driver": "hostpath",
"path": "/var/lib/csi-local-hostpath/v/integration_test_cluster_volume",
"provisioner_driver": "local-hostpath"
},
"VolumeID": "integration_test_cluster_volume",
"AccessibleTopology": [
{
"Segments": {
"org.democratic-csi.topology/node": "ip-10-0-109-88"
}
}
]
}AccessibleTopology is an array of objects, each with a Segments key containing a
map[string]string.
Expected behavior
The swagger spec should be updated to reflect the actual struct:
Topology:
description: |
A map of topological domains to topological segments. For in depth
details, see documentation for the Topology object in the CSI
specification.
type: "object"
properties:
Segments:
type: "object"
additionalProperties:
type: "string"Affected fields
AccessibleTopology is an array of Topology objects:
|
AccessibleTopology: |
|
type: "array" |
|
description: | |
|
The topology this volume is actually accessible from. |
|
items: |
|
$ref: "#/definitions/Topology" |
|
// AccessibleTopology is the topology this volume is actually accessible |
|
// from. |
|
AccessibleTopology []Topology `json:",omitempty"` |
The same Topology type is also used in ClusterVolumeSpec.AccessMode.AccessibilityRequirements for Requisite and Preferred.
docker version
Affects all API versions where CSI volume support is present (`v1.41+`). Confirmed unchanged between `v1.44` (Docker `25.0.2`) and `v1.53` (Docker `29.3.1`).
docker version of the CI system:
Client:
Version: 29.3.1
API version: 1.51 (downgraded from 1.54)
Go version: go1.25.8
Git commit: c2be9cc
Built: Wed Mar 25 16:12:39 2026
OS/Arch: linux/amd64
Context: default
Server: Docker Engine - Community
Engine:
Version: 28.3.0
API version: 1.51 (minimum version 1.24)
Go version: go1.24.4
Git commit: 265f709
Built: Tue Jun 24 15:44:12 2025
OS/Arch: linux/amd64
Experimental: false
containerd:
Version: 1.7.27
GitCommit: 05044ec0a9a75232cad458027ca83437aae3f4da
runc:
Version: 1.2.5
GitCommit: v1.2.5-0-g59923ef
docker-init:
Version: 0.19.0
GitCommit: de40ad0
Client:
Version: 29.3.1
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc.)
Version: v0.33.0
Path: /usr/local/libexec/docker/cli-plugins/docker-buildx
compose: Docker Compose (Docker Inc.)
Version: v5.1.1
Path: /usr/local/libexec/docker/cli-plugins/docker-composedocker info
Server:
Containers: 2
Running: 2
Paused: 0
Stopped: 0
Images: 3
Server Version: 28.3.0
Storage Driver: overlay2
Backing Filesystem: extfs
Supports d_type: true
Using metacopy: false
Native Overlay Diff: true
userxattr: false
Logging Driver: json-file
Cgroup Driver: systemd
Cgroup Version: 2
Plugins:
Volume: local
Network: bridge host ipvlan macvlan null overlay
Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
CDI spec directories:
/etc/cdi
/var/run/cdi
Swarm: inactive
Runtimes: io.containerd.runc.v2 runc
Default Runtime: runc
Init Binary: docker-init
containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
runc version: v1.2.5-0-g59923ef
init version: de40ad0
Security Options:
apparmor
seccomp
Profile: builtin
cgroupns
Kernel Version: 6.14.0-1018-aws
Operating System: Ubuntu 24.04.3 LTS
OSType: linux
Architecture: x86_64
CPUs: 2
Total Memory: 7.599GiB
Name: ip-10-0-181-66
ID: 1ee0ce25-1a64-464a-a603-2be5c590df40
Docker Root Dir: /var/lib/docker
Debug Mode: false
Experimental: false
Insecure Registries:
::1/128
127.0.0.0/8
Live Restore Enabled: false
Firewall Backend: iptables
Additional Info
No response
Description
The
Topologytype in the swagger spec is defined as a flatadditionalProperties: string, but the actual Go implementation has aSegmentsfield. Client code generated from the swagger spec produces the wrong type and cannot deserialise Docker output forAccessibleTopologyand related fields.The swagger spec defines:
moby/api/swagger.yaml
Lines 5974 to 5981 in 240a9fc
But the Go type in
api/types/volume/cluster_volume.gois:moby/api/types/volume/cluster_volume.go
Lines 333 to 335 in 8f99275
The Go struct serializes as
{"Segments": {"key": "value"}}, not{"key": "value"}.Reproduce
I've confirmed this end-to-end by installing the democratic-csi local-hostpath plugin as a Docker plugin (
docker plugin createfrom exported rootfs), initialising a single-node Swarm, creating a cluster volume withdriver: csi-local-path, and callingGET /volumes/{name}using Bollard. An integration test will link to this ticket shortly.The actual Docker daemon output for
ClusterVolume.Infois:{ "VolumeContext": { "node_attach_driver": "hostpath", "path": "/var/lib/csi-local-hostpath/v/integration_test_cluster_volume", "provisioner_driver": "local-hostpath" }, "VolumeID": "integration_test_cluster_volume", "AccessibleTopology": [ { "Segments": { "org.democratic-csi.topology/node": "ip-10-0-109-88" } } ] }AccessibleTopologyis an array of objects, each with aSegmentskey containing amap[string]string.Expected behavior
The swagger spec should be updated to reflect the actual struct:
Affected fields
AccessibleTopologyis an array ofTopologyobjects:moby/api/swagger.yaml
Lines 7647 to 7652 in 8f99275
moby/api/types/volume/cluster_volume.go
Lines 417 to 419 in 8f99275
The same
Topologytype is also used inClusterVolumeSpec.AccessMode.AccessibilityRequirementsforRequisiteandPreferred.docker version
docker info
Additional Info
No response