Merge pull request #242989 from Muksvso/master

Snapshots Docs

Author: v-dirichards

articles/azure-app-configuration/TOC.yml

@@ -138,6 +138,8 @@
   items:
     - name: Keys and values
       href: concept-key-value.md
+    - name: Snapshots
+      href: concept-snapshots.md
     - name: Point-in-time key-values
       href: concept-point-time-snapshot.md
     - name: Feature management
@@ -176,6 +178,8 @@
   items:
     - name: Use labels for per-environment configuration
       href: howto-labels-aspnet-core.md
+    - name: Create and manage Snapshots
+      href: howto-create-snapshots.md
     - name: Import or export configuration data
       href: howto-import-export-data.md
     - name: Use JSON content-type for key-values

articles/azure-app-configuration/concept-snapshots.md

@@ -0,0 +1,89 @@
+---
+title: Snapshots in Azure App Configuration (preview)
+description: Details of Snapshots in Azure App Configuration
+author: Muksvso
+ms.author: mubatra
+ms.service: azure-app-configuration
+ms.topic: conceptual 
+ms.date: 05/16/2023
+---
+
+# Snapshots (preview)
+
+A snapshot is a named, immutable subset of an App Configuration store's key-values. The key-values that make up a snapshot are chosen during creation time through the usage of key and label filters. Once a snapshot is created, the key-values within are guaranteed to remain unchanged.
+
+## Deploy safely with snapshots
+
+Snapshots are designed to safely deploy configuration changes. Deploying faulty configuration changes into a running environment can cause issues such as service disruption and data loss. In order to avoid such issues, it's important to be able to vet configuration changes before moving into production environments. If such an issue does occur, it's important to be able to roll back any faulty configuration changes in order to restore service. Snapshots are created for managing these scenarios.
+
+Configuration changes should be deployed in a controlled, consistent way. Developers can use snapshots to perform controlled rollout. The only change needed in an application to begin a controlled rollout is to update the name of the snapshot the application is referencing. As the application moves into production, there's a guarantee that the configuration in the referenced snapshot remains unchanged. This guarantee against any change in a snapshot protects against unexpected settings making their way into production. The immutability and ease-of-reference of snapshots make it simple to ensure that the right set of configuration changes are rolled out safely.
+
+## Scenarios for using snapshots
+
+* **Controlled rollout**: Snapshots are well suited for supporting controlled rollout due to their immutable nature. When developers utilize snapshots for configuration, they can be confident that the configuration remains unchanged as the release progresses through different phases of the rollout.
+
+* **Last Known Good (LKG) configuration**: Snapshots can be used to support safe deployment practices for Configuration. With snapshots, developers can ensure that a Last known Good (LKG) configuration is available for rollback if there was any issue during deployment.
+
+* **Configuration versioning**: Snapshots can be used to create a version history of configuration settings to sync with release versions. Settings captured in each snapshot can be compared to identify changes between versions.
+
+* **Auditing**: Snapshots can be used for auditing and compliance purposes. Developers can maintain a record of configuration changes in between releases by using the snapshots for the releases.
+
+* **Testing and Staging environments**: Snapshots can be used to create consistent testing and staging environments. Developers can ensure that the same configuration is used across different environments, by using the same snapshot, which can help with debugging and testing.
+
+* **Simplified Client Configuration composition**: Usually, the clients of App Configuration need a subset of the key-values from the App Configuration instance. To get the set of required key-values, they need to have query logic written in code. As Snapshots support providing filters during creation time, it helps simplify client composition because clients can now refer to the set of key-values they require by name.
+
+## Snapshot operations
+
+As snapshots are immutable entities, snapshots can only be created and archived. No deleting, purging or editing is possible.  
+
+* **Create snapshot**: Snapshots can be created by defining the key and label filters to capture the required key-values from App Configuration instance. The filtered key-values are stored as a snapshot with the name provided during creation.  
+
+* **Archive snapshot**: Archiving a snapshot puts it in an archived state. While a snapshot is archived, it's still fully functional. When the snapshot is archived, an expiration time is set based on the retention period configured during the snapshot's creation. If the snapshot remains in the archived state up until the expiration time, then it automatically disappears from the system when the expiration time passes. Archival is used for phasing out snapshots that are no longer in use.
+
+* **Recover snapshot**: Recovering a snapshot puts it back in an active state. At this point, the snapshot is no longer subject to expiration based on its configured retention period. Recovery is only possible in the retention period after archival.
+
+> [!NOTE]
+> The retention period can only be set during the creation of a snapshot. The default value for retention period is 30 days for Standard stores and 7 days for Free stores.
+
+## Requirements for snapshot operations
+
+The following sections detail the permissions required to perform snapshot related operations with Azure AD and HMAC authentication.
+
+### Create a snapshot
+
+To create a snapshot in stores using Azure Active Directory (Azure AD) authentication, the following permissions are required. The App Configuration Data Owner role already has these permissions.
+- `Microsoft.AppConfiguration/configurationStores/keyvalues/read`
+- `Microsoft.AppConfiguration/configurationStores/snapshots/write`
+
+To archive and/or recover a snapshot using HMAC authentication, a read-write access key must be used.
+
+### Archive and recover a snapshot
+
+To archive and/or recover a snapshot using Azure AD authentication, the following permission is needed. The App Configuration Data Owner role already has this permission.
+- `Microsoft.AppConfiguration/configurationStores/snapshots/archive/action`
+
+To archive and/or recover a snapshot using HMAC authentication, a read-write access key must be used.
+
+### Read and list snapshots
+
+To  list all snapshots, or get all the key-values in an individual snapshot by name the following permission is needed for stores utilizing Azure AD authentication. The built-in Data Owner and Data Reader roles already have this permission.
+- `Microsoft.AppConfiguration/configurationStores/snapshots/read`
+
+For stores that use HMAC authentication, both the "read snapshot" operation (to read the key-values from a snapshot) and the "list snapshots" operation can be performed using either the read-write access keys or the read-only access keys.
+
+## Billing considerations and limits
+
+The storage quota for snapshots is detailed in the "storage per resource section" of the [App Configuration pricing page](https://azure.microsoft.com/pricing/details/app-configuration/) There's no extra charge for snapshots before the included snapshot storage quota is exhausted.
+
+App Configuration has two tiers, Free and Standard. Check the following details for snapshot quotas in each tier.
+
+* **Free tier**: This tier has a snapshot storage quota of 10 MB.  One can create as many snapshots as possible as long as the total storage size of all active and archived snapshots is less than 10 MB.
+
+* **Standard tier**: This tier has a snapshot storage quota of 1 GB. One can create as many snapshots as possible as long as the total storage size of all active and archived snapshots is less than 1 GB.
+
+The maximum size for a snapshot is 1 MB.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Create a snapshot](./howto-create-snapshots.md)  

