search

hashicorp / nomad

Nomad is an easy-to-use, flexible, and performant workload orchestrator that can deploy a mix of microservice, batch, containerized, and non-containerized applications. Nomad is easy to operate and scale and has native Consul and Vault integrations.
https://www.nomadproject.io/
Other
14.93k stars 1.96k forks source link

Add proper error responses to the various api endpoints #10476

Open josegonzalez opened 3 years ago

josegonzalez commented 3 years ago

Proposal

It would be great if Nomad errors were not plaintext strings and instead were some sort of structured objects. This would allow clients to be able to show errors in a more useful manner than just printing the output and hoping that Nomad structured it properly.

Additionally, some of the warning output even shows "errors". Kinda confusing for users that see there are errors but don't know if they actually are errors.

Screen Shot 2021-04-29 at 12 34 23 PM

Having standard error responses would allow clients to decide on more user-friendly ways to expose those errors/warnings/etc.

Use-cases

For background, I was looking to see what it would take to implement a transparent proxy around certain Nomad api endpoints (for job plan and job apply at least). We would use our admission-controller as a wrapper around the nomad api, injecting data into the job before it gets submitted upstream.

The annotations feature is great because we could in theory add annotations saying “this key was injected” and that would come out in the plan output.

One thing we were hoping to do was to have structured feedback as to what sections are causing errors in the job submission process (as in, maybe we disable raw_exec driver, and want to turn deprecations into errors). This would then allow clients to make changes to their code to conform to our own policies.

In the case of Warnings from those api endpoints, they aren’t even properly indented, so the faux-structure presented by the Nomad api isn’t the greatest for end users.

Attempted Solutions

No real solutions except for doing regex parsing of the error output, which is far from ideal.

tgross commented 3 years ago

Hi @josegonzalez! I hear your pain on this one for sure. The Create Job API does distinguish between Warnings that get returned as blob of strings but at least in the expected structure, but then errors come back unstructured. This is definitely something we want to improve; it does break backwards compatibility, so we have some design work to do across the whole API to make sure we're making changes in a way that doesn't disrupt existing users.