Resource filtering

Filter objects by namespace, type, labels or resource policies.

This page describes how to filter resources for backup and restore. Users can use include and exclude flags with the velero backup and velero restore commands. Users can also use resource policies for fine-grained resource filtering during backup and restore, as well as volume handling during backup. By default, Velero includes all objects in a backup or restore when no filtering options are used.

Includes

Only specific resources are included, all others are excluded.

Wildcard takes precedence when both a wildcard and specific resource are included.

–include-namespaces

Namespaces to include. Accepts glob patterns (*, ?, [abc]). Default is *, all namespaces.

See Namespace Glob Patterns for more details on supported patterns.

Note: * alone is reserved for empty fields, which means all namespaces.

• Backup a namespace and it’s objects.

  velero backup create <backup-name> --include-namespaces <namespace>
  

• Restore two namespaces and their objects.

  velero restore create --from-backup <backup-name> --include-namespaces <namespace1>,<namespace2>
  

–include-resources

Kubernetes resources to include in the backup, formatted as resource.group, such as storageclasses.storage.k8s.io (use * for all resources). Cannot work with --include-cluster-scoped-resources, --exclude-cluster-scoped-resources, --include-namespace-scoped-resources and --exclude-namespace-scoped-resources.

• Backup all deployments in the cluster.

  velero backup create <backup-name> --include-resources deployments
  

• Restore all deployments and configmaps in the cluster.

  velero restore create --from-backup <backup-name> --include-resources deployments,configmaps
  

• Backup the deployments in a namespace.

  velero backup create <backup-name> --include-resources deployments --include-namespaces <namespace>
  

–include-cluster-resources

Includes cluster-scoped resources. Cannot work with --include-cluster-scoped-resources, --exclude-cluster-scoped-resources, --include-namespace-scoped-resources and --exclude-namespace-scoped-resources. This option can have three possible values:

• true: all cluster-scoped resources are included.

• false: no cluster-scoped resources are included.

• nil (“auto” or not supplied):

  • Cluster-scoped resources are included when backing up or restoring all namespaces. Default: true.

  • Cluster-scoped resources are not included when namespace filtering is used. Default: false.

    • Some related cluster-scoped resources may still be backed/restored up if triggered by a custom action (for example, PVC->PV) unless --include-cluster-resources=false.

• Backup entire cluster including cluster-scoped resources.

  velero backup create <backup-name>
  

• Restore only namespaced resources in the cluster.

  velero restore create --from-backup <backup-name> --include-cluster-resources=false
  

• Backup a namespace and include cluster-scoped resources.

  velero backup create <backup-name> --include-namespaces <namespace> --include-cluster-resources=true
  

–selector

• Include resources matching the label selector.

  velero backup create <backup-name> --selector <key>=<value>
  

• Include resources that are not matching the selector

  velero backup create <backup-name> --selector "<key> notin (<value>)"
  

The same selector syntax works on restore. Set-based selectors are useful for phased restores: restore labeled resources first, then everything else.

• Restore only resources matching the label selector.

  velero restore create --from-backup <backup-name> --selector <key>=<value>
  

• Restore everything in the backup except resources matching the selector.

  velero restore create --from-backup <backup-name> --selector "<key> notin (<value>)"
  

  notin also matches resources that don’t have the <key> label at all: this restores resources whose <key> label has any other value, as well as resources without the <key> label.

• Restore only resources that do not have a particular label key.

  velero restore create --from-backup <backup-name> --selector '!<key>'
  

Note: resources pulled in as dependencies of selected items by restore item actions (for example, a restored pod’s service account or persistent volume claims) are restored even if the label selector would exclude them.

For more information read the Kubernetes label selector documentation

–or-selector

To include the resources that match at least one of the label selectors from the list. Separate the selectors with or. The or is used as a separator to split label selectors, and it is not an operator.

This option cannot be used together with --selector.

• Include resources matching any one of the label selector, foo=bar or baz=qux

  velero backup create backup1 --or-selector "foo=bar or baz=qux"
  

• Include resources that are labeled environment=production or env=prod or env=production or environment=prod.

  velero restore create restore-prod --from-backup=prod-backup --or-selector "env in (prod,production) or environment in (prod, production)"
  

–include-cluster-scoped-resources

