platform: backup to another region (BTAR) docs

.github/vale/dicts/aiven.dic

@@ -24,6 +24,7 @@ Azure
 binlog
 boolean
 boot
+BTAR
 Bucardo
 business
 BYOC

.github/vale/styles/Aiven/capitalization_headings.yml

@@ -23,6 +23,7 @@ exceptions:
   - Azure
   - Azure Marketplace
   - Boot
+  - BTAR
   - Business
   - BYOC
   - Cassandra

_toc.yml

@@ -165,6 +165,17 @@ entries:
           title: Rename custom cloud
         - file: docs/platform/howto/byoc/delete-custom-cloud
           title: Delete custom cloud
+    - file: docs/platform/howto/list-backup-to-another-region
+      title: Backup to another region
+      entries:
+        - file: docs/platform/concepts/backup-to-another-region
+          title: About cross-region backup
+        - file: docs/platform/howto/enable-backup-to-another-region
+          title: Add cross-region backup
+        - file: docs/platform/howto/manage-backup-to-another-region
+          title: Manage cross-region backup
+        - file: docs/platform/howto/disable-backup-to-another-region
+          title: Delete cross-region backup
     - file: docs/platform/concepts/enhanced-compliance-env
     - file: docs/platform/concepts/aiven-node-firewall-configuration
     - file: docs/platform/concepts/cloud-security
@@ -1403,4 +1414,3 @@ entries:
   # -------- SUPPORT --------
   - file: docs/platform/howto/project-support-center
     title: Support
-

docs/platform/concepts/backup-to-another-region.rst

@@ -0,0 +1,79 @@
+About backup to another region for Aiven services
+=================================================
+
+.. important::
+
+    Backup to another region (BTAR) is available on ``:doc:Pro Platform </docs/platform/concepts/pro-platform>``.
+
+Discover the backup to another region (BTAR) feature, check why use it, and learn how it works.
+
+About BTAR
+----------
+
+The backup to another region (BTAR) feature allows existing backup files to be copied from the service's primary backup region to an additional (secondary) region. As a disaster recovery feature, BTAR is particularly useful when the service-hosting region is down since it allows forking the service from an additional copy of the backup residing outside the service-hosting region.
+
+BTAR is currently supported for the following services:
+
+* Aiven for PostgreSQL®
+* Aiven for MySQL®
+
+Why use BTAR
+------------
+
+BTAR provides an additional level of data resilience, helping you make your data safe and protected. BTAR is a cost-efficient low-complexity disaster recovery feature that allows you to replicate your data in a secondary backup region and recover it there in case of outage, downtime, data loss, or data corruption in the primary backup region.
+
+How BTAR works
+--------------
+
+By enabling the backup to another region (BTAR) feature, you create a service backup that is additional to the default backup. This secondary backup is always located in a region of your choice different from the primary backup region.
+
+Secondary backups are generated from primary backups, not from the service itself. For this reason, your secondary backup becomes available only after the primary backup is taken. There might be a data replication lag between the primary region and the secondary region.
+
+Restoring from a secondary backup, for example in case of an outage of the primary region, can be done by creating a fork of the service in the region where the secondary backup is located.
+
+.. mermaid::
+
+    flowchart LR
+        subgraph Primary_region
+            direction TB
+            subgraph Service_X
+                end
+            subgraph Primary_backups
+                direction LR
+                PB1
+                PB2
+                PB3
+                PBn
+                end
+            end
+        subgraph Secondary_region
+            direction TB
+            subgraph Forked_service_X
+                end
+            subgraph Secondary_backups
+                direction LR
+                SB1
+                SB2
+                SB3
+                SBn
+                end
+            end
+        Service_X -- Default \n backups --> Primary_backups
+        Primary_backups -- Cross-region backups \n if BTAR  enabled --> Secondary_backups
+        Secondary_backups -- Secondary backups \n to restore service X --> Forked_service_X
+        Service_X -- Forking service X \n if primary region down --> Forked_service_X
+
+Limitations
+-----------
+
+* When selecting a cloud region for your additional backup, you need to use the same cloud provider that your service uses.
+* When you want to :ref:`restore your service from an additional backup <fork-and-restore>` and you use a point in time to specify the scope of data to be restored, you need to set up the time to no later than the time of the latest backup.
+* Secondary backup can only be restored in the region where it was stored.
+* Secondary backup is generated only after a primary backup is complete, and there might be a data replication lag between the primary region and the secondary region.
+
+Related pages
+-------------
+
+* :doc:`Enable BTAR </docs/platform/howto/enable-backup-to-another-region>`
+* :doc:`Manage BTAR </docs/platform/howto/manage-backup-to-another-region>`
+* :doc:`Disable BTAR </docs/platform/howto/disable-backup-to-another-region>`

