Skip to content

[dataprotection] improve docs, help, example to reflect new retention rule changes #29648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IannGeorges wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[dataprotection] improve docs, help, example to reflect new retention rule changes #29648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eaf1ae0
improve docs, help, example to reflect new changes
May 20, 2026
c09c7ba
address copilot comments
May 20, 2026
09c9248
fix linting documentation issues
May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions ...n.Autorest/custom/Cmdlets/Policy/Edit-AzDataProtectionPolicyRetentionRuleClientObject.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ function Edit-AzDataProtectionPolicyRetentionRuleClientObject {
[Microsoft.Azure.PowerShell.Cmdlets.DataProtection.Models.IBackupPolicy]
${Policy},

[Parameter(ParameterSetName='AddRetention',Mandatory, HelpMessage='Retention Rule Name. Note: Default_OperationalStore is applicable to AzureBlob only and is reserved for OperationalStore lifecycles; on AzureBlob, -Name Default is reserved for VaultStore lifecycles.')]
[Parameter(ParameterSetName='RemoveRetention',Mandatory, HelpMessage='Retention Rule Name. Note: Default and Default_OperationalStore are default retention rules and cannot be removed.')]
[Parameter(ParameterSetName='AddRetention',Mandatory, HelpMessage='Retention Rule Name.')]
[Parameter(ParameterSetName='RemoveRetention',Mandatory, HelpMessage='Retention Rule Name. Note: "Default" retention rules cannot be removed, regardless of lifecycle.')]
Comment on lines +20 to +21
[Microsoft.Azure.PowerShell.Cmdlets.DataProtection.Support.RetentionRuleName]
${Name},

Expand All @@ -30,7 +30,7 @@ function Edit-AzDataProtectionPolicyRetentionRuleClientObject {
[System.Management.Automation.SwitchParameter]
${RemoveRule},

[Parameter(ParameterSetName='AddRetention',Mandatory=$false, HelpMessage='Specifies whether to modify an existing LifeCycle.')]
[Parameter(ParameterSetName='AddRetention',Mandatory=$false, HelpMessage='[Deprecated] Optional; this parameter will be removed in an upcoming release. Setting -OverwriteLifeCycle $false blocks updating an existing retention rule; when $true or omitted, the existing rule lifecycles are replaced in place — the default behavior once this parameter is removed.')]
[Nullable[System.Boolean]]
${OverwriteLifeCycle},

Expand Down
30 changes: 26 additions & 4 deletions ...rotection.Autorest/docs/Edit-AzDataProtectionPolicyRetentionRuleClientObject.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ schema: 2.0.0
# Edit-AzDataProtectionPolicyRetentionRuleClientObject

## SYNOPSIS
Adds or removes Retention Rule to existing Policy
Adds or removes Retention Rule to an existing backup policy.

## SYNTAX

Expand All @@ -25,7 +25,7 @@ Edit-AzDataProtectionPolicyRetentionRuleClientObject -IsDefault <Boolean> -LifeC
```

## DESCRIPTION
Adds or removes Retention Rule to existing Policy
Adds or removes Retention Rule to an existing backup policy.

## EXAMPLES

Expand Down Expand Up @@ -59,6 +59,23 @@ DatasourceType ObjectType

This command removes weekly retention rule if it exists in given backup policy.

### Example 3: Add an OperationalStore retention rule to an AzureBlob policy
```powershell
$pol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
$opLifecycle = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $pol -Name Default_OperationalStore -LifeCycles $opLifecycle -IsDefault $true
```

```output
DatasourceType ObjectType
-------------- ----------
{Microsoft.Storage/storageAccounts/blobServices} BackupPolicy
```

For AzureBlob, OperationalStore retention rules **must** be named `Default_OperationalStore`. The rule is added additively — the existing `Default` (VaultStore) retention rule on the policy template is preserved. Passing `-Name Default` with an OperationalStore lifecycle is rejected by validation.

Note: `-OverwriteLifeCycle` is deprecated and will be removed in an upcoming release. Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.

## PARAMETERS

### -IsDefault
Expand Down Expand Up @@ -92,12 +109,14 @@ Accept wildcard characters: False
```

### -Name
Retention Rule Name
Retention Rule Name.
Note: `"Default"` retention rules cannot be removed, regardless of lifecycle.
Comment on lines +112 to +113

```yaml
Type: Microsoft.Azure.PowerShell.Cmdlets.DataProtection.Support.RetentionRuleName
Parameter Sets: (All)
Aliases:
Accepted values: Default, Daily, Weekly, Monthly, Yearly, Default_OperationalStore
Comment thread
IannGeorges marked this conversation as resolved.

Required: True
Position: Named
Expand All @@ -107,7 +126,7 @@ Accept wildcard characters: False
```

### -OverwriteLifeCycle
Specifies whether to modify an existing LifeCycle.
[Deprecated] Optional; this parameter will be removed in an upcoming release. Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.

```yaml
Type: System.Nullable`1[[System.Boolean, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]
Expand Down Expand Up @@ -162,5 +181,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

## NOTES

* **`"Default"` retention rules cannot be removed**, regardless of lifecycle. `-RemoveRule -Name Default` throws `Removing Default Retention Rule is not allowed. Please try again with different rule name.`
* **`-OverwriteLifeCycle` is deprecated and will be removed in an upcoming release.** Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.

## RELATED LINKS

29 changes: 4 additions & 25 deletions ...DataProtection/DataProtection.Autorest/docs/New-AzDataProtectionBackupPolicy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,28 +112,6 @@ The seventh, eight commands update the policy object with lifecycles created.
Next we create FirstOfDay, FirstOfWeek tag criteria and update the policy.
The last command creates the policy.

### Example 4: Create a operational policy for AzureBlob
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
Edit-AzDataProtectionPolicyTriggerClientObject -Policy $defaultPol -RemoveSchedule
$lifeCycleOperationalTier = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default -LifeCycles $lifeCycleOperationalTier -IsDefault $true -OverwriteLifeCycle $true
$opPolicy = New-AzDataProtectionBackupPolicy -SubscriptionId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -ResourceGroupName "resourceGroupName" -VaultName "vaultName" -Name "operationalPolicyName" -Policy $defaultPol
```

```output
Name Type
---- ----
operationalPolicyName Microsoft.DataProtection/backupVaults/backupPolicies
```

The first command gets the default policy template for AzureBlob.
Policy template is by default vaulted policy.
The second command removes the vaulted policy schedule since we are creating operational policy.
The third command creates a operational store lifecycle for 30 Days.
The fourth command overwrites the vault lifecycle with operational store lifecycle.
The last command creates the operational store policy.

### Example 4: Create a vaulted policy for AzureBlob
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
Expand All @@ -160,7 +138,7 @@ The last command creates the vault store policy.
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
$lifeCycleOperationalTier = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default -LifeCycles $lifeCycleOperationalTier -IsDefault $true -OverwriteLifeCycle $false
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default_OperationalStore -LifeCycles $lifeCycleOperationalTier -IsDefault $true
$lifeCycleVaultTierWeekly = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore VaultStore -SourceRetentionDurationType Weeks -SourceRetentionDurationCount 7
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Weekly -LifeCycles $lifeCycleVaultTierWeekly -IsDefault $false
$tagCriteria = New-AzDataProtectionPolicyTagCriteriaClientObject -AbsoluteCriteria FirstOfWeek
Expand Down Expand Up @@ -188,8 +166,9 @@ Name Type
operationalVaultedPolicyName Microsoft.DataProtection/backupVaults/backupPolicies
```

The first command gets the default vaulted policy template for AzureBlob.
The second to fifteenth command defines and updates the Operational, vaulted weekly, monthly, yearly lifecycle and tagcriteria.
The first command gets the default vaulted policy template for AzureBlob. The template ships with a `Default` (VaultStore) retention rule.
The second and third commands add an OperationalStore retention rule named `Default_OperationalStore` to the policy. This is **additive** — the existing `Default` (VaultStore) rule is preserved.
The fourth through fifteenth commands define and update the vaulted weekly, monthly, yearly lifecycles and tag criteria.
Next we define a trigger object with schedule time and timezone, set it to 2:30 AM West Europe standard time.
The last command creates the hybrid AzureBlob policy.

Expand Down
4 changes: 2 additions & 2 deletions ...ction.Autorest/examples/Edit-AzDataProtectionPolicyRetentionRuleClientObject.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ DatasourceType ObjectType
{Microsoft.Storage/storageAccounts/blobServices} BackupPolicy
```

For AzureBlob, OperationalStore retention rules **must** be named `Default_OperationalStore`. The rule is added additively — the existing `Default` (Vault) retention rule on the policy template is preserved.
For AzureBlob, OperationalStore retention rules **must** be named `Default_OperationalStore`. The rule is added additively — the existing `Default` (VaultStore) retention rule on the policy template is preserved. Passing `-Name Default` with an OperationalStore lifecycle is rejected by validation.

Note: passing `-Name Default` with an OperationalStore lifecycle now errors out (it was previously the buggy `-OverwriteLifeCycle $true`/`$false` patterns that produced a duplicate-`Default` rule).
Note: `-OverwriteLifeCycle` is deprecated and will be removed in an upcoming release. Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.

30 changes: 26 additions & 4 deletions ...ion/DataProtection/help/Edit-AzDataProtectionPolicyRetentionRuleClientObject.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ schema: 2.0.0
# Edit-AzDataProtectionPolicyRetentionRuleClientObject

## SYNOPSIS
Adds or removes Retention Rule to existing Policy
Adds or removes Retention Rule to an existing backup policy.

## SYNTAX

Expand All @@ -26,7 +26,7 @@ Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy <IBackupPolicy> -Na
```

## DESCRIPTION
Adds or removes Retention Rule to existing Policy
Adds or removes Retention Rule to an existing backup policy.

## EXAMPLES

Expand Down Expand Up @@ -60,6 +60,23 @@ DatasourceType ObjectType

This command removes weekly retention rule if it exists in given backup policy.

### Example 3: Add an OperationalStore retention rule to an AzureBlob policy
```powershell
$pol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
$opLifecycle = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $pol -Name Default_OperationalStore -LifeCycles $opLifecycle -IsDefault $true
```

```output
DatasourceType ObjectType
-------------- ----------
{Microsoft.Storage/storageAccounts/blobServices} BackupPolicy
```

For AzureBlob, OperationalStore retention rules **must** be named `Default_OperationalStore`. The rule is added additively — the existing `Default` (VaultStore) retention rule on the policy template is preserved. Passing `-Name Default` with an OperationalStore lifecycle is rejected by validation.

Note: `-OverwriteLifeCycle` is deprecated and will be removed in an upcoming release. Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.
Comment thread
IannGeorges marked this conversation as resolved.

## PARAMETERS

### -IsDefault
Expand Down Expand Up @@ -93,7 +110,8 @@ Accept wildcard characters: False
```

### -Name
Retention Rule Name
Retention Rule Name.
Note: `"Default"` retention rules cannot be removed, regardless of lifecycle.

```yaml
Type: Microsoft.Azure.PowerShell.Cmdlets.DataProtection.Support.RetentionRuleName
Expand All @@ -109,7 +127,7 @@ Accept wildcard characters: False
```

### -OverwriteLifeCycle
Specifies whether to modify an existing LifeCycle.
[Deprecated] Optional; this parameter will be removed in an upcoming release. Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.
Comment thread
IannGeorges marked this conversation as resolved.

```yaml
Type: System.Nullable`1[System.Boolean]
Expand Down Expand Up @@ -164,4 +182,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

## NOTES

* **`"Default"` retention rules cannot be removed**, regardless of lifecycle. `-RemoveRule -Name Default` throws `Removing Default Retention Rule is not allowed. Please try again with different rule name.`
* **`-OverwriteLifeCycle` is deprecated and will be removed in an upcoming release.** Setting `-OverwriteLifeCycle $false` blocks updating an existing retention rule; when `$true` or omitted, the existing rule's lifecycles are replaced in place — the default behavior once this parameter is removed.
Comment thread
IannGeorges marked this conversation as resolved.


## RELATED LINKS
29 changes: 4 additions & 25 deletions src/DataProtection/DataProtection/help/New-AzDataProtectionBackupPolicy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,28 +112,6 @@ The seventh, eight commands update the policy object with lifecycles created.
Next we create FirstOfDay, FirstOfWeek tag criteria and update the policy.
The last command creates the policy.

### Example 4: Create a operational policy for AzureBlob
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
Edit-AzDataProtectionPolicyTriggerClientObject -Policy $defaultPol -RemoveSchedule
$lifeCycleOperationalTier = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default -LifeCycles $lifeCycleOperationalTier -IsDefault $true -OverwriteLifeCycle $true
$opPolicy = New-AzDataProtectionBackupPolicy -SubscriptionId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -ResourceGroupName "resourceGroupName" -VaultName "vaultName" -Name "operationalPolicyName" -Policy $defaultPol
```

```output
Name Type
---- ----
operationalPolicyName Microsoft.DataProtection/backupVaults/backupPolicies
```

The first command gets the default policy template for AzureBlob.
Policy template is by default vaulted policy.
The second command removes the vaulted policy schedule since we are creating operational policy.
The third command creates a operational store lifecycle for 30 Days.
The fourth command overwrites the vault lifecycle with operational store lifecycle.
The last command creates the operational store policy.

### Example 4: Create a vaulted policy for AzureBlob
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
Expand All @@ -160,7 +138,7 @@ The last command creates the vault store policy.
```powershell
$defaultPol = Get-AzDataProtectionPolicyTemplate -DatasourceType AzureBlob
$lifeCycleOperationalTier = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore OperationalStore -SourceRetentionDurationType Days -SourceRetentionDurationCount 30
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default -LifeCycles $lifeCycleOperationalTier -IsDefault $true -OverwriteLifeCycle $false
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Default_OperationalStore -LifeCycles $lifeCycleOperationalTier -IsDefault $true
$lifeCycleVaultTierWeekly = New-AzDataProtectionRetentionLifeCycleClientObject -SourceDataStore VaultStore -SourceRetentionDurationType Weeks -SourceRetentionDurationCount 7
Edit-AzDataProtectionPolicyRetentionRuleClientObject -Policy $defaultPol -Name Weekly -LifeCycles $lifeCycleVaultTierWeekly -IsDefault $false
$tagCriteria = New-AzDataProtectionPolicyTagCriteriaClientObject -AbsoluteCriteria FirstOfWeek
Expand Down Expand Up @@ -188,8 +166,9 @@ Name Type
operationalVaultedPolicyName Microsoft.DataProtection/backupVaults/backupPolicies
```

The first command gets the default vaulted policy template for AzureBlob.
The second to fifteenth command defines and updates the Operational, vaulted weekly, monthly, yearly lifecycle and tagcriteria.
The first command gets the default vaulted policy template for AzureBlob. The template ships with a `Default` (VaultStore) retention rule.
The second and third commands add an OperationalStore retention rule named `Default_OperationalStore` to the policy. This is **additive** — the existing `Default` (VaultStore) rule is preserved.
The fourth through fifteenth commands define and update the vaulted weekly, monthly, yearly lifecycles and tag criteria.
Next we define a trigger object with schedule time and timezone, set it to 2:30 AM West Europe standard time.
The last command creates the hybrid AzureBlob policy.

Expand Down
Loading