path: root/contrib/libs/yandex-cloud-api-protos/yandex/cloud/mdb/kafka/v1/cluster_service.proto

syntax = "proto3";

package yandex.cloud.mdb.kafka.v1;

import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "yandex/cloud/api/operation.proto";
import "yandex/cloud/mdb/kafka/v1/cluster.proto";
import "yandex/cloud/mdb/kafka/v1/maintenance.proto";
import "yandex/cloud/mdb/kafka/v1/topic.proto";
import "yandex/cloud/mdb/kafka/v1/user.proto";
import "yandex/cloud/operation/operation.proto";
import "yandex/cloud/validation.proto";

option go_package = "github.com/yandex-cloud/go-genproto/yandex/cloud/mdb/kafka/v1;kafka";
option java_package = "yandex.cloud.api.mdb.kafka.v1";

// A set of methods for managing Apache Kafka® clusters.
service ClusterService {
  // Returns the specified Apache Kafka® cluster.
  //
  // To get the list of available Apache Kafka® clusters, make a [List] request.
  rpc Get(GetClusterRequest) returns (Cluster) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters/{cluster_id}"};
  }

  // Retrieves the list of Apache Kafka® clusters that belong to the specified folder.
  rpc List(ListClustersRequest) returns (ListClustersResponse) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters"};
  }

  // Creates a new Apache Kafka® cluster in the specified folder.
  rpc Create(CreateClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {
      post: "/managed-kafka/v1/clusters"
      body: "*"
    };
    option (yandex.cloud.api.operation) = {
      metadata: "CreateClusterMetadata"
      response: "Cluster"
    };
  }

  // Updates the specified Apache Kafka® cluster.
  rpc Update(UpdateClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {
      patch: "/managed-kafka/v1/clusters/{cluster_id}"
      body: "*"
    };
    option (yandex.cloud.api.operation) = {
      metadata: "UpdateClusterMetadata"
      response: "Cluster"
    };
  }

  // Deletes the specified Apache Kafka® cluster.
  rpc Delete(DeleteClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {delete: "/managed-kafka/v1/clusters/{cluster_id}"};
    option (yandex.cloud.api.operation) = {
      metadata: "DeleteClusterMetadata"
      response: "google.protobuf.Empty"
    };
  }

  // Moves the specified Apache Kafka® cluster to the specified folder.
  rpc Move(MoveClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {
      post: "/managed-kafka/v1/clusters/{cluster_id}:move"
      body: "*"
    };
    option (yandex.cloud.api.operation) = {
      metadata: "MoveClusterMetadata"
      response: "Cluster"
    };
  }

  // Starts the specified Apache Kafka® cluster.
  rpc Start(StartClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {post: "/managed-kafka/v1/clusters/{cluster_id}:start"};
    option (yandex.cloud.api.operation) = {
      metadata: "StartClusterMetadata"
      response: "Cluster"
    };
  }

  // Stops the specified Apache Kafka® cluster.
  rpc Stop(StopClusterRequest) returns (operation.Operation) {
    option (google.api.http) = {post: "/managed-kafka/v1/clusters/{cluster_id}:stop"};
    option (yandex.cloud.api.operation) = {
      metadata: "StopClusterMetadata"
      response: "Cluster"
    };
  }

  // Reschedule planned maintenance operation.
  rpc RescheduleMaintenance(RescheduleMaintenanceRequest) returns (operation.Operation) {
    option (google.api.http) = {
      post: "/managed-kafka/v1/clusters/{cluster_id}:rescheduleMaintenance"
      body: "*"
    };
    option (yandex.cloud.api.operation) = {
      metadata: "RescheduleMaintenanceMetadata"
      response: "Cluster"
    };
  }

  // Retrieves logs for the specified Apache Kafka® cluster.
  //
  // For more information about logs, see the [Logs](/docs/managed-kafka/operations/cluster-logs) section in the documentation.
  rpc ListLogs(ListClusterLogsRequest) returns (ListClusterLogsResponse) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters/{cluster_id}:logs"};
  }

  // Same as [ListLogs] but using server-side streaming. Also allows for `tail -f` semantics.
  rpc StreamLogs(StreamClusterLogsRequest) returns (stream StreamLogRecord) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters/{cluster_id}:stream_logs"};
  }

  // Retrieves the list of operations for the specified Apache Kafka® cluster.
  rpc ListOperations(ListClusterOperationsRequest) returns (ListClusterOperationsResponse) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters/{cluster_id}/operations"};
  }

  // Retrieves a list of hosts for the specified Apache Kafka® cluster.
  rpc ListHosts(ListClusterHostsRequest) returns (ListClusterHostsResponse) {
    option (google.api.http) = {get: "/managed-kafka/v1/clusters/{cluster_id}/hosts"};
  }
}

