Volumes HTTP API

The /volume and /volumes endpoints are used to query for and interact with Container Storage Interface (CSI) volumes and dynamic host volumes.

List Volumes

This endpoint lists all volumes.

Method	Path	Produces
`GET`	`/v1/volumes`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:csi-list-volume` `namespace:host-volume-read`

Parameters

type (string: <required>) - Specifies the type of volume to query. One of csi or host. The host value queries dynamic host volumes. Specify this as a query string parameter.
node_id (string: "") - Specifies a string to filter volumes based on an Node ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.
plugin_id (string: "") - Specifies a string to filter volumes based on a plugin ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.
next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string which identifies the next expected volume. This value can be obtained from the X-Nomad-NextToken header from the previous response.
per_page (int: 0) - Specifies a maximum number of volumes to return for this request. If omitted, the response is not paginated. The value of the X-Nomad-NextToken header of the last response can be used as the next_token of the next request to fetch additional pages.
filter (string: "") - Specifies the expression used to filter the results. Consider using pagination or a query parameter to reduce resource used to serve the request.

Sample Request

$ curl \
    https://localhost:4646/v1/volumes?type=csi&node_id=foo&plugin_id=plugin-id1

Sample Response for CSI Volumes

[
  {
    "ID": "volume-id1",
    "ExternalID": "vol-abcdef",
    "Namespace": "default",
    "Name": "volume id1",
    "Topologies": [
      {
        "foo": "bar"
      }
    ],
    "AccessMode": "multi-node-single-writer",
    "AttachmentMode": "file-system",
    "CurrentReaders": 2,
    "CurrentWriters": 1,
    "Schedulable": true,
    "PluginID": "plugin-id1",
    "Provider": "ebs",
    "ControllerRequired": true,
    "ControllersHealthy": 3,
    "ControllersExpected": 3,
    "NodesHealthy": 15,
    "NodesExpected": 18,
    "ResourceExhausted": 0,
    "CreateIndex": 42,
    "ModifyIndex": 64
  }
]

Sample Response for dynamic host volumes

[
  {
    "CapacityBytes": 1048576000,
    "CreateIndex": 42,
    "CreateTime": 1736191825846395400,
    "ID": "3735cc2c-cc64-11ef-89ed-bfb5b3bc38ea",
    "ModifyIndex": 64,
    "ModifyTime": 1736191825846395400,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "5c5830d0-cc64-11ef-a293-4f03e55969ea",
    "NodePool": "default",
    "PluginID": "plugin-id1",
    "State": "ready"
  }
]

Read CSI Volume

This endpoint reads information about a specific CSI volume.

Method	Path	Produces
`GET`	`/v1/volume/csi/:volume_id`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:csi-read-volume`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Request

$ curl \
    https://localhost:4646/v1/volume/csi/volume-id1

Sample Response

{
  "ID": "volume-id1",
  "Name": "volume id1",
  "Namespace": "default",
  "ExternalID": "vol-abcdef",
  "Topologies": [{ "foo": "bar" }],
  "AccessMode": "multi-node-single-writer",
  "AttachmentMode": "file-system",
  "RequestedCapabilities": [
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "file-system"
    },
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "block-device"
    }
  ],
  "Allocations": [
    {
      "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
      "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
      "Name": "example.cache[0]",
      "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
      "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
      "RescheduleTracker": {
        "Events": [
          {
            "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
            "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
            "RescheduleTime": 1517434161192946200,
            "Delay": "5000000000"
          }
        ]
      },
      "JobID": "example",
      "TaskGroup": "cache",
      "DesiredStatus": "run",
      "DesiredDescription": "",
      "ClientStatus": "running",
      "ClientDescription": "",
      "TaskStates": {
        "redis": {
          "State": "running",
          "FinishedAt": "0001-01-01T00:00:00Z",
          "LastRestart": "0001-01-01T00:00:00Z",
          "Restarts": 0,
          "StartedAt": "2017-07-25T23:36:26.106431265Z",
          "Failed": false,
          "Events": [
            {
              "Type": "Received",
              "Time": 1495747371795703800,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": ""
            },
            {
              "Type": "Driver",
              "Time": 1495747371798867200,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": "Downloading image redis:7"
            },
            {
              "Type": "Started",
              "Time": 1495747379525667800,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": ""
            }
          ]
        }
      },
      "CreateIndex": 54,
      "ModifyIndex": 57,
      "CreateTime": 1495747371794276400,
      "ModifyTime": 1495747371794276400
    }
  ],
  "ReadAllocs": {
    "a8198d79-cfdb-6593-a999-1e9adabcba2e": null
  },
  "WriteAllocs": {},
  "Schedulable": true,
  "PluginID": "plugin-id1",
  "Provider": "ebs",
  "Version": "1.0.1",
  "ControllerRequired": true,
  "ControllersHealthy": 3,
  "ControllersExpected": 3,
  "NodesHealthy": 15,
  "NodesExpected": 18,
  "ResourceExhausted": 0,
  "CreateIndex": 42,
  "ModifyIndex": 64
}

