From bcc0c8780362a38ec6844968125b356884af796a Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Wed, 1 Mar 2023 17:50:35 +0100 Subject: [PATCH] btar docs --- .github/vale/dicts/aiven.dic | 1 + .../styles/Aiven/capitalization_headings.yml | 1 + _toc.yml | 12 +- .../concepts/backup-to-another-region.rst | 79 +++++++++ .../disable-backup-to-another-region.rst | 60 +++++++ .../howto/enable-backup-to-another-region.rst | 162 ++++++++++++++++++ .../howto/list-backup-to-another-region.rst | 10 ++ .../howto/manage-backup-to-another-region.rst | 108 ++++++++++++ 8 files changed, 432 insertions(+), 1 deletion(-) create mode 100644 docs/platform/concepts/backup-to-another-region.rst create mode 100644 docs/platform/howto/disable-backup-to-another-region.rst create mode 100644 docs/platform/howto/enable-backup-to-another-region.rst create mode 100644 docs/platform/howto/list-backup-to-another-region.rst create mode 100644 docs/platform/howto/manage-backup-to-another-region.rst diff --git a/.github/vale/dicts/aiven.dic b/.github/vale/dicts/aiven.dic index 8d08282ea..5498e967f 100644 --- a/.github/vale/dicts/aiven.dic +++ b/.github/vale/dicts/aiven.dic @@ -24,6 +24,7 @@ Azure binlog boolean boot +BTAR Bucardo business BYOC diff --git a/.github/vale/styles/Aiven/capitalization_headings.yml b/.github/vale/styles/Aiven/capitalization_headings.yml index 6cad06735..b198ef30c 100644 --- a/.github/vale/styles/Aiven/capitalization_headings.yml +++ b/.github/vale/styles/Aiven/capitalization_headings.yml @@ -23,6 +23,7 @@ exceptions: - Azure - Azure Marketplace - Boot + - BTAR - Business - BYOC - Cassandra diff --git a/_toc.yml b/_toc.yml index fc7b87f3b..387206bdd 100644 --- a/_toc.yml +++ b/_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 - diff --git a/docs/platform/concepts/backup-to-another-region.rst b/docs/platform/concepts/backup-to-another-region.rst new file mode 100644 index 000000000..c7e602c42 --- /dev/null +++ b/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 ``. + +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 ` 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 ` +* :doc:`Manage BTAR ` +* :doc:`Disable BTAR ` diff --git a/docs/platform/howto/disable-backup-to-another-region.rst b/docs/platform/howto/disable-backup-to-another-region.rst new file mode 100644 index 000000000..d5b926af6 --- /dev/null +++ b/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 ``. + +Delete :doc:`an additional service backup ` from a region other than where primary service backups are stored. + +Disable BTAR via console +------------------------ + +1. Log in to the `Aiven Console `_. +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 ` 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 `_ endpoint to remove all target regions names from the ``additional_backup_regions`` array. + + Existing service > `Update service configuration `_ + +.. 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 ` +* :doc:`Enable BTAR for your Aiven service ` +* :doc:`Manage BTAR for your Aiven service ` diff --git a/docs/platform/howto/enable-backup-to-another-region.rst b/docs/platform/howto/enable-backup-to-another-region.rst new file mode 100644 index 000000000..03fda53d7 --- /dev/null +++ b/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 ``. + +Enable :doc:`the backup to another region (BTAR) feature ` 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 `_ +* 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 `` enabled +* Depending on the method you choose to use for enabling CCR + + * Access to the `Aiven Console `_ + * `cURL` CLI tool + * `Aiven CLI tool `_ + +Back up to another region via console +------------------------------------- + +1. Log in to the `Aiven Console `_. +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 `. + +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 ` is used to interact with Aiven APIs. + +Using CLI, you can enable BTAR for + +* :ref:`New Aiven service ` or +* :ref:`Existing Aiven service `. + +.. 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 ` 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 ` 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 `, you can enable BTAR for + +* :ref:`New Aiven service ` or +* :ref:`Existing Aiven service `. + +.. 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 `_ 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 `_ 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 ` +* :doc:`Manage BTAR for your Aiven service ` +* :doc:`Disable BTAR for your Aiven service ` diff --git a/docs/platform/howto/list-backup-to-another-region.rst b/docs/platform/howto/list-backup-to-another-region.rst new file mode 100644 index 000000000..48db5debb --- /dev/null +++ b/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 ``. + + This is a :doc:`limited availability feature `. If you're interested in trying out this feature, contact the sales team at `sales@Aiven.io `_. + +.. tableofcontents:: diff --git a/docs/platform/howto/manage-backup-to-another-region.rst b/docs/platform/howto/manage-backup-to-another-region.rst new file mode 100644 index 000000000..04067cdb6 --- /dev/null +++ b/docs/platform/howto/manage-backup-to-another-region.rst @@ -0,0 +1,108 @@ +Manage a cross-region backup +============================ + +.. important:: + + Backup to another region (BTAR) is available on ``:doc:Pro Platform ``. + +Manage a service that has the :doc:`backup to another region (BTAR) feature ` enabled (a cross-region backup added): + +* Change the backup region for the service by selecting another cross-region location. +* Monitor the status status, replication lag, and more. +* Fork and restore the service using :doc:`a cross-region backup `. +* Migrate the service. + +Prerequisites +------------- + +You have at least one :doc:`Aiven service with BTAR enabled `. + +Change a backup region +---------------------- + +1. Log in to the `Aiven Console `_. +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 **Edit secondary backup location** window, use the **Secondary location** dropdown menu to select a region for your additional backup. Confirm your choice by selecting **Save**. + +Monitor a service with BTAR +--------------------------- + +There are a few things you may want to check for your Aiven service in the context for BTAR: + +* What is the status of a secondary backup? + + * Does your service has a backup in another region? + * What is the target region of the secondary backup? + +* What is the replication lag between data availability in the primary region and the secondary region? + +Check BTAR status in the console +'''''''''''''''''''''''''''''''' + +To check out the availability, the status, and the target region of a secondary (BTAR) backup in the `Aiven Console `_, navigate to your **service's page** > **Backups** view > **Secondary backup location** column. + +Check replication lag with API +'''''''''''''''''''''''''''''' + +To check out the target region and the replication lag for a secondary (BTAR) backup of your service, call the `ServiceBackupToAnotherRegionReport `_ endpoint. + +Configure the call as follows: + +1. Enter YOUR-PROJECT-NAME and YOUR-SERVICE-NAME into the URL. +2. Specify DESIRED-TIME-PERIOD depending on the time period you need the metrics for: select one of the following values for the ``period`` key: ``hour``, ``day``, ``week``, ``month``, or ``year``. + +.. code-block:: bash + + curl --request POST \ + --url https://api.aiven.io/v1/project/YOUR-PROJECT-NAME/service/YOUR-SERVICE-NAME/backup_to_another_region/report \ + --header 'Authorization: Bearer YOUR-BEARER-TOKEN' \ + --header 'content-type: application/json' \ + --data '{"period":"DESIRED-TIME-PERIOD"}' + +.. topic:: Output + + As an output, you get metrics including replication lags at specific points in time. + +.. _fork-and-restore: + +Fork and restore a service with BTAR +------------------------------------ + +You can use the `Aiven Console `_ to recover your service from a backup in another region. To restore your service using BTAR, :doc:`create a fork ` of the original service in the region where the secondary backup resides. + +.. note:: + + When you **Fork & restore** from the secondary backup, your new fork service is created in the cloud and region where the secondary backup is located. The fork service gets the same plan that the primary service uses. Backups of the fork service are located in the region where this new service is hosted. + +1. Open the `Aiven Console `_ and navigate to your service homepage. +2. Select **Backups** from the sidebar. +3. On the **Backups** page, select **Fork & restore**. +4. In the **New database fork** window, apply the following settings: + + 1. As **Source backup location**, select **Secondary location**. + 2. As **Source backup version**, select either **Latest transaction** or **Point in time**. + + .. note:: + + For the point-in-time recovery (PITR) option, set up the time to no later than the time of taking the latest backup. + + 3. Specify a name for the new fork service. + 4. Select **Create fork**. + +Migrate a service with BTAR +--------------------------- + +You can migrate a service with BTAR the same way you :doc:`migrate a service with a regular backup `. + +.. note:: + + When you migrate your service, locations of service backups, both primary and secondary ones, do not change. + +Related pages +------------- + +* :doc:`About the backup to another region feature in Aiven ` +* :doc:`Enable BTAR for your Aiven service ` +* :doc:`Disable BTAR for your Aiven service `