pipelines/backend/api/v1beta1/job.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/v1beta1/go_client";
package api;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "backend/api/v1beta1/pipeline_spec.proto";
import "backend/api/v1beta1/resource_reference.proto";
import "protoc-gen-swagger/options/annotations.proto";
import "backend/api/v1beta1/error.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 JobService {
  // Creates a new job.
  rpc CreateJob(CreateJobRequest) returns (Job) {
    option (google.api.http) = {
      post: "/apis/v1beta1/jobs"
      body: "job"
    };
  }

  // Finds a specific job by ID.
  rpc GetJob(GetJobRequest) returns (Job) {
    option (google.api.http) = {
      get: "/apis/v1beta1/jobs/{id}"
    };
  }

  // Finds all jobs.
  rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) {
    option (google.api.http) = {
      get: "/apis/v1beta1/jobs"
    };
  }

  // Restarts a job that was previously stopped. All runs associated with the job will continue.
  rpc EnableJob(EnableJobRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/jobs/{id}/enable"
    };
  }

  // Stops a job and all its associated runs. The job is not deleted.
  rpc DisableJob(DisableJobRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v1beta1/jobs/{id}/disable"
    };
  }

  // Deletes a job.
  rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v1beta1/jobs/{id}"
    };
  }
}

message CreateJobRequest {
  // The job to be created
  Job job = 1;
}

message GetJobRequest {
  // The ID of the job to be retrieved
  string id = 1;
}

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

  // The number of jobs to be listed per page. If there are more jobs 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".
  // Ascending by default.
  string sort_by = 3;

  // What resource reference to filter on.
  // E.g. If listing job 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/v1beta1/filter.proto)).
  string filter = 5;
}

message ListJobsResponse {
  // A list of jobs returned.
  repeated Job jobs = 1;

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

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

message DeleteJobRequest {
  // The ID of the job to be deleted
  string id = 1;
}

message EnableJobRequest {
  // The ID of the job to be enabled
  string id = 1;
}

message DisableJobRequest {
  // The ID of the job to be disabled
  string id = 1;
}

// CronSchedule allow scheduling the job with unix-like cron
message CronSchedule {
  // The start time of the cron job
  google.protobuf.Timestamp start_time = 1;

  // The end time of the cron job
  google.protobuf.Timestamp end_time = 2;

  // The cron string. For details how to compose a cron, visit
  // ttps://en.wikipedia.org/wiki/Cron
  string cron = 3;
}

// PeriodicSchedule allow scheduling the job periodically with certain interval
message PeriodicSchedule {
  // The start time of the periodic job
  google.protobuf.Timestamp start_time = 1;

  // The end time of the periodic job
  google.protobuf.Timestamp end_time = 2;

  // The time interval between the starting time of consecutive jobs
  int64 interval_second = 3;
}

// Trigger defines what starts a pipeline run.
message Trigger {
  oneof trigger {
    CronSchedule cron_schedule = 1;
    PeriodicSchedule periodic_schedule = 2;
  }
}

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

  // Required input field. Job name provided by user. Not unique.
  string name = 2;

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

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

  // Optional input field. Specify which resource this job belongs to.
  repeated ResourceReference resource_references = 5;

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

  // Required input field.
  // Specify how many runs can be executed concurrently. Rage [1-10]
  int64 max_concurrency = 6;

  // Required input field.
  // Specify how a run is triggered. Support cron mode or periodic mode.
  Trigger trigger = 7;

  // Required input.
  enum Mode {
    UNKNOWN_MODE = 0;
    ENABLED = 1;
    // The job won't schedule any run if disabled.
    DISABLED = 2;
  }
  Mode mode = 8;

  // Output. The time this job is created.
  google.protobuf.Timestamp created_at = 9;

  // Output. The last time this job is updated.
  google.protobuf.Timestamp updated_at = 10;

  // Output. The status of the job.
  // One of [Enable, Disable, Error]
  string status = 11;

  // In case any error happens retrieving a job field, only job 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;

  // Input. Whether the job is enabled or not.
  bool enabled = 16;

  // Optional input field. Whether the job should catch up if behind schedule.
  // If true, the job will only schedule the latest interval if behind schedule.
  // If false, the job will catch up on each past interval.
  bool no_catchup = 17;
}
// Next field number of Job will be 19