• Michael Schurter's avatar
    docs: update json jobs docs (#12766) · e4d6d510
    Michael Schurter authored
    * docs: update json jobs docs
    
    Did you know that Nomad has not 1 but 2 JSON formats for jobs? 2½ if you
    want to acknowledge that sometimes our JSON job representations have a
    Job top-level wrapper and sometimes do not.
    
    The 2½ formats are:
    ```
     1.   HCL JSON
     2.   Input API JSON (top-level Job field)
     2.5. Output API JSON (lacks top-level Job field)
    ```
    
    `#2` is what our docs consider our API JSON. `#2.5` seems to be an
    accident of history we can't fix with breaking API compatibility.
    
    `#1` is an even more interesting accident of history: the `jobspec2`
    package automatically detects if the input to Parse is JSON and switches
    to a JSON parser. This behavior is undocumented, the format is
    unspecified, and there is no official HashiCorp tooling to produce this
    JSON from HCL. The plot thickens when you discover popular third party
    tools like hcl2json.com and https://github.com/tmccombs/hcl2json seem to
    produce JSON that `nomad run` accepts!
    
    Since we have no telemetry around whether or not anyone passes HCL JSON
    to `nomad run`, and people don't file bugs around features that Just
    Work, I'm choosing to leave that code path in place and *acknowledged
    but not suggested* in documentation.
    
    See https://github.com/hashicorp/hcl/issues/498
    
     for a more comprehensive
    discussion of what officially supporting HCL JSON in Nomad would look
    like.
    
    (I also added some of the missing fields to the (Input API flavor) JSON
    Job documentation, but it still needs a lot of work to be
    comprehensive.)
    Co-authored-by: default avatarTim Gross <tgross@hashicorp.com>
    e4d6d510