ydb_maintenance.proto

syntax = "proto3";
option cc_enable_arenas = true;

import "src/api/protos/annotations/validation.proto";
import "src/api/protos/ydb_discovery.proto";
import "src/api/protos/ydb_operation.proto";
import "src/api/protos/ydb_status_codes.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

package Ydb.Maintenance;
option java_package = "com.yandex.ydb.maintenance";

// Represents state of an abstract item: e.g. node or device.
enum ItemState {
    // Item's state couldn't be identified.
    ITEM_STATE_UNSPECIFIED = 0;
    // Item is up.
    ITEM_STATE_UP = 1;
    // Item is down due to planned maintenance.
    ITEM_STATE_MAINTENANCE = 2;
    // Item is down off-schedule.
    ITEM_STATE_DOWN = 3;
}

message Node {
    message StorageNode {
    }

    message DynamicNode {
        string tenant = 1;
    }

    uint32 node_id = 1;
    string host = 2;
    uint32 port = 3;
    Ydb.Discovery.NodeLocation location = 4;
    ItemState state = 5;
    oneof type {
        StorageNode storage = 6;
        DynamicNode dynamic = 7;
    }
    // start_time defines time when node was registered in cms.
    google.protobuf.Timestamp start_time = 8;
    // version defines YDB version for current Node.
    // For example, 'ydb-stable-24-1'.
    string version = 9;
}

message ListClusterNodesRequest {
    Ydb.Operations.OperationParams operation_params = 1;
}

message ListClusterNodesResult {
    repeated Node nodes = 1;
}

message ListClusterNodesResponse {
    // operation.result = ListClusterNodesResult
    Ydb.Operations.Operation operation = 1;
}

enum AvailabilityMode {
    AVAILABILITY_MODE_UNSPECIFIED = 0;

    // In this mode allowed:
    // - at most 1 unavailable disk in each affected storage group;
    // - at most 1 unavailable state storage ring.
    // For nodes tenant and cluster policies are followed.
    AVAILABILITY_MODE_STRONG = 1;

    // In this mode:
    // - total number of an unavailable disks in each affected storage group
    //   shouldn't exceed number of parity parts in that group;
    // - it is allowed to disable (n_to_select - 1) / 2 state storage rings.
    // Nodes are handled as in strong mode.
    AVAILABILITY_MODE_WEAK = 2;

    // Ignore any storage group & state storage checks.
    // Using this mode might cause data unavailability.
    AVAILABILITY_MODE_FORCE = 3;
}

message MaintenanceTaskOptions {
    // User-defined _unique_ task identifier.
    string task_uid = 1 [(length).le = 128];
    // User-defined description.
    string description = 2 [(length).le = 128];
    // Availability mode.
    AvailabilityMode availability_mode = 3;
    bool dry_run = 4;
    // Priority of the task. Lower value indicates higher priority.
    int32 priority = 5 [(value) = "[-100; 100]"];
}

// Used to describe the scope of a single action.
message ActionScope {
    message PDiskId {
        uint32 node_id = 1;
        uint32 pdisk_id = 2;
    }
    message PDiskLocation {
        string host = 1 [(length).le = 255];
        string path = 2 [(length).le = 255];
    }
    message PDisk {
        oneof pdisk {
            PDiskId pdisk_id = 1;
            PDiskLocation pdisk_location = 2;
        }
    }
    oneof scope {
        uint32 node_id = 1;
        string host = 2 [(length).le = 255];
        PDisk pdisk = 3;
    }
}

// Taking an exclusive lock to perform maintenance.
message LockAction {
    ActionScope scope = 1;
    google.protobuf.Duration duration = 2;
}

message Action {
    oneof action {
        LockAction lock_action = 1;
    }
}

message ActionGroup {
    repeated Action actions = 1 [(size).ge = 1];
}

message CreateMaintenanceTaskRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    MaintenanceTaskOptions task_options = 2;
    repeated ActionGroup action_groups = 3 [(size).ge = 1];
}

message RefreshMaintenanceTaskRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    string task_uid = 2 [(length).le = 128];
}

