This SDK requires at least a Java 7 runtime.
val api = NomadScalaApi("http://my.nomad.server:4646");
Methods are grouped into into API groupings according to their function, and these groupings can be accessed from the client. For example, to list the jobs running on the cluster, use the
list method on the jobs API grouping:
val responseFuture: ServerQueryResponse[Seq[JobListStub]] = api.jobs.list()
The result is a
ServerQueryResponse. The API has a few different response types, depending on the type of query. The response classes have some methods for getting metadata about the response, and a
getValue method that returns the response value. The generic type parameter in the response class indicates the response value type, so in this case,
getValue will return a sequence of
Endpoints that interact with server APIs accept
WriteOptions, which let you specify additional options when making a request.
WriteOptions allow you to specify a region to support cross-region requests. Requests sent to a Nomad server are bound to a particular region; if no region is specified, the server assumes the request is bound for its own region. You can specify an explicit region per-request using the options, and you can specify a client-wide default in the client configuration. You can also rely on the default behaviour.
Note on Terminology
Nomad agents can operate as Nomad servers which perform scheduling, or Nomad clients which connect to servers and run the task groups they are assigned, or both (see the Nomad glossary). Regardless of their client and/or server roles in the Nomad cluster, all agents have an embedded HTTP server that serves the Nomad HTTP API. This Java API makes use of an HTTP client to connect to that API, and is thus a Nomad HTTP API client.
So be aware that there are two conflicting meanings of "client" in scope.
NomadApiClient is the main API client class, and has nothing to do with the Nomad client concept. The
ClientApi class, on the other hand, is the API for interacting with Nomad client agents.
The SDK is built with sbt. You can use
scripts/build.sh to run a build, provided an appropriate Nomad executable is available for tests as described below.
The tests make use of Nomad's
mock_driver, a driver for test purposes that isn't built into Nomad by default. To build Nomad with
mock_driver support, you will need Go, a properly configured
GOPATH, and the Nomad source, which you can clone with git or with
go get, e.g.:
go get github.com/hashicorp/nomad
You will then need to pass the
nomad_test flag passed to the Go compiler when building Nomad, e.g. the follow will put a Nomad executable in
go install -tags nomad_test github.com/hashicorp/nomad
You can then run the tests with this executable on the
PATH="$GOPATH/bin:$PATH" sbt test