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
@@ -1401,4 +1412,3 @@ entries:
   # -------- SUPPORT --------
   - file: docs/platform/howto/project-support-center
     title: Support
-

docs/platform/concepts.rst

@@ -18,4 +18,3 @@ Learn more about the Aiven platform.
 * :doc:`Service integrations </docs/integrations>`
 
 * :doc:`Get support </docs/platform/howto/project-support-center>`
-

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 one or more regions different from the primary one. 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 security for your data. It is a cost-efficient low-complexity disaster recovery feature that allows you to spread your data across different regions and recovery it in case of data loss or corruption in the primary region. During an outage or a downtime on the primary region, your data is protected and safe in a secondary backup location.
+
+How BTAR works
+--------------
+
+By enabling the backup to another region (BTAR) feature, you create an additional backup on top of the default one located in a primary region where your service is hosted. Contrary to the primary backup, the secondary backup is located outside the primary region.
+
+Secondary backups are taken from primary backups, not from the service itself. For this reason, your secondary backup is available only after a primary backup is there. There might be a data replication lag between the primary region and the secondary region.
+
+If you want to have your service restored from a secondary backup, for example, in case of an outage of the primary region, you create a fork of the service using a region where your 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 (support for creating cross-cloud-provider backups coming soon!).
+* 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.
+* To restore a service from an additional (not default) backup, you need to create a fork of the original service in the region where the additional backup resides.
+* Secondary backup is available only after a primary backup is there 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 @@
+Detete 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 londer 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 `[email protected] <mailto:[email protected]>`_.
+
+.. tableofcontents::