message ActionUid {
    string task_uid = 1 [(length).le = 128];
    // Unique ids within a single task, assigned by the server.
    string group_id = 2 [(length).le = 128];
    string action_id = 3 [(length).le = 128];
}

message ActionState {
    enum ActionStatus {
        ACTION_STATUS_UNSPECIFIED = 0;
        // Action can't be performed now.
        ACTION_STATUS_PENDING = 1;
        // Action performed: e.g. lock is taken.
        ACTION_STATUS_PERFORMED = 2;
    }

    enum ActionReason {
        ACTION_REASON_UNSPECIFIED = 0;
        // Everything is ok.
        ACTION_REASON_OK = 1;
        // Affected storage group has too many unavailable (locked or down) vdisks.
        ACTION_REASON_TOO_MANY_UNAVAILABLE_VDISKS = 2;
        // Too many unavailable state storage rings.
        ACTION_REASON_TOO_MANY_UNAVAILABLE_STATE_STORAGE_RINGS = 3;
        // Too many disabled nodes (storage & dynamic) in cluster.
        ACTION_REASON_DISABLED_NODES_LIMIT_REACHED = 4;
        // Too many disabled dynamic nodes of specific tenant.
        ACTION_REASON_TENANT_DISABLED_NODES_LIMIT_REACHED = 5;
        // Wrong request.
        ACTION_REASON_WRONG_REQUEST = 6;
        // Too many unavailable nodes with system tablets.
        ACTION_REASON_SYS_TABLETS_NODE_LIMIT_REACHED = 7;
        // Generic reason.
        ACTION_REASON_GENERIC = 8;
    }

    Action action = 1;
    ActionUid action_uid = 2;
    ActionStatus status = 3;
    ActionReason reason = 4;
    string reason_details = 6;
    google.protobuf.Timestamp deadline = 5;
}

message ActionGroupStates {
    repeated ActionState action_states = 1;
}

message MaintenanceTaskResult {
    string task_uid = 1;
    repeated ActionGroupStates action_group_states = 2;
    // Try again after this deadline. Specified if there are no performed actions.
    optional google.protobuf.Timestamp retry_after = 3;
    // The time when the mainteance task was created.
    google.protobuf.Timestamp create_time = 4;
    // The last time when the mainteance task was refreshed. Initially equals to create_time.
    google.protobuf.Timestamp last_refresh_time = 5;
}

message MaintenanceTaskResponse {
    // operation.result = MaintenanceTaskResult
    Ydb.Operations.Operation operation = 1;
}

message GetMaintenanceTaskRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    string task_uid = 2 [(length).le = 128];
}

message GetMaintenanceTaskResult {
    MaintenanceTaskOptions task_options = 1;
    repeated ActionGroupStates action_group_states = 2;
    // The time when the mainteance task was created.
    google.protobuf.Timestamp create_time = 3;
    // The last time when the mainteance task was refreshed. Initially equals to create_time.
    google.protobuf.Timestamp last_refresh_time = 4;
}

message GetMaintenanceTaskResponse {
    // operation.result = GetMaintenanceTaskResult
    Ydb.Operations.Operation operation = 1;
}

message ListMaintenanceTasksRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    // User SID (Security ID).
    // If specified, it will return the tasks created by this user.
    // Otherwise all tasks will be returned.
    optional string user = 2;
}

message ListMaintenanceTasksResult {
    repeated string tasks_uids = 1;
}

message ListMaintenanceTasksResponse {
    // operation.result = ListMaintenanceTasksResult
    Ydb.Operations.Operation operation = 1;
}

message DropMaintenanceTaskRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    string task_uid = 2 [(length).le = 128];
}

message ManageMaintenanceTaskResponse {
    Ydb.Operations.Operation operation = 1;
}

message CompleteActionRequest {
    Ydb.Operations.OperationParams operation_params = 1;
    repeated ActionUid action_uids = 2 [(size).ge = 1];
}

message ManageActionResult {
    message Status {
        ActionUid action_uid = 1;
        StatusIds.StatusCode status = 2;
    }

    repeated Status action_statuses = 1;
}

message ManageActionResponse {
    // operation.result = ManageActionResult
    Ydb.Operations.Operation operation = 1;
}