Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Restore Azure Kubernetes Service (AKS) using Azure Backup. description: This article explains how to restore backed-up Azure Kubernetes Service (AKS) using Azure Backup. ms.topic: how-to ms.service: azure-backup ms.custom: - ignite-2024 ms.date: 08/18/2026 author: AbhishekMallick-MS ms.author: v-mallicka # Customer intent: "As a cloud operations engineer, I want to restore a backed-up Azure Kubernetes Service cluster using Azure Backup, so that I can recover cluster resources and ensure continuity of services during disruptions." --- # Restore Azure Kubernetes Service using Azure Backup This article describes how to restore backed-up Azure Kubernetes Service (AKS). You can also restore AKS cluster using [Azure PowerShell](azure-kubernetes-service-cluster-restore-using-powershell.md). Azure Backup now allows you to back up AKS clusters (cluster resources and persistent volumes attached to the cluster) using a backup extension, which must be installed in the cluster. Backup vault communicates with the cluster via this Backup Extension to perform backup and restore operations. ## Before you start - AKS backup allows you to restore to original AKS cluster (that was backed up) and to an alternate AKS cluster. AKS backup allows you to perform a full restore and item-level restore. You can utilize [restore configurations](#configure-item-level-restore-for-aks-cluster) to define parameters based on the cluster resources that are to be restored. - You must [install the Backup Extension](azure-kubernetes-service-cluster-manage-backups.md#install-backup-extension) in the target AKS cluster. Also, you must [enable Trusted Access](azure-kubernetes-service-cluster-manage-backups.md#trusted-access-related-operations) between the Backup vault and the AKS cluster. - For Azure Files-based volumes, ensure that the persistent volumes have the Reclaim Policy set to **Retain** before performing a restore. This ensures that snapshots remain secure even if the PVC is deleted. If you need to restore and the PVC still exists in the target cluster, delete it before starting the restore operation. - For Azure Files-based volumes, the target AKS cluster must have the **Storage File Data Privileged Contributor** role assigned on the storage account hosting the file shares. For dynamically provisioned volumes, the Backup vault handles this assignment automatically. For statically provisioned volumes, you must assign this role manually. - Azure Files-based volumes can only be restored to clusters within the same subscription and region. Cross-region and cross-subscription restore is not supported for Azure Files volumes. - To restore a backup stored in Vault Tier, provide a storage account as a staging location. Backup data is stored in the Backup vault as a blob within the Microsoft tenant. During a restore operation, the backup data is copied from one vault to a staging storage account across tenants. Vault Tier supports only Azure Disk-based volumes; Azure Files volumes use Operational Tier only. - Azure Backup doesn't automatically scale out AKS nodes—it only restores data and associated resources. AKS manages autoscaling by using features like the Cluster Autoscaler. If autoscaling is enabled on the target cluster, it should handle resource scaling automatically. Before restoring, ensure that the target cluster has sufficient resources to avoid restore failures or performance issues For more information on the limitations and supported scenarios, see the [support matrix](azure-kubernetes-service-cluster-backup-support-matrix.md). ## Restore the AKS clusters To restore the backed-up AKS cluster, follow these steps: 1. Go to **Resiliency** and select **Recover**. 2. On the **Recover** pane, select **Azure Kubernetes Services** as the **Datasource type**, and then click **Select** under **Protected item**. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/select-protected-item.png" alt-text="Screenshot that shows the selection of a protected AKS cluster for restore." lightbox="./media/azure-kubernetes-service-cluster-restore/select-protected-item.png"::: 1. On the **Select Protected item** pane, select a backed-up AKS cluster from the list, and then click **Select**. 1. On the **Recover** pane, select **Continue**. 1. On the **Restore** pane, on the **Basics** tab, select **Next: Restore point**. If the instance is available in both *Primary* and *Secondary Region*, select the *region to restore* too, and then select **Continue**. 1. On the **Restore point** tab, for **Restore Point**, click **Select restore point** to select the *restore point* you want to restore. If the restore point is available in both Vault and Operation datastore, select the one you want to restore from. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/select-restore-points-for-kubernetes.png" alt-text="Screenshot that shows the process to view the restore points."::: 1. On the **Select restore point** pane, select a restore point from the list, and then click **Select**. 1. On the **Restore** pane, select **Next: Restore parameters** to configure the restore parameters. 4. On the **Restore parameters** tab, click **Select Kubernetes Service**. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/parameter-selection.png" alt-text="Screenshot shows how to initiate parameter selection." lightbox="./media/azure-kubernetes-service-cluster-restore/parameter-selection.png"::: 1. On the **Select Kubernetes service** pane, select the target *AKS cluster* from the list, and then click **Select**. 1. On the **Restore** pane, to select the *backed-up cluster resources* for restore, click **Select resources**. Learn more about [restore configurations](#configure-item-level-restore-for-aks-cluster). If you select a recovery point for restore from *Vault-standard datastore*, then provide a *snapshot resource group* and *storage account* as the staging location. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/restore-parameters.png" alt-text="Screenshot shows the parameters to add for restore from Vault-standard storage."::: :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/restore-parameter-storage.png" alt-text="Screenshot shows the storage parameter to add for restore from Vault-standard storage."::: > [!NOTE] >During the restore operation, the Backup vault and the AKS cluster need to have certain roles assigned to perform the restore: > > - *Target AKS* cluster should have *Contributor* role on the *Snapshot Resource Group*. > - The *User Identity* attached with the Backup Extension should have *Storage Blob Data Contributor* roles on the *storage account* where backups are stored in case of Operational Tier and on the *staging storage account* in case of Vault Tier. > - The *Backup vault* should have a *Reader* role on the *Target AKS cluster* and *Snapshot Resource Group* in case of restoring from Operational Tier. > - The *Backup vault* should have a *Contributor* role on the *Staging Resource Group* in case of restoring backup from Vault Tier. > - The *Backup vault* should have a *Storage Account Contributor* and *Storage Blob Data Owner* role on the *Staging Storage Account* in case of restoring backup from Vault Tier. 1. Select **Validate** to run validation on the cluster selections for restore. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/validate-restore-parameters.png" alt-text="Screenshot shows the validation of restore parameters."::: > [!NOTE] > - For Azure Files-based volumes, validation checks that the target AKS cluster has the **Storage File Data Privileged Contributor** role on the storage account. If this role is missing, you may need to assign it manually, especially for statically provisioned volumes. > - If you're restoring Azure Files volumes and Kubernetes secrets are used to store storage account keys, ensure that secrets were included in the backup configuration. 1. After the validation is successful, select **Next: Review + restore**. 1. On the **Review + restore** pane, review the selections, and then select **Restore** to restore the backups to the selected cluster. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/review-restore-tab.png" alt-text="Screenshot shows the Review + restore tab for restore." lightbox="./media/azure-kubernetes-service-cluster-restore/review-restore-tab.png"::: >[!NOTE] >The restore job doesn't automatically clean up the resources hydrated in the staging resource group and storage account. Delete these resources manually. ### Configure item-level restore for AKS cluster As part of item-level restore capability of AKS backup, you can utilize multiple restore configuration filters to perform restore. - Select the *Namespaces* that you want to restore from the list. The list shows only the backed-up Namespaces. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/select-namespace.png" alt-text="Screenshot shows selection of Namespace." lightbox="./media/azure-kubernetes-service-cluster-restore/select-namespace.png"::: You can also select the checkboxes if you want to restore cluster scoped resources and persistent volumes. To restore specific cluster resources, use the labels attached to them in the textbox. Only resources with the entered labels are backed up. - You can provide *API Groups* and *Kinds* to restore specific resource types. The list of *API Group* and *Kind* is available in the *Appendix*. You can enter *multiple API Groups*. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/use-api-for-restore.png" alt-text="Screenshot shows the usage of API for restore." lightbox="./media/azure-kubernetes-service-cluster-restore/use-api-for-restore.png"::: - To restore a workload, such as Deployment from a backup via API Group, the entry should be: - **Kind**: Select **Deployment**. - **Group**: Select **Group**. - **Namespace Mapping**: To migrate the backed-up cluster resources to a different *Namespace*, select the *backed-up Namespace*, and then enter the *Namespace* to which you want to migrate the resources. If the *Namespace* doesn't exist in the AKS cluster, it gets created. If a conflict occurs during the cluster resources restore, you can skip or patch the conflicting resources. :::image type="content" source="./media/azure-kubernetes-service-cluster-restore/select-backed-up-namespace-for-migrate.png" alt-text="Screenshot shows the selection of namespace for migration." lightbox="./media/azure-kubernetes-service-cluster-restore/select-backed-up-namespace-for-migrate.png"::: - **Resource Modifier** (Optional): To modify resource properties during restore (such as changing the storage class for persistent volume claims), you can deploy a Resource Modifier ConfigMap in the target cluster. This is useful when restoring to an alternate cluster with different storage classes. For example, to change the storage class: 1. Create a YAML file with resource modification rules: ```yaml version: v1 resourceModifierRules: - conditions: groupResource: persistentvolumeclaims patches: - operation: replace path: "/spec/storageClassName" value: "azurefile-csi-premium" ``` 2. Deploy the ConfigMap: `kubectl create cm <configmap-name> --from-file=<yaml-file> -n <namespace>` 3. Reference this ConfigMap in the restore configuration under **Resource Modifier**. Azure Backup for AKS currently supports the following two options when doing a restore operation when resource clash happens (backed-up resource has the same name as the resource in the target AKS cluster). You can choose one of these options when defining the restore configuration. - **Skip**: This option is selected by default. For example, if you backed up a PVC named *pvc-azuredisk* and you're restoring it in a target cluster that has the PVC with the same name, then the backup extension skips restoring the backed-up persistent volume claim (PVC). In such scenarios, we recommend you to delete the resource from the cluster, and then do the restore operation. - **Patch**: This option allows the patching mutable variable in the backed-up resource on the resource in the target cluster. If you want to update the number of replicas in the target cluster, you can opt for patching as an operation. >[!Note] >AKS backup currently doesn't delete and recreate resources in the target cluster if they already exist. If you attempt to restore Persistent Volumes in the original location, delete the existing Persistent Volumes, and then do the restore operation. ## Verify restore completion After the restore operation completes, verify that resources have been successfully restored: 1. Check that the resources are available in the target cluster: ```bash kubectl get pods -n <namespace> kubectl get pvc -n <namespace> kubectl get pv ``` 2. For Azure Files-based volumes, verify that the application can access the restored data: ```bash kubectl exec -it <pod-name> -n <namespace> -- ls /mnt/azure ``` Replace `/mnt/azure` with your actual mount path. 3. Verify that Azure Files snapshots are still available in the storage account for future restores. 4. If you're restoring statically provisioned Azure Files volumes, ensure that: - The Kubernetes secrets used to access the file shares were restored. - The **Storage File Data Privileged Contributor** role is assigned to the target AKS cluster on the storage account. - The file share exists in the storage account. ## Restore the AKS clusters in secondary region To restore the AKS cluster in the secondary region, [configure Geo redundancy and Cross Region Restore in the Backup vault](azure-kubernetes-service-cluster-backup.md#create-a-backup-vault), and then [trigger restore](tutorial-restore-aks-backups-across-regions.md#restore-in-secondary-region). ## Next steps - [Manage Azure Kubernetes Service cluster backup](azure-kubernetes-service-cluster-manage-backups.md) - [Overview of Azure Kubernetes Service cluster backup](azure-kubernetes-service-cluster-backup-concept.md)