gRPC API

The gRPC protocol created by Google is a remoting protocol that has efficiencies over a REST interface. gRPC supports multiple programming languages. At this time, we only provide examples in the Go programming language.

The runner service is accessed using TLS which provides encryption in transit, and allows the client to authenticate the service. In addition an API key is provided in the gRPC message metadata which authorizes the administrator or application access to the provided APIs. The service validates that the API key is allowed access to the operation. Operations are split into two categories, administration and application. Administrative APIs should generally be accessed through the Nextmv CLI.

A set of integration tests provided as part of the samples during installation/update show how to do each of the operations provided by the runner API. Additionally a gRPC client wrapper (grpc_client.go) in the sample application shows how to submit various types of runs. Integration test data is also provided as part of the sample so that you can test your installation running the integration tests to verify everything is operational.

Shared Definitions enum RunStatus = REQUESTED, STARTED, SUCCEEDED, FAILED, TIMED_OUT

message Status {
  RunStatus status
  string error
}

StartRun

StartRun Input Message

message StartRunRequest {
  string owner
  string job_name
  string job_version
  map<string, string> metadata
  string pool_id
  bytes  input
}

StartRun Output Message

message StartRunResponse {
  string run_id
  RunStatus status
  google.protobuf.Timestamp created_at
}

GetRunStatus

GetRunStatus Input Message

message GetRunRequest {
  string run_id
}

GetRunStatus Output Message

message GetRunStatusResponse {
  string run_id
  Status last_status
  string owner
}

GetRunOutput

GetRunOutput Input Message

message GetRunRequest {
  string run_id
}

GetRunOutput Output Message

message DataDownloadResponse {
  string run_id
  string downloadUrl
}

GetRunInput

GetRunInput Input Message

message GetRunRequest {
  string run_id
}

GetRunInput Output Message

message DataDownloadResponse {
  string run_id
  string downloadUrl
}

CreateArtifact

CreateArtifact Input Message

message CreateArtifactRequest {
  string key
  string namespace
  string account_id
  string location_url
}

Artifacts generically represent customer created objects like binaries that will be used by the runner. The combination of key+namespace+accountId must be unique across all artifacts. When the system is installed a bucket is created in the form <appId>-nextmv-private-artifact-upload-<region> to which the service has read access. So for example if your appId is driver-1, and the service is deployed to eu-west-1, then the bucket would be driver-1-nextmv-private-artifact-upload-eu-west-1.

CreateArtifact Output Message

message Metadata {
  string schema_version
  string uri
  string key
  string namespace
  string account_id
  google.protobuf.Timestamp created_at
  int64 size
}

message CreateArtifactResponse {
  Metadata artifact
}

CreateSecret

CreateSecret Input Message

message CreateSecretRequest {
  string key
  string namespace
  string account_id
  bytes value
}

The only job that uses a secret key is Onfleet. The URI for the key is specified in the Onfleet input schema. The values of key, namespace, and account_id are used to form a unique identifier for the key, and must be unique. This supports future operations like listing all keys for an account, or account and namespace. If you don't foresee needing that functionality, then you can always assign the same namespace and account for all keys.

CreateSecret Output Message

message Secret {
  string schema_version
  string uri
  string key
  string namespace
  string account_id
  google.protobuf.Timestamp created_at
  bytes value
}

message SecretResponse {
  Secret secret
}

DeleteSecret

DeleteSecret Input Message

message DeleteSecretRequest { string uri }

DeleteSecret Output Message

message DeleteSecretResponse {}