Register CSI Volume

This endpoint registers an external CSI volume with Nomad. The volume must exist in the external storage provider. Refer to the Create CSI Volume section for details.

Making the same request again with a higher RequestedCapacityMin value may trigger a Volume Expansion.

Method	Path	Produces
`PUT`	`/v1/volume/csi/:volume_id`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Payload

The payload must include a JSON document that describes the volume's parameters. Note that the NodeID field is required for the register API.

{
  "Volumes": [
    {
      "ExternalID": "vol-abcdef",
      "ID": "volume-id1",
      "Name": "volume one",
      "Namespace": "default",
      "PluginID": "plugin-id1",
      "RequestedCapabilities": [
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "file-system"
        },
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "block-device"
        }
      ],
      "Secrets": {
        "password": "xyzzy"
      },
      "Topologies": [{ "foo": "bar" }]
    }
  ]
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/csi/volume-id1

Create CSI Volume

This endpoint creates a CSI volume in an external storage provider and registers it with Nomad. Only CSI plugins that implement the Controller interface with the CREATE_DELETE_VOLUME capability support this endpoint.

Making the same request again with a higher RequestedCapacityMin value may trigger a Volume Expansion.

Method	Path	Produces
`PUT`	`/v1/volume/csi/:volume_id/create`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Payload

The payload must include a JSON document that describes the volume's parameters.

{
  "Volumes": [
    {
      "ID": "volume-id1",
      "Name": "volume one",
      "Namespace": "default",
      "PluginID": "plugin-id1",
      "MountOptions": {
        "FsType": "ext4",
        "MountFlags": ["ro", "noatime"],
      },
      "RequestedCapacityMin": 10737418240,
      "RequestedCapacityMax": 21474836480,
      "RequestedCapabilities": [
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "file-system"
        },
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "block-device"
        }
      ],
      "Secrets": {
        "password": "xyzzy"
      },
      "SnapshotID": "snap-12345",
      "Topologies": [{ "foo": "bar" }]
    }
  ]
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/csi/volume-id1

Deregister CSI Volume

This endpoint deregisters an external CSI volume from Nomad. It is an error to deregister a volume that is in use.

Method	Path	Produces
`DELETE`	`/v1/volume/csi/:volume_id`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.
force (bool: false) - Force deregistration of the volume and immediately drop claims for terminal allocations. Returns an error if the volume has running allocations. This does not detach the volume from client nodes. Specify this as a query string parameter.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/csi/volume-id1?force=false

Delete CSI Volume

This endpoint deletes an external CSI volume from the storage provider, and deregisters it from Nomad. It is an error to delete a volume that is in use. Only CSI plugins that implement the Controller interface with the CREATE_DELETE_VOLUME capability support this endpoint.

Method	Path	Produces
`DELETE`	`/v1/volume/csi/:volume_id/delete`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

This endpoint accepts a X-Nomad-CSI-Secrets header to set secrets for deleting the volume as comma-separated key-value pairs (see the example below). These secrets will be merged with any secrets already stored when the CSI volume was created.

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Request

$ curl \
    --request DELETE \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volume/csi/volume-id1/delete

Detach CSI Volume

This endpoint detaches an external CSI volume from a Nomad client node. It is an error to detach a volume that is in use.

Method	Path	Produces
`DELETE`	`/v1/volume/csi/:volume_id/detach`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.
node (string: <required>) - The node to detach the volume from. Specify this as a query string parameter.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000

List External CSI Volumes

This endpoint lists storage CSI volumes that are known to the external storage provider but may not be registered with Nomad. Only CSI plugins that implement the Controller interface with the LIST_VOLUMES capability support this endpoint.

