Merge pull request #8131 from Lyndon-Li/backup-repo-config-doc

Add doc for backup repo config

changelogs/unreleased/8131-Lyndon-Li

@@ -0,0 +1 @@
+Fix issue #7620, add doc for backup repo config

site/content/docs/main/backup-repository-configuration.md

@@ -0,0 +1,50 @@
+---
+title: "Backup Repository Configuration"
+layout: docs
+---
+
+Velero uses selectable backup repositories for various backup/restore methods, i.e., [file-system backup][1], [CSI snapshot data movement][2], etc. To achieve the best performance, backup repositories may need to be configured according to the running environments.  
+
+Velero uses a BackupRepository CR to represent the instance of the backup repository. Now, a new field `repositoryConfig` is added to support various configurations to the underlying backup repository.  
+
+Velero also allows you to specify configurations before the BackupRepository CR is created through a configMap. The configurations in the configMap will be copied to the BackupRepository CR when it is created at the due time.  
+The configMap should be in the same namespace where Velero is installed. If multiple Velero instances are installed in different namespaces, there should be one configMap in each namespace which applies to Velero instance in that namespace only. The name of the configMap should be specified in the Velero server parameter `--backup-repository-config`.  
+
+Conclusively, you have two ways to add/change/delete configurations of a backup repository:  
+- If the BackupRepository CR for the backup repository is already there, you should modify the `repositoryConfig` field. The new changes will be applied to the backup repository at the due time, it doesn't require Velero server to restart.   
+- Otherwise, you can create the backup repository configMap as a template for the BackupRepository CRs that are going to be created.  
+
+The backup repository configMap is repository type (i.e., kopia, restic) specific, so for one repository type, you only need to create one set of configurations, they will be applied to all BackupRepository CRs of the same type. Whereas, the changes of `repositoryConfig` field apply to the specific BackupRepository CR only, you may need to change every BackupRepository CR of the same type.  
+
+Below is an example of the BackupRepository configMap with the configurations:  
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: <config-name>
+  namespace: velero
+data:
+  <kopia>: |
+    {
+      "cacheLimitMB": 2048    
+    }
+  <other-repository-type>: |
+    {
+      "cacheLimitMB": 1024   
+    } 
+```
+
+To create the configMap, you need to save something like the above sample to a file and then run below commands:  
+```shell
+kubectl apply -f <yaml-file-name>
+```
+
+When and how the configurations are used is decided by the backup repository itself. Though you can specify any configuration to the configMap or `repositoryConfig`, the configuration may/may not be used by the backup repository, or the configuration may be used at an arbitrary time.  
+
+Below is the supported configurations by Velero and the specific backup repository.  
+***Kopia repository:***  
+`cacheLimitMB`: specifies the size limit(in MB) for the local data cache. The more data is cached locally, the less data may be downloaded from the backup storage, so the better performance may be achieved. Practically, you can specify any size that is smaller than the free space so that the disk space won't run out. This parameter is for repository connection, that is, you could change it before connecting to the repository. E.g., before a backup/restore/maintenance.  
+
+
+[1]: file-system-backup.md
+[2]: csi-snapshot-data-movement.md

site/content/docs/main/csi-snapshot-data-movement.md

@@ -481,7 +481,7 @@ For Velero built-in data mover, Velero uses [BestEffort as the QoS][13] for node
 If you want to constraint the CPU/memory usage, you need to [customize the resource limits][11]. The CPU/memory consumption is always related to the scale of data to be backed up/restored, refer to [Performance Guidance][12] for more details, so it is highly recommended that you perform your own testing to find the best resource limits for your data.   
 
 During the restore, the repository may also cache data/metadata so as to reduce the network footprint and speed up the restore. The repository uses its own policy to store and clean up the cache.  
-For Kopia repository, the cache is stored in the node-agent pod's root file system and the cleanup is triggered for the data/metadata that are older than 10 minutes (not configurable at present). So you should prepare enough disk space, otherwise, the node-agent pod may be evicted due to running out of the ephemeral storage.  
+For Kopia repository, the cache is stored in the node-agent pod's root file system. Velero allows you to configure a limit of the cache size so that the data mover pod won't be evicted due to running out of the ephemeral storage. For more details, check [Backup Repository Configuration][17].  
 
 ### Node Selection
 
@@ -513,4 +513,4 @@ advanced configuration options for `BackupPVC`, allowing users to fine-tune acce
 [14]: node-agent-concurrency.md
 [15]: data-movement-backup-node-selection.md
 [16]: data-movement-backup-pvc-configuration.md
-
+[17]: backup-repository-configuration.md

site/content/docs/main/file-system-backup.md

@@ -642,7 +642,7 @@ Velero node-agent uses [BestEffort as the QoS][14] for node-agent pods (so no CP
 If you want to constraint the CPU/memory usage, you need to [customize the resource limits][15]. The CPU/memory consumption is always related to the scale of data to be backed up/restored, refer to [Performance Guidance][16] for more details, so it is highly recommended that you perform your own testing to find the best resource limits for your data.   
 
 During the restore, the repository may also cache data/metadata so as to reduce the network footprint and speed up the restore. The repository uses its own policy to store and clean up the cache.  
-For Kopia repository, the cache is stored in the node-agent pod's root file system and the cleanup is triggered for the data/metadata that are older than 10 minutes (not configurable at present). So you should prepare enough disk space, otherwise, the node-agent pod may be evicted due to running out of the ephemeral storage.  
+For Kopia repository, the cache is stored in the node-agent pod's root file system. Velero allows you to configure a limit of the cache size so that the node-agent pod won't be evicted due to running out of the ephemeral storage. For more details, check [Backup Repository Configuration][18].  
 
 ## Restic Deprecation  
 
@@ -695,3 +695,4 @@ In the output of `velero backup describe` command for a backup with fs-backup:
 [15]: customize-installation.md#customize-resource-requests-and-limits
 [16]: performance-guidance.md
 [17]: https://github.com/vmware-tanzu/velero/blob/main/GOVERNANCE.md#deprecation-policy
+[18]: backup-repository-configuration.md

site/data/docs/main-toc.yml

@@ -55,6 +55,8 @@ toc:
         url: /node-agent-concurrency
       - page: Backup PVC Configuration
         url: /data-movement-backup-pvc-configuration
+      - page: Backup Repository Configuration
+        url: /backup-repository-configuration        
       - page: Verifying Self-signed Certificates
         url: /self-signed-certificates
       - page: Changing RBAC permissions