Tutorials

gRPC API

Using the gRPC protocol with Nextmv private cloud

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.

Security

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.

Operations

Administrative Operations
BootstrapInitializes the service installation
CreateApiKeyCreates an administrator or application key
DeactivateApiKeyDeactivates an administrator or application key

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.

Application Operations
StartRunInitiates a job run, which gets scheduled to a worker pool for processing
GetRunStatusGets the current status of a submitted run
GetRunOutputGets the output for a run
GetRunInputGets the input of a run
CreateArtifactCreates an artifact for use with a run
DeleteArtifactDeletes an artifact
CreateSecretCreates a secret to use for a job run
DeleteSecretDeletes a secret

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
}
FieldValue
ownerA logical identifier tracked for the run owner. The runner tracks this for you but doesn't do anything with it.
job_nameThe name of the job - this will be one of the following values: Fleet, version: 1; Onfleet, version: 1; Binary, version: 1; SDK, version: 1 (coming soon)
job_versionThe version of the job to run. See versions from job_name values above.
metadataString name-value pairs to track related to the job run
pool_idThe pool identifier to assign this run to process
inputThe input for the job. For fleet and Onfleet, the input adheres to the JSON schema for those services. For binary and SDK runs, the input is a JSON object that adheres to: { ArtifactURI: string, Input: string } Where the ArtifactURI identifies the binary/sdk artifact to execute, and Input is a base64 encoded string. When running binary or SDK runs, the input is written directly to stdin and read by the binary, and output is saved from stdout as the output of the run.
StartRun Output Message
message StartRunResponse {
  string run_id
  RunStatus status
  google.protobuf.Timestamp created_at
}
FieldValue
run_idA unique identifier for the run
statusAn enumerated value with one of the following values: REQUESTED, STARTED, SUCCEEDED, FAILED, TIMED_OUT
created_atA gRPC timestamp representing the time the run was submitted to the runner

GetRunStatus

GetRunStatus Input Message
message GetRunRequest {
  string run_id
}
FieldValue
run_idThe ID of the run to get status for
GetRunStatus Output Message
message GetRunStatusResponse {
  string run_id
  Status last_status
  string owner
}
FieldValue
run_idA unique identifier for the run
last_status.statusAn enumerated value with one of the following values: REQUESTED, STARTED, SUCCEEDED, FAILED, TIMED_OUT
last_status.errorIf the status is FAILED, then this field contains the error message for the failure.
ownerThe owner of this run

GetRunOutput

GetRunOutput Input Message
message GetRunRequest {
  string run_id
}
FieldValue
run_idThe ID of the run to get output for
GetRunOutput Output Message
message DataDownloadResponse {
  string run_id
  string downloadUrl
}
FieldValue
run_idA unique identifier for the run
downloadUrlA temporary URL used download the output result

GetRunInput

GetRunInput Input Message
message GetRunRequest {
  string run_id
}
FieldValue
run_idThe ID of the run to get input for
GetRunInput Output Message
message DataDownloadResponse {
  string run_id
  string downloadUrl
}
FieldValue
run_idA unique identifier for the run
downloadUrlA temporary URL used download the original input

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.

FieldValue
keyIdentifier for this artifact
namespaceThe namespace for this artifact. This can be any string.
account_idAn account for this artifact. This can be any string.
location_urlAn s3 url for the location of the artifact binary or tarball. For example s3://driver-1-nextmv-private-artifact-upload-eu-west-1/apps/my-driver-binary
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
}
FieldValue
artifact.schema_versionThe schema version identifier for interpreting this artifact. This can be ignored.
artifact.uriThe unique identifier for the artifact. You should store this value to reference the artifact when using it in input.
artifact.keyThe key for the artifact
artifact.namespaceThe namespace for the artifact
artifact.account_idThe account ID for the artifact
artifact.created_atThe timestamp the artifact was created
artifact.sizeThe size of the 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.

FieldValue
keyIdentifier for this key (ex Onfleet)
namespaceThe namespace for this key. This can be any string.
account_idAn account for this key. This can be any string.
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
}
FieldValue
secret.schema_versionThe schema version identifier for interpreting this secret message. This can be ignored.
secret.uriThe unique identifier for the secret. You should store this value to reference the secret when using it in input.
secret.keyThe key name assigned to this secret
secret.namespaceThe namespaced assigned to this secret
secret.account_idThe account ID assigned to this secret
secret.created_atThe timestamp the secret was created
secret.valueThe decrypted value to use for this secret

DeleteSecret

DeleteSecret Input Message
message DeleteSecretRequest { string uri }
FieldValue
uriThe URI of the key to delete
DeleteSecret Output Message
message DeleteSecretResponse {}

Page last updated

Go to on-page nav menu