message GetClusterRequest {
  // ID of the Apache Kafka® Cluster resource to return.
  //
  // To get the cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
}

message ListClustersRequest {
  // ID of the folder to list Apache Kafka® clusters in.
  //
  // To get the folder ID, make a [yandex.cloud.resourcemanager.v1.FolderService.List] request.
  string folder_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // The maximum number of results per page to return.
  //
  // If the number of available results is larger than [page_size], the service returns a [ListClustersResponse.next_page_token] that can be used to get the next page of results in subsequent list requests.
  int64 page_size = 2 [(value) = "<=1000"];

  // Page token.
  //
  // To get the next page of results, set [page_token] to the [ListClustersResponse.next_page_token] returned by the previous list request.
  string page_token = 3 [(length) = "<=100"];

  // Filter support is not currently implemented. Any filters are ignored.
  string filter = 4 [(length) = "<=1000"];
}

message ListClustersResponse {
  // List of Apache Kafka® clusters.
  repeated Cluster clusters = 1;

  // Token that allows you to get the next page of results for list requests.
  //
  // If the number of results is larger than [ListClustersRequest.page_size], use [next_page_token] as the value for the [ListClustersRequest.page_token] parameter in the next list request.
  // Each subsequent list request will have its own [next_page_token] to continue paging through the results.
  string next_page_token = 2;
}

message CreateClusterRequest {
  reserved 9;
  // ID of the folder to create the Apache Kafka® cluster in.
  //
  // To get the folder ID, make a [yandex.cloud.resourcemanager.v1.FolderService.List] request.
  string folder_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // Name of the Apache Kafka® cluster. The name must be unique within the folder.
  string name = 2 [
    (required) = true,
    (length) = "1-63",
    (pattern) = "[a-z]([-a-z0-9]{0,61}[a-z0-9])?"
  ];

  // Description of the Apache Kafka® cluster.
  string description = 3 [(length) = "<=256"];

  // Custom labels for the Apache Kafka® cluster as `key:value` pairs.
  //
  // For example, "project": "mvp" or "source": "dictionary".
  map<string, string> labels = 4 [
    (yandex.cloud.size) = "<=64",
    (length) = "<=63",
    (pattern) = "[-_./\\@0-9a-z]*",
    (map_key).length = "1-63",
    (map_key).pattern = "[a-z][-_./\\@0-9a-z]*"
  ];

  // Deployment environment of the Apache Kafka® cluster.
  Cluster.Environment environment = 5;

  // Kafka and hosts configuration the Apache Kafka® cluster.
  ConfigSpec config_spec = 6;

  // One or more configurations of topics to be created in the Apache Kafka® cluster.
  repeated TopicSpec topic_specs = 7;

  // Configurations of accounts to be created in the Apache Kafka® cluster.
  repeated UserSpec user_specs = 8;

  // ID of the network to create the Apache Kafka® cluster in.
  string network_id = 10 [(length) = "<=50"];

  // IDs of subnets to create brokers in.
  repeated string subnet_id = 11;

  // User security groups
  repeated string security_group_ids = 12;

  // Host groups to place VMs of cluster on.
  repeated string host_group_ids = 13;

  // Deletion Protection inhibits deletion of the cluster
  bool deletion_protection = 14;

  // Window of maintenance operations.
  MaintenanceWindow maintenance_window = 15;
}

message CreateClusterMetadata {
  // ID of the Apache Kafka® cluster that is being created.
  string cluster_id = 1;
}

message UpdateClusterRequest {
  reserved 10;

  // ID of the Apache Kafka® cluster to update.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  google.protobuf.FieldMask update_mask = 2;

  // New description of the Apache Kafka® cluster.
  string description = 3 [(length) = "<=256"];

  // Custom labels for the Apache Kafka® cluster as `key:value` pairs.
  //
  // For example, "project": "mvp" or "source": "dictionary".
  //
  // The new set of labels will completely replace the old ones.
  // To add a label, request the current set with the [ClusterService.Get] method, then send an [ClusterService.Update] request with the new label added to the set.
  map<string, string> labels = 4 [
    (yandex.cloud.size) = "<=64",
    (length) = "<=63",
    (pattern) = "[-_0-9a-z]*",
    (map_key).length = "1-63",
    (map_key).pattern = "[a-z][-_0-9a-z]*"
  ];

  // New configuration and resources for hosts in the Apache Kafka® cluster.
  //
  // Use [update_mask] to prevent reverting all cluster settings that are not listed in [config_spec] to their default values.
  ConfigSpec config_spec = 5;

  // New name for the Apache Kafka® cluster.
  string name = 6 [
    (length) = "<=63",
    (pattern) = "[a-zA-Z0-9_-]*"
  ];

  // User security groups
  repeated string security_group_ids = 7;

  // Deletion Protection inhibits deletion of the cluster
  bool deletion_protection = 8;

  // New maintenance window settings for the cluster.
  MaintenanceWindow maintenance_window = 9;

  // IDs of subnets where the hosts are located or a new host is being created
  repeated string subnet_ids = 11;
}