Kubernetes cluster-scoped resources to include in the backup, formatted as resource.group, such as storageclasses.storage.k8s.io(use ‘*’ for all resources). Cannot work with --include-resources, --exclude-resources and --include-cluster-resources. This parameter only works for backup, not for restore.

• Backup all StorageClasses and ClusterRoles in the cluster.

  velero backup create <backup-name> --include-cluster-scoped-resources="storageclasses,clusterroles"
  

• Backup all cluster-scoped resources in the cluster.

  velero backup create <backup-name> --include-cluster-scoped-resources="*"
  

–include-namespace-scoped-resources

Kubernetes namespace resources to include in the backup, formatted as resource.group, such as deployments.apps(use ‘*’ for all resources). Cannot work with --include-resources, --exclude-resources and --include-cluster-resources. This parameter only works for backup, not for restore.

• Backup all Deployments and ConfigMaps in the cluster.

  velero backup create <backup-name> --include-namespace-scoped-resources="deployments.apps,configmaps"
  

• Backup all namespace resources in the cluster.

  velero backup create <backup-name> --include-namespace-scoped-resources="*"
  

Excludes

Exclude specific resources from the backup.

Wildcard excludes are ignored.

–exclude-namespaces

Namespaces to exclude. Accepts glob patterns (*, ?, [abc]).

See Namespace Glob Patterns for more details on supported patterns.

• Exclude kube-system from the cluster backup.

  velero backup create <backup-name> --exclude-namespaces kube-system
  

• Exclude two namespaces during a restore.

  velero restore create --from-backup <backup-name> --exclude-namespaces <namespace1>,<namespace2>
  

–exclude-resources

Kubernetes resources to exclude, formatted as resource.group, such as storageclasses.storage.k8s.io. Cannot work with --include-cluster-scoped-resources, --exclude-cluster-scoped-resources, --include-namespace-scoped-resources and --exclude-namespace-scoped-resources.

• Exclude secrets from the backup.

  velero backup create <backup-name> --exclude-resources secrets
  

• Exclude secrets and rolebindings.

  velero backup create <backup-name> --exclude-resources secrets,rolebindings
  

velero.io/exclude-from-backup=true

• Resources with the label velero.io/exclude-from-backup=true are not included in backup, even if it contains a matching selector label.

–exclude-cluster-scoped-resources

Kubernetes cluster-scoped resources to exclude from the backup, formatted as resource.group, such as storageclasses.storage.k8s.io(use ‘*’ for all resources). Cannot work with --include-resources, --exclude-resources and --include-cluster-resources. This parameter only works for backup, not for restore.

• Exclude StorageClasses and ClusterRoles from the backup.

  velero backup create <backup-name> --exclude-cluster-scoped-resources="storageclasses,clusterroles"
  

• Exclude all cluster-scoped resources from the backup.

  velero backup create <backup-name> --exclude-cluster-scoped-resources="*"
  

–exclude-namespace-scoped-resources

Kubernetes namespace resources to exclude from the backup, formatted as resource.group, such as deployments.apps(use ‘*’ for all resources). Cannot work with --include-resources, --exclude-resources and --include-cluster-resources. This parameter only works for backup, not for restore.

• Exclude all Deployments and ConfigMaps from the backup.

  velero backup create <backup-name> --exclude-namespace-scoped-resources="deployments.apps,configmaps"
  

• Exclude all namespace resources from the backup.

  velero backup create <backup-name> --exclude-namespace-scoped-resources="*"
  

Resource policies

Velero provides resource policies (defined in a ConfigMap and referenced via --resource-policies-configmap or spec.resourcePolicy) to define fine-grained resource filters and volume handling rules.

Resource policies support both Backup and Restore operations, though certain policy sections are specific to backup workflows.

Supported policy sections by operation

Creating and referencing resource policies

Using resource policies is a two-step process:

1. Create the resource policies ConfigMap

   Create a ConfigMap in the Velero installation namespace (typically velero) containing your YAML policy definition:

   kubectl create cm <configmap-name> --from-file <yaml-file> -n velero
   

2. Reference the resource policies ConfigMap in a Backup or Restore

   • For Backup: Reference the ConfigMap via CLI flag or in the Backup CR spec:

     velero backup create <backup-name> --resource-policies-configmap <configmap-name>
     

     Or in Backup.spec:

     spec:
       resourcePolicy:
         kind: ConfigMap
         name: <configmap-name>
     

   • For Restore: Reference the ConfigMap via CLI flag or in the Restore CR spec:

     velero restore create <restore-name> --from-backup <backup-name> --resource-policies-configmap <configmap-name>
     

     Or in Restore.spec:

     spec:
       resourcePolicy:
         kind: ConfigMap
         name: <configmap-name>
     

   These flags and fields can also be combined with standard include and exclude options.

