[CLOUDGA-31245] Add roles functionality to backup commands

[pranbansal02]

Overview

This PR contains the changes to support the new use_roles field in backup, restore, and backup schedule APIs. This feature enables users to include global YSQL roles and permissions (grants) when creating backups and restore them when performing a restore operation.

Changes

Apiserver has been enhanced with a new use_roles boolean field across:

• Backup API (BackupSpec) - Include roles/grants when creating a backup
• Restore API (RestoreSpec) - Restore roles/grants from a backup
• Backup Schedule API (ScheduleSpecV2) - Include roles/grants in scheduled backups

The CLI changes add an --include-roles flag (gated behind a feature flag) to the relevant commands and display the roles inclusion status in list/describe outputs.

---

Feature Flag

The --include-roles flag is controlled by a feature flag and is only available when enabled.

Enabling the Feature

export YBM_FF_INCLUDE_ROLES_DURING_BACKUP_RESTORE=true

Feature Flag Definition

Feature Flag Name	Environment Variable
INCLUDE_ROLES_DURING_BACKUP_RESTORE	YBM_FF_INCLUDE_ROLES_DURING_BACKUP_RESTORE

---

Commands Modified

1. ybm backup create

Creates a backup for a cluster with optional roles/grants inclusion.

Help Output

Create backup for a cluster in YugabyteDB Aeon

Usage:
  ybm backup create [flags]

Flags:
      --cluster-name string      [REQUIRED] Name for the cluster.
      --description string       [OPTIONAL] Description of the backup.
  -h, --help                     help for create
      --include-roles            [OPTIONAL] Include global YSQL roles and permissions in the backup. (Default: false)
      --retention-period int32   [OPTIONAL] Retention period of the backup in days. (Default: 1)

Example Usage

# Create backup without roles (default)
ybm backup create --cluster-name my-cluster

# Create backup with roles and grants included
ybm backup create --cluster-name my-cluster --include-roles

---

2. ybm backup restore

Restores a backup into a cluster with optional roles/grants restoration.

Help Output

Restore backups into a cluster in YugabyteDB Aeon

Usage:
  ybm backup restore [flags]

Flags:
      --backup-id string       [REQUIRED] ID of the backup to be restored.
      --cluster-name string    [REQUIRED] Name of the cluster to restore backups.
  -h, --help                   help for restore
      --include-roles          [OPTIONAL] Restore global YSQL roles and permissions from the backup. (Default: false)

Example Usage

# Restore backup without roles (default)
ybm backup restore --cluster-name my-cluster --backup-id <backup-uuid>

# Restore backup with roles and grants
ybm backup restore --cluster-name my-cluster --backup-id <backup-uuid> --include-roles

Important Note

The --include-roles flag on restore can only be used if the original backup was taken with use_roles=true. The API will return an error if you try to restore roles from a backup that doesn't contain them.

---

3. ybm backup policy enable

Enables a backup policy for a cluster with optional roles/grants inclusion.

Help Output

Enable backup policies for cluster in YugabyteDB Aeon

Usage:
  ybm backup policy enable [flags]

Flags:
      --cluster-name string   [REQUIRED] Name of the cluster to enable backup policies.
  -h, --help                  help for enable
      --include-roles         [OPTIONAL] Include global YSQL roles and permissions in scheduled backups. (Default: false)

Example Usage

# Enable backup policy without roles
ybm backup policy enable --cluster-name my-cluster

# Enable backup policy with roles included in scheduled backups
ybm backup policy enable --cluster-name my-cluster --include-roles

---

4. ybm backup policy update

Updates a backup policy for a cluster with optional roles/grants inclusion.

Help Output

Update backup policies for cluster in YugabyteDB Aeon

Usage:
  ybm backup policy update [flags]

Flags:
      --cluster-name string                             [REQUIRED] Name of the cluster to update backup policies.
      --full-backup-frequency-in-days int32             [OPTIONAL] Frequency of full backup in days. (default 1)
      --full-backup-schedule-days-of-week string        [OPTIONAL] Days of the week when the backup has to run.
      --full-backup-schedule-time string                [OPTIONAL] Time of the day at which the backup has to run. (24hr HH:MM format)
  -h, --help                                            help for update
      --include-roles                                   [OPTIONAL] Include global YSQL roles and permissions in scheduled backups. (Default: false)
      --incremental-backup-frequency-in-minutes int32   [OPTIONAL] Frequency of incremental backup in minutes. (default 60)
      --retention-period-in-days int32                  [REQUIRED] Retention period of the backup in days. (default 1)

Example Usage

# Update policy without roles
ybm backup policy update --cluster-name my-cluster --retention-period-in-days 7 --full-backup-frequency-in-days 1

# Update policy with roles included
ybm backup policy update --cluster-name my-cluster \
    --retention-period-in-days 7 \
    --full-backup-frequency-in-days 1 \
    --include-roles

---

5. ybm backup list

Lists backups with a new "Roles & Grants" column showing inclusion status.

Example Output

ID                                    Created On        Inc  Expire On         Cluster Name  State  Type  Roles & Grants
9e74ca8f-331b-4dec-89b0-4e59b81e903c  2024-01-25,09:06  🟡   2024-02-01,09:06  my-cluster    ✅     👤    Included
a1b2c3d4-5678-90ab-cdef-1234567890ab  2024-01-24,15:30  🟡   2024-01-31,15:30  my-cluster    ✅     📅    Not Included

Column Meanings

Column	Description
Roles & Grants	Shows "Included" if backup contains roles/grants, "Not Included" otherwise

---

6. ybm backup describe

Describes a backup with roles/grants inclusion status in the detailed view.

Example Output

General
ID                                    Created On        Inc  Cluster Name  State
9e74ca8f-331b-4dec-89b0-4e59b81e903c  2024-01-25,09:06  🟡   my-cluster    ✅

Type  Size(bytes)  Expire On         Duration   Roles & Grants
👤    1234567890   2024-02-01,09:06  45 mins    Included

Databases/Keyspaces
Database/Keyspace  API Type
yugabyte           PGSQL_TABLE_TYPE

---

7. ybm backup policy list

Lists backup policies with a new "Include Roles & Grants" column.

Example Output

Time Interval(days)  Incr. Interval(mins)  Days of the Week  Backup Start Time  Retention Period(days)  Roles & Grants  State
1                    60                    NA                NA                 7                       Included        ACTIVE

Column Meanings

Column	Description
Include Roles & Grants	Shows "Included" if backup policy include roles/grants, "Not Included" otherwise

[posriniv]

Looks great!