Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CSI Volume Registration has wrong documentation / API design #8879

Closed
josemaia opened this issue Sep 14, 2020 · 3 comments · Fixed by #8880
Closed

CSI Volume Registration has wrong documentation / API design #8879

josemaia opened this issue Sep 14, 2020 · 3 comments · Fixed by #8880
Assignees
Labels
theme/docs Documentation issues and enhancements theme/storage

Comments

@josemaia
Copy link
Contributor

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
Copy link
Member

tgross commented Sep 14, 2020

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 tgross added theme/docs Documentation issues and enhancements theme/storage labels Sep 14, 2020
@tgross tgross self-assigned this Sep 14, 2020
@tgross
Copy link
Member

tgross commented Sep 14, 2020

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
Copy link

github-actions bot commented Nov 2, 2022

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.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Nov 2, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
theme/docs Documentation issues and enhancements theme/storage
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants