This document describes how to use `ProtectedApplication` resources to customize
the behavior of backup and restores in Google Distributed Cloud (GDC) air-gapped.

These steps are optional and aren't required to successfully configure backup and restoration for your workloads. `ProtectedApplication` resources are optional Kubernetes resources in namespaces that customize the backup and restore of individual stateful applications. Without `ProtectedApplication` resources, the following restrictions apply:

- You restrict the backup and restore scope granularity to the namespace level.
- No flush and quiesce operations occur on workloads during backup execution.This might result in virtual machines with multiple disks not being crash-consistent after restoration.

`ProtectedApplication` resources are optional Kubernetes namespace resources
used to customize the backup and restore of individual stateful applications.
The `ProtectedApplication` resource defines which Kubernetes resources belong to
an application instance. You can manually set up a specialized orchestration
using the `kubectl` command to create a backup and restore of those applications in the following
scenarios:

- To identify a set of resources in a namespace that might be backed up or restored independently of the other resources in that namespace. A `ProtectedApplication` is the most fine-grained namespace entity that you can identify for a backup or restore scope.
- To provide specialized backup orchestration whenever the `ProtectedApplication` falls within the scope of a backup. In particular, if the `ProtectedApplication` contains `PersistentVolumeClaim` (PVC) resources either directly or through a template from a `StatefulSet`, you can run *hooks* before and after backing up the volumes. Hooks are commands that run in application containers. These hooks are often used for flush, quiesce, or unquiesce operations, and provide an application-consistent backup.

## Before you begin

Define the `ProtectedApplication` resource before creating a backup plan. 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 use `ProtectedApplication` resources, 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.

## Deploy protected application resources

The following yaml snippet is an example of a `Deployment` specification with a
`ProtectedApplication` resource that backs up all of the resources associated with
the application during backup, and restores all resources during the restore:

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: USER_CLUSTER_NS
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: protected-application-deployment
  namespace: USER_CLUSTER_NS
  labels:
    app: protected
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: unprotected-application-deployment
  namespace: USER_CLUSTER_NS
  labels:
    app: unprotected
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80
---
apiVersion: gkebackup.gke.io/v1
kind: ProtectedApplication
metadata:
  name: PROTECTED_APP_NAME
  namespace: USER_CLUSTER_NS
spec:
  resourceSelection:
    type: Selector
    selector:
      matchLabels:
        app: protected
  components:
    - name: application-deployment
      resourceKind: Deployment
      resourceNames:
        - protected-application-deployment
      strategy:
        type: BackupAllRestoreAll
        backupAllRestoreAll: {}
```

Replace the following:

- `USER_CLUSTER_NS`: the namespace within the Kubernetes cluster where your protected application resides.
- `PROTECTED_APP_NAME`: the name of your `ProtectedApplication`.

This example includes the following values for `ProtectedApplication`:

| Value | Description |
|---|---|
| `resourceSelection` | Defines how to identify resources that belong to the protected application: - `type:` Specify one of: - `ApplicationName`: Backs up a sig-apps application within the same namespace. - `Selector`: Backs up resources that match a given selector within the same namespace. - `applicationName`: If `type` is `ApplicationName`, specifies the name of the sig-apps Application within the same namespace. This is the application the data protection specification applies to. - `selector`: If `type` is `Selector`, specifies the label selector to select resources within the same namespace. |
| `components` | The list of components for the protected application, such as deployments or stateful sets: - `name`: The unique name of the component. <!-- --> - `resourceKind`: Choose between `Deployment` or `StatefulSet`. <!-- --> - `resourceNames`: The list of names identifying the `resourceKind` in the namespace. <!-- --> - `strategy`: Additional details on how to back up or restore this component. For more information, see [Protected application strategies](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/protected-application-strategies). |

Specify the `ProtectedApplication` in the list of `selectedApplications` in the `backupScope`. For example:

```yaml
apiVersion: backup.gdc.goog/v1
kind: BackupPlan
metadata:
  name: BACKUP_PLAN
  namespace: USER_CLUSTER_NS
spec:
  clusterName: USER_CLUSTER
  backupSchedule:
    cronSchedule: CRON_SCHEDULE
    paused: BACKUP_SCHEDULE_STATUS
  backupConfig:
    backupScope:
      selectedApplications:
        namespacedNames:
        - name: PROTECTED_APP_NAME
          namespace: USER_CLUSTER_NS
    backupRepository: BACKUP_REPOSITORY
  retentionPolicy:
    backupDeleteLockDays: BACKUP_DELETE_LOCK_DAYS
    backupRetainDays: BACKUP_RETAIN_DAYS
```

Replace the following:

- `BACKUP_PLAN`: the name of your backup plan.
- `USER_CLUSTER`: the name of your Kubernetes cluster.
- `CRON_SCHEDULE`: a crontab schedule indicating when to schedule backups, such as `"*/30 * * * *"`. The minimum interval between scheduled backups is 10 minutes.
- `BACKUP_SCHEDULE_STATUS`: if `true`, periodic backups are not scheduled.
- `PROTECTED_APP_NAME`: the name you gave to your `ProtectedApplication` resource.
- `BACKUP_REPOSITORY`: the name of the backup repository you are using to store backups.
- `BACKUP_DELETE_LOCK_DAYS`: prevents deletion of the backup for the number of days specified after backup creation, for example, `10`.
- `BACKUP_RETAIN_DAYS`: defines the total number of days to retain the backup. After this period, the backup is automatically deleted. Setting this value to a higher number might lead to storage exhaustion, while setting it to a lower value can increase the risk of data loss. This value is set to 35 by default if not specified. Retention policies don't override the retention policies of the storage location, nor can they exceed 90 days.

## What's next

- To select a protected application strategy, see [Protected application strategies](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/protected-application-strategies).