docs/platform/howto/disable-backup-to-another-region.rst

@@ -0,0 +1,60 @@
+Delete a cross-region backup
+============================
+
+.. important::
+
+    Backup to another region (BTAR) is available on ``:doc:Pro Platform </docs/platform/concepts/pro-platform>``.
+
+Delete :doc:`an additional service backup </docs/platform/concepts/backup-to-another-region>` from a region other than where primary service backups are stored.
+
+Disable BTAR via console
+------------------------
+
+1. Log in to the `Aiven Console <https://console.aiven.io/>`_.
+2. From the **Services** view, select an Aiven service on which you'd like to disable BTAR.
+3. On your service's page, select **Backups** from the sidebar.
+4. On the **Backups** page, select the actions (**...**) menu > **Secondary backup location**.
+5. In the **Edit secondary backup location** window, select **Disable**.
+
+Your additional service backup is no longer visible on your service's **Backups** page in the **Secondary backup location** column.
+
+Disable BTAR via CLI
+--------------------
+
+To remove secondary backups for your service, use the :ref:`avn service update <avn-cli-service-update>` command to remove all target regions names from the ``additional_backup_regions`` array.
+
+.. code-block:: bash
+
+    avn service update your-sevice-name                   \
+        -c additional_backup_regions=[]
+
+Disable BTAR via API
+--------------------
+
+To remove secondary backups for your service, use the `ServiceUpdate <https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate>`_ endpoint to remove all target regions names from the ``additional_backup_regions`` array.
+
+    Existing service > `Update service configuration <https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate>`_
+
+.. code-block:: bash
+
+    curl --request PUT                                                                  \
+    --url https://api.aiven.io/v1/project/YOUR_PROJECT_NAME/service/YOUR_SERVICE_NAME   \
+    --header 'Authorization: Bearer YOUR_BEARER_TOKEN'                                  \
+    --header 'content-type: application/json'                                           \
+    --data
+      '{
+        "user_config": {
+          "additional_backup_regions": []
+          }
+      }'
+
+.. topic:: Result
+
+   Your service has no longer secondary backups in regions different from its hosting region.
+
+Related pages
+-------------
+
+* :doc:`About the backup to another region feature in Aiven </docs/platform/concepts/backup-to-another-region>`
+* :doc:`Enable BTAR for your Aiven service </docs/platform/howto/enable-backup-to-another-region>`
+* :doc:`Manage BTAR for your Aiven service </docs/platform/howto/manage-backup-to-another-region>`

docs/platform/howto/enable-backup-to-another-region.rst

