• added path templates for ACL Policies and ACL Tokens APIs
• added 2 new in-path parameters in v1api.go:

1. aclPolicyNameParam (added "acl" prefix to avoid potential conflicts with other policy names -- such as Sentinel)
2. tokenAccessorParam

Issue: generator/system.go is supposed to use POST and not PUT, but Nomad's agent/system_endpoint.go only accepts PUT. As a result, the v1/system_test.go gets a 405 invalid method error which is absolutely valid.

What I've tried: changing http.MethodPost to http.MethodPut, and make v1 builds successfully but then test will complain about v1/system.go's SystemApi

How sure how to approach it at this point :(

Ready for review. I'll do a follow-up for Keyring once this has been merged so that I'm not reworking both with the same comments emerging from any misunderstanding I have of what I'm supposed to be doing here. 😀

There's a few bits in the generator README that don't appear to be up-to-date, and I'm not sure if those are just not a problem anymore or if I'm got something silently failing:

• The number of operations per path doesn't appear to be really capped at 3.
• PUT being deprecated for POST isn't something that's happening in the v1 Nomad API as far as I've seen.
• I'm not sure what a "test client" is but it doesn't seem to be referred to anywhere else in that doc other than at the end.

Also, what's the expectations around the "higher level API" package here? I've done some spot checks and it doesn't actually look higher-level to me.

The Nomad OperatorAutopilotConfiguration handler supports PUT operations, and accepts WriteOpts parameters, but it does not set the index or any other WriteMeta values. OperatorServerHealth has the same issue but for GET.

There aren't helpers in the api.go file yet that handle a responses with this shape. We need to add them so that the client WriteOpts or QueryOpts will be set. Currently, the workaround is to use ExecRequest which works for unit tests and simple scenarios, but silently ignore any WriteOpts or QueryOpts set by callers.

The Nomad API returns null values quite often for several fields. Without the nullable: true property OpenAPI clients will throw an error when trying to parse the response.

Example from a Python script:

nomad_client.exceptions.ApiTypeError: Invalid type for variable 'networks'. Required value type is list and passed type was NoneType at ['received_data'][0]['allocated_resources']['tasks']['redis']['networks']

I set nullable: true to all array, object and date-time strings, but I didn't check if all these fields can actually be null.

I think the impact of mistakenly setting a field as nullable is that the generated clients will use a different data type, so client consumers may need to check for null values even if the API never returns null.

Since there's no official documentation on which fields can or cannot return a null maybe it's better to be safe? 😅

Hi @DerekStrickland ,

I've been struggling with the Operator API a bit and will need you help in completing this.

In generator/operator.go, the following are not implemented:

• licenses
• snapshots (get & restore), I'm just not sure how to handle the streaming output :|

In v1/operator_tests.go, I have tests written for everything else, but also have a bunch commented out due to errors that I'm unsure of how to handle.

Currently, TLS is only configured if all of CA, client certificate and client key are provided. This also includes tlsSkipVerify, which makes it mostly useless as it is only respected if you also provide a CA and client cert.

In addition, it's currently impossible to specify just the CA without setting a client certificate.

We can fix this by setting only the configuration provided, which is also in line with how nomad behaves.

Hello,

from what I can see there exists no such endpoint nomad/v1/allocation/<id> in the openapi spec.

On my running instance (v1.2.3) I found the endpoint and it seems to return additional information.

The only way to get my required information was to perform v1/allocations?resources=true&task_states=true which produces way more content than necessary and requires additional filtering on the allocation id of interest.

Is there any chance that this endpoint will make it in the openapi spec?

Thanks!

Hi @DerekStrickland !

For the status-api, I find that the make tests fail consistently for TestGetStatusLeader and TestGetStatusPeers with the following:

127.0.0.1:9732 2021-11-12T16:14:46.196-0500 [ERROR] http: request failed: method=GET path=/v1/status/leader error="No cluster leader" code=500
127.0.0.1:9732 2021-11-12T16:14:46.197-0500 [DEBUG] http: request complete: method=GET path=/v1/status/leader duration=402.382µs
    status_test.go:16:
                Error Trace:    status_test.go:16
                                                        api_test.go:33
                                                        status_test.go:11
                Error:          Received unexpected error:
                                500 Internal Server Error
                Test:           TestGetStatusLeader
127.0.0.1:9732 2021-11-12T16:14:46.197-0500 [DEBUG] http: shutting down http server

But running the tests individually passes with no issue.

GETs (using require.Contains to match only the IP and ':' as the port is a random high number port in the 9000's)

• return value contains 127.0.0.1: for /v1/status/leader
• returns list with 1 element for /v1/status/peers
• returned list element value contains 127.0.0.1: for /v1/status/peers

##Problem

• Currently, the API exposes the RPC QueryOptions/WriteOptions on input/output structs returned from the primary Nomad API package.
• This is confusing as a user because all of those options are also accepted as parameters (query or header).
• It would be less confusing to users if the generated request/response models excluded those structs and could rely solely on the parameters.
• Currently, the generated models have setters for the embedded struct fields, but the framework ignores them and instead consumes the passed parameters
• Uninitiated contributors might easily make the mistake of bypassing the parameter parsing methodology if they rely on IntelliSense discovery rather than looking at existing implementations.
• Inclusion of these embedded structs bloats the generated models, the payload size, and the generated YAML.
• I'd like to remove these embedded structs from the request/response models, but I am unsure if it is safe to do so.
• Generally, the handler code maps the input parameters to the RPC structs before making RPC calls, but not having been through all the handlers yet, I am unclear if this is always guaranteed.

@schmichael @jrasell Can one of you weigh in on whether this will be safe to do, or point me in the direction of the best person to ask?

Updated the following to use the new helper functions:

• v1/status.go
• v1/operator.go

I think this should be it, but opening it draft mode as I plan to do a quick review of the other endpoints to see if these new helpers fit there as well.

In the openapi spec, when the type is array, the generated python validation code will complain when the value is null, which the nomad restful API does return. For example, if I call:

    configuration = nomad_client.Configuration(host="http://127.0.01:4646/v1")
    api_client = nomad_client.ApiClient(configuration)
    api_instance = JobsApi(api_client)
    job_name = HELLO_WORLD_JOB_NAME
    job_status = api_instance.get_job(job_name)
    print(job_status)

the get_job call should return a job, but a number of fields such as constraints are returned null, but it is defined as array type in the openapi spec. The same with object type. The openapi solution seems to be adding nullable: true to these fields, but there are a lot of them. Not sure what is the best solution to automatically fix this.

Hi,

maybe I'm overlooking something but the pip install as mentioned in the readme doesn't work me

~/temp/foo via 🐍 v3.9.12 (foovenv)
❯ pip install git+https://github.com/hashicorp/nomad-openapi/clients/python/v1.git
Collecting git+https://github.com/hashicorp/nomad-openapi/clients/python/v1.git
  Cloning https://github.com/hashicorp/nomad-openapi/clients/python/v1.git to /private/var/folders/zt/4d___54j41q5xhgw80pcmtyh0000gn/T/pip-req-build-clmb4zx8
  Running command git clone --filter=blob:none --quiet https://github.com/hashicorp/nomad-openapi/clients/python/v1.git /private/var/folders/zt/4d___54j41q5xhgw80pcmtyh0000gn/T/pip-req-build-clmb4zx8
  remote: Not Found
  fatal: Repository 'https://github.com/hashicorp/nomad-openapi/clients/python/v1.git/' not found
  error: subprocess-exited-with-error

  × git clone --filter=blob:none --quiet https://github.com/hashicorp/nomad-openapi/clients/python/v1.git /private/var/folders/zt/4d___54j41q5xhgw80pcmtyh0000gn/T/pip-req-build-clmb4zx8 did not run successfully.
  │ exit code: 128
  ╰─> See above for output.

Any suggestions?