YAML template

The policies YAML config file showing all supported sections:

# Currently supports v1 version
version: v1

# Fine-grained namespace-scoped filters (Supported for both Backup and Restore)
namespacedFilterPolicies:
  - namespace: "app-ns-*"
    resourceFilters:
      - kind: "deployment"
        labelSelector:
          matchLabels:
            app: frontend
        includedResourceNames:
          - "web-*"
      - kind: "secret"
        excludedResourceNames:
          - "sensitive-secret"

# Fine-grained cluster-scoped filter overlay (Supported for both Backup and Restore)
clusterScopedFilterPolicy:
  resourceFilters:
    - kind: "storageclass"
      labelSelector:
        matchLabels:
          tier: gold

# Volume handling policies (Supported for Backup ONLY)
volumePolicies:
  - conditions:
      capacity: "10,100Gi"
      csi:
        driver: ebs.csi.aws.com
      storageClass:
        - gp2
        - standard
      pvcPhase:
        - Pending
      pvcVolumeMode: Block
      pvcAccessModes:
        - ReadWriteOnce
    action:
      type: skip
  - conditions:
      nfs: {}
    action:
      type: fs-backup

# Legacy scoped resource include/exclude filters (Supported for Backup ONLY)
# NOTE: Cannot be combined with --include-resources, --exclude-resources, or --include-cluster-resources in Backup.
includeExcludePolicy:
  includedClusterScopedResources:
    - "crd"
    - "pv"
  excludedClusterScopedResources: []
  includedNamespaceScopedResources:
    - "pod"
    - "service"
    - "deployment"
    - "pvc"
  excludedNamespaceScopedResources:
    - "configmap"
    - "secret"

Fine-grained backup and restore filters

namespacedFilterPolicies and clusterScopedFilterPolicy allow defining per-namespace and per-kind rules with independent label selectors and resource name patterns.

• During Backup: Controls which resources are backed up from matching namespaces or kinds.
• During Restore: Controls which resources are restored from a backup archive without modifying the backup itself.

For comprehensive guides, syntax details, and detailed examples, see:

• Fine-Grained Backup Filters
• Fine-Grained Restore Filters

IncludeExcludePolicy (Backup only)

The includeExcludePolicy is used to filter resources based on the namespace-scoped and cluster-scoped resources. User can use it to define a group of filters and reuse them across different backups.

For example, user can configmap my-policy of resource policies with following content:

version: v1
includeExcludePolicy:
  includedClusterScopedResources:
    - "crd"
  excludedClusterScopedResources: []
  includedNamespaceScopedResources: []
  excludedNamespaceScopedResources:
    - "configmap"
    - "event"

If the user creates a backup via command like

velero backup create <backup-name> --resource-policies-configmap my-policy --include-namespaces my-workload-ns

The backup will include all resources in namespace my-workload-ns except for configmap and event, and all CRDs in the cluster.

Limitations

The includeExcludePolicy does not work with --include-resources, --exclude-resources and --include-cluster-resources filters in Backup. If the user create the backup with command like velero backup create my-backup --include-cluster-resources --include-namespaces workload-ns --resource-policies-configmap my-policy the backup will fail with status FailedValidation

The filters in includeExcludePolicy cannot include *. Only specific resources can be set in the filters.

“includeExcludePolicy” .vs. filters in Backup Spec

User can use the includeExcludePolicy with other scoped filters when creating a backup. velero will combine the filters when it’s collecting the resources during the backup. During this process the filters in the Backup Spec have higher priority. For example, if the user use this command to create a backup, reusing the resource policies created in the previous example:

velero backup create <backup-name> --resource-policies-configmap my-policy --include-namespace-scoped-resources * --include-cluster-scoped-resources -apiservices --include-namespaces my-workload-ns

The backup will include all resources in namespace my-workload-ns, including configmap and event, and all CRDs and apiservices in the cluster.

Namespace selection by label (Backup only)