Method	Path	Produces
`GET`	`/v1/volumes/external`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:csi-list-volume`

Parameters

plugin_id (string: "") - Specifies a string to filter volumes based on a plugin ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.
next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string returned in a previous response's NextToken field to request the next page of results.
per_page (int: <required>) - Specifies a maximum number of snapshots to return for this request. The response includes a NextToken field that can be passed to the next request to fetch additional pages.

Sample Request

$ curl \
    https://localhost:4646/v1/volumes/external?&plugin_id=plugin-id1&per_page=2

Sample Response

{
  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
  "Volumes": [
    {
      "ExternalID": "vol-37ac485e",
      "CapacityBytes": 1000000,
      "SnapshotID": "snap-12345",
      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
      "IsAbnormal": false,
      "Status": ""
    },
    {
      "ExternalID": "vol-10ac4879",
      "CapacityBytes": 1000000,
      "SnapshotID": "snap-abcdef",
      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
      "IsAbnormal": true,
      "Status": "example error message from provider"
    }
  ]
}

Create CSI Volume Snapshot

This endpoint creates a snapshot of a CSI volume on the external storage provider. Only CSI plugins that implement the Controller interface with the CREATE_DELETE_SNAPSHOT capability support this endpoint.

Method	Path	Produces
`POST`	`/v1/volumes/snapshot`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Sample Payload

The payload must include a JSON document that describes the snapshot's parameters.

{
  "Snapshots": [
    {
      "SourceVolumeID": "volume-id1",
      "PluginID": "plugin-id1",
      "Name": "mysnap",
      "Secrets": {
        "password": "xyzzy"
      },
      "Parameters": {
        "example": "infrequent_access"
      }
    }
  ]
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/volumes/snapshot

Sample Response

{
  "Snapshots": [
    {
      "ID": "snap-031f5f7e3406d594a",
      "SizeBytes": 10737418240,
      "CreateTime": 1617909982,
      "IsReady": false,
      "SourceVolumeID": "volume-id1"
    }
  ]
}

Delete CSI Volume Snapshot

This endpoint deletes a CSI volume snapshot from the external storage provider. Only CSI plugins that implement the Controller interface with the CREATE_DELETE_SNAPSHOT capability support this endpoint.

Method	Path	Produces
`DELETE`	`/v1/volumes/snapshot`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

This endpoint accepts a X-Nomad-CSI-Secrets header to set secrets for deleting the snapshot as comma-separated key-value pairs (see the example below). These secrets will be merged with any secrets already stored when the CSI snapshot was created.

Parameters

plugin_id (string: <required>) - Specifies the prefix of a CSI plugin ID to perform the delete. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.
snapshot_id (string: <required>) - Specifies the snapshot ID to delete. Specify this as a query parameter.

Sample Request

$ curl \
    --request DELETE \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volumes/snapshot

List CSI Volume Snapshots

This endpoint lists CSI volume snapshots on the external storage provider. Only CSI plugins that implement the Controller interface with the LIST_SNAPSHOTS capability support this endpoint.

Method	Path	Produces
`GET`	`/v1/volumes/snapshot`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:csi-list-volume`

Parameters

plugin_id (string: <required>) - Specifies the prefix of a CSI plugin ID to perform the list. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.
next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string returned in a previous response's NextToken field to request the next page of results.
per_page (int: <required>) - Specifies a maximum number of snapshots to return for this request. The response includes a NextToken field that can be passed to the next request to fetch additional pages.

Sample Request

$ curl \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volumes/snapshot?plugin_id=plugin-id1&per_page=2

Sample Response

{
  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
  "Snapshots": [
    {
      "CreateTime": 1227088980,
      "ExternalSourceVolumeID": "vol-37ac485e",
      "ID": "snap-9df717f4",
      "IsReady": true,
      "Parameters": null,
      "PluginID": "aws-ebs0",
      "SizeBytes": 2147483648
    },
    {
      "CreateTime": 1227091232,
      "ExternalSourceVolumeID": "vol-10ac4879",
      "ID": "snap-5cf81835",
      "IsReady": true,
      "Parameters": null,
      "PluginID": "aws-ebs0",
      "SizeBytes": 11811160064
    }
  ]
}

Read Dynamic Host Volume

This endpoint reads information about a specific dynamic host volume.

