isabella232 / nomad-scala-sdk

A Scala SDK for interfacing with HashiCorp's Nomad

Nomad Scala SDK

A Scala SDK for interacting with HashiCorp's Nomad through its HTTP API. This is a wrapper around the Java SDK.

This SDK requires at least a Java 8 runtime.

Using

Create a NomadScalaApi.

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 JobListStubs.

Request Options

Endpoints that interact with server APIs accept ScalaQueryOptions or WriteOptions, which let you specify additional options when making a request.

ScalaQueryOptions supports stale queries, and blocking queries. It also supports repeated performing blocking queries until a condition is met.

Regions

Both ScalaQueryOptions or 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.

Building

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.

Testing

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 $GOPATH/bin/:

go install -tags nomad_test github.com/hashicorp/nomad

You can then run the tests with this executable on the PATH, e.g.:

PATH="$GOPATH/bin:$PATH" sbt test