includedNamespacesByLabel and excludedNamespacesByLabel let you dynamically include or exclude entire namespaces from a backup based on Kubernetes label selectors applied to the namespace objects themselves, without enumerating namespace names in BackupSpec or a schedule. This is useful when namespaces are created and labeled dynamically and you don’t want to update --include-namespaces/--exclude-namespaces (or a schedule) every time.

Both fields live in includeExcludePolicy, alongside the resource-scoped filters above, and are lists of Kubernetes label selector strings (same syntax as kubectl get ns -l <selector>). A realistic policy commonly sets both together — include any namespace opted into a schedule by team, but always exclude confidential ones regardless of team:

version: v1
includeExcludePolicy:
  includedNamespacesByLabel:
    - "velero-backup-schedule=weekly"
    - "team=platform"
  excludedNamespacesByLabel:
    - "confidential=true"

With the policy above, a namespace labeled velero-backup-schedule=weekly AND confidential=true is still excluded — excludedNamespacesByLabel always wins (see Precedence below).

By default, multiple entries within includedNamespacesByLabel (and, independently, within excludedNamespacesByLabel) are OR’d together: a namespace matching any entry in the list is included/excluded. Set labelSelectorLogic: "AND" to require a namespace to match every entry in the list instead:

version: v1
includeExcludePolicy:
  labelSelectorLogic: "AND"
  includedNamespacesByLabel:
    - "tier=critical"
    - "compliance=pci"

(A single selector string can already express AND via comma-separated requirements, e.g. "tier=critical,compliance=pci" — that’s standard labels.Parse syntax and unrelated to labelSelectorLogic, which only controls how separate list entries combine.)

Precedence

• If includedNamespacesByLabel is configured and BackupSpec.IncludedNamespaces was left empty (the common case — a schedule with no explicit namespace list), the namespaces resolved by label become the entire inclusion baseline instead of “all namespaces.” If the selector currently matches nothing, the backup selects nothing — it does not fall back to “everything.”
• If BackupSpec.IncludedNamespaces is also set explicitly, the label-resolved namespaces are added to that list. An explicit --include-namespaces '*' is treated the same way as any other explicit value here — it is preserved, not narrowed down to just the label matches, since * already means “every namespace” regardless of what else is in the list.
• excludedNamespacesByLabel always subtracts from the effective set, the same way --exclude-namespaces does, whether or not includedNamespacesByLabel is configured.
• BackupSpec.LabelSelector/--selector is unaffected by any of this — it continues to filter individual resources, not namespaces. A namespace selected via includedNamespacesByLabel gets its own Namespace object backed up even if that namespace doesn’t separately match --selector; resources inside it are still filtered by --selector as usual. This matches how an explicitly-named --include-namespaces entry already behaves today.

This union-vs-replacement distinction is subtle but matters in practice — the same includedNamespacesByLabel policy produces a different effective namespace set depending on what else is configured on the backup:

Selectors are evaluated once, when the backup starts — a namespace labeled to match after that point isn’t picked up until the next backup runs. The resolved names are written into the created Backup’s own spec.includedNamespaces (and spec.excludedNamespaces), so velero backup describe and kubectl get backup <name> -o yaml show exactly which namespaces were actually selected. When a selector matches nothing, that field shows the internal [-]* pattern (resourcepolicies.NoNamespaceMatchesPattern) rather than an actual namespace name — a placeholder namespace glob guaranteed to match nothing, not a sign anything went wrong.

Limitations

• Not usable in a RestoreSpec.ResourcePolicy ConfigMap — like the rest of includeExcludePolicy, a ConfigMap containing these fields is rejected for Restore.
• Not honored in the global --global-backup-volume-policies-configmap; set these on a per-backup (or per-schedule) ResourcePolicy ConfigMap referenced via --resource-policies-configmap / BackupSpec.ResourcePolicy.
• An empty (or whitespace-only) selector string is rejected at validation time rather than silently matching every namespace.
• labelSelectorLogic applies the same OR/AND choice to both includedNamespacesByLabel and excludedNamespacesByLabel when both are set — there’s no way to set AND for one and OR for the other. Setting "AND" to narrow which namespaces are included also requires every excludedNamespacesByLabel entry to match before a namespace is excluded, which excludes fewer namespaces than the OR default. If you rely on excludedNamespacesByLabel as a safety net, keep it to a single selector entry (comma-separated requirements within that one entry already express AND, independent of labelSelectorLogic) so its behavior doesn’t change based on how includedNamespacesByLabel is tuned.
• Narrowing BackupSpec.IncludedNamespaces from “all namespaces” down to a resolved subset — whether via includedNamespacesByLabel or a plain explicit namespace list — also stops cluster-scoped resources (CRDs, ClusterRoles, StorageClasses, etc.) from being backed up by default, per Velero’s existing IncludeClusterResources auto-detection (unset means “only include cluster-scoped resources on a full, all-namespaces backup”). Set includeClusterResources: true on the backup explicitly if you still want them.

VolumePolicy (Backup only)

VolumePolicy is a data structure to control how velero handle the volumes matching certain conditions.

Supported VolumePolicy actions

There are three actions supported via the VolumePolicy feature:

• skip: don’t back up the action matching volume’s data.
• snapshot: back up the action matching volume’s data by the snapshot way.
• fs-backup: back up the action matching volumes’ data by the fs-backup way.

Supported conditions

Currently, Velero supports the volume attributes listed below:

• capacity: matching volumes have the capacity that falls within this capacity range. The capacity value should include the lower value and upper value concatenated by commas, the unit of each value in capacity could be Ti, Gi, Mi, Ki etc, which is a standard storage unit in Kubernetes. And it has several combinations below:
  • “0,5Gi” or “0Gi,5Gi” which means capacity or size matches from 0 to 5Gi, including value 0 and value 5Gi
  • “,5Gi” which is equal to “0,5Gi”
  • “5Gi,” which means capacity or size matches larger than 5Gi, including value 5Gi
  • “5Gi” which is not supported and will be failed in validating the configuration
• storageClass: matching volumes those with specified storageClass, such as gp2, ebs-sc in eks
• volume sources: matching volumes that used specified volume sources. Currently we support nfs or csi backend volume source
• pvcPhase: matching volumes based on the phase of their associated PVCs (Pending, Bound, Lost)
• pvcVolumeMode: matching volumes based on the volume mode of their associated PVCs (Filesystem, Block)
• pvcAccessModes: matching volumes based on the access modes of their associated PVCs (ReadWriteOnce, ReadOnlyMany, ReadWriteMany, ReadWriteOncePod). All configured access modes must be present on the PVC.

Velero supported conditions and format listed below:

• capacity

  # match volume has the size between 10Gi and 100Gi
  capacity: "10Gi,100Gi"
  

• storageClass

  # match volume has the storage class gp2 or ebs-sc
  storageClass:
    - gp2
    - ebs-sc
  

• volume sources (currently only support below format and attributes)

1. Specify the volume source name, the name could be nfs, rbd, iscsi, csi etc, but Velero only support nfs and csi currently.

   # match any volume has nfs volume source
   nfs : {}
   # match any volume has csi volume source
   csi : {}
   

2. Specify details for the related volume source (currently we only support csi driver filter and nfs server or path filter)

   # match volume has csi volume source and using `aws.efs.csi.driver`
   csi:
     driver: aws.efs.csi.driver 
   # match volume has nfs volume source and using below server and path
   nfs:
     server: 192.168.200.90
     path: /mnt/nfs
   

   For volume provisioned by Persistent Volumes support all above attributes, but for pod Volume only support filtered by volume source.

• volume types

  Support filter volumes by types

  volumeTypes: 
    # matches volumes listed below
    - emptyDir
    - downwardAPI
    - configmap
    - cinder
  

  Volume types could be found in Persistent Volumes and pod Volume

• pvc Labels

  This condition filters volumes based on the labels on their associated PVCs. The condition is specified as a simple key/value mapping. The volume matches this condition if all the key/value pairs defined in the policy are present on the PVC.

  pvcLabels:
    environment: production
  

  Some examples:

  • Environment specific labels: Snapshot volumes whose associated PVC has the label environment: production.

    volumePolicies:
    - conditions:
        pvcLabels:
          environment: production
      action:
        type: snapshot
    

  • Subset Matching: Even if the PVC contains extra labels, it will match as long as the required key/value pair is present. For example, if the PVC has:

    labels:
      environment: production
      team: backend
    

    the following policy will match because it only requires environment: production:

    volumePolicies:
    - conditions:
        pvcLabels:
          environment: production
      action:
        type: skip
    

  • Mismatched PVC Labels: If the policy requires both environment: production and app: frontend, but the PVC only has environment: production, the volume will not match.

    volumePolicies:
    - conditions:
        pvcLabels:
          environment: production
          app: frontend
      action:
        type: skip
    

