Backup and Restore
-------------------

You can backup and restore your Jenkins data related to jobs, plugins or configurations with the Backup and Restore
feature provided by the Operator.

For this, you need to first create `BackupVolume` s which you would like to use where your backups would be stored.
These custom resources are backed by `PersistentVolumeClaims`.

Create `BackupVolume`
^^^^^^^^^^^^^^^^^^^^^^

```yaml
apiVersion: jenkins.io/v1alpha2
kind: BackupVolume
metadata:
  name: backup-volume-1
spec:
  size: 1Gi
```

The default storageclassname would be used if it isn't provided in the spec.

`pvcName` can be provided in the spec if there is an already existing `PersistentVolumeClaim` which is already being used
for backups. If a PVC with the given name does not exist then a new one will be created with the provided name instead of
creating a PVC with the `<backupvolume-name>-jenkins-backup` naming formula.

To use a particular `BackupVolume` in a Jenkins instance, you would have 

Reference the `BackupVolume` in your `Jenkins` CR
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To enable backup for your Jenkins instance, reference your backupvolumes in the Jenkins CR.

```yaml
apiVersion: jenkins.io/v1alpha2
kind: Jenkins
metadata:
  name: jenkins-with-backup-enabled
spec:
  backupVolumes: ["backup-volume-1"]
...
```

===== Example

_Create *BackupVolume* to be consumed by Jenkins_

```shell 
$ kubectl create -f config/samples/jenkins_v1alpha2_backupvolume.yaml
backupvolume.jenkins.io/backupvolume-sample created
```

_Create *Jenkins* with *BackupVolume* s_

```shell
$ kubectl create -f config/samples/jenkins_v1alpha2_jenkins_with_backup.yaml
jenkins.jenkins.io/jenkins-with-backup-sample created
```


Apart from that, a sidecar container called `backup` is created alongside the rest of the containers in the Pod which
aid in the backup and restore operations. This sidecar container is backed by a Volume which is mounted at
`/jenkins-backups` where all the backups are stored.


BackupStrategy
~~~~~~~~~~~~~~
*BackupStrategy* contains the configuration needed by the Backup and Restore controllers to carry out tasks before and
after a backup/restore job and also what exactly needs to be backed up and restored for a particular *Jenkins* instance.

===== Example

_Create *BackupStrategy* with everything enabled _

```yaml
apiVersion: jenkins.io/v1alpha2
kind: BackupStrategy
metadata:
  name: backupstrategy-sample
spec:
  backupOptions:
    config: true
    jobs: true
    plugins: true
  restartAfterRestore:
    enabled: true
    safe: true
```

A *BackupStrategy* can be created by the user and then used by any `Backup` instance, this way backupStrategies can be
used across multiple Jenkins instances and multiple backup volumes.

backupOptions
^^^^^^^^^^^^^
This spec reflects what should be backed up from the *Jenkins* instance when backup is triggered.

`.spec.backupOptions.config` points to all the `xml` configuration files in the root of the Jenkins Home.

`.spec.backupOptions.jobs` points to the `jobs` directory in the Jenkins Home.

`.spec.backupOptions.plugins` points to the `plugins` directory in the Jenkins Home.

Backup
~~~~~~

*Backup* contains the information necessary for triggering a backup for your *Jenkins*.
To create a backup we need to know which Jenkins instance we want to back up and to which volume in the Jenkins instance. 

_Create a **Backup**_

```shell
$ kubectl create -f config/samples/jenkins_v1alpha2_backup.yaml
backup.jenkins.io/backup-sample created
```

===== Example

_**Backup** `backup-sample` definition_

```yaml
apiVersion: jenkins.io/v1alpha2
kind: Backup
metadata:
  name: backup-sample
  namespace: jenkins-backup-test
spec:
  jenkinsRef: jenkins sample
  strategyRef: backupstrategy-sample
  backupVolumeRef: backup-volume-1
```

A *Backup* is created with a *BackupStrategy* in mind (noted in `.spec.strategyRef`) which contains information on the
what to backup exactly. It also contianer the jenkinsRef which let's the operator know what jenkins instance needs to be
backed up and the backupVolumeRef, noting where the backup needs to end up.

Once the backup is complete we should be able to see the backup in the `/jenkins-backups/<backup-volume-name>/<backup-name>`
directory.

[NOTE]
====
Only `.spec.backupOptions` from the *BackupStrategy* are used for the *Backup* operations.
====

jenkinsRef
^^^^^^^^^^
This spec reflects which *Jenkins* instance is a particular *BackupStrategy* meant for.

strategyRef
^^^^^^^^^^^
This spec reflects the *BackupStrategy* which has to be used for performing the backup.

Restore
~~~~~~~
*Restore* contains the information necessary for triggering a restore for your *Jenkins* given that a *Backup* already
exists.

_Create a **Restore**_

```shell
$ kubectl create -f config/samples/jenkins_v1alpha2_restore.yaml
restore.jenkins.io/restore-sample created

```

_**Restore** `restore-sample` definition_

```yaml
apiVersion: jenkins.io/v1alpha2
kind: Restore
metadata:
  name: restore-sample
  namespace: jenkins-backup-test
spec:
  backupRef: backup-sample
```

The restore operation would be responsible for moving the necessary files and folders from the backup directory present
in `/jenkins-backups/<backup-volume-name>/` to the correct location in Jenkins Home.

[NOTE]
====
Only `.spec.restoreAfterRestart` from the *BackupStrategy* are used for the *Restore* operations.
====

backupRef
^^^^^^^^^
This spec reflects the *Backup* which would be used figure out the *Jenkins*, *BackupStrategy* and *BackupVolume* used
for the restore.