articles/azure-app-configuration/howto-create-snapshots.md

@@ -0,0 +1,128 @@
+---
+title: How to create snapshots (preview) in Azure App Configuration
+description: How to create and manage snapshots Azure App Configuration store.
+author: Muksvso
+ms.author: mubatra
+ms.service: azure-app-configuration
+ms.topic: how-to 
+ms.date: 05/16/2023
+---
+
+# Use snapshots (preview)
+
+In this article, learn how to create and manage snapshots in Azure App Configuration. Snapshot is a set of App Configuration settings stored in an immutable state.
+
+## Prerequisites
+
+- An App Configuration store. [Create a store](./quickstart-azure-app-configuration-create.md#create-an-app-configuration-store).
+- "DataOwner" role in the App Configuration store. Details on required [role and permissions for snapshots](./concept-snapshots.md)
+
+### Add key-values to the App configuration store
+
+In your App Configuration store, go to **Operations** > **Configuration explorer** and add the following key-values. Leave **Content Type** with its default value. For more information about how to add key-values to a store using the Azure portal or the CLI, go to [Create a key-value](./quickstart-azure-app-configuration-create.md#create-a-key-value).
+
+| Key            | Value          | Label    |
+|----------------|----------------|----------|
+| *app2/bgcolor* | *Light Gray*   | *label2* |
+| *app1/color*   | *Black*        | No label |
+| *app1/color*   | *Blue*         | *label1* |
+| *app1/color*   | *Green*        | *label2* |
+| *app1/color*   | *Yellow*       | *label3* |
+| *app1/message* | *Hello*        | *label1* |
+| *app1/message* | *Hi!*          | *label2* |
+| *app2/message* | *Good morning!*| *label1* |
+
+## Create a snapshot
+
+ > [!IMPORTANT]
+   > You may see any error "You are not authorized to view this configuration store data" when you switch to the Snapshots blade in the Azure portal if you opt to use Azure AD authentication in the Configuration explorer or the Feature manager blades. This is a known issue in the Azure portal, and we are working on addressing it. It doesn't affect any scenarios other than the Azure Portal regarding accessing snapshots with Azure AD authentication.
+
+As a temporary workaround, you can switch to using Access keys authentication from either the Configuration explorer or the Feature manager blades. You should then see the Snapshot blade displayed properly, assuming you have permission for the access keys.
+
+Under **Operations** > **Snapshots (preview)**, select **Create a new snapshot**.
+
+1. Enter a **snapshot name** and optionally also add **Tags**.
+1. Under  **Choose the composition type**, keep the default value **Key (default)**.
+   - With the *Key* composition type, if your store has identical keys with different labels, only the  key-value specified in the last applicable filter is included in the snapshot. Identical key-values with other labels are left out of the snapshot.
+   - With the *Key-Label* composition type, if your store has identical keys with different labels, all  key-values with identical keys but different labels are included in the snapshot depending on the specified filters.
+1. Select **Add filters** to select the key-values for your snapshot. Filtering is done by selecting filters: **Equals**, **Starts with**, **Any of** and **All** for keys and for labels. You can enter between one and three filters.
+   1. Add the first filter:
+      - Under **Key**, select **Starts with** and enter *app1*
+      - Under **Label**, select **Equals** and select *label2* from the drop-down menu.
+   1. Add the second filter:
+      - Under **Key**, select **Starts with** and enter *app1*
+      - Under **Label**, select **Equals** and select *label1*  from the drop-down menu.
+
+1. If you archive a snapshot, by default, it will be retained for 30 days after archival. Optionally, under **Recovery options**, decrease the number of retention days the snapshot will be available after archival.
+
+   > [!NOTE]
+   > The duration of the retention period can't be updated once the snapshot has been created.
+
+1. Select **Create** to generate the snapshot. In this example, the created snapshot has **Key** composition type and below filters:
+   - Keys that start with *app1*, with *label2* label
+   - Keys that start with *app1*, with *label1* label.
+  
+    :::image type="content" source="./media/howto-create-snapshots/create-snapshot.png" alt-text="Screenshot of the Create form with data filled as above steps and Create button highlighted.":::
+  
+1. Check the table to understand which key-values from the configuration store end up in the snapshot based on the provided parameters.  
+
+    | Key            | Value          | Label    | Included in snapshot                                                                                              |
+    |----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------|
+    | *app2/bgcolor* | *Light Gray*   | *label2* | No: doesn't start with *app1*.
+    | *app1/color*   | *Black*        | No label | No: doesn't have the label *label2* or *label1*.
+    | *app1/color*   | *Blue*         | *label1* | Yes: Has the right label *label1* from the last of applicable filters.
+    | *app1/color*   | *Green*        | *label2* | No: Same key with label *label1* selected by the second filter overrides this one though it has the selected label, *label2*.
+    | *app1/color*   | *Yellow*       | *label3* | No: doesn't have the label *label2* or *label1*.
+    | *app1/message* | *Hello*        | *label1* | Yes: Has the right label *label1* from the last of applicable filters.
+    | *app1/message* | *Hi!*          | *label2* | No:  Same key with label *label1* selected by the second filter overrides this one though it has the selected label, *label2*.
+    | *app2/message* | *Good morning!*| *label1* | No: doesn't start with *app1*.
+
+## Create sample snapshots
+
+To create sample snapshots and check how the snapshots feature work, use the snapshot sandbox. This sandbox contains sample data you can play with to better understand how snapshot's composition type and filters work.
+
+1. In **Operations** > **Snapshots (preview)** > **Active snapshots**, select **Test in sandbox**.
+1. Review the sample data and practice creating snapshots by filling out the form with a composition type and one or more filters.
+1. Select **Create** to generate the sample snapshot.
+1. Check out the snapshot result generated under **Generated sample snapshot**. The sample snapshot displays all keys that are included in the sample snapshot, according to your selection.
+
+## Manage active snapshots
+
+The page under **Operations** > **Snapshots (preview)** displays two tabs: **Active snapshots** and **Archived snapshots**. Select **Active snapshots** to view the list of all active snapshots in an App Configuration store.
+
+   :::image type="content" source="./media/howto-create-snapshots/snapshots-view-list.png" alt-text="Screenshot of the list of active snapshots.":::
+
+### View existing snapshot
+
+In the **Active snapshots** tab, select the ellipsis **...** on the right of an existing snapshot and select **View** to view a snapshot. This action opens a Snapshot details page that displays the snapshot's settings and the key-values included in the snapshot.
+
+   :::image type="content" source="./media/howto-create-snapshots/snapshot-details-view.png" alt-text="Screenshot of the detailed view of an active snapshot.":::
+
+### Archive a snapshot
+
+In the **Active snapshots** tab, select the ellipsis **...** on the right of an existing snapshot and select **Archive** to archive a snapshot. Confirm archival by selecting **Yes** or cancel with **No**. Once a snapshot has been archived, a notification appears to confirm the operation and the list of active snapshots is updated.
+
+   :::image type="content" source="./media/howto-create-snapshots/archive-snapshot.png" alt-text="Screenshot of the archive option in the active snapshots.":::
+
+## Manage archived snapshots
+
+Go to **Operations** > **Snapshots (preview)** > **Archived snapshots** to view the list of all archived snapshots in an App Configuration store. Archived snapshots remain accessible for the retention period that was selected during their creation.
+
+   :::image type="content" source="./media/howto-create-snapshots/archived-snapshots.png" alt-text="Screenshot of the list of archived snapshots.":::
+
+### View archived snapshot
+
+Detailed view of snapshot is available in the archive state as well. In the **Archived snapshots** tab, select the ellipsis **...** on the right of an existing snapshot and select **View** to view a snapshot. This action opens a Snapshot details page that displays the snapshot's settings and the key-values included in the snapshot.
+
+   :::image type="content" source="./media/howto-create-snapshots/archived-snapshots-details.png" alt-text="Screenshot of the detailed view of an archived snapshot.":::
+
+### Recover an archived snapshot
+
+In the **Archived snapshots** tab, select the ellipsis **...** on the right of an archived snapshot and select **Recover** to recover a snapshot. Confirm App Configuration snapshot recovery by selecting **Yes** or cancel with **No**. Once a snapshot has been recovered, a notification appears to confirm the operation and the list of archived snapshots is updated.
+
+   :::image type="content" source="./media/howto-create-snapshots/recover-snapshots.png" alt-text="Screenshot of the recover option in the archived snapshots.":::
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Snapshots in Azure App Configuration](./concept-snapshots.md)

articles/azure-app-configuration/index.yml

@@ -44,7 +44,9 @@ landingContent:
         links:
         - text: Keys and values
           url: concept-key-value.md
-        - text: Point-in-time snapshot
+        - text: Snapshots
+          url: concept-snapshots.md
+        - text: Point-in-time key-values
           url: concept-point-time-snapshot.md
         - text: Feature Management
           url: concept-feature-management.md