From 0176f939cba41e23c90bc6e7973314eacc518267 Mon Sep 17 00:00:00 2001 From: ulya-sidorina Date: Mon, 30 Dec 2024 15:08:05 +0100 Subject: [PATCH] doc(ydbcp): add comments to proto files --- pkg/proto/ydbcp/v1alpha1/backup.proto | 24 ++++++++- .../ydbcp/v1alpha1/backup_schedule.proto | 32 ++++++++--- .../v1alpha1/backup_schedule_service.proto | 54 +++++++++++++++---- pkg/proto/ydbcp/v1alpha1/backup_service.proto | 54 +++++++++++++++---- pkg/proto/ydbcp/v1alpha1/operation.proto | 20 ++++++- .../ydbcp/v1alpha1/operation_service.proto | 19 ++++++- 6 files changed, 173 insertions(+), 30 deletions(-) diff --git a/pkg/proto/ydbcp/v1alpha1/backup.proto b/pkg/proto/ydbcp/v1alpha1/backup.proto index 6d6fa22a..18c29bdf 100644 --- a/pkg/proto/ydbcp/v1alpha1/backup.proto +++ b/pkg/proto/ydbcp/v1alpha1/backup.proto @@ -24,29 +24,49 @@ message Backup { RUNNING = 6; DELETING = 7; } + // Unique identifier for the backup. string id = 1; + // An identifier of an external resource which holds the record about the backup + // (it can be the container id where the database is located). string container_id = 2; + // Name of the database for which the backup was created. string database_name = 3; + // GRPC endpoint of the database. string database_endpoint = 4; + // S3 location where the backup is stored. S3Location location = 5; + // Audit information for the backup. AuditInfo audit = 6; + // Size of the backup in bytes. int64 size = 7; + // Current status of the backup. Status status = 8; + // Message associated with the backup status. string message = 9; + // Timestamp when the backup will expire. google.protobuf.Timestamp expire_at = 10; + // Unique identifier for the schedule that initiated the backup. string schedule_id = 11; - repeated string source_paths = 12; + // List of source paths included in the backup (empty list means backup of root directory). + repeated string source_paths = 12; // [(size) = "<=256"]; } message S3Location { + // S3 endpoint. string endpoint = 1; + // S3 bucket name. string bucket = 2; + // S3 region. string region = 3; + // Path prefix in the S3 bucket. string path_prefix = 4; } message AuditInfo { + // Creator of the backup, YDBCP receives this info from the IAM. string creator = 1; + // Timestamp when the TakeBackup operation was created. google.protobuf.Timestamp created_at = 2; + // Timestamp when the TakeBackup operation was completed. google.protobuf.Timestamp completed_at = 3; -} +} \ No newline at end of file diff --git a/pkg/proto/ydbcp/v1alpha1/backup_schedule.proto b/pkg/proto/ydbcp/v1alpha1/backup_schedule.proto index a0280f4b..e7a81eba 100644 --- a/pkg/proto/ydbcp/v1alpha1/backup_schedule.proto +++ b/pkg/proto/ydbcp/v1alpha1/backup_schedule.proto @@ -9,19 +9,30 @@ import "google/protobuf/timestamp.proto"; message BackupSchedulePattern { + // Crontab expression defining the schedule. string crontab = 1; } message BackupScheduleSettings { + // Pattern for scheduling backups. BackupSchedulePattern schedule_pattern = 1; + // Time-to-live for the backups created by this schedule. google.protobuf.Duration ttl = 2; + // Recovery point objective duration (maximum length of time permitted, that data can be restored). google.protobuf.Duration recovery_point_objective = 3; } message ScheduledBackupInfo { + // Unique identifier for the backup. string backup_id = 1; + // Current recovery point + // (the datetime at which the last successful backup has been taken). google.protobuf.Timestamp recovery_point = 2; + // Margin interval for the last backup's rpo + // (how much time was left to break the rpo at the moment when the last backup completed, + // negative means is has been broken). google.protobuf.Duration last_backup_rpo_margin_interval = 3; + // Margin ratio for the last backup's rpo (the same as the previous as a share of the rpo). double last_backup_rpo_margin_ratio = 4; } @@ -33,22 +44,29 @@ message BackupSchedule { DELETED = 3; } - //backup settings + // Unique identifier for the backup schedule. string id = 1; + // An identifier of an external resource which holds the record about the backup + // (it can be the container id where the database is located). string container_id = 2; + // Name of the database associated with the backup schedule. string database_name = 3; + // GRPC endpoint of the database. string endpoint = 4; + // List of source paths included in the backup (empty list means backup of root directory). repeated string source_paths = 5; // [(size) = "<=256"]; + // List of source paths to exclude from the backup. repeated string source_paths_to_exclude = 6; // [(size) = "<=256"]; - + // Audit information for the backup schedule. ydbcp.v1alpha1.AuditInfo audit = 7; - + // Name of the backup schedule. string schedule_name = 8; + // Current status of the backup schedule. Status status = 9; - + // Settings for the backup schedule. BackupScheduleSettings schedule_settings = 10; - + // Timestamp for the next scheduled backup. google.protobuf.Timestamp next_launch = 11; - + // Information about the last successful backup. ScheduledBackupInfo last_successful_backup_info = 12; -} +} \ No newline at end of file diff --git a/pkg/proto/ydbcp/v1alpha1/backup_schedule_service.proto b/pkg/proto/ydbcp/v1alpha1/backup_schedule_service.proto index cd8c93e1..ba2785c7 100644 --- a/pkg/proto/ydbcp/v1alpha1/backup_schedule_service.proto +++ b/pkg/proto/ydbcp/v1alpha1/backup_schedule_service.proto @@ -5,68 +5,104 @@ option go_package = "github.com/ydb-platform/ydbcp/pkg/proto/ydbcp/v1alpha1;ydbc import "ydbcp/v1alpha1/backup_schedule.proto"; +// Service for managing backup schedules. +// YDB auth token can be passed via GRPC request metadata using authorization header. service BackupScheduleService { + // Creates a new backup schedule. + // Required YDB permissions: `ydb.databases.backup` rpc CreateBackupSchedule (CreateBackupScheduleRequest) returns (BackupSchedule); + + // Updates an existing backup schedule by its ID. + // Required YDB permissions: `ydb.databases.backup` rpc UpdateBackupSchedule (UpdateBackupScheduleRequest) returns (BackupSchedule); + + // Retrieves a backup schedule by its ID. + // Required YDB permissions: `ydb.databases.get` rpc GetBackupSchedule (GetBackupScheduleRequest) returns (BackupSchedule); + + // Lists all backup schedules for a specified container. + // Required YDB permissions: `ydb.databases.list` rpc ListBackupSchedules (ListBackupSchedulesRequest) returns (ListBackupSchedulesResponse); + + // Toggles the state of a backup schedule by its ID. + // Required YDB permissions: `ydb.databases.backup` rpc ToggleBackupSchedule (ToggleBackupScheduleRequest) returns (BackupSchedule); + + // Deletes a backup schedule by its ID. + // Required YDB permissions: `ydb.databases.backup` rpc DeleteBackupSchedule (DeleteBackupScheduleRequest) returns (BackupSchedule); } message CreateBackupScheduleRequest { - //fields of MakeBackupRequest to schedule + // An identifier of an external resource which holds the record about the backup + // (it can be the container id where the database is located). string container_id = 1; + // The name of the database for which schedule will be created. string database_name = 2; + // GRPC endpoint of the database. string endpoint = 3; + // List of source paths included in the backup (empty list means backup of root directory). repeated string source_paths = 4; // [(size) = "<=256"]; + // List of source paths to exclude from the backup. repeated string source_paths_to_exclude = 5; // [(size) = "<=256"]; - + // The name of the backup schedule. string schedule_name = 6; + // The settings for the backup schedule. BackupScheduleSettings schedule_settings = 7; } message UpdateBackupScheduleRequest { + // The ID of the backup schedule to update. string id = 1; - //fields of MakeBackupRequest to schedule + // List of source paths included in the backup (empty list means backup of root directory). repeated string source_paths = 2; // [(size) = "<=256"]; + // List of source paths to exclude from the backup. repeated string source_paths_to_exclude = 3; // [(size) = "<=256"]; - + // The name of the backup schedule. string schedule_name = 4; + // The settings for the backup schedule. BackupScheduleSettings schedule_settings = 5; } message ListBackupSchedulesRequest { + // The ID of the container for which to list backup schedules. string container_id = 1; + // A mask to filter operations by database name using LIKE operator for pattern matching (ex.: "your_db_prefix%"). + // For more information about LIKE operator, see the https://ydb.tech/docs/en/yql/reference/syntax/expressions#check-match. string database_name_mask = 2; + // A list of statuses to filter backup schedules. repeated BackupSchedule.Status display_status = 3; - // The maximum number of results per page that should be returned. If the number of available // results is larger than `page_size`, the service returns a `next_page_token` that can be used // to get the next page of results in subsequent ListBackupSchedules requests. // Acceptable values are 0 to 1000, inclusive. Default value: 100. - uint32 page_size = 1000; // [(value) = "0-1000"]; - + uint32 page_size = 1000; // Page token. Set `page_token` to the `next_page_token` returned by a previous ListBackups // request to get the next page of results. - string page_token = 1001; // [(length) = "<=100"]; + string page_token = 1001; } message ListBackupSchedulesResponse { + // The list of backup schedules. repeated BackupSchedule schedules = 1; + // The token for the next page of results. string next_page_token = 2; } message GetBackupScheduleRequest { + // The ID of the backup schedule to retrieve. string id = 1; } message ToggleBackupScheduleRequest { + // The ID of the backup schedule to toggle. string id = 1; + // The new state of the backup schedule (true - active, false - inactive). bool active_state = 2; } message DeleteBackupScheduleRequest { + // The ID of the backup schedule to delete. string id = 1; -} +} \ No newline at end of file diff --git a/pkg/proto/ydbcp/v1alpha1/backup_service.proto b/pkg/proto/ydbcp/v1alpha1/backup_service.proto index 63b91b2c..df1ec32c 100644 --- a/pkg/proto/ydbcp/v1alpha1/backup_service.proto +++ b/pkg/proto/ydbcp/v1alpha1/backup_service.proto @@ -7,31 +7,50 @@ import "ydbcp/v1alpha1/backup.proto"; import "ydbcp/v1alpha1/operation.proto"; import "google/protobuf/duration.proto"; -message ListBackupsOrder { - BackupField field = 1; - bool desc = 2; -} - -// A set of methods for managing backups;. +// A set of methods for managing backups. +// YDB auth token can be passed via GRPC request metadata using authorization header. service BackupService { + // Returns the list of backups for the specified container. + // Required YDB permissions: `ydb.databases.list` rpc ListBackups(ListBackupsRequest) returns (ListBackupsResponse); // Returns the specified backup. - rpc GetBackup (GetBackupRequest) returns (Backup); + // Required YDB permissions: `ydb.databases.get` + rpc GetBackup(GetBackupRequest) returns (Backup); + // Creates a backup of the specified database. + // Required YDB permissions: `ydb.databases.backup` rpc MakeBackup(MakeBackupRequest) returns (Operation); + // Deletes the specified backup and returns DeleteBackup operation. + // Required YDB permissions: `ydb.databases.backup` rpc DeleteBackup(DeleteBackupRequest) returns (Operation); + // Restores the specified backup and returns MakeRestore operation. + // Required YDB permissions: `ydb.tables.create` rpc MakeRestore(MakeRestoreRequest) returns (Operation); + // Updates the TTL of the specified backup. + // Required YDB permissions: `ydb.databases.backup` rpc UpdateBackupTtl(UpdateBackupTtlRequest) returns (Backup); } +message ListBackupsOrder { + // The field by which to order the backups. + BackupField field = 1; + // The order for the backups (true - descending, false - ascending). + bool desc = 2; +} + message ListBackupsRequest { + // The ID of the container for which to list backups. string container_id = 1; + // A mask to filter operations by database name using LIKE operator for pattern matching (ex.: "your_db_prefix%"). + // For more information about LIKE operator, see the https://ydb.tech/docs/en/yql/reference/syntax/expressions#check-match. string database_name_mask = 2; + // A list of statuses to filter backups. repeated Backup.Status display_status = 3; + // The order in which to list the backups. ListBackupsOrder order = 4; // The maximum number of results per page that should be returned. If the number of available @@ -47,40 +66,57 @@ message ListBackupsRequest { } message ListBackupsResponse { + // The list of backups. repeated Backup backups = 1; + // The token for the next page of results. string next_page_token = 2; } message GetBackupRequest { + // The ID of the backup to retrieve. string id = 1; } message MakeBackupRequest { + // An identifier of an external resource which holds the record about the backup + // (it can be the container id where the source database is located). string container_id = 1; + // The name of the database for which the backup will be created. string database_name = 2; + // GRPC endpoint of the database. string database_endpoint = 3; - // Full path to a table or directory. Empty source_paths means backup of root directory. + // List of source paths included in the backup (empty list means backup of root directory). repeated string source_paths = 4; // [(size) = "<=256"]; // Regexp for paths excluded from backup. repeated string source_paths_to_exclude = 5; // [(size) = "<=256"]; + // The time-to-live for the backup. google.protobuf.Duration ttl = 6; } message DeleteBackupRequest { + // The ID of the backup to delete. string backup_id = 1; } message MakeRestoreRequest { + // An identifier of an external resource which holds the record about the backup + // (it can be the container id where the target database is located). string container_id = 1; + // The ID of the backup to restore. string backup_id = 2; + // The name of the database to restore. string database_name = 3; + // GRPC endpoint of the database. string database_endpoint = 4; + // The prefix for the destination path. string destination_prefix = 5; // Paths to s3 objects to restore. repeated string source_paths = 6; } message UpdateBackupTtlRequest { + // The ID of the backup to update. string backup_id = 1; + // The new time-to-live for the backup. google.protobuf.Duration ttl = 2; -} +} \ No newline at end of file diff --git a/pkg/proto/ydbcp/v1alpha1/operation.proto b/pkg/proto/ydbcp/v1alpha1/operation.proto index 569aa998..30b1f1a6 100644 --- a/pkg/proto/ydbcp/v1alpha1/operation.proto +++ b/pkg/proto/ydbcp/v1alpha1/operation.proto @@ -18,20 +18,38 @@ message Operation { START_CANCELLING = 6; RUNNING = 7; } + + // Unique identifier for the operation. string id = 1; + // An identifier of an external resource which holds the record about the operation + // (it can be the container id where the database is located). string container_id = 2; + // Type of the operation (TB - TakeBackup, RB - RestoreBackup, DB - DeleteBackup, TBWR - TakeBackupWithRetries). string type = 3; + // Name of the database associated with the operation. string database_name = 4; + // GRPC endpoint of the database. string database_endpoint = 5; + // Identifier for the YDB server export/import operation. string ydb_server_operation_id = 6; + // Identifier for the backup associated with the operation. string backup_id = 7; + // List of source paths included in the backup (only for MakeBackup operation). repeated string source_paths = 8; // [(size) = "<=256"]; + // List of source paths to exclude from the backup (only for MakeBackup operation). repeated string source_paths_to_exclude = 9; // [(size) = "<=256"]; + // List of paths included in restore (only for MakeRestore operation). repeated string restore_paths = 10; // [(size) = "<=256"]; + // Audit information for the operation. AuditInfo audit = 11; + // Current status of the operation. Status status = 12; + // Message associated with the operation status. string message = 13; + // Timestamp when the operation was last updated. google.protobuf.Timestamp updated_at = 14; + // Identifier for the parent operation, if exist. string parent_operation_id = 15; + // Retry configuration for the operation. RetryConfig retry_config = 16; -} +} \ No newline at end of file diff --git a/pkg/proto/ydbcp/v1alpha1/operation_service.proto b/pkg/proto/ydbcp/v1alpha1/operation_service.proto index e821603f..0c454f7c 100644 --- a/pkg/proto/ydbcp/v1alpha1/operation_service.proto +++ b/pkg/proto/ydbcp/v1alpha1/operation_service.proto @@ -5,18 +5,29 @@ option go_package = "github.com/ydb-platform/ydbcp/pkg/proto/ydbcp/v1alpha1;ydbc import "ydbcp/v1alpha1/operation.proto"; -// A set of methods for managing operations;. +// A set of methods for managing operations. +// YDB auth token can be passed via GRPC request metadata using authorization header. service OperationService { + // Lists all operations for the specified container. + // Required YDB permissions: `ydb.databases.list` rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse); + // Cancels the specified operation by its ID (only long-running operations TakeBackup/RestoreBackup can be cancelled). + // Required YDB permissions: `ydb.databases.backup` for TakeBackup operation, `ydb.tables.create` for RestoreBackup operation. rpc CancelOperation(CancelOperationRequest) returns (Operation); + // Retrieves the specified operation by its ID. + // Required YDB permissions: `ydb.databases.get` rpc GetOperation(GetOperationRequest) returns (Operation); } message ListOperationsRequest { + // The ID of the container for which to list operations. string container_id = 1; + // A mask to filter operations by database name using LIKE operator for pattern matching (ex.: "your_db_prefix%"). + // For more information about LIKE operator, see the https://ydb.tech/docs/en/yql/reference/syntax/expressions#check-match. string database_name_mask = 2; + // A list of operation types to filter. repeated string operation_types = 3; // The maximum number of results per page that should be returned. If the number of available @@ -31,14 +42,18 @@ message ListOperationsRequest { } message ListOperationsResponse { + // The list of operations. repeated Operation operations = 1; + // The token for the next page of results. string next_page_token = 2; } message CancelOperationRequest { + // The ID of the operation to cancel. string operation_id = 1; } message GetOperationRequest { + // The ID of the operation to retrieve. string id = 1; -} +} \ No newline at end of file