This document describes how to create a fine-grained restore for a backup in Google Distributed Cloud (GDC) air-gapped.

The fine-grained restore feature lets you restore a subset of resources from a
backup. This feature provides the flexibility
to refine the restore scope defined in the restore plan.

## Before you begin

Ensure you have an existing backup. For more information, see [Plan a set of backups](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/cluster-backup/plan-backups.md.txt).

### Request IAM roles

To create a fine-grained restore for a backup, ask your IAM Org Admin or
IAM Project Admin to grant you one of the following roles:

- **User Cluster Backup Admin** (`user-cluster-backup-admin`): creates, gets, lists,
  watches, updates, patches, and deletes backup resources such as backup and restore
  plans in user clusters. Contact your IAM Org Admin to request this role.

- **Backup Creator** (`backup-creator`): creates, gets, lists, watches, updates, patches,
  and deletes manual backup requests and manual restore requests. Contact your
  IAM Project Admin to
  request this role.

## Create a fine-grained restore

To create a restore with a fine-grained filter, follow these steps:

1. Create the fine-grained restore filters. You can use the following YAML
   example.

   ```yaml
   inclusionFilters:
     - groupKind:
         group: foo.io
         kind: Bar
       name: name1
       namespace: ns1
   exclusionFilters:
     - labels:
         key1: value1
         key2: value2
   ```
2. Create a `ManualRestoreRequest` custom resource to plan restores from
   an existing `Backups`. Here's an example of a `ManualRestoreRequest`:

   ```yaml
   apiVersion: backup.gdc.goog/v1
   kind: ManualRestoreRequest
   metadata:
     name: RESTORE_NAME
     namespace: PROJECT_NAMESPACE
   spec:
     restoreName: RESTORE_NAME
     restorePlanName: RESTORE_PLAN
     backupName: BACKUP_NAME
     filter:
       FINE_GRAINED_RESTORE_FILTERS
   ```

Replace the following:

- `RESTORE_NAME`: the name of the restore that you want to create.
- `PROJECT_NAMESPACE`: the name of your GDC project.
- `RESTORE_PLAN`: the name of the restore plan this restore is derived from.
- `BACKUP_NAME`: the backup to restore. This backup must be associated with the backup plan to which the restore plan refers to. For more information, see [Plan a set of restores](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/cluster-backup/plan-restores.md.txt#create-restore-plan).
- `FINE_GRAINED_RESTORE_FILTER`: the fine-grained restore filters. For examples, see [Fine-grained restore filter
  examples](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/cluster-backup/fine-grained-restore#fine-grained-restore-filter-examples).

## Fine-grained restore filter examples

The following examples are provided in the YAML format used by Google Cloud CLI.

### Restore a single namespace scoped resource

This example restores a `ConfigMap` resource with the name `nginx-vars` in the
namespace `webserver`, using the fine-grained restore `inclusionFilters` to select
the resource. If you want to choose resources under the core group, use an empty
string for the `group` field.

```yaml
filter:
  inclusionFilters:
  - groupKind:
      kind: ConfigMap
    name: nginx-vars
    namespace: webserver
```

### Exclude a single cluster scoped resource

This example restores all available resources except for one `groupKind`
resource with the name `sc1`, using the fine-grained restore
`exclusionFilters` to exclude the resource.

```yaml
filter:
  exclusionFilters:
  - groupKind:
      group: storage.k8s.io
      kind: StorageClass
    name: sc1

```

### Restore resources with two labels

This example restores resources which have both labels `key1:value1` and
`key2:value2`, using the fine-grained restore `inclusionFilters` to select the
resources.

```yaml
filter:
  inclusionFilters:
  - labels:
      key1: value1
      key2: value2
```

### Exclude all resources of some GroupKinds

This example restores all available resources except for the `groupKind` resources of `ConfigMap`
and `storage.k8s.io/StorageClass`, using the fine-grained restore `exclusionFilters`
to exclude these two GroupKinds.

```yaml
filter:
  exclusionFilters:
  - groupKind:
      kind: ConfigMap
  - groupKind:
      group: storage.k8s.io
      kind: StorageClass
```

## What's next

- [View and delete a restore](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/cluster-backup/view-and-delete-restore.md.txt)