• pvc Phase

  This condition filters volumes based on the phase of their associated PVCs. The condition is specified as a list of phases to match. The volume matches this condition if the PVC’s phase matches any of the phases in the list. Supported phases are: Pending, Bound, and Lost.

  pvcPhase:
    - Pending
  

  Some examples:

  • Skip Pending PVCs: Skip backup of volumes whose associated PVC is in Pending phase (useful for PVCs that haven’t been bound to a PV yet).

    volumePolicies:
    - conditions:
        pvcPhase:
          - Pending
      action:
        type: skip
    

  • Skip multiple phases: Skip backup of volumes whose associated PVC is either in Pending or Lost phase.

    volumePolicies:
    - conditions:
        pvcPhase:
          - Pending
          - Lost
      action:
        type: skip
    

  • Backup only Bound PVCs: Only backup volumes whose associated PVC is in Bound phase.

    volumePolicies:
    - conditions:
        pvcPhase:
          - Bound
      action:
        type: snapshot
    

  • Combine with other conditions: You can combine PVC phase conditions with other conditions like storage class or labels.

    volumePolicies:
    - conditions:
        pvcPhase:
          - Pending
        storageClass:
          - gp2
      action:
        type: skip
    

• pvc VolumeMode

  This condition filters PVC-backed volumes based on the volume mode of their associated PVCs. The condition is specified as a single volume mode to match. The volume matches this condition if the PVC’s volume mode exactly matches the configured value. Matching is case-sensitive, so block does not match Block. Supported volume modes are: Filesystem and Block. If pvcVolumeMode is omitted from a policy, volume mode is not restricted. Non-PVC volumes, such as emptyDir, configMap, or inline volumes without an associated PVC, do not match policies that require this condition.

  pvcVolumeMode: Block
  

  Some examples:

  • Skip Block PVCs: Skip backup of volumes whose associated PVC uses Block volume mode.

    volumePolicies:
    - conditions:
        pvcVolumeMode: Block
      action:
        type: skip
    

  • Combine with other conditions: You can combine PVC volume mode conditions with other conditions like PVC phase, storage class, or labels.

    volumePolicies:
    - conditions:
        pvcVolumeMode: Block
        pvcPhase:
          - Bound
      action:
        type: snapshot
    

• pvc AccessModes

  This condition filters PVC-backed volumes based on the access modes of their associated PVCs. The condition is specified as a list of access modes to match. The volume matches this condition only if the PVC has all of the access modes in the list. Matching is case-sensitive, so readwriteonce does not match ReadWriteOnce. Supported access modes are: ReadWriteOnce, ReadOnlyMany, ReadWriteMany, and ReadWriteOncePod. Non-PVC volumes, such as emptyDir, configMap, or inline volumes without an associated PVC, do not match policies that require this condition.

  pvcAccessModes:
    - ReadWriteOnce
  

  Some examples:

  • Skip ReadWriteOnce PVCs: Skip backup of volumes whose associated PVC includes the ReadWriteOnce access mode.

    volumePolicies:
    - conditions:
        pvcAccessModes:
          - ReadWriteOnce
      action:
        type: skip
    

  • Match multiple access modes: Apply an action to volumes whose associated PVC includes both ReadOnlyMany and ReadWriteMany.

    volumePolicies:
    - conditions:
        pvcAccessModes:
          - ReadOnlyMany
          - ReadWriteMany
      action:
        type: snapshot
    

  • Combine with other conditions: You can combine PVC access mode conditions with other conditions like PVC volume mode, PVC phase, storage class, or labels.

    volumePolicies:
    - conditions:
        pvcAccessModes:
          - ReadWriteOnce
        pvcVolumeMode: Block
      action:
        type: snapshot
    

Resource policies rules

• Velero already has lots of include or exclude filters. the resource policies are the final filters after others include or exclude filters in one backup processing workflow. So if use a defined similar filter like the opt-in approach to backup one pod volume but skip backup of the same pod volume in resource policies, as resource policies are the final filters that are applied, the volume will not be backed up.
• If volume resource policies conflict with themselves the first matched policy will be respected when many policies are defined.

VolumePolicy priority with existing filters

