pipelines/backend/api/v2beta1/recurring_run.proto

// Copyright 2022 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 "backend/api/v2beta1/runtime_config.proto";
import "backend/api/v2beta1/run.proto";
import "google/protobuf/struct.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/rpc/status.proto";

service RecurringRunService {
  // Creates a new recurring run in an experiment, given the experiment ID.
  rpc CreateRecurringRun(CreateRecurringRunRequest) returns (RecurringRun) {
    option (google.api.http) = {
      post: "/apis/v2beta1/recurringruns"
      body: "recurring_run"
    };
  }

  // Finds a specific recurring run by ID.
  rpc GetRecurringRun(GetRecurringRunRequest) returns (RecurringRun) {
    option (google.api.http) = {
      get: "/apis/v2beta1/recurringruns/{recurring_run_id}"
      };
    }

  // Finds all recurring runs given experiment and namespace. 
  // If experiment ID is not specified, find all recurring runs across all experiments.
  rpc ListRecurringRuns(ListRecurringRunsRequest) returns (ListRecurringRunsResponse) {
    option (google.api.http) = {
      get: "/apis/v2beta1/recurringruns"
    };
  }

  // Restarts a recurring run that was previously stopped. All runs associated with the 
  // recurring run will continue.
  rpc EnableRecurringRun(EnableRecurringRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v2beta1/recurringruns/{recurring_run_id}:enable"
    };
  }

  // Stops a recurring run and all its associated runs. The recurring run is not deleted.
  rpc DisableRecurringRun(DisableRecurringRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v2beta1/recurringruns/{recurring_run_id}:disable"
    };
  }

  // Deletes a recurring run.
  rpc DeleteRecurringRun(DeleteRecurringRunRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v2beta1/recurringruns/{recurring_run_id}"
    };
  }
}

message RecurringRun {
  // Output. Unique run ID generated by API server.
  string recurring_run_id = 1;

  // Required input field. Recurring run name provided by user. Not unique.
  string display_name = 2;

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

  // Required input field. Specifies the source of the pipeline spec for this 
  // recurring run. Can be either a pipeline version id, or a pipeline spec.
  oneof pipeline_source {
    // The ID of the pipeline version used for creating runs.
    string pipeline_version_id = 4 [deprecated=true];
    // The pipeline spec.
    google.protobuf.Struct pipeline_spec = 5;
    // Reference to a pipeline version containing pipeline_id and pipeline_version_id.
    PipelineVersionReference pipeline_version_reference = 18;
  }

  // Runtime config of the pipeline. 
  RuntimeConfig runtime_config = 6;

  // Optional input field. Specifies which Kubernetes service account this recurring run uses.
  string service_account = 7;

  // Required input field.
  // Specifies how many runs can be executed concurrently. Range [1-10].
  int64 max_concurrency = 8;

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

  // Required input.
  // User setting to enable or disable the recurring run. 
  // Only used for creation of recurring runs. Later updates use enable/disable API.
  enum Mode {
    MODE_UNSPECIFIED = 0;
    ENABLE = 1;
    // The recurring run won't schedule any run if disabled.
    DISABLE = 2;
  }
  Mode mode = 10;

  // Output. The time this recurring run was created.
  google.protobuf.Timestamp created_at = 11;

  // Output. The last time this recurring run was updated.
  google.protobuf.Timestamp updated_at = 12;

  // Output. The status of the recurring run.
  enum Status {
    STATUS_UNSPECIFIED = 0;
    ENABLED = 1;
    DISABLED = 3;
  }
  Status status = 13;

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

  // Optional input field. Whether the recurring run should catch up if behind schedule.
  // If true, the recurring run will only schedule the latest interval if behind schedule.
  // If false, the recurring run will catch up on each past interval.
  bool no_catchup = 15;

  // TODO (gkclat): consider removing this field if it can be obtained from the parent experiment.
  // Output only. Namespace this recurring run belongs to. Derived from the parent experiment.
  string namespace = 16;

  // ID of the parent experiment this recurring run belongs to.
  string experiment_id = 17;
}

message CreateRecurringRunRequest {
  // The recurring run to be created.
  RecurringRun recurring_run = 1;
}

message GetRecurringRunRequest {
  // The ID of the recurring run to be retrieved.
  string recurring_run_id = 1;
}

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

  // The number of recurring runs to be listed per page. If there are more recurring 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 formatted as "field_name", "field_name asc" or "field_name desc".
  // Ascending by default.
  string sort_by = 3;

  // Optional input. The namespace the recurring runs belong to. 
  string namespace = 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;

  // The ID of the experiment to be retrieved. If empty, list recurring runs across all experiments.
  string experiment_id = 6;
}

message ListRecurringRunsResponse {
  // A list of recurring runs returned.
  repeated RecurringRun recurringRuns = 1;

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

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

message EnableRecurringRunRequest {
  // The ID of the recurring runs to be enabled.
  string recurring_run_id = 1;
}

message DisableRecurringRunRequest {
  // The ID of the recurring runs to be disabled.
  string recurring_run_id = 1;
}

message DeleteRecurringRunRequest {
  // The ID of the recurring run to be deleted.
  string recurring_run_id = 1;
}

// CronSchedule allow scheduling the recurring run 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 recurring run periodically with certain interval.
message PeriodicSchedule {
  // The start time of the periodic recurring run.
  google.protobuf.Timestamp start_time = 1;

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

  // The time interval between the starting time of consecutive recurring runs.
  int64 interval_second = 3;
}

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