Query parameters

• filters string(json)

  JSON encoded value of the filters (a map[string][]string) to process on the volumes list. Available filters:

  • dangling=<boolean> When set to true (or 1), returns all volumes that are not in use by a container. When set to false (or 0), only volumes that are in use by one or more containers are returned.
  • driver=<volume-driver-name> Matches volumes based on their driver.
  • label=<key> or label=<key>:<value> Matches volumes based on the presence of a label alone or a label and a value.
  • name=<volume-name> Matches all or part of a volume name.

Responses

• 200 application/json

  Summary volume data that matches the query

  Hide response attributes Show response attributes object

  • Volumes array[object]

    List of volumes

    Hide Volumes attributes Show Volumes attributes object

    • Name string Required

      Name of the volume.

    • Driver string Required

      Name of the volume driver used by the volume.

    • Mountpoint string Required

      Mount path of the volume on the host.

    • CreatedAt string(dateTime)

      Date/Time the volume was created.

    • Status object

      Low-level details about the volume, provided by the volume driver. Details are returned as a map with key/value pairs: {"key":"value","key2":"value2"}.

      The Status field is optional, and is omitted if the volume driver does not support this feature.

      Hide Status attribute Show Status attribute object

      • * object Additional properties
    • Labels object Required

      User-defined key/value metadata.

      Hide Labels attribute Show Labels attribute object

      • * string Additional properties
    • Scope string Required

      The level at which the volume exists. Either global for cluster-wide, or local for machine level.

      Values are local or global. Default value is local.

    • ClusterVolume object

      Options and information specific to, and only present on, Swarm CSI cluster volumes.

      Hide ClusterVolume attributes Show ClusterVolume attributes object

      • ID string

        The Swarm ID of this volume. Because cluster volumes are Swarm objects, they have an ID, unlike non-cluster volumes. This ID can be used to refer to the Volume instead of the name.

      • Version object

        The version number of the object such as node, service, etc. This is needed to avoid conflicting writes. The client must send the version number along with the modified specification when updating these objects.

        This approach ensures safe concurrency and determinism in that the change on the object may not be applied if the version number has changed from the last read. In other words, if two update requests specify the same base version, only one of the requests can succeed. As a result, two separate update requests that happen at the same time will not unintentionally overwrite each other.

        Hide Version attribute Show Version attribute object

        • Index integer(uint64)
      • CreatedAt string(dateTime)
      • UpdatedAt string(dateTime)
      • Spec object

        Cluster-specific options used to create the volume.

        Hide Spec attributes Show Spec attributes object

        • Group string

          Group defines the volume group of this volume. Volumes belonging to the same group can be referred to by group name when creating Services. Referring to a volume by group instructs Swarm to treat volumes in that group interchangeably for the purpose of scheduling. Volumes with an empty string for a group technically all belong to the same, emptystring group.

        • AccessMode object

          Defines how the volume is used by tasks.

          Hide AccessMode attributes Show AccessMode attributes object

          • Scope string

            The set of nodes this volume can be used on at one time.

            • single The volume may only be scheduled to one node at a time.
            • multi the volume may be scheduled to any supported number of nodes at a time.

            Values are single or multi. Default value is single.

          • Sharing string

            The number and way that different tasks can use this volume at one time.

            • none The volume may only be used by one task at a time.
            • readonly The volume may be used by any number of tasks, but they all must mount the volume as readonly
            • onewriter The volume may be used by any number of tasks, but only one may mount it as read/write.
            • all The volume may have any number of readers and writers.

            Values are none, readonly, onewriter, or all. Default value is none.

          • MountVolume object

            Options for using this volume as a Mount-type volume.

            Either MountVolume or BlockVolume, but not both, must be present. properties: FsType: type: "string" description: | Specifies the filesystem type for the mount volume. Optional. MountFlags: type: "array" description: | Flags to pass when mounting the volume. Optional. items: type: "string" BlockVolume: type: "object" description: | Options for using this volume as a Block-type volume. Intentionally empty.

          • Secrets array[object]

            Swarm Secrets that are passed to the CSI storage plugin when operating on this volume.

            One cluster volume secret entry. Defines a key-value pair that is passed to the plugin.

            Hide Secrets attributes Show Secrets attributes object

            • Key string

              Key is the name of the key of the key-value pair passed to the plugin.

            • Secret string

              Secret is the swarm Secret object from which to read data. This can be a Secret name or ID. The Secret data is retrieved by swarm and used as the value of the key-value pair passed to the plugin.

          • AccessibilityRequirements object

            Requirements for the accessible topology of the volume. These fields are optional. For an in-depth description of what these fields mean, see the CSI specification.

            Hide AccessibilityRequirements attributes Show AccessibilityRequirements attributes object

            • Requisite array[object]

              A list of required topologies, at least one of which the volume must be accessible from.

              A map of topological domains to topological segments. For in depth details, see documentation for the Topology object in the CSI specification.

              Hide Requisite attribute Show Requisite attribute object

              • * string Additional properties
            • Preferred array[object]

              A list of topologies that the volume should attempt to be provisioned in.

              A map of topological domains to topological segments. For in depth details, see documentation for the Topology object in the CSI specification.

              Hide Preferred attribute Show Preferred attribute object

              • * string Additional properties
          • CapacityRange object

            The desired capacity that the volume should be created with. If empty, the plugin will decide the capacity.

            Hide CapacityRange attributes Show CapacityRange attributes object

            • RequiredBytes integer(int64)

              The volume must be at least this big. The value of 0 indicates an unspecified minimum

            • LimitBytes integer(int64)

              The volume must not be bigger than this. The value of 0 indicates an unspecified maximum.

          • Availability string

            The availability of the volume for use in tasks.

            • active The volume is fully available for scheduling on the cluster
            • pause No new workloads should use the volume, but existing workloads are not stopped.
            • drain All workloads using this volume should be stopped and rescheduled, and no new ones should be started.

            Values are active, pause, or drain. Default value is active.

      • Info object

        Information about the global status of the volume.

        Hide Info attributes Show Info attributes object

        • CapacityBytes integer(int64)

          The capacity of the volume in bytes. A value of 0 indicates that the capacity is unknown.

        • VolumeContext object

          A map of strings to strings returned from the storage plugin when the volume is created.

          Hide VolumeContext attribute Show VolumeContext attribute object

          • * string Additional properties
        • VolumeID string

          The ID of the volume as returned by the CSI storage plugin. This is distinct from the volume's ID as provided by Docker. This ID is never used by the user when communicating with Docker to refer to this volume. If the ID is blank, then the Volume has not been successfully created in the plugin yet.

        • AccessibleTopology array[object]

          The topology this volume is actually accessible from.

          A map of topological domains to topological segments. For in depth details, see documentation for the Topology object in the CSI specification.

          Hide AccessibleTopology attribute Show AccessibleTopology attribute object

          • * string Additional properties
      • PublishStatus array[object]

        The status of the volume as it pertains to its publishing and use on specific nodes

        Hide PublishStatus attributes Show PublishStatus attributes object

        • NodeID string

          The ID of the Swarm node the volume is published on.

        • State string

          The published state of the volume.

          • pending-publish The volume should be published to this node, but the call to the controller plugin to do so has not yet been successfully completed.
          • published The volume is published successfully to the node.
          • pending-node-unpublish The volume should be unpublished from the node, and the manager is awaiting confirmation from the worker that it has done so.
          • pending-controller-unpublish The volume is successfully unpublished from the node, but has not yet been successfully unpublished on the controller.

          Values are pending-publish, published, pending-node-unpublish, or pending-controller-unpublish.

        • PublishContext object

          A map of strings to strings returned by the CSI controller plugin when a volume is published.

          Hide PublishContext attribute Show PublishContext attribute object

          • * string Additional properties
    • Options object Required

      The driver specific options used when creating the volume.

      Hide Options attribute Show Options attribute object

      • * string Additional properties
    • UsageData object

      Usage details about the volume. This information is used by the GET /system/df endpoint, and omitted in other endpoints.

      Hide UsageData attributes Show UsageData attributes object

      • Size integer(int64) Required

        Amount of disk space used by the volume (in bytes). This information is only available for volumes created with the "local" volume driver. For volumes created with other volume drivers, this field is set to -1 ("not available")

        Default value is -1.

      • RefCount integer(int64) Required

        The number of containers referencing this volume. This field is set to -1 if the reference-count is not available.

        Default value is -1.

  • Warnings array[string]

    Warnings that occurred when fetching the list of volumes.

• 500 application/json

  Server error

  Hide response attribute Show response attribute object

  • message string Required

    The error message.