Back up your Aiven for Grafana® service to another region Limited availability
Copy your Aiven for Grafana® service backups to a secondary region for disaster recovery.
In addition to the primary service backup, you can keep a secondary backup in another region.
This feature is in limited availability. Contact your account team to enable it for your project.
Backup to another region (BTAR) is a disaster recovery feature that copies backup files from your service's primary backup region to an additional, secondary region. BTAR improves data resilience and protects your data against an outage in the primary backup region. If the primary region becomes unavailable, you can fork your service from the backup copy stored in the secondary region.
BTAR is not a live replica of your database. It replicates backup files asynchronously, so recovery means forking or restoring from those files rather than failing over to a running standby. For a live standby with managed failover, use cross-region disaster recovery on Aiven for PostgreSQL® instead.
Limitations
- The cloud provider for your secondary backup region must match the cloud provider for your service and its primary backup.
- You can configure one secondary backup region for each service.
- You can restore a secondary backup only in the region where it is stored.
- To fork from a secondary backup, the backup must already be replicated to the secondary region.
- Read replicas cannot restore from a secondary backup.
For a project that has the backup to another region (BTAR) feature enabled, you can add or change a secondary backup location, check the secondary backup status, monitor the replication lag, fork and restore using the cross-region backup, or migrate to another cloud or region.
The Aiven Console does not support BTAR for this service. Manage the secondary backup
location with the Aiven CLI, the Aiven API, the
Aiven Provider for Terraform, or the
Aiven Operator for Kubernetes®, by setting the
additional_backup_regions option in your service configuration.
Prerequisites
- At least one Aiven service in a project with BTAR enabled
- One of the following: the Aiven CLI, the Aiven API, the Aiven Provider for Terraform, or the Aiven Operator for Kubernetes®
Add or change a secondary backup location
Set additional_backup_regions to the cloud and region you want to hold the secondary
backup. To change the region later, set the option to a different value.
- Aiven CLI
- Aiven API
- Terraform
- Kubernetes
Use the avn service update command.
avn service update SERVICE_NAME \
--project PROJECT_NAME \
-c additional_backup_regions='["SECONDARY_REGION"]'
Replace the following:
SERVICE_NAME: the name of your servicePROJECT_NAME: the name of your projectSECONDARY_REGION: the cloud and region to hold the secondary backup, for exampleaws-us-east-2
Use the ServiceUpdate endpoint.
curl --request PUT \
--url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \
--header 'Authorization: Bearer BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"user_config": {"additional_backup_regions": ["SECONDARY_REGION"]}}'
Replace the following:
PROJECT_NAME: the name of your projectSERVICE_NAME: the name of your serviceBEARER_TOKEN: your authentication tokenSECONDARY_REGION: the cloud and region to hold the secondary backup, for exampleaws-us-east-2
Set additional_backup_regions in the service's user configuration block. The example
uses Aiven for Valkey™; for Aiven for Grafana®, use aiven_grafana and
grafana_user_config.
resource "aiven_valkey" "example" {
project = var.project_name
service_name = "example-service"
cloud_name = "google-europe-west1"
plan = "business-4"
valkey_user_config {
additional_backup_regions = ["google-europe-north1"]
}
}
Set additional_backup_regions under spec.userConfig. The example uses the Valkey
kind; for Aiven for Grafana®, use the Grafana kind.
apiVersion: aiven.io/v1alpha1
kind: Valkey
metadata:
name: example-service
spec:
project: PROJECT_NAME
cloudName: google-europe-west1
plan: business-4
userConfig:
additional_backup_regions:
- google-europe-north1
Aiven provisions storage in the region you selected and starts replicating backup files to it. Until the first backup finishes replicating, you cannot fork your service from the secondary backup.
Changing the secondary backup region starts a new base backup. You can fork your service from the new region only after that backup finishes.
Check BTAR status
To see whether your service has a secondary backup and which region holds it, read
user_config.additional_backup_regions for the service. If the service has no secondary
backup, the field is not set.
- Aiven CLI
- Aiven API
- Terraform
- Kubernetes
avn service get SERVICE_NAME --project PROJECT_NAME --json
Call the ServiceGet endpoint.
curl --request GET \
--url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \
--header 'Authorization: Bearer BEARER_TOKEN'
Read the attribute from the Terraform state.
terraform state show aiven_valkey.example
Read the field from the service manifest.
kubectl get valkey example-service \
-o jsonpath='{.spec.userConfig.additional_backup_regions}'
Determine replication lag
Determine the target region and the replication lag for a secondary (BTAR) backup of your service, call the ServiceBackupToAnotherRegionReport endpoint.
Configure the call as follows:
- Enter
YOUR-PROJECT-NAMEandYOUR-SERVICE-NAMEinto the URL. - Specify
DESIRED-TIME-PERIODdepending on the time period you need the metrics for: select one of the following values for theperiodkey:hour,day,week,month, oryear.
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"}'
As output, you get metrics including replication lags at specific points in time.
Fork and restore a service with BTAR
To restore your service using BTAR, create a fork of the original service in the region where the secondary backup resides.
When you fork and 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.
- Aiven CLI
- Aiven API
- Terraform
- Kubernetes
Run the avn service create command
with the --service-to-fork-from option and the --recovery-target-timeoption. Set
--recovery-target-time to no earlier than the time of taking the oldest replicated base
backup.
avn service create FORK_SERVICE_NAME \
--plan SERVICE_PLAN \
--project PROJECT_NAME \
--service-type SERVICE_TYPE \
--cloud SECONDARY_BACKUP_REGION \
--recovery-target-time "YYYY-MM-DDTHH:MM:SS+00:00" \
--service-to-fork-from PRIMARY_SERVICE_NAME
Replace the following with meaningful data:
FORK_SERVICE_NAMESERVICE_PLANPROJECT_NAMESERVICE_TYPESECONDARY_BACKUP_REGIONPRIMARY_SERVICE_NAMEYYYY-MM-DDTHH:MM:SS+00:00
Use the ServiceCreate API
to create a fork service. When constructing the API request, add the user_config object
to the request body and nest the service_to_fork_from field and the
recovery_target_time field inside. Set recovery_target_time to no earlier than the
time of taking the oldest replicated base backup.
curl --request POST \
--url https://api.aiven.io/v1/project/PROJECT_NAME/service \
--header 'Authorization: Bearer BEARER_TOKEN' \
--header 'content-type: application/json' \
--data
'{
"cloud": "SECONDARY_BACKUP_REGION",
"plan": "SERVICE_PLAN",
"service_name": "FORK_SERVICE_NAME",
"service_type": "SERVICE_TYPE",
"user_config": {
"service_to_fork_from": "PRIMARY_SERVICE_NAME",
"recovery_target_time": "YYYY-MM-DDTHH:MM:SS+00:00"
}
}'
Replace the following with meaningful data:
FORK_SERVICE_NAMESERVICE_PLANPROJECT_NAMESERVICE_TYPESECONDARY_BACKUP_REGIONPRIMARY_SERVICE_NAMEYYYY-MM-DDTHH:MM:SS+00:00
Create a new service in the secondary backup region, with service_to_fork_from and
recovery_target_time set in its user configuration block. Set recovery_target_time to
no earlier than the time of taking the oldest replicated base backup. The example uses
Aiven for Valkey™; for Aiven for Grafana®, use aiven_grafana and grafana_user_config.
resource "aiven_valkey" "fork" {
project = var.project_name
service_name = "example-fork"
cloud_name = "google-europe-north1"
plan = "business-4"
valkey_user_config {
service_to_fork_from = "example-service"
recovery_target_time = "2026-11-04T10:00:00+00:00"
}
}
Create a new service in the secondary backup region, with service_to_fork_from and
recovery_target_time set under spec.userConfig. Set recovery_target_time to no
earlier than the time of taking the oldest replicated base backup. The example uses the
Valkey kind; for Aiven for Grafana®, use the Grafana kind.
apiVersion: aiven.io/v1alpha1
kind: Valkey
metadata:
name: example-fork
spec:
project: PROJECT_NAME
cloudName: google-europe-north1
plan: business-4
userConfig:
service_to_fork_from: example-service
recovery_target_time: "2026-11-04T10:00:00+00:00"
Migrate a service with BTAR
You can migrate a service with BTAR the same way you migrate a service with a regular backup.
When you migrate your service, locations of service backups, both primary and secondary ones, do not change.
Delete a cross-region backup
Delete an additional service backup created in a region different from your primary backup region. When you delete the additional cross-region backup, you still have the default backup located in the primary, service-hosting region.
- Aiven CLI
- Aiven API
- Terraform
- Kubernetes
Use the avn service update command to remove all target
region names from the additional_backup_regions array.
avn service update SERVICE_NAME \
--project PROJECT_NAME \
-c additional_backup_regions='[]'
Use the ServiceUpdate
endpoint to remove all target region names from the additional_backup_regions array.
curl --request PUT \
--url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \
--header 'Authorization: Bearer BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"user_config": {"additional_backup_regions": []}}'
Set additional_backup_regions to an empty list, then apply the change.
valkey_user_config {
additional_backup_regions = []
}
Set additional_backup_regions to an empty list, then apply the manifest.
spec:
userConfig:
additional_backup_regions: []
Related pages