@@ -0,0 +1,162 @@
+Add a backup to another region
+==============================
+
+.. important::
+
+    Backup to another region (BTAR) is available on ``:doc:Pro Platform </docs/platform/concepts/pro-platform>``.
+
+Enable :doc:`the backup to another region (BTAR) feature </docs/platform/concepts/backup-to-another-region>` and create an additional cross-region service backup on top of a regular backup stored in the region where your service is hosted.
+
+About enabling BTAR
+-------------------
+
+Tools
+'''''
+
+To add an additional service backup for your service, you can use the following tools:
+
+* `Aiven console <https://console.aiven.io/>`_
+* CLI
+* API
+
+Limitations
+'''''''''''
+
+* Currently, BTAR is supported for Aiven for MySQL® and Aiven for PostgreSQL® only.
+
+Prerequisites
+-------------
+
+* Aiven organization, project, and service
+* ``:doc:Pro Platform </docs/platform/concepts/pro-platform>`` enabled
+* Depending on the method you choose to use for enabling CCR
+
+  * Access to the `Aiven Console <https://console.aiven.io/>`_
+  * `cURL` CLI tool
+  * `Aiven CLI tool <https://github.com/aiven/aiven-client>`_
+
+Back up to another region via console
+-------------------------------------
+
+1. Log in to the `Aiven Console <https://console.aiven.io/>`_.
+2. From the **Services** view, select an Aiven service on which you'd like to enable BTAR.
+3. On your service's page, select **Backups** from the sidebar.
+4. On the **Backups** page, select the actions (**...**) menu > **Secondary backup location**.
+5. In the **Secondary backup location** window, use the **Secondary location** dropdown menu to select a region for your additional backup. Confirm your choice by selecting **Enable**.
+
+   .. tip::
+
+      For names of the cloud regions supported in Aiven, see column *Cloud* in :doc:`List of available cloud regions </docs/platform/reference/list_of_clouds>`.
+
+Your new additional backup is now visible on your service's **Backups** page in the **Secondary backup location** column.
+
+Back up to another region with CLI
+----------------------------------
+
+.. note::
+
+   In this instruction, the :doc:`Aiven CLI client </docs/tools/cli>` is used to interact with Aiven APIs.
+
+Using CLI, you can enable BTAR for
+
+* :ref:`New Aiven service <new-service-cli>` or
+* :ref:`Existing Aiven service <existing-service-cli>`.
+
+.. topic:: ``additional_backup_regions``
+
+   To enable BTAR on an Aiven service, you need to add the ``additional_backup_regions`` parameter to relevant commands.
+
+.. _new-service-cli:
+
+Create a new service with BTAR via CLI
+''''''''''''''''''''''''''''''''''''''
+
+Use the :ref:`avn service create <avn-cli-service-create>` command to create a new service. Include ``additional_backup_regions`` as a parameter to the command and set its value to the name of desired cloud region.
+
+.. code-block:: bash
+
+    avn service create                                      \
+        --service-type service_type_name                    \
+        --cloud cloud_region_name                           \
+        --plan service_plan_name                            \
+        -c additional_backup_regions=[name_of_cloud_region] \
+        new_service_name
+
+.. _existing-service-cli:
+
+Enable BTAR on an existing service via CLI
+''''''''''''''''''''''''''''''''''''''''''
+
+Use the :ref:`avn service update <avn-cli-service-update>` command to configure your service so that it supports BTAR. Include ``additional_backup_regions`` as a parameter to the command and set its value to the name of desired cloud region.
+
+.. code-block:: bash
+
+    avn service update name_of_existing_service                    \
+        -c additional_backup_regions=[\"name_of_cloud_region\"]
+
+Back up to another region with API
+----------------------------------
+
+.. note::
+
+   In this instruction, the `curl` command line tool is used to interact with Aiven APIs.
+
+Using :doc:`Aiven APIs </docs/tools/api>`, you can enable BTAR for
+
+* :ref:`New Aiven service <new-service-api>` or
+* :ref:`Existing Aiven service <existing-service-api>`.
+
+.. topic:: ``additional_backup_regions``
+
+   To enable BTAR on an Aiven service, you need to include the ``additional_backup_regions`` parameter in relevant calls.
+
+.. _new-service-api:
+
+Create a new service with BTAR via API
+''''''''''''''''''''''''''''''''''''''
+
+Use the `ServiceCreate <https://api.aiven.io/doc/#tag/Service/operation/ServiceCreate>`_ API to create a new service with BTAR enabled. When constructing the API request, add the ``user_config`` object to the request body and nest the ``additional_backup_regions`` field inside.
+
+.. code-block:: bash
+
+    curl --request POST                                                    \
+        --url https://api.aiven.io/v1/project/YOUR_PROJECT_NAME/service    \
+        --header 'Authorization: Bearer YOUR_BEARER_TOKEN'                 \
+        --header 'content-type: application/json'                          \
+        --data
+            '{
+            "cloud": "string",
+            "plan": "string",
+            "service_name": "service_2_name",
+            "service_type": "cassandra",
+            "user_config": {
+                "additional_backup_regions": ["cloud-region-name"]
+            }
+        }'
+
+.. _existing-service-api:
+
+Enable BTAR on an existing service via API
+''''''''''''''''''''''''''''''''''''''''''
+
+Use the `ServiceUpdate <https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate>`_ API to configure your existing service so that it supports BTAR. When constructing the API request, add the ``user_config`` object to the request body and nest the ``additional_backup_regions`` field inside. Set the value of the ``additional_backup_regions`` parameter to the name of desired cloud region.
+
+.. code-block:: bash
+
+    curl --request PUT                                                                       \
+        --url https://api.aiven.io/v1/project/YOUR_PROJECT_NAME/service/YOUR_SERVICE_NAME    \
+        --header 'Authorization: Bearer YOUR_BEARER_TOKEN'                 \
+        --header 'content-type: application/json'                          \
+        --data
+            '{
+            "user_config": {
+                "additional_backup_regions": ["cloud-region-name"]
+            }
+        }'
+
+Related pages
+-------------
+
+* :doc:`About the backup to another region feature in Aiven </docs/platform/concepts/backup-to-another-region>`
+* :doc:`Manage BTAR for your Aiven service </docs/platform/howto/manage-backup-to-another-region>`
+* :doc:`Disable BTAR for your Aiven service </docs/platform/howto/disable-backup-to-another-region>`

docs/platform/howto/list-backup-to-another-region.rst

@@ -0,0 +1,10 @@
+Backup to another region
+========================
+
+.. important::
+
+    Backup to another region (BTAR) is available on ``:doc:Pro Platform </docs/platform/concepts/pro-platform>``.
+
+    This is a :doc:`limited availability feature </docs/platform/concepts/beta_services>`. If you're interested in trying out this feature, contact the sales team at `sales@Aiven.io <mailto:sales@Aiven.io>`_.
+
+.. tableofcontents::