pipelines/backend/api/run.proto

// Copyright 2018 The Kubeflow Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

option go_package = "github.com/kubeflow/pipelines/backend/api/go_client";
package api;

import "backend/api/error.proto";
import "google/protobuf/empty.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "backend/api/pipeline_spec.proto";
import "backend/api/resource_reference.proto";
import "protoc-gen-swagger/options/annotations.proto";

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
  responses: {
    key: "default";
    value: {
      schema: {
        json_schema: {
          ref: ".api.Status";
        }
      }
    }
  }
  // Use bearer token for authorizing access to job service.
  // Kubernetes client library(https://kubernetes.io/docs/reference/using-api/client-libraries/)
  // uses bearer token as default for authorization. The section below
  // ensures security definition object is generated in the swagger definition.
  // For more details see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityDefinitionsObject
  security_definitions: {
    security: {
      key: "Bearer";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "authorization";
      }
    }
  }
  security: {
    security_requirement: {
      key: "Bearer";
      value: {};
    }
  }
};


service RunService {
  // Creates a new run.
  rpc CreateRun(CreateRunRequest) returns (RunDetail) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs"
      body: "run"
    };
  }

  // Finds a specific run by ID.
  rpc GetRun(GetRunRequest) returns (RunDetail) {
    option (google.api.http) = {
      get: "/apis/v1beta1/runs/{run_id}"
    };
  }

  // Finds all runs.
  rpc ListRuns(ListRunsRequest) returns (ListRunsResponse) {
    option (google.api.http) = {
      get: "/apis/v1beta1/runs"
    };
  }

  // Archives a run.
  rpc ArchiveRun(ArchiveRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs/{id}:archive"
    };
  }

  // Restores an archived run.
  rpc UnarchiveRun(UnarchiveRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs/{id}:unarchive"
    };
  }

  // Deletes a run.
  rpc DeleteRun(DeleteRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v1beta1/runs/{id}"
    };
  }

  // ReportRunMetrics reports metrics of a run. Each metric is reported in its
  // own transaction, so this API accepts partial failures. Metric can be
  // uniquely identified by (run_id, node_id, name). Duplicate reporting will be
  // ignored by the API. First reporting wins.
  rpc ReportRunMetrics(ReportRunMetricsRequest)
      returns (ReportRunMetricsResponse) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs/{run_id}:reportMetrics"
      body: "*"
    };
  }

  // Finds a run's artifact data.
  rpc ReadArtifact(ReadArtifactRequest) returns (ReadArtifactResponse) {
    option (google.api.http) = {
      get: "/apis/v1beta1/runs/{run_id}/nodes/{node_id}/artifacts/{artifact_name}:read"
    };
  }

  // Terminates an active run.
  rpc TerminateRun(TerminateRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs/{run_id}/terminate"
    };
  }

  // Re-initiates a failed or terminated run.
  rpc RetryRun(RetryRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/runs/{run_id}/retry"
    };
  }
}

message CreateRunRequest {
  Run run = 1;
}

message GetRunRequest {
  // The ID of the run to be retrieved.
  string run_id = 1;
}

message ListRunsRequest {
  // A page token to request the next page of results. The token is acquried
  // from the nextPageToken field of the response from the previous
  // ListRuns call or can be omitted when fetching the first page.
  string page_token = 1;

  // The number of runs to be listed per page. If there are more runs than this
  // number, the response message will contain a nextPageToken field you can use
  // to fetch the next page.
  int32 page_size = 2;

  // Can be format of "field_name", "field_name asc" or "field_name desc"
  // (Example, "name asc" or "id desc"). Ascending by default.
  string sort_by = 3;

  // What resource reference to filter on.
  // E.g. If listing run for an experiment, the query string would be
  // resource_reference_key.type=EXPERIMENT&resource_reference_key.id=123
  ResourceKey resource_reference_key = 4;

  // A url-encoded, JSON-serialized Filter protocol buffer (see
  // [filter.proto](https://github.com/kubeflow/pipelines/blob/master/backend/api/filter.proto)).
  string filter = 5;
}

message TerminateRunRequest {
  // The ID of the run to be terminated.
  string run_id = 1;
}

message RetryRunRequest {
  // The ID of the run to be retried.
  string run_id = 1;
}

message ListRunsResponse {
  repeated Run runs = 1;

  // The total number of runs for the given query.
  int32 total_size = 3;

  // The token to list the next page of runs.
  string next_page_token = 2;
}

message ArchiveRunRequest {
  // The ID of the run to be archived.
  string id = 1;
}