• Includes filters and Excludes filters have the highest priority. The filtered-out resources by them cannot reach to the VolumePolicy.
• The VolumePolicy has the second priority. It supersedes all the other filters.
• The filesystem volume backup opt-in/opt-out way has the third priority.
• The backup.Spec.SnapshotVolumes has the fourth priority.

Support for fs-backup and snapshot actions via volume policy feature

• Starting from velero 1.14, the volume policy feature has been extended to support more actions like fs-backup and snapshot.
• This feature only extends the action aspect of volume policy and not criteria aspect, the criteria components as described above remain the same.
• When we are using the volume policy approach for backing up the volumes then the volume policy criteria and action need to be specific and explicit, there is no default behaviour, if a volume matches fs-backup action then fs-backup method will be used for that volume and similarly if the volume matches the criteria for snapshot action then the snapshot workflow will be used for the volume backup.
• Another thing to note is that the volume policy workflow uses the legacy opt-in/opt-out approach as a fallback option. For instance, the user specifies a volume policy but for a particular volume included in the backup there are no actions(fs-backup/snapshot) matching in the volume policy for that volume, in such a scenario the legacy approach will be used for backing up the particular volume. Considering everything, the recommendation would be to use only one of the approaches to backup volumes - volume policy approach or the opt-in/opt-out legacy approach, and not mix them for clarity.
• Snapshot action can either be a native snapshot or a csi snapshot or csi snapshot datamover, as is the case with the current flow where velero itself makes the decision based on the backup CR’s existing options.
• The snapshot action supports an optional snapshotClass parameter that specifies which VolumeSnapshotClass to use for CSI snapshots. This is useful when multiple storage arrays share the same CSI driver but require different VolumeSnapshotClasses. When specified, this takes priority over backup annotations and VolumeSnapshotClass labels, but is overridden by PVC-level annotations. See the CSI documentation for the full VolumeSnapshotClass selection priority order.
• The snapshot action via Volume Policy has higher priority if there is a snapshot action matching for a particular volume, this volume would be backed up via snapshot irrespective of the value of backup.Spec.SnapshotVolumes.
• If for a particular volume there is no snapshot matching action then the volume will be backed up via snapshot given that backup.Spec.SnapshotVolumes is not explicitly set to false.
• Let’s see some examples on how to use the volume policy feature for fs-backup and snapshot action purposes:

We will use a simple application example in which there is an application pod which has 2 volumes:

• Volume 1 has associated Persistent Volume Claim 1 and Persistent Volume 1 which uses storage class gp2-csi
• Volume 2 has associated Persistent Volume Claim 2 and Persistent Volume 2 which uses storage class gp3-csi

Now lets go through some example uses-cases and their outcomes:

Example 1: User wants to use fs-backup action for backing up the volumes having storage class as gp2-csi

1. User specifies the volume policy as follows:

version: v1
volumePolicies:
- conditions:
    storageClass:
    - gp2-csi
  action:
    type: fs-backup

2. User creates a backup using this volume policy
3. The outcome would be that velero would perform fs-backup operation only on Volume 1 as only Volume 1 satisfies the criteria for fs-backup action.

Example 2: User wants to use snapshot action for backing up the volumes having storage class as gp2-csi

1. User specifies the volume policy as follows:

version: v1
volumePolicies:
- conditions:
    storageClass:
    - gp2-csi
  action:
    type: snapshot

2. User creates a backup using this volume policy
3. The outcome would be that velero would perform snapshot operation only on Volume 1 as only Volume 1 satisfies the criteria for snapshot action.

Example 3: User wants to use snapshot action for backing up the volumes having storage class as gp2-csi and wants to use fs-backup action for backing up the volumes having storage class as gp3-csi

1. User specifies the volume policy as follows:

version: v1
volumePolicies:
- conditions:
    storageClass:
    - gp2-csi
  action:
    type: snapshot
- conditions:
    storageClass:
    - gp3-csi
  action:
    type: fs-backup

2. User creates a backup using this volume policy
3. The outcome would be that velero would perform snapshot operation only on Volume 1 as only Volume 1 satisfies the criteria for snapshot action. Also, velero would perform fs-backup operation only on Volume 2 as only Volume 2 satisfies the criteria for fs-backup action.

Example 4: User wants to use snapshot action for backing up the volumes having storage class as gp3-csi and at the same time also annotates the pod to use opt-in fs-backup legacy approach for Volume 1

1. User specifies the volume policy as follows and also annotates the pod with backup.velero.io/backup-volumes=Volume 1

version: v1
volumePolicies:
- conditions:
    storageClass:
    - gp3-csi
  action:
    type: snapshot

2. User creates a backup using this volume policy
3. The outcome would be that velero would perform snapshot operation for Volume 2 as it matches the action criteria and velero would also perform the fs-backup operation for Volume-1 via the legacy annotations based fallback approach as there is no matching action for Volume-1

Example 5: User wants to use fs-backup action for backing up the volumes having storage class as gp2-csi and at the same time also specifies defaultVolumesToFSBackup: true (fallback option for no action matching volumes)

1. User specifies the volume policy as follows and specifies defaultVolumesToFSBackup: true:

version: v1
volumePolicies:
- conditions:
    storageClass:
    - gp2-csi
  action:
    type: fs-backup

2. User creates a backup using this volume policy
3. The outcome would be that velero would perform fs-backup operation on both the volumes
   • fs-backup on Volume 1 because Volume 1 satisfies the criteria for fs-backup action.
   • Also, for Volume 2 as no matching action was found so legacy approach will be used as a fallback option for this volume (fs-backup operation will be done as defaultVolumesToFSBackup: true is specified by the user).

Example 6: User has two storage arrays using the same CSI driver and needs different VolumeSnapshotClasses for each

1. User specifies the volume policy as follows:

version: v1
volumePolicies:
- conditions:
    storageClass:
    - array-1-sc
  action:
    type: snapshot
    parameters:
      snapshotClass: vsc-array-1
- conditions:
    storageClass:
    - array-2-sc
  action:
    type: snapshot
    parameters:
      snapshotClass: vsc-array-2

2. User creates a backup using this volume policy
3. The outcome would be that velero would use vsc-array-1 VolumeSnapshotClass for volumes on storage class array-1-sc and vsc-array-2 VolumeSnapshotClass for volumes on storage class array-2-sc, even though both storage classes use the same CSI driver.

Global backup volume policies

Resource policies (volume policies) are normally opt-in per backup via --resource-policies-configmap. An administrator can instead configure a cluster-wide baseline that applies to every backup by starting the Velero server with the --global-backup-volume-policies-configmap flag, pointing at a ConfigMap in the Velero install namespace:

velero server --global-backup-volume-policies-configmap global-volume-policy

The ConfigMap uses the exact same format as a per-backup resource policies ConfigMap (a single data key holding a ResourcePolicies YAML document):

apiVersion: v1
kind: ConfigMap
metadata:
  name: global-volume-policy
  namespace: velero
data:
  policies.yaml: |
    version: v1
    volumePolicies:
      - conditions:
          storageClass:
            - gp2
        action:
          type: skip

Behavior

• Only volumePolicies apply globally. If the global ConfigMap contains includeExcludePolicy, clusterScopedFilterPolicy, or namespacedFilterPolicies, those sections are ignored and a warning is logged. Those filters are tied to a specific backup use case, so they remain per-backup only.

• Merge semantics. When a backup runs, the effective volumePolicies list is the backup-level policies followed by the global policies:

  merged.volumePolicies = backup.volumePolicies ++ global.volumePolicies
  

  Because the first matching policy wins, a backup can override the global baseline for a specific volume while still inheriting every global rule it does not override. If a backup references no resource policy, the global policy applies on its own.

• Validation. The global ConfigMap is validated at server startup (the server fails to start if it is missing or invalid) and again on each backup (a backup whose global policy has become missing or invalid is moved to the FailedValidation phase).

Example

Global policy (--global-backup-volume-policies-configmap=global-volume-policy): skip gp2 volumes.

version: v1
volumePolicies:
  - conditions:
      storageClass:
        - gp2
    action:
      type: skip

Backup-level policy (--resource-policies-configmap backup01): fs-backup NFS volumes.

version: v1
volumePolicies:
  - conditions:
      nfs: {}
    action:
      type: fs-backup

Effective (merged) policy used for the backup — backup rules first, then global:

version: v1
volumePolicies:
  - conditions:
      nfs: {}
    action:
      type: fs-backup
  - conditions:
      storageClass:
        - gp2
    action:
      type: skip

When a global policy contributes to a backup, velero backup describe surfaces the contributing ConfigMap under a Global volume policies section.