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!

API docs: https://www.nomadproject.io/api-docs/regions#regions-http-api

Add support for the Event Stream. The current very rough thinking is to

• Create an AsyncAPI specification
• Devise a way to serve the Event Stream over websockets rather than long polling
• Generate Websocket based clients from the specification

• Update make file to generate more language targets
• Language targets TBD

Functions such as nomad_client::apis::jobs_api::get_job_allocations, which access APIs that use X-Nomad-Nexttoken headers to express pagination, do not actually expose that header to the caller, preventing them from retrieving anything beyond the first page of results.

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?

• npm
• crates.io
• mavencentral

When using the OpenAPI client with Nomad clusters that have ACLs enabled, there is currently no way to set the ACL token on the client and therefore all requests are rejected by Nomad with a 403 error code.

Related: hashicorp/nomad-pack#110

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.

The search API endpoint is useful when wishing to identify any Nomad objects of a certain kind which are running with a specific prefix.

The jobName parameter in generator/v1api.go is erroneously named due to a similar available naming mistake in Nomad itself. This parameter should be renamed jobID to more accurately express what data is represented.

• Integrate with makefile
• Integrate with CI
• Experiment with dedicated channels

When instantiating a new client for use, it would be useful to have a simple ping/connectivity check that can be called before proceeding. This would help avoid situations where a lot of processing work is performed, to ultimately make a call with the client which will fail. I believe it will also improve the UX.

Workflow Name: Go Tests
Branch: main
Run URL: https://github.com/hashicorp/nomad-openapi/actions/runs/4166903825

save-state deprecation warnings: 0
set-output deprecation warnings: 0
node12 deprecation warnings: 1

Please review these deprecation warnings as soon as possible and merge in the necessary updates.

GitHub will be removing support for these commands and plan to fully disable them on 31st May 2023. At this time, any workflow that still utilizes these commands will fail. See https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/.

GitHub have not finalized a date for deprecating node12 yet but have indicated that this will be summer 2023. So it is advised to switch to node16 asap. See https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.

If you need any help, please reach out to us in #team-rel-eng.

Once this PR is released, we'll need to assess the OpenAPI for required changes.

Create Github action to execute tests on push/merge

Once this PR lands, Evaluations will be the first API to support pagination and filtering options.

We'll need to:

• Update the QueryOpts struct to support LastToken and deprecate NextToken.
• Update the setQueryOpts framework method and associated tests to manage the new parameter and warn on use of the deprecated parameter (possibly a new X-Deprecation-Warning header or something similar - need to design)
• Update the Evaluations generator code to include new supported query parameters
• Update the set of default query options in the generator code
• Regenerate clients

• Split client directory changes into a separate commit automatically
• Investigate if it could be a commit hook
• Investigate if it should create one commit per language

Every update will result in a big ol' PR like #124 until we've updated the generator to output proper copyright headers. Let's do this before we make any additional changes here.

Hi,

I just noticed that the Nomad Service Endpoints are missing.

Are there any plans to add those?

This has been requested on the nomad-pack project: hashicorp/nomad-pack#154

In a similar way to the Nomad token, users would like to be able to set the namespace via env vars. This matches the current behaviour with the Nomad CLI and in-tree core client.

Issue content copied from hashicorp/nomad-pack#153

Using username and password included in NOMAD_ADDR:

$ export NOMAD_ADDR=https://user:[email protected]/
$ nomad-pack run hello_world
! Failed To Parse Job Specification

        Error:   401 Unauthorized
        Type:    client.GenericOpenAPIError
        Context:
                 - Template Name: hello_world/templates/hello_world.nomad.tpl
                 - Registry Name: default
                 - Pack Name: hello_world
                 - Pack Ref: latest
                 - Deployment Name: hello_world@latest
$ nomad status
ID           Type     Priority  Status   Submit Date
hello_world  service  50        running  2021-10-24T13:04:06+02:00
traefik      service  50        running  2021-07-14T20:36:18+02:00

As you can see, nomad supports this way of authorization but nomad-pack doesn't

Note: details in NOMAD_ADDR were redacted due to security reasons

• Should ingest endpoint docs from website
• Should prefer godoc strings for schemas and fall back to website docs if not present

As an example the JobListStub is defined in the openapi.yml as:

JobListStub:
      properties:
        CreateIndex:
          maximum: 1.8446744073709552e+19
          minimum: 0
          type: integer

Which seems to generate the golang code without further validations:

// JobListStub struct for JobListStub
type JobListStub struct {
	CreateIndex *int32 `json:"CreateIndex,omitempty"`
	...
}

But for ruby/python validations are added:

    validations = {
        ('create_index',): {
            'inclusive_maximum': 384,
            'inclusive_minimum': 0,
        },
         ...
    }

    # Check to see if the all the properties in the model are valid
    # @return true if the model is valid
    def valid?
      return false if !@create_index.nil? && @create_index > 384
      return false if !@create_index.nil? && @create_index < 0
      return false if !@job_modify_index.nil? && @job_modify_index > 384
      return false if !@job_modify_index.nil? && @job_modify_index < 0
      return false if !@modify_index.nil? && @modify_index > 384
      return false if !@modify_index.nil? && @modify_index < 0
      true
    end

The ruby client seems to be a python client due to incorrect config file.
The current file states:

# File is used by the openapi-generator cli to generate a javascript client.
generatorName: python
gitUserId: hashicorp
gitRepoId: nomad-openapi/clients/ruby/v1
inputSpec: /local/v1/openapi.yaml
outputDir: /local/clients/ruby/v1
moduleName: NomadClient
packageVersion: 1.1.4
gemLicense: MPL 2.0

But I guess it should be:

# File is used by the openapi-generator cli to generate a ruby client.
generatorName: ruby <---
gitUserId: hashicorp
gitRepoId: nomad-openapi/clients/ruby/v1
inputSpec: /local/v1/openapi.yaml
outputDir: /local/clients/ruby/v1
moduleName: NomadClient
packageVersion: 1.1.4
gemLicense: MPL 2.0

A bit offtopic:

I am wondering what is the benefit of having all the clients generated in this repository? I think it would make more sense to either publish the generated clients to whatever package manager the language uses or to only keep the configuration files and document the command to generate any of the clients:

docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli:v5.2.0 batch --clean path/to/config.yaml

One potential option: https://github.com/matusf/openapi-fuzzer

Per the docs, blocking queries occur when a compatible API request is made with an index query parameter. However, the Rust client code sends index as a header, which Nomad then ignores.

The linked example is pervasive, and is likely due to this schema definition, which does not match the API docs.

Once this PR lands, we'll need to assess the impact on the OpenAPI and make the required adjustments.

In an attempt to standardize on POST, the generator did not support PUT configuration for endpoints. Community contributor @Neutrollized ran into some endpoints that only accept PUT. We need to update the generator to all PUT configuration.

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.

##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?

Review this PR and update with changes.

Update the Nomad version and add coverage for changes made since 1.1.4.