mirror of
https://github.com/vmware-tanzu/velero.git
synced 2026-08-15 19:56:06 +00:00
Merge pull request #10016 from adam-jian-zhang/restore-filters-guide
add documentation for fine-grained restore filters
This commit is contained in:
Adam Zhang
@@ -0,0 +1 @@
|
||||
Fix issue #9938, add use guide for restore fine-grained filters via resource policy
|
||||
@@ -0,0 +1,726 @@
|
||||
---
|
||||
title: "Fine-Grained Restore Filters"
|
||||
layout: docs
|
||||
---
|
||||
|
||||
This guide explains how to use Velero's **fine-grained restore filters**: per-namespace, per-kind rules with independent label selectors and resource name patterns. Configuration lives in a **ResourcePolicy ConfigMap**, using the exact same format introduced for fine-grained backup filters.
|
||||
|
||||
For architecture and pipeline details, see the [design document](https://github.com/velero-io/velero/blob/main/design/restore-filter-enhancement/fine-grained-restore-filters-design.md).
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Velero's traditional restore filters apply the same namespace list, resource types, and label selector to every namespace being restored. Common scenarios need more control:
|
||||
|
||||
- **Selective restore from a full backup** — restore only specific application components from a namespace, leaving out monitoring or logging resources that were also backed up.
|
||||
- **Cross-environment migration** — restore StatefulSets and PVCs in a database namespace, but only Deployments and Services in a frontend namespace.
|
||||
- **Filter by resource name** — restore `app-config` and `app-secret` without restoring `monitoring-config` from the same namespace.
|
||||
- **Restore-time override** — apply different label selectors during restore than were used during backup to handle environment differences.
|
||||
|
||||
Fine-grained filters add two optional sections to the ResourcePolicy ConfigMap:
|
||||
|
||||
| Section | Scope | Behavior |
|
||||
|---------|-------|----------|
|
||||
| `namespacedFilterPolicies` | Namespaces you match (exact name or glob) | **Exclusive allowlist** — only resource kinds listed in `resourceFilters` (or covered by a catch-all) are restored for those namespaces, provided they pass global filters. |
|
||||
| `clusterScopedFilterPolicy` | Cluster-scoped resources globally | **Refinement overlay** — listed kinds get per-kind label and name rules; unlisted cluster-scoped kinds still use global RestoreSpec filters. |
|
||||
|
||||
**Backward compatible:** Fine-grained restore filters are optional. If a restore does not reference a ResourcePolicy, Velero relies solely on standard RestoreSpec filters (includedNamespaces, includedResources, labelSelector, etc.).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites and wiring
|
||||
|
||||
### What you need
|
||||
|
||||
- A ResourcePolicy ConfigMap in the Velero namespace (`velero` by default).
|
||||
- Permission to create Restores that reference the ConfigMap.
|
||||
|
||||
### End-to-end pattern
|
||||
|
||||
Every example below follows the same three steps:
|
||||
|
||||
1. **Create or update** a ConfigMap with `data.policy` containing `version: v1` and your filter rules.
|
||||
2. **Create a Restore** that includes the target namespaces and references the ConfigMap.
|
||||
3. **Verify** with `velero restore describe` and inspect the restored resources.
|
||||
|
||||
### Minimal skeleton
|
||||
|
||||
Use this once; later examples show only the `policy:` body.
|
||||
|
||||
**ResourcePolicy ConfigMap:**
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: my-restore-filter-policy
|
||||
namespace: velero
|
||||
data:
|
||||
policy: |
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- my-namespace
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
|
||||
```yaml
|
||||
apiVersion: velero.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: my-restore
|
||||
namespace: velero
|
||||
spec:
|
||||
backupName: my-backup
|
||||
includedNamespaces:
|
||||
- my-namespace
|
||||
resourcePolicy:
|
||||
kind: configmap
|
||||
name: my-restore-filter-policy
|
||||
```
|
||||
|
||||
**CLI equivalent:**
|
||||
|
||||
```bash
|
||||
velero restore create my-restore \
|
||||
--from-backup my-backup \
|
||||
--include-namespaces my-namespace \
|
||||
--resource-policies-configmap my-restore-filter-policy
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
|
||||
```bash
|
||||
velero restore describe my-restore
|
||||
```
|
||||
|
||||
### Important: Interaction with Global Filters
|
||||
|
||||
The restore pipeline evaluates **global resource filters first**:
|
||||
- `RestoreSpec.IncludedResources` and `RestoreSpec.ExcludedResources` act as a global gate.
|
||||
- A resource kind **must** pass the global gate before per-namespace filters are evaluated.
|
||||
- **A namespace policy cannot re-include a globally excluded kind.** If you globally exclude `secrets`, listing `Secret` in a namespace policy will have no effect.
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
Each example includes: **goal**, **policy YAML**, **restore notes**, and **expected outcome**.
|
||||
|
||||
---
|
||||
|
||||
### Example 0 — Baseline (no new filters)
|
||||
|
||||
**Goal:** Confirm that namespaces without a `namespacedFilterPolicies` entry still use global RestoreSpec filters.
|
||||
|
||||
**Policy:** Omit `namespacedFilterPolicies` and `clusterScopedFilterPolicy` entirely.
|
||||
|
||||
**Restore:**
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
includedNamespaces:
|
||||
- ns-a
|
||||
- ns-b
|
||||
# No resourcePolicy — global filters only
|
||||
```
|
||||
|
||||
**Expected outcome:** All resources in included namespaces follow `includedNamespaces`, `labelSelector`, `includedResources`, and related global fields — same as before this feature.
|
||||
|
||||
---
|
||||
|
||||
### Example 1 — Per-namespace kinds and labels
|
||||
|
||||
**Goal:** In `ns-a`, restore only ConfigMaps, Secrets, Deployments, and Pods with `app=my-app`. In `ns-b`, use global filters (no policy entry for that namespace).
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap, Secret, Deployment, Pod]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
includedNamespaces:
|
||||
- ns-a
|
||||
- ns-b
|
||||
resourcePolicy:
|
||||
kind: configmap
|
||||
name: per-namespace-resource-filter-policy
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- **ns-a:** Only listed kinds with label `app=my-app` (e.g. `app-config`, `app-secret`, `app-deployment`). Resources like `monitoring-config` (different labels) are excluded.
|
||||
- **ns-b:** Everything allowed by global filters (no namespace policy match).
|
||||
|
||||
---
|
||||
|
||||
### Example 2 — Exact resource names
|
||||
|
||||
**Goal:** Restore only two ConfigMaps by exact name, optionally requiring a label.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- target-namespace
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap]
|
||||
names: [vm-1, vm-2]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
resource-type: VirtualMachine
|
||||
```
|
||||
|
||||
**Expected outcome:** Only `vm-1` and `vm-2` ConfigMaps with `resource-type=VirtualMachine` are restored. `vm-3` and other ConfigMaps are skipped.
|
||||
|
||||
---
|
||||
|
||||
### Example 3 — Glob name patterns with exclusions
|
||||
|
||||
**Goal:** Restore `app-*` ConfigMaps and Secrets in `production`, but exclude temporary and debug names.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- production
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap, Secret]
|
||||
names: ["app-*"]
|
||||
excludedNames: ["*-tmp-*", "*-debug-*", "*-tmp", "*-debug"]
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- **Included:** `app-config`, `app-cache-config`, `app-secret`
|
||||
- **Excluded:** `app-config-tmp`, `app-tmp-config`, `app-debug-config`, `monitoring-tmp-secret`
|
||||
|
||||
`excludedNames` takes precedence over `names` when both match.
|
||||
|
||||
---
|
||||
|
||||
### Example 4 — Per-kind label selectors
|
||||
|
||||
**Goal:** Apply different label rules to different resource types in the same namespace.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- target-namespace
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap]
|
||||
orLabelSelectors:
|
||||
- matchLabels:
|
||||
app: production-workload-1
|
||||
component: vm-group
|
||||
- matchLabels:
|
||||
app: production-workload-2
|
||||
component: vm-service
|
||||
```
|
||||
|
||||
**Expected outcome:** ConfigMaps matching either label combination are restored; other ConfigMaps in the namespace are not.
|
||||
|
||||
**Note:** Prefer `matchExpressions` with `In` for value-OR on a single key (see next example). Use `orLabelSelectors` when you need OR across **independent multi-key groups**. `labelSelector` and `orLabelSelectors` cannot appear in the same `resourceFilters` entry.
|
||||
|
||||
---
|
||||
|
||||
### Example 4b — Set-based label selectors (`matchExpressions`)
|
||||
|
||||
**Goal:** Restore Deployments and Pods that are in `prod` or `staging`, belong to `app=my-app`, and do **not** carry a skip label.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- production
|
||||
resourceFilters:
|
||||
- kinds: [Deployment, Pod]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
matchExpressions:
|
||||
- key: environment
|
||||
operator: In
|
||||
values: [prod, staging]
|
||||
- key: do-not-restore
|
||||
operator: DoesNotExist
|
||||
```
|
||||
|
||||
**Supported operators:** `In`, `NotIn`, `Exists`, `DoesNotExist` (same as Kubernetes / Velero global `--selector`).
|
||||
|
||||
**Other useful patterns:**
|
||||
|
||||
```yaml
|
||||
# Exclude environments
|
||||
matchExpressions:
|
||||
- key: environment
|
||||
operator: NotIn
|
||||
values: [dev, test]
|
||||
|
||||
# Require a label key to be present (any value)
|
||||
matchExpressions:
|
||||
- key: tier
|
||||
operator: Exists
|
||||
```
|
||||
|
||||
**Expected outcome:** Only Deployments/Pods with `app=my-app`, `environment` in `{prod, staging}`, and without `do-not-restore` are restored.
|
||||
|
||||
---
|
||||
|
||||
### Example 5 — OR label selectors across kinds
|
||||
|
||||
**Goal:** Restore ConfigMaps, Secrets, or Deployments that match any of several label conditions.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap, Secret]
|
||||
orLabelSelectors:
|
||||
- matchLabels:
|
||||
app: my-app
|
||||
- matchLabels:
|
||||
app: monitoring
|
||||
- kinds: [Deployment]
|
||||
orLabelSelectors:
|
||||
- matchLabels:
|
||||
app: my-app
|
||||
- matchLabels:
|
||||
app: monitoring
|
||||
- matchLabels:
|
||||
component: backend
|
||||
```
|
||||
|
||||
**Expected outcome:** Resources included if they match **any** selector in `orLabelSelectors` for their kind (AND within each selector, OR across the list).
|
||||
|
||||
---
|
||||
|
||||
### Example 6 — Multiple criteria on one kind
|
||||
|
||||
**Goal:** Combine exact names with OR label selectors for a single kind.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- target-namespace
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap]
|
||||
names: [vm-1, vm-2]
|
||||
orLabelSelectors:
|
||||
- matchLabels:
|
||||
resource-type: VirtualMachine
|
||||
- matchLabels:
|
||||
component: vm-group
|
||||
- matchLabels:
|
||||
component: vm-service
|
||||
```
|
||||
|
||||
**Expected outcome:** Only `vm-1` and `vm-2` that also satisfy one of the label OR branches.
|
||||
|
||||
---
|
||||
|
||||
### Example 7 — One policy entry, multiple namespaces
|
||||
|
||||
**Goal:** Apply the same rules to `ns-a`, `ns-b`, and `production` in a single policy block.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
- ns-b
|
||||
- production
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap]
|
||||
- kinds: [Deployment]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
tier: web
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- All ConfigMaps in those namespaces (no label filter on that entry).
|
||||
- Deployments with `tier=web` only.
|
||||
|
||||
---
|
||||
|
||||
### Example 8 — Namespace glob patterns and ordering
|
||||
|
||||
**Goal:** Different restore breadth for `team-frontend-prod`, `team-frontend-dev`, and `team-backend-test` using glob patterns.
|
||||
|
||||
**Note on Precedence:** Exact namespace matches always take precedence regardless of where they are listed. However, if multiple glob patterns could match a namespace, they are evaluated in the order they appear. Always list specific globs before broad globs.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
# Globs must be ordered specific-to-broad
|
||||
- namespaces:
|
||||
- "team-frontend-*" # specific pattern match
|
||||
resourceFilters:
|
||||
- kinds: [Deployment, Service, ConfigMap]
|
||||
- namespaces:
|
||||
- "team-*" # broad pattern
|
||||
resourceFilters:
|
||||
- kinds: [Deployment, Service]
|
||||
|
||||
# Exact matches always win, even if placed at the bottom
|
||||
- namespaces:
|
||||
- team-frontend-prod # exact match
|
||||
resourceFilters:
|
||||
- kinds: [Deployment, Service, ConfigMap, Secret, PersistentVolumeClaim]
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
| Namespace | Matched policy | Kinds restored |
|
||||
|-----------|----------------|-----------------|
|
||||
| `team-frontend-prod` | `team-frontend-prod` (Exact match priority) | 5 kinds |
|
||||
| `team-frontend-dev` | `team-frontend-*` (First matching glob) | 3 kinds |
|
||||
| `team-backend-test` | `team-*` (First matching glob) | 2 kinds |
|
||||
|
||||
Velero uses **first-match** semantics: the first policy entry whose namespace pattern matches wins.
|
||||
|
||||
---
|
||||
|
||||
### Example 9 — Catch-all by label
|
||||
|
||||
**Goal:** Restore any resource kind that has a given label, without listing every kind. Kind-specific entries override the catch-all.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: ["*"] # catch-all
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: common-app
|
||||
- kinds: [ConfigMap, Secret] # override for these kinds
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: specialized-app
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- At most **one** catch-all per namespace policy entry.
|
||||
- Catch-all entries **cannot** use `names` or `excludedNames`.
|
||||
- Catch-all does **not** inherit `RestoreSpec.LabelSelector`.
|
||||
|
||||
**Expected outcome:** ConfigMaps and Secrets use `app=specialized-app`; all other kinds listed only via catch-all use `app=common-app`.
|
||||
|
||||
---
|
||||
|
||||
### Example 10 — Catch-all with per-kind name overrides
|
||||
|
||||
**Goal:** Pin critical Deployments and Secrets by exact name; restore everything else with a label convention.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: [Deployment]
|
||||
names: [api-server, worker]
|
||||
- kinds: [Secret]
|
||||
names: [db-credentials, tls-cert]
|
||||
- kinds: ["*"]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
restore: "true"
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- Deployments: only `api-server` and `worker`
|
||||
- Secrets: only `db-credentials` and `tls-cert`
|
||||
- Other kinds (ConfigMap, Service, …): resources with `restore=true` only
|
||||
|
||||
---
|
||||
|
||||
### Example 11 — Override-only catch-all (no label on catch-all)
|
||||
|
||||
**Goal:** Apply a strict name filter to one kind while restoring all other kinds without listing them or adding labels.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: [Secret]
|
||||
names: [app-secret]
|
||||
- kinds: ["*"] # no labelSelector — all other kinds included
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- Secrets: only `app-secret`
|
||||
- Other kinds in `ns-a`: all instances restored (subject to global filters)
|
||||
|
||||
---
|
||||
|
||||
### Example 12 — Cluster-scoped refinement
|
||||
|
||||
**Goal:** Refine which cluster-scoped resources are restored by name and label, without replacing global cluster-scoped inclusion.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
clusterScopedFilterPolicy:
|
||||
resourceFilters:
|
||||
- kinds: [StorageClass]
|
||||
names: ["my-app-*"]
|
||||
- kinds: [ClusterRole, ClusterRoleBinding]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
```
|
||||
|
||||
**Restore (required):** You must still include cluster-scoped kinds on the Restore:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
includeClusterResources: true
|
||||
resourcePolicy:
|
||||
kind: configmap
|
||||
name: cluster-scoped-filter-policy
|
||||
```
|
||||
|
||||
**Expected outcome:**
|
||||
|
||||
- StorageClasses matching `my-app-*` only
|
||||
- ClusterRoles and ClusterRoleBindings with `app=my-app` only
|
||||
- Other cluster-scoped resources: restored according to global filters.
|
||||
|
||||
**Differences from namespace policies:**
|
||||
|
||||
- **Not** an allowlist — unlisted cluster-scoped kinds fall back to global filters.
|
||||
- **No catch-all** — `kinds: []` or `kinds: ["*"]` is invalid and fails validation.
|
||||
|
||||
---
|
||||
|
||||
### Example 13 — Global `ExcludedResources` and namespace filters
|
||||
|
||||
**Goal:** Understand that global **exclusions** cannot be overridden per namespace.
|
||||
|
||||
**Restore:**
|
||||
```yaml
|
||||
spec:
|
||||
excludedResources:
|
||||
- secrets
|
||||
```
|
||||
|
||||
**Policy:**
|
||||
```yaml
|
||||
version: v1
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- ns-a
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap, Secret, Deployment]
|
||||
labelSelector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
```
|
||||
|
||||
**Result:** No Secrets are restored — the namespace policy cannot re-include a globally excluded kind. Velero logs a warning at restore start if you list an excluded kind in `namespacedFilterPolicies`.
|
||||
|
||||
---
|
||||
|
||||
### Example 14 — Separate ConfigMaps for Backup and Restore
|
||||
|
||||
**Goal:** Understand why you cannot use a single ConfigMap for both backup and restore operations if it contains backup-specific policies.
|
||||
|
||||
**Policy:**
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
volumePolicies:
|
||||
- conditions:
|
||||
capacity: "0,10Gi"
|
||||
action:
|
||||
type: fs-backup
|
||||
namespacedFilterPolicies:
|
||||
- namespaces:
|
||||
- production
|
||||
resourceFilters:
|
||||
- kinds: [ConfigMap, Secret]
|
||||
names: ["app-*"]
|
||||
```
|
||||
|
||||
**Expected outcome:** The restore operation will **fail validation**. The Velero restore pipeline strictly rejects any ResourcePolicy ConfigMap containing `volumePolicies` or `includeExcludePolicy`. To avoid this, the restore-side ConfigMap should contain only the restore-supported sections (`namespacedFilterPolicies` and/or `clusterScopedFilterPolicy`).
|
||||
|
||||
---
|
||||
|
||||
### Example 15 — `velero.io/exclude-from-backup=true` always wins
|
||||
|
||||
**Goal:** Ensure explicitly excluded resources never appear in the restore.
|
||||
|
||||
If a resource was backed up (perhaps before the label was added, or manually modified in the archive) but has `velero.io/exclude-from-backup: "true"`, the restore pipeline honors it. Any item carrying this label is skipped regardless of whether it matches global or per-namespace restore filters.
|
||||
|
||||
---
|
||||
|
||||
## Concepts reference
|
||||
|
||||
### `resourceFilters` fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `kinds` | Resource type names (e.g. `ConfigMap`, `deployments`). Empty or `["*"]` = catch-all (namespace policies only). |
|
||||
| `labelSelector` | Kubernetes-style selector with `matchLabels` and/or `matchExpressions` (`In`, `NotIn`, `Exists`, `DoesNotExist`). All requirements are AND-ed. |
|
||||
| `orLabelSelectors` | List of selectors; match if **any** entry matches (AND within each, OR across the list). Use for OR of multi-key groups; prefer `In` for value-OR on one key. Mutually exclusive with `labelSelector`. |
|
||||
| `names` | Exact names or glob patterns to include. |
|
||||
| `excludedNames` | Patterns to exclude; wins over `names` when both match. |
|
||||
|
||||
### Glob pattern syntax
|
||||
|
||||
Name and namespace patterns use the same glob style as elsewhere in Velero (`gobwas/glob`):
|
||||
|
||||
- Supported: `*`, `?`, `[abc]`, `[a-z]`
|
||||
- Not supported: `**`, regex, `|`, `()`, `!`, `{}`, `,`
|
||||
|
||||
Examples: `app-*`, `team-frontend-*`, `*-tmp`.
|
||||
|
||||
### Precedence cheat sheet
|
||||
|
||||
**Namespaces**
|
||||
|
||||
1. `RestoreSpec.ExcludedNamespaces` — excluded namespaces are never restored.
|
||||
2. `namespacedFilterPolicies` — first matching pattern (exact match checked before globs in pattern order).
|
||||
3. No match — use global RestoreSpec filters.
|
||||
|
||||
**Namespace-scoped resources (when a namespace policy matches)**
|
||||
|
||||
1. Global `RestoreSpec.IncludedResources` / `ExcludedResources` apply first.
|
||||
2. Only kinds in `resourceFilters` (or catch-all) are allowlisted for restoration.
|
||||
3. Per-kind `labelSelector` / `orLabelSelectors` replace global selectors.
|
||||
4. Per-kind `names` / `excludedNames` filter by resource name.
|
||||
5. Label `velero.io/exclude-from-backup=true` always excludes.
|
||||
6. **Plugin Additional Items** bypass fine-grained filters to ensure dependencies (like PVs) are restored.
|
||||
|
||||
**Cluster-scoped resources**
|
||||
|
||||
1. Must be allowed by global cluster settings (`includeClusterResources`).
|
||||
2. If `clusterScopedFilterPolicy` lists the kind, apply its label and name rules.
|
||||
3. If not listed in `clusterScopedFilterPolicy`, use global RestoreSpec filters.
|
||||
4. `velero.io/exclude-from-backup=true` always excludes.
|
||||
|
||||
### Catch-all summary
|
||||
|
||||
| Rule | Detail |
|
||||
|------|--------|
|
||||
| Syntax | `kinds: ["*"]` or `kinds: []` |
|
||||
| Count | At most one catch-all per `namespacedFilterPolicies` entry |
|
||||
| Names | `names` / `excludedNames` not allowed on catch-all |
|
||||
| Override | Kind-specific entries take precedence over catch-all |
|
||||
| Label inheritance | Does not use `RestoreSpec.LabelSelector` |
|
||||
| Cluster-scoped | Catch-all **not** supported in `clusterScopedFilterPolicy` |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting and validation
|
||||
|
||||
### Verify a restore
|
||||
|
||||
```bash
|
||||
velero restore describe RESTORE_NAME
|
||||
velero restore logs RESTORE_NAME
|
||||
```
|
||||
|
||||
The output of `velero restore describe` will show the `Resource Policy` field if a ConfigMap was used.
|
||||
|
||||
### Common misconfigurations
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---------|----------------|-----|
|
||||
| Fewer resources than expected in `team-frontend-prod` | Broad namespace pattern listed before specific one | Reorder policies: most specific `namespaces` first |
|
||||
| Namespace policy lists Secrets but none restored | `RestoreSpec.ExcludedResources` excludes `secrets` globally | Remove global exclusion or accept no Secrets |
|
||||
| `ClusterRole` in namespace policy has no effect | Cluster-scoped kind in `namespacedFilterPolicies` | Move rule to `clusterScopedFilterPolicy`; check logs for warning |
|
||||
| Catch-all does not use restore-wide label | By design | Set `labelSelector` on the catch-all entry |
|
||||
| Cluster-scoped policy validation error on `kinds: ["*"]` | Catch-all not allowed for cluster policy | List each cluster-scoped kind explicitly |
|
||||
|
||||
### Velero logs
|
||||
|
||||
```bash
|
||||
kubectl logs -n velero deployment/velero | grep -i "namespacedFilterPolicies\|clusterScopedFilterPolicy"
|
||||
kubectl logs -n velero deployment/velero | grep "globally excluded by RestoreSpec.ExcludedResources"
|
||||
```
|
||||
|
||||
### Validation errors (policy ConfigMap)
|
||||
|
||||
Velero validates the ResourcePolicy when a restore starts. Common errors:
|
||||
|
||||
| Error (summary) | Cause |
|
||||
|-----------------|--------|
|
||||
| `at least one namespace must be specified` | Empty `namespaces: []` |
|
||||
| `at least one resourceFilter must be specified` | Empty `resourceFilters: []` |
|
||||
| `names or excludedNames cannot be specified for catch-all filters` | Name patterns on catch-all entry |
|
||||
| `only one catch-all resource filter is allowed` | Multiple catch-alls in one policy entry |
|
||||
| `kind "X" appears in both resourceFilters[...]` | Same kind in two entries |
|
||||
| `labelSelector and orLabelSelectors cannot co-exist` | Both set in one entry |
|
||||
| `invalid label selector` | Bad operator, values, or label key/value syntax |
|
||||
| `duplicate namespace pattern` | Same namespace string in two policy entries |
|
||||
| `invalid glob pattern` | Bad characters in namespace or name pattern |
|
||||
| `clusterScopedFilterPolicy... kinds must be specified (catch-all is not supported)` | Empty or `["*"]` kinds in cluster policy |
|
||||
|
||||
### Silent edge cases (no error)
|
||||
|
||||
- Namespace pattern matches no existing namespace in the backup — policy loaded but never applied.
|
||||
- Kind listed but no instances in namespace — empty result, restore still succeeds.
|
||||
- `excludedNames` narrows `names` — e.g. `names: ["app-*"]` + `excludedNames: ["app-config"]` excludes `app-config` only.
|
||||
|
||||
---
|
||||
|
||||
## Related links
|
||||
|
||||
- [Fine-grained restore filters design](https://github.com/velero-io/velero/blob/main/design/restore-filter-enhancement/fine-grained-restore-filters-design.md)
|
||||
@@ -5,8 +5,8 @@ layout: docs
|
||||
|
||||
*Filter objects by namespace, type, labels or resource policies.*
|
||||
|
||||
This page describes how to filter resource for backup and restore.
|
||||
User could use the include and exclude flags with the `velero backup` and `velero restore` commands. And user could also use resource policies to handle backup.
|
||||
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
|
||||
@@ -229,104 +229,139 @@ Kubernetes namespace resources to exclude from the backup, formatted as resource
|
||||
```
|
||||
|
||||
## Resource policies
|
||||
Velero provides resource policies to filter resources to do backup, which may contain `includeExcludePolicy` and `volumePolicies`.
|
||||
|
||||
### Creating 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.
|
||||
|
||||
Below is the two-step of using resource policies in backup:
|
||||
1. Creating resource policies configmap
|
||||
Resource policies support both **Backup** and **Restore** operations, though certain policy sections are specific to backup workflows.
|
||||
|
||||
Users need to create one configmap in Velero install namespace from a YAML file that defined resource policies. The creating command would be like the below:
|
||||
### Supported policy sections by operation
|
||||
|
||||
| Policy Section | Description | Supported Operations | Learn More |
|
||||
| --- | --- | --- | --- |
|
||||
| `namespacedFilterPolicies` | Fine-grained per-namespace and per-kind filters with label selectors and resource name patterns. | **Backup** & **Restore** | [Fine-Grained Backup Filters](fine-grained-backup-filters.md) / [Fine-Grained Restore Filters](fine-grained-restore-filters.md) |
|
||||
| `clusterScopedFilterPolicy` | Fine-grained cluster-scoped filter overlays with per-kind label selectors and resource name patterns. | **Backup** & **Restore** | [Fine-Grained Backup Filters](fine-grained-backup-filters.md) / [Fine-Grained Restore Filters](fine-grained-restore-filters.md) |
|
||||
| `volumePolicies` | Rules to control volume data backup methods (`skip`, `snapshot`, `fs-backup`) based on conditions. | **Backup** only | See [VolumePolicy](#volumepolicy-backup-only) |
|
||||
| `includeExcludePolicy` | Reusable scoped resource include/exclude filters. | **Backup** only | See [IncludeExcludePolicy](#includeexcludepolicy-backup-only) |
|
||||
|
||||
### 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:
|
||||
```bash
|
||||
kubectl create cm <configmap-name> --from-file <yaml-file> -n velero
|
||||
```
|
||||
2. Creating a backup reference to the defined resource policies
|
||||
|
||||
Users create a backup with the flag `--resource-policies-configmap`, which will reference the current backup to the defined resource policies. The creating command would be like the below:
|
||||
```bash
|
||||
velero backup create --resource-policies-configmap <configmap-name>
|
||||
```
|
||||
This flag could also be combined with the other include and exclude filters above
|
||||
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:
|
||||
```bash
|
||||
velero backup create <backup-name> --resource-policies-configmap <configmap-name>
|
||||
```
|
||||
Or in `Backup.spec`:
|
||||
```yaml
|
||||
spec:
|
||||
resourcePolicy:
|
||||
kind: ConfigMap
|
||||
name: <configmap-name>
|
||||
```
|
||||
|
||||
* **For Restore:** Reference the ConfigMap via CLI flag or in the Restore CR spec:
|
||||
```bash
|
||||
velero restore create <restore-name> --from-backup <backup-name> --resource-policies-configmap <configmap-name>
|
||||
```
|
||||
Or in `Restore.spec`:
|
||||
```yaml
|
||||
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 would look like this:
|
||||
- Yaml template:
|
||||
```yaml
|
||||
# currently only supports v1 version
|
||||
version: v1
|
||||
# The filters in includeExcludePolicy work the same as the scoped resources filters in the Spec of a Backup
|
||||
# NOTE: similar to scoped filters in Backup Spec, the includeExcludePolicy does not work with --include-resources, --exclude-resources and --include-cluster-resources filters in Backup.
|
||||
includeExcludePolicy:
|
||||
includedClusterScopedResources:
|
||||
- "crd"
|
||||
- "pv"
|
||||
excludedClusterScopedResources: []
|
||||
includedNamespaceScopedResources:
|
||||
- "pod"
|
||||
- "service"
|
||||
- "deployment"
|
||||
- "pvc"
|
||||
excludedNamespaceScopedResources:
|
||||
- "configmap"
|
||||
- "secret"
|
||||
volumePolicies:
|
||||
# each policy consists of a list of conditions and an action
|
||||
# we could have lots of policies, but if the resource matched the first policy, the latter will be ignored
|
||||
# each key in the object is one condition, and one policy will apply to resources that meet ALL conditions
|
||||
# NOTE: capacity or storageClass is suited for [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes), and pod [Volume](https://kubernetes.io/docs/concepts/storage/volumes) not support it.
|
||||
- conditions:
|
||||
# capacity condition matches the volumes whose capacity falls into the range
|
||||
capacity: "10,100Gi"
|
||||
# pv matches specific csi driver
|
||||
csi:
|
||||
driver: ebs.csi.aws.com
|
||||
# pv matches one of the storage class list
|
||||
storageClass:
|
||||
- gp2
|
||||
- standard
|
||||
# pvc matches specific phase(s)
|
||||
pvcPhase:
|
||||
- Pending
|
||||
# pvc matches specific volume mode
|
||||
pvcVolumeMode: Block
|
||||
# pvc matches specific access mode(s)
|
||||
pvcAccessModes:
|
||||
- ReadWriteOnce
|
||||
action:
|
||||
type: skip
|
||||
- conditions:
|
||||
capacity: "0,100Gi"
|
||||
# nfs volume source with specific server and path (nfs could be empty or only config server or path)
|
||||
nfs:
|
||||
server: 192.168.200.90
|
||||
path: /mnt/data
|
||||
action:
|
||||
type: skip
|
||||
- conditions:
|
||||
nfs:
|
||||
server: 192.168.200.90
|
||||
action:
|
||||
type: fs-backup
|
||||
- conditions:
|
||||
# nfs could be empty which matches any nfs volume source
|
||||
nfs: {}
|
||||
action:
|
||||
type: skip
|
||||
- conditions:
|
||||
# csi could be empty which matches any csi volume source
|
||||
csi: {}
|
||||
action:
|
||||
type: snapshot
|
||||
- conditions:
|
||||
volumeTypes:
|
||||
- emptyDir
|
||||
- downwardAPI
|
||||
- configmap
|
||||
- cinder
|
||||
action:
|
||||
type: skip
|
||||
```
|
||||
### IncludeExcludePolicy
|
||||
|
||||
The policies YAML config file showing all supported sections:
|
||||
|
||||
```yaml
|
||||
# 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-backup-filters.md)
|
||||
* [Fine-Grained Restore Filters](fine-grained-restore-filters.md)
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -365,7 +400,7 @@ velero backup create <backup-name> --resource-policies-configmap my-policy --inc
|
||||
The backup will include all resources in namespace `my-workload-ns`, including `configmap` and `event`, and all CRDs and
|
||||
`apiservices` in the cluster.
|
||||
|
||||
### VolumePolicy
|
||||
### VolumePolicy (Backup only)
|
||||
VolumePolicy is a data structure to control how velero handle the volumes matching certain conditions.
|
||||
|
||||
#### Supported VolumePolicy actions
|
||||
|
||||
@@ -35,6 +35,8 @@ toc:
|
||||
url: /resource-filtering
|
||||
- page: Fine-Grained Backup Filters
|
||||
url: /fine-grained-backup-filters
|
||||
- page: Fine-grained restore filters
|
||||
url: /fine-grained-restore-filters
|
||||
- page: Namespace glob patterns
|
||||
url: /namespace-glob-patterns
|
||||
- page: Backup reference
|
||||
|
||||
Reference in New Issue
Block a user