diff --git a/changelogs/unreleased/5773-qiuming-best b/changelogs/unreleased/5773-qiuming-best new file mode 100644 index 0000000000..d638457d0a --- /dev/null +++ b/changelogs/unreleased/5773-qiuming-best @@ -0,0 +1 @@ +Design for Handling backup of volumes by resources filters diff --git a/design/handle-backup-of-volumes-by-resources-filters.md b/design/handle-backup-of-volumes-by-resources-filters.md index 7096891998..912ba21feb 100644 --- a/design/handle-backup-of-volumes-by-resources-filters.md +++ b/design/handle-backup-of-volumes-by-resources-filters.md @@ -5,7 +5,7 @@ Currently, Velero doesn't have one flexible way to filter volumes. If users want to skip backup of volumes or only backup some volumes in different namespaces in batch, currently they need to use the opt-in and opt-out approach one by one, or use label-selector but if it has big different labels on each different related pods, which is cumbersome when they have lots of volumes to handle with. it would be convenient if Velero could provide one way to filter the backup of volumes just by `some specific volumes attributes`. -Also, currently, it's not accurate enough if the users want to select a specific volume to do a backup or skip by without patching labels or annotations to the pods. It would be useful if users could accurately select target volume by `one specific resource selector. for the users could accurately select the volume to backup or skip in their console when using velero for secondary development. +Also, currently, it's not accurate enough if the users want to select a specific volume to do a backup or skip by without patching labels or annotations to the pods. It would be useful if users could accurately select target volume by `one specific resource selector`. Users could accurately select the volume to backup or skip in their own console when using velero for secondary development. ## Background As of Today, Velero has lots of filters to handle (backup or skip backup) resources including resources filters like `IncludedNamespaces, ExcludedNamespaces`, label selectors like `LabelSelector, OrLabelSelectors`, annotation like `backup.velero.io/must-include-additional-items` etc. But it's not enough flexible to handle volumes, we need one generic way to filter volumes. @@ -39,12 +39,12 @@ When Velero handles volumes backup should respect the filter rules defined in th The resources filters rules should contain both `include` and `exclude` rules. For the rules on `one specific resource selector`, we introduced a `GVRN` way of resources filters, for resources are identified by their resource type and resource name, or GVRN. - -Here we call it `Volumes Attributes Selector`, which matches volumes with the same attributes defined. - + +Here we call it `GVRN Selector` which exactly matches the resources to be handled. + For the attributes on `some specific volumes attributes`, we basically follow the defined data struct [PersistentVolumeSpec](https://github.com/kubernetes/kubernetes/blob/v1.26.0/pkg/apis/core/types.go#L304), and only handle partial common fields of it currently. -Here we call it `GVRN Selector` which exactly matches the resources to be handled. +Here we call it `Volumes Attributes Selector`, which matches volumes with the same attributes defined. ### filter fields format The filter JSON config file would look like this: @@ -108,17 +108,19 @@ Both `Kopia, Restic` and `Volume snapshot` share one JSON configuration file. #### resources In the resources part, we defined `GVRN Selector` to filter resources. In a filter, an empty or omitted group, version, resource type, or resource name matches any value. `GVRN selector` could match Persistent Volume and other Kubernetes resources. - + +Taking select PV as an example, if users want to backup PV with name nginx-logs, the `groupResource` could be "/persistentvolumes" in which the group should be empty, the `namespacedNames` could be "/nginx-logs" in which the namespace should be empty. + #### storage In the storage part, we defined `Volumes Attributes Selector` to filter resources. The storage part defined rules including `pv` and `volume`, which correspond to `Kopia, Restic` and `Volume snapshot`. -A filter in storage with a specific key and empty value, which means the value matches any value. For example, if the `storage.pv.exclude.persistentVolumeSource.nfs` is `{}` it means if `NFS` is used as `persistentVolumeSource` in Persistent Volume will be skipped no matter if the NFS server or NFS Path is, +A filter in storage with a specific key and empty value, which means the value matches any value. For example, if the `storage.pv.exclude.persistentVolumeSource.nfs` is `{}` it means if `NFS` is used as `persistentVolumeSource` in Persistent Volume will be skipped no matter what the NFS server or NFS Path is, A filter may have multiple values, all the values are concatenated by commas. For example, the `storage.pv.include.storageClassName` is `gp2, ebs-sc` which means Persistent Volume with gp2 or ebs-sc storage class both will be back up. -The size of each single filter value should limit to 256 bytes in case of an unfriendly variable assignment. +The size of each single filter value should limit to 256 bytes in case of an unfriendly long variable assignment. If user defined pv filter rules but used Kopia or Restic to do a backup, the backup will fail in validating the resource filter configuration. Same as the situation if using defined volume filter rules but using CSI or plugins to take volume snapshots. @@ -167,7 +169,7 @@ data: kind: ConfigMap metadata: creationTimestamp: "2023-01-16T14:08:12Z" - name: backup01 + name: cm-backup01 namespace: default resourceVersion: "17891025" uid: b73e7f76-fc9e-4e72-8e2e-79db717fe9f1 @@ -178,13 +180,13 @@ The configmap only stores those filters assigned value not the whole resources f The name of the configmap is `cm-`+`$BackupName`, and it's in Velero install namespace. -#### Live-cycle of resource filter configmap +#### Life-cycle of resource filter configmap - If resource filter configmap is only been imported by Velero backup command with flag `from-file`. - If the referenced backup has been deleted, the relevant configmap should be removed. - Resource filter configmap should also persist into object storage and could be also synchronized automatically when at startup. ### Display of volume resource filter -As the resource filter configmap is referenced by backup CR, the rules in configmap are not so intuitive, so we need to integrate rules in configmap to the output of the command `velero backup describe` +As the resource filter configmap is referenced by backup CR, the rules in configmap are not so intuitive, so we need to integrate rules in configmap to the output of the command `velero backup describe`, and make it more readable. ## Compatibility Currently, we have these resources filters: