329 lines
10 KiB
Protocol Buffer
329 lines
10 KiB
Protocol Buffer
// 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/v2beta1/go_client";
|
|
package kubeflow.pipelines.backend.api.v2beta1;
|
|
|
|
import "google/api/annotations.proto";
|
|
import "google/protobuf/timestamp.proto";
|
|
import "google/protobuf/empty.proto";
|
|
import "google/protobuf/struct.proto";
|
|
import "google/rpc/status.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: ".google.rpc.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 PipelineService {
|
|
// Creates a pipeline.
|
|
rpc CreatePipeline(CreatePipelineRequest) returns (Pipeline) {
|
|
option (google.api.http) = {
|
|
post: "/apis/v2beta1/pipelines"
|
|
body: "pipeline"
|
|
};
|
|
}
|
|
|
|
// Finds a specific pipeline by ID.
|
|
rpc GetPipeline(GetPipelineRequest) returns (Pipeline) {
|
|
option (google.api.http) = {
|
|
get: "/apis/v2beta1/pipelines/{pipeline_id}"
|
|
};
|
|
}
|
|
|
|
// Finds a specific pipeline by name and namespace.
|
|
rpc GetPipelineByName(GetPipelineByNameRequest) returns (Pipeline) {
|
|
option (google.api.http) = {
|
|
get: "/apis/v2beta1/pipelines/names/{name}"
|
|
};
|
|
}
|
|
|
|
// Finds all pipelines within a namespace.
|
|
rpc ListPipelines(ListPipelinesRequest) returns (ListPipelinesResponse) {
|
|
option (google.api.http) = {
|
|
get: "/apis/v2beta1/pipelines"
|
|
};
|
|
}
|
|
|
|
// Deletes an empty pipeline by ID. Returns error if the pipeline has pipeline versions.
|
|
rpc DeletePipeline(DeletePipelineRequest) returns (google.protobuf.Empty) {
|
|
option (google.api.http) = {
|
|
delete: "/apis/v2beta1/pipelines/{pipeline_id}"
|
|
};
|
|
}
|
|
|
|
// Creates a new pipeline and a new pipeline version in a single transaction.
|
|
rpc CreatePipelineAndVersion(CreatePipelineAndVersionRequest) returns (Pipeline) {
|
|
option (google.api.http) = {
|
|
post: "/apis/v2beta1/pipelines/create"
|
|
body: "*"
|
|
};
|
|
}
|
|
|
|
// Adds a pipeline version to the specified pipeline ID.
|
|
rpc CreatePipelineVersion(CreatePipelineVersionRequest)
|
|
returns (PipelineVersion) {
|
|
option (google.api.http) = {
|
|
post: "/apis/v2beta1/pipelines/{pipeline_id}/versions"
|
|
body: "pipeline_version"
|
|
};
|
|
}
|
|
|
|
// Gets a pipeline version by pipeline version ID and pipeline ID.
|
|
rpc GetPipelineVersion(GetPipelineVersionRequest) returns (PipelineVersion) {
|
|
option (google.api.http) = {
|
|
get: "/apis/v2beta1/pipelines/{pipeline_id}/versions/{pipeline_version_id}"
|
|
};
|
|
}
|
|
|
|
// Lists all pipeline versions of a given pipeline ID.
|
|
rpc ListPipelineVersions(ListPipelineVersionsRequest)
|
|
returns (ListPipelineVersionsResponse) {
|
|
option (google.api.http) = {
|
|
get: "/apis/v2beta1/pipelines/{pipeline_id}/versions"
|
|
};
|
|
}
|
|
|
|
// Deletes a specific pipeline version by pipeline version ID and pipeline ID.
|
|
rpc DeletePipelineVersion(DeletePipelineVersionRequest)
|
|
returns (google.protobuf.Empty) {
|
|
option (google.api.http) = {
|
|
delete: "/apis/v2beta1/pipelines/{pipeline_id}/versions/{pipeline_version_id}"
|
|
};
|
|
}
|
|
}
|
|
|
|
message Pipeline {
|
|
// Output. Unique pipeline ID. Generated by API server.
|
|
string pipeline_id = 1;
|
|
|
|
// Required input field. Pipeline name provided by user.
|
|
string display_name = 2;
|
|
|
|
// Optional input field. A short description of the pipeline.
|
|
string description = 3;
|
|
|
|
// Output. Creation time of the pipeline.
|
|
google.protobuf.Timestamp created_at = 4;
|
|
|
|
// Input. A namespace this pipeline belongs to.
|
|
// Causes error if user is not authorized to access the specified namespace.
|
|
// If not specified in CreatePipeline, default namespace is used.
|
|
string namespace = 5;
|
|
|
|
// In case any error happens retrieving a pipeline field, only pipeline ID,
|
|
// and the error message is returned. Client has the flexibility of choosing
|
|
// how to handle the error. This is especially useful during listing call.
|
|
google.rpc.Status error = 6;
|
|
}
|
|
|
|
message PipelineVersion {
|
|
// Required input field. Unique ID of the parent pipeline.
|
|
// This is ignored in CreatePipelineAndVersion API.
|
|
string pipeline_id = 1;
|
|
|
|
// Output. Unique pipeline version ID. Generated by API server.
|
|
string pipeline_version_id = 2;
|
|
|
|
// Required input field. Pipeline version name provided by user.
|
|
// This is ignored in CreatePipelineAndVersion API.
|
|
string display_name = 3;
|
|
|
|
// Optional input field. Short description of the pipeline version.
|
|
// This is ignored in CreatePipelineAndVersion API.
|
|
string description = 4;
|
|
|
|
// Output. Creation time of the pipeline version.
|
|
google.protobuf.Timestamp created_at = 5;
|
|
|
|
// Input. Required. The URL to the source of the pipeline version.
|
|
// This is required when creating the pipeine version through
|
|
// CreatePipelineVersion or CreatePipelineAndVersion API.
|
|
Url package_url = 6;
|
|
|
|
// Input. Optional. The URL to the code source of the pipeline version.
|
|
// The code is usually the Python definition of the pipeline and potentially
|
|
// related the component definitions. This allows users to trace back to how
|
|
// the pipeline YAML was created.
|
|
string code_source_url = 9;
|
|
|
|
// Output. The pipeline spec for the pipeline version.
|
|
google.protobuf.Struct pipeline_spec = 7;
|
|
|
|
// In case any error happens retrieving a pipeline version field, only
|
|
// pipeline ID, pipeline version ID, and the error message are returned.
|
|
// Client has the flexibility of choosing how to handle the error.
|
|
// This is especially useful during List() calls.
|
|
google.rpc.Status error = 8;
|
|
}
|
|
|
|
message Url {
|
|
// URL of the pipeline version definition.
|
|
string pipeline_url = 1;
|
|
}
|
|
|
|
message CreatePipelineRequest {
|
|
// Required input. Pipeline that needs to be created.
|
|
Pipeline pipeline = 1;
|
|
}
|
|
|
|
message GetPipelineRequest {
|
|
// Required input. The ID of the pipeline to be retrieved.
|
|
string pipeline_id = 1;
|
|
}
|
|
|
|
message ListPipelinesRequest {
|
|
// Optional input. Namespace for the pipelines.
|
|
string namespace = 1;
|
|
|
|
// A page token to request the results page.
|
|
string page_token = 2;
|
|
|
|
// The number of pipelines to be listed per page. If there are more pipelines
|
|
// than this number, the response message will contain a valid value in the
|
|
// nextPageToken field.
|
|
int32 page_size = 3;
|
|
|
|
// Sorting order in form of "field_name", "field_name asc" or "field_name desc".
|
|
// Ascending by default.
|
|
string sort_by = 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 ListPipelinesResponse {
|
|
// Returned pipelines.
|
|
repeated Pipeline pipelines = 1;
|
|
|
|
// The total number of pipelines for the given query.
|
|
int32 total_size = 2;
|
|
|
|
// The token to list the next page of pipelines.
|
|
// This token can be used on the next ListPipelinesRequest.
|
|
string next_page_token = 3;
|
|
}
|
|
|
|
message GetPipelineByNameRequest {
|
|
// Optional input. Namespace of the pipeline.
|
|
// It could be empty if default namespaces needs to be used or if multi-user
|
|
// support is turned off.
|
|
string namespace = 1;
|
|
|
|
// Required input. Name of the pipeline to be retrieved.
|
|
string name = 2;
|
|
}
|
|
|
|
message DeletePipelineRequest {
|
|
// Required input. ID of the pipeline to be deleted.
|
|
string pipeline_id = 1;
|
|
}
|
|
|
|
message CreatePipelineAndVersionRequest {
|
|
// Required input. Pipeline (parent) to be created.
|
|
Pipeline pipeline = 1;
|
|
|
|
// Required input. Pipeline version (child) to be created.
|
|
// Pipeline spec will be downloaded from pipeline_version.package_url.
|
|
PipelineVersion pipeline_version = 2;
|
|
}
|
|
|
|
message CreatePipelineVersionRequest {
|
|
// Required input. ID of the parent pipeline.
|
|
string pipeline_id = 1;
|
|
|
|
// Required input. Pipeline version ID to be created.
|
|
PipelineVersion pipeline_version = 2;
|
|
}
|
|
|
|
message GetPipelineVersionRequest {
|
|
// Required input. ID of the parent pipeline.
|
|
string pipeline_id = 1;
|
|
|
|
// Required input. ID of the pipeline version to be retrieved.
|
|
string pipeline_version_id = 2;
|
|
}
|
|
|
|
message ListPipelineVersionsRequest {
|
|
// Required input. ID of the parent pipeline.
|
|
string pipeline_id = 1;
|
|
|
|
// A page token to request the results page.
|
|
string page_token = 2;
|
|
|
|
// The number of pipeline versions to be listed per page. If there are more pipeline
|
|
// versions than this number, the response message will contain a valid value in the
|
|
// nextPageToken field.
|
|
int32 page_size = 3;
|
|
|
|
// Sorting order in form of "field_name", "field_name asc" or "field_name desc".
|
|
// Ascending by default.
|
|
string sort_by = 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 ListPipelineVersionsResponse {
|
|
// Returned pipeline versions.
|
|
repeated PipelineVersion pipeline_versions = 1;
|
|
|
|
// The token to list the next page of pipeline versions.
|
|
string next_page_token = 2;
|
|
|
|
// The total number of pipeline versions for the given query.
|
|
int32 total_size = 3;
|
|
}
|
|
|
|
message DeletePipelineVersionRequest {
|
|
// Required input. ID of the parent pipeline.
|
|
string pipeline_id = 1;
|
|
|
|
// Required input. The ID of the pipeline version to be deleted.
|
|
string pipeline_version_id = 2;
|
|
} |