Forking a Service Instance
Currently, a9s KeyValue, a9s MariaDB, a9s Messaging, a9s MongoDB, and a9s PostgreSQL are the only Data Services that support performing forking for a Service Instance via the Disaster Recovery API or Plugin. All other a9s Data Services will need some manual interaction, which are not specified and may vary from Data Service to Data Service.
Trying to apply the information contained on this document to an a9s Data Service aside from the ones mentioned above can leave the Service Instances in an irrecuperable state.
This document helps the Application Developer in creating a fork of an existing Service Instance, based on a specific backup.
Creating a fork of a service instance is based on the Disaster Recovery API/Plugin.
For an Application Developer to be able to Create a Fork via Disaster Recovery, both the a9s Backup Manager and the Service Instances need to be prepared. In other words the Platform Operator must configure the a9s Backup Manager and a fresh and compatible Service Instance must be ready for use.
Overview
The steps needed to create a Fork of a Service Instance is very similar to the one needed to perform a Disaster
Recovery. The difference is that in order to fork from a specific backup instead of the last one, it is necessary
retrieve the backup_id instead of the backup_guid. so the steps are the following:
- Procuring the
backup_idof the wanted backup. - Procuring the encryption key.
- Performing the operation.
This document provides the general steps to execute forking of a Service Instance via both the a9s Cloud Foundry CLI plugin for disaster recovery and the a9s Public API v1.
The a9s Backup Manager does not provide the encryption key, as this must be set by the Application Developer.
Downloading and Installing the a9s Cloud Foundry CLI Plugin
The plugin can be obtained from our public S3 bucket. The plugin is available for the following operating systems:
- Linux (sha:493bd71f62baea006f9de8ac1df6a4e5382c3a3a3e95303482ce9072a13491fc)
- MacOS (sha:3616fdf1dadd8452e439a3d49796cfb1b8f085c1e041adce08ae70e69ed164e5)
- Windows (sha:d609d4bb70eade48141e145153ac1a59b6ab9e8a9b0d075706d1103063d9fbd3)
Once the binary file has been downloaded, it can be installed into the Cloud Foundry CLI with the following command:
cf install-plugin <source-path>/cf-disaster-recovery-plugin -f
Please notice that the -f flag is used in the command. This is necessary because this plugin is not signed by Cloud
Foundry, therefore the -f flag is needed to ignore the unsigned certificate when installing the binary to the CLI.
Prepare the Service Instance
It is mandatory to have some information about the original Service Instance holding the data to be forked, as it is required in order to locate the correct backup collection and, if necessary, create a fresh Service Instance with the same settings:
| Key | Description |
|---|---|
| Dashboard URL | The URL to the Dashboard of the Service Instance. Used to retrieve the Backup GUID. |
| Backup ID | The ID that is used by the Backup Manager to retrieve the specific Backup to fork from. |
| Backup Encryption Key | The encryption key used to encrypt the backup |
| Service Name | The name of the service used to create the Service Instance. |
| Plan Name | The name of the plan used to create the Service Instance |
| Custom Service Parameters | Custom parameter set during creating or updating of the Service Instance |
It is strongly recommended to retrieve this information as soon as possible, especially when updating the encryption key, and storing it in a secure place.
When using Cloud Foundry, most of the information can be retrieved using the Cloud Foundry CLI with a simple
cf service <service-instance-name>, except:
- The Service Instance's encryption key.
- The Specific Backup ID Backup ID.
It is worth noting the following caveats:
The new Service Instance has a completely different Backup GUID. This means that any backup that is created in the new Service Instance will have a different Backup GUID. Therefore it is imperative to properly distinguish them during the process and when saving them for future reference.
The new Service Instance will not have a user defined encryption key until one is set by the Application Developer. This encryption key will not affect the current disaster recovery, but it is important to note it down. It is imperative to properly distinguish both encryption key during the process and when saving them for future reference.
Setting the Backup's Encryption Key
For setting the backup's encryption key, follow the instructions in: Disaster Recovery - Setting the encryption Key
Retrieving the Wanted Backup's ID
In order to retrieve the backup_id, the endpoint API V1 - List All Backup can be
called. This endpoint will return a array of Objects that are composed of multiple fields, the required field for this
step is backup_id.
Perform the Fork
To be able to create a fork via Disaster Recovery, a new Service Instance must be created to host the data to recover. This requires the new Service Instance to be created with the same parameters and with the same or bigger plan as the old Service Instance to avoid unexpected behavior when restoring the data (e.g. a persistent disk that can not store the whole data). This information must be gathered in the Prepare the Service Instance step.
Cloud Foundry Example:
cf create-service <service name> <plan_name> my_psql_service -c <custom service parameters>
E.g.:
cf create-service a9s-postgresql13 postgresql-replica-small my_psql_service -c '{"continuous_archiving": "enabled"}'
After that, a disaster recovery can be triggered, with the additional information shown below:
| Key | Required | Description |
|---|---|---|
| Backup ID | True | The ID that is used by the Backup Manager to retrieve the specific Backup to fork from. |
| Backup Encryption Key | True | The encryption key used to decrypt the Backup. |
If a Service Instance is configured with continuous archiving it can only be recovered to a Service Instance configured with continuous archiving.
checking the status of the disaster recovery task is possible using the a9s Dashboard of the Service Instance recovering the data. After the task is finished with success, the Service Instance is ready for use.
After the restore finishes, a new service binding to the new Service Instance must be created in order to be able to access the data.
Perform Forking Using the Disaster Recovery API Directly
Create new Service Instance
First, create a new Service Instance, as shown in the example below:
cf create-service a9s-postgresql13 postgresql-replica-small my_recovered_psql_service -c '{"continuous_archiving": "enabled"}'
Authentication
To use the API, it is required to be authenticated and authorized, as well as creating a cookie, which will store the authenticated session. The necessary steps to do so are explained in the a9s Public API documentation.
After the authentication step, bearer_token will be obtained, and url environment variables and the cookie file
called session.cookie will be created.
The url variable to be specified in the API call to perform the disaster recovery must use the a9s Service Dashboard
URL of the new Service Instance, as the call is made against it.
Endpoint
POST /v1/instances/:instance_id/disaster-recovery/perform
Parameters
| Name | Type | Description |
|---|---|---|
backup_id | string | |
encryption_key | string | The encryption key that was used to encrypt the backups. |
Perform Disaster Recovery with cURL
To perform a disaster recovery via cURL, the request must be executed against the full url of the new Service Instance
as described in the example below:
curl -X POST --cookie test.cookie --cookie-jar test.cookie --location \
--header "Content-Type: application/json" \
--header "Authorization: ${bearer_token}" \
"${url}/disaster-recovery/perform" \
--data '{"encryption_key":"<encryption_key>", "backup_id":"<backup_id>"}'
Perform Disaster Recovery via the CF CLI Plugin
A specific backup can be restored by running the following command:
cf disaster-recovery-restore <service-instance> <backup-id> <encryption-key>
This will restore a specific backup from the original instance on a fresh Service Instance.