message UpdateClusterMetadata {
  // ID of the Apache Kafka® cluster that is being updated.
  string cluster_id = 1;
}

message DeleteClusterRequest {
  // ID of the Apache Kafka® cluster to delete.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
}

message DeleteClusterMetadata {
  // ID of the Apache Kafka® cluster that is being deleted.
  string cluster_id = 1;
}

message ListClusterLogsRequest {
  // ID of the Apache Kafka® cluster to request logs for.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // Columns from the logs table to request.
  //
  // If no columns are specified, full log records are returned.
  repeated string column_filter = 2;

  // Start timestamp for the logs request.
  google.protobuf.Timestamp from_time = 3;

  // End timestamp for the logs request.
  google.protobuf.Timestamp to_time = 4;

  // The maximum number of results per page to return.
  //
  // If the number of available results is larger than [page_size], the service returns a [ListClusterLogsResponse.next_page_token] that can be used to get the next page of results in subsequent list requests.
  int64 page_size = 5 [(value) = "<=1000"];

  // Page token.
  //
  // To get the next page of results, set [page_token] to the [ListClusterLogsResponse.next_page_token] returned by the previous list request.
  string page_token = 6 [(length) = "<=100"];

  // The flag that defines behavior of providing the next page token.
  //
  // If this flag is set to `true`, this API method will always return [ListClusterLogsResponse.next_page_token], even if current page is empty.
  bool always_next_page_token = 7;

  // A filter expression that filters resources listed in the response.
  //
  // The expression must specify:
  // 1. The field name to filter by. Currently filtering can be applied to the `hostname` field.
  // 2. An `=` operator.
  // 3. The value in double quotes (`"`). Must be 1-63 characters long and match the regular expression `[a-z0-9.-]{1,61}`.
  //
  // Example of a filter: `message.hostname='node1.db.cloud.yandex.net'`
  string filter = 8 [(length) = "<=1000"];
}

// A single log record.
message LogRecord {
  // Log record timestamp.
  google.protobuf.Timestamp timestamp = 1;

  // Contents of the log record.
  map<string, string> message = 2;
}

message ListClusterLogsResponse {
  // Requested log records.
  repeated LogRecord logs = 1;

  // Token that allows you to get the next page of results for list requests.
  //
  // If the number of results is larger than [ListClusterLogsRequest.page_size], use [next_page_token] as the value for the [ListClusterLogsRequest.page_token] query parameter in the next list request.
  // Each subsequent list request will have its own [next_page_token] to continue paging through the results.
  // This value is interchangeable with [StreamLogRecord.next_record_token] from StreamLogs method.
  string next_page_token = 2;
}

message StreamLogRecord {
  // One of the requested log records.
  LogRecord record = 1;

  // This token allows you to continue streaming logs starting from the exact same record.
  //
  // To continue streaming, specify value of [next_record_token] as value for [StreamClusterLogsRequest.record_token] parameter in the next StreamLogs request.
  //
  // This value is interchangeable with [ListClusterLogsResponse.next_page_token] from ListLogs method.
  string next_record_token = 2;
}

message StreamClusterLogsRequest {
  // ID of the Apache Kafka® cluster.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // Columns from logs table to get in the response.
  //
  // If no columns are specified, full log records are returned.
  repeated string column_filter = 2;

  // Start timestamp for the logs request.
  google.protobuf.Timestamp from_time = 3;

  // End timestamp for the logs request.
  //
  // If this field is not set, all existing logs will be sent and then the new ones as they appear.
  // In essence it has `tail -f` semantics.
  google.protobuf.Timestamp to_time = 4;

  // Record token.
  //
  // Set [record_token] to the [StreamLogRecord.next_record_token] returned by a previous [ClusterService.StreamLogs] request to start streaming from next log record.
  string record_token = 5 [(length) = "<=100"];

  // A filter expression that filters resources listed in the response.
  //
  // The expression must specify:
  // 1. The field name to filter by. Currently filtering can be applied to the `hostname` field.
  // 2. An `=` operator.
  // 3. The value in double quotes (`"`). Must be 3-63 characters long and match the regular expression `[a-z][-a-z0-9]{1,61}[a-z0-9]`.
  //
  // Example of a filter: `message.hostname='node1.db.cloud.yandex.net'`
  string filter = 6 [(length) = "<=1000"];
}