message UnarchiveRunRequest {
  // The ID of the run to be restored.
  string id = 1;
}

message DeleteRunRequest {
  // The ID of the run to be deleted.
  string id = 1;
}

message Run {
  // Output. Unique run ID. Generated by API server.
  string id = 1;

  // Required input field. Name provided by user,
  // or auto generated if run is created by scheduled job. Not unique.
  string name = 2;

  enum StorageState {
    STORAGESTATE_AVAILABLE = 0;
    STORAGESTATE_ARCHIVED = 1;
  }

  // Output. Specify whether this run is in archived or available mode.
  StorageState storage_state = 10;

  // Optional input field. Describing the purpose of the run
  string description = 3;

  // Required input field.
  // Describing what the pipeline manifest and parameters to use for the run.
  PipelineSpec pipeline_spec = 4;

  // Optional input field. Specify which resource this run belongs to.
  // When creating a run from a particular pipeline version, the pipeline
  // version can be specified here.
  repeated ResourceReference resource_references = 5;

  // Optional input field. Specify which Kubernetes service account this run uses.
  string service_account = 14;

  // Output. The time that the run created.
  google.protobuf.Timestamp created_at = 6;

  // Output. When this run is scheduled to run. This could be different from
  // created_at. For example, if a run is from a backfilling job that was
  // supposed to run 2 month ago, the scheduled_at is 2 month ago,
  // v.s. created_at is the current time.
  google.protobuf.Timestamp scheduled_at = 7;

  // Output. The time this run is finished.
  google.protobuf.Timestamp finished_at = 13;

  // Output. The status of the run.
  // One of [Pending, Running, Succeeded, Skipped, Failed, Error]
  string status = 8;

  // In case any error happens retrieving a run field, only run ID
  // and the error message is returned. Client has the flexibility of choosing
  // how to handle error. This is especially useful during listing call.
  string error = 12;

  // Output. The metrics of the run. The metrics are reported by ReportMetrics
  // API.
  repeated RunMetric metrics = 9;
}
// Next field number of Run will be 15

message PipelineRuntime {
  // Output. The runtime JSON manifest of the pipeline, including the status
  // of pipeline steps and fields need for UI visualization etc.
  string pipeline_manifest = 10;

  // Output. The runtime JSON manifest of the argo workflow.
  // This is deprecated after pipeline_runtime_manifest is in use.
  string workflow_manifest = 11;
}

message RunDetail {
  Run run = 1;
  PipelineRuntime pipeline_runtime = 2;
}

message RunMetric {
  // Required. The user defined name of the metric. It must between 1 and 63
  // characters long and must conform to the following regular expression:
  // `[a-z]([-a-z0-9]*[a-z0-9])?`.
  string name = 1;

  // Required. The runtime node ID which reports the metric. The node ID can be
  // found in the RunDetail.workflow.Status. Metric with same (node_id, name)
  // are considerd as duplicate. Only the first reporting will be recorded. Max
  // length is 128.
  string node_id = 2;

  oneof value {
    // The number value of the metric.
    double number_value = 3;
  }

  enum Format {
    // Default value if not present.
    UNSPECIFIED = 0;
    // Display value as its raw format.
    RAW = 1;
    // Display value in percentage format.
    PERCENTAGE = 2;
  }
  // The display format of metric.
  Format format = 4;
}

message ReportRunMetricsRequest {
  // Required. The parent run ID of the metric.
  string run_id = 1;

  // List of metrics to report.
  repeated RunMetric metrics = 2;
}

message ReportRunMetricsResponse {
  message ReportRunMetricResult {
    // Output. The name of the metric.
    string metric_name = 1;

    // Output. The ID of the node which reports the metric.
    string metric_node_id = 2;

    enum Status {
      // Default value if not present.
      UNSPECIFIED = 0;
      // Indicates successful reporting.
      OK = 1;
      // Indicates that the payload of the metric is invalid.
      INVALID_ARGUMENT = 2;
      // Indicates that the metric has been reported before.
      DUPLICATE_REPORTING = 3;
      // Indicates that something went wrong in the server.
      INTERNAL_ERROR = 4;
    }
    // Output. The status of the metric reporting.
    Status status = 3;

    // Output. The detailed message of the error of the reporting.
    string message = 4;
  }
  repeated ReportRunMetricResult results = 1;
}

message ReadArtifactRequest {
  // The ID of the run.
  string run_id = 1;
  // The ID of the running node.
  string node_id = 2;
  // The name of the artifact.
  string artifact_name = 3;
}

message ReadArtifactResponse {
  // The bytes of the artifact content.
  bytes data = 1;
}