CSI Volume Registration has wrong documentation / API design

[josemaia]

Nomad version

Nomad v0.12.1

Issue

API documentation for the command to register volumes is inconsistent with what the API is expecting

Reproduction steps

• do nomad volume register myvolume.hcl with a valid volume HCL configuration
• capture the request (e.g. via netcat)
• notice that the CLI app is sending your payload "wrapped" in a Volumes[] array despite the PUT command targeting a specific volume syntactically (e.g. PUT /v1/volume/csi/myvolume)

Job file (if appropriate)

HCL used by the CLI app:

id = "teste1"
name = "teste1"
type = "csi"
external_id = "/subscriptions/132432423/resourceGroups/teste-core-rg/providers/Microsoft.Compute/disks/teste-core-teste1-disk"
plugin_id = "az-disk0"
access_mode = "single-node-writer"
attachment_mode = "file-system"
mount_options {
 fs_type = "ext4"
 mount_flags = ["ro"]
}

Correct payload in JSON:

{"Volumes":[{"ID":"teste1","Name":"teste1","Namespace":"default","ExternalID":"/subscriptions/132432423/resourceGroups/teste-core-rg/providers/Microsoft.Compute/disks/teste-core-teste1-disk","Topologies":[],"AccessMode":"single-node-writer","AttachmentMode":"file-system","PluginID":"az-disk0"}]}

Other notes

• if you submit the command via a curl to the API endpoint /v1/volume/csi/myvolume instead of the CLI, without wrapping in Volumes[] you will get a missing volume definition error, which isn't great for debugging! I had to crack open wireshark before just thinking of using nc
• link to the sample payload is at https://www.nomadproject.io/api-docs/volumes#sample-payload
• either the fix is in the documentation and the API is kind of weird (you specify the volume ID to put to in the URL then send an array?) or it may cause some breakage if anyone is using this endpoint

[tgross]

Hi @josemaia!

either the fix is in the documentation and the API is kind of weird (you specify the volume ID to put to in the URL then send an array?) or it may cause some breakage if anyone is using this endpoint

I'll admit the API is kind of weird; there was an affordance left in the API struct to allow for batch registration, which will be useful for large jobs when we implement #8212.

That being said, it's definitely a documentation bug. If you're willing to submit a PR to the volumes API docs I'd be happy to review it, otherwise I'll do that myself shortly.

[tgross]

Thanks for the PR, @josemaia... that'll get pushed out in the next docs website update (should be in the next day or two).

[github-actions]

I'm going to lock this issue because it has been closed for 120 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.