Method	Path	Produces
`GET`	`/v1/volume/host/:volume_id`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:host-volume-read`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Request

$ curl \
    https://localhost:4646/v1/volume/host/c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f

Sample Response

{
  "Allocations": [],
  "CapacityBytes": 49283072,
  "CreateIndex": 11,
  "CreateTime": 1736191993011594200,
  "HostPath": "/run/nomad/dev/alloc_mounts/c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
  "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
  "ModifyIndex": 12,
  "ModifyTime": 1736191993011594200,
  "Name": "external-plugin",
  "Namespace": "default",
  "NodeID": "670cb259-bc26-653b-e316-655af04ad260",
  "NodePool": "default",
  "Parameters": {
    "hello": "world"
  },
  "PluginID": "example-plugin-mkfs",
  "RequestedCapabilities": [
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "file-system"
    }
  ],
  "RequestedCapacityMaxBytes": 50000000,
  "RequestedCapacityMinBytes": 50000000,
  "State": "ready"
}

Create Dynamic Host Volume

This endpoint creates a dynamic host volume and registers it with Nomad.

The response body includes the volume definition with the ID and NodeID fields populated. Making the same request without the ID creates a new volume on a different node. Making a request with the ID set updates the volume to the new parameters, if possible.

Method	Path	Produces
`PUT`	`/v1/volume/host/create`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:host-volume-create` or `namespace:host-volume-write`. `namespace:sentinel-override` if `PolicyOverride` set

Parameters

Volume (Volume: <required>) - Specifies the JSON definition of the host volume. You should include the ID field if you are updating an existing volume.
PolicyOverride (bool: false) - If set, Nomad overrides any soft mandatory Sentinel policies. This field allows creating a volume when it would be denied by policy.

Sample Payload

{
  "PolicyOverride": false,
  "Volume": {
    "Name": "example",
    "Namespace": "default",
    "NodePool": "prod",
    "PluginID": "mkdir",
    "RequestedCapacityMinBytes": 10737418240,
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "Parameters": {
      "foo": "bar"
    }
  }
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/host/create

Sample Response

{
  "Volume": {
    "Allocations": [],
    "CapacityBytes": 21474836480,
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "CreateIndex": 11,
    "CreateTime": 1736191993011594200,
    "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
    "ModifyIndex": 11,
    "ModifyTime": 1736191993011594200,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "45460554-cc67-11ef-84b7-33d383a55487",
    "NodePool": "prod",
    "Parameters": {
      "foo": "bar"
    },
    "PluginID": "mkdir",
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapacityMinBytes": 10737418240,
    "State": "pending"
  },
  "Warnings": null
}

Register Dynamic Host Volume

This endpoint registers an existing dynamic host volume with Nomad.

Method	Path	Produces
`PUT`	`/v1/volume/host/register`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:host-volume-register` or `namespace:host-volume-write`. `namespace:sentinel-override` if `PolicyOverride` set

Parameters

Volume (Volume: <required>) - Specifies the JSON definition of the host volume. You should include the ID field if you are updating an existing volume.
PolicyOverride (bool: false) - If set, Nomad overrides any soft mandatory Sentinel policies. This field allows registering a volume when it would be denied by policy.

Sample Payload

{
  "PolicyOverride": false,
  "Volume": {
    "Name": "example",
    "Namespace": "default",
    "NodePool": "prod",
    "PluginID": "mkdir",
    "RequestedCapacityMinBytes": 10737418240,
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "Parameters": {
      "foo": "bar"
    }
  }
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/host/register

Sample Response

{
  "Volume": {
    "Allocations": [],
    "CapacityBytes": 21474836480,
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "CreateIndex": 11,
    "CreateTime": 1736191993011594200,
    "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
    "ModifyIndex": 31,
    "ModifyTime": 1736191993721594200,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "45460554-cc67-11ef-84b7-33d383a55487",
    "NodePool": "prod",
    "Parameters": {
      "foo": "bar"
    },
    "PluginID": "mkdir",
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapacityMinBytes": 10737418240,
    "State": "ready"
  },
  "Warnings": null
}

Delete Dynamic Host Volume

This endpoint deletes a dynamic host volume, and deregisters it from Nomad. It is an error to delete a volume that is in use.

Method	Path	Produces
`DELETE`	`/v1/volume/host/:volume_id/delete`	`application/json`

The following table shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:host-volume-write` or `namespace:host-volume-delete`

Parameters

:volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/host/ba97ef42-cc68-11ef-a2e7-ffddaecbdb89