message ListClusterOperationsRequest {
  // ID of the Apache Kafka® cluster to list operations for.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // The maximum number of results per page to return.
  //
  // If the number of available results is larger than [page_size], the service returns a [ListClusterOperationsResponse.next_page_token] that can be used to get the next page of results in subsequent list requests.
  int64 page_size = 2 [(value) = "<=1000"];

  // Page token.
  //
  // To get the next page of results, set [page_token] to the [ListClusterOperationsResponse.next_page_token] returned by the previous list request.
  string page_token = 3 [(length) = "<=100"];
}

message ListClusterOperationsResponse {
  // List of operations for the specified Apache Kafka® cluster.
  repeated operation.Operation operations = 1;

  // Token that allows you to get the next page of results for list requests.
  //
  // If the number of results is larger than [ListClusterOperationsRequest.page_size], use [next_page_token] as the value for the [ListClusterOperationsRequest.page_token] query parameter in the next list request.
  // Each subsequent list request will have its own [next_page_token] to continue paging through the results.
  string next_page_token = 2;
}

message ListClusterHostsRequest {
  // ID of the Apache Kafka® cluster.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // The maximum number of results per page to return.
  //
  // If the number of available results is larger than [page_size], the service returns a [ListClusterHostsResponse.next_page_token] that can be used to get the next page of results in subsequent list requests.
  int64 page_size = 2 [(value) = "<=1000"];

  // Page token.
  //
  // To get the next page of results, set [page_token] to the [ListClusterHostsResponse.next_page_token] returned by the previous list request.
  string page_token = 3 [(length) = "<=100"];
}

message ListClusterHostsResponse {
  // List of hosts.
  repeated Host hosts = 1;

  // Token that allows you to get the next page of results for list requests.
  //
  // If the number of results is larger than [ListClusterHostsRequest.page_size], use the [next_page_token] as the value for the [ListClusterHostsRequest.page_token] query parameter in the next list request.
  // Each subsequent list request will have its own [next_page_token] to continue paging through the results.
  string next_page_token = 2;
}

message MoveClusterRequest {
  // ID of the Apache Kafka® cluster to move.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  // ID of the destination folder.
  string destination_folder_id = 2 [
    (required) = true,
    (length) = "<=50"
  ];
}

message MoveClusterMetadata {
  // ID of the Apache Kafka® cluster being moved.
  string cluster_id = 1;

  // ID of the source folder.
  string source_folder_id = 2;

  // ID of the destnation folder.
  string destination_folder_id = 3;
}

message StartClusterRequest {
  // ID of the Apache Kafka® cluster to start.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
}

message StartClusterMetadata {
  // ID of the Apache Kafka® cluster.
  string cluster_id = 1;
}

message StopClusterRequest {
  // ID of the Apache Kafka® cluster to stop.
  //
  // To get the Apache Kafka® cluster ID, make a [ClusterService.List] request.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
}

message StopClusterMetadata {
  // ID of the Apache Kafka® cluster.
  string cluster_id = 1;
}

message RescheduleMaintenanceRequest {
  // ID of the Kafka cluster to reschedule the maintenance operation for.
  string cluster_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];

  enum RescheduleType {
    RESCHEDULE_TYPE_UNSPECIFIED = 0;

    // Start the maintenance operation immediately.
    IMMEDIATE = 1;

    // Start the maintenance operation within the next available maintenance window.
    NEXT_AVAILABLE_WINDOW = 2;

    // Start the maintenance operation at the specific time.
    SPECIFIC_TIME = 3;
  }

  // The type of reschedule request.
  RescheduleType reschedule_type = 2 [(required) = true];

  // The time until which this maintenance operation should be delayed. The value should be ahead of the first time when the maintenance operation has been scheduled for no more than two weeks. The value can also point to the past moment of time if [reschedule_type.IMMEDIATE] reschedule type is chosen.
  google.protobuf.Timestamp delayed_until = 3;
}

message RescheduleMaintenanceMetadata {
  reserved 2 to 3;
  // ID of the Kafka cluster.
  string cluster_id = 1;

  // The time until which this maintenance operation is to be delayed.
  google.protobuf.Timestamp delayed_until = 4;
}