Elastic Data engines (engines backed by object storage)

Prerequisites

Repave on elastic data engines is supported as of version 27.0.
The target engine must be in the same version as the source engine.

How to repave a Delphix Elastic Data Engine

A sysadmin initiates repave/prepare on the source engine. All Delphix datasets are disabled and the Delphix management service is shut down.
The new target engine will connect to the same object storage data container during the repave apply process, with object parameters provided by the sysadmin in the repave apply payload.
To get an immediate and consistent performance on the new engine, the sysadmin can detach the block storage devices for cache from the Delphix engine and attach them to a new Delphix engine. This can be done through cloud APIs or manual operation. Another option is to use new/different block storage devices for cache with the caveat that the previously cached data from the source engine will be lost.
A sysadmin calls repave/apply on the new engine. All previously disabled data sources are enabled again.

Repave API calls

GET repave on the source engine obtains the domain0PoolGUID value for the next step.
POST repave/prepare initiates the repave preparation on the source engine.
POST repave/preview (optional) on the target engine provides a preview of the configurable metadata and engine summary of the source engine and determines its eligibility for applying repave on the target engine.
POST repave/apply on the target engine starts the process of applying repave from the source engine to the target engine.
GET repave returns the repave state, configurable metadata, and engine summary of the target engine.

The API calls to repave can also be executed with the command line interface (CLI). The equivalent CLI command(s) are listed with the REST API command. It is recommended CLI commands are used to execute the repave process.

This image illustrates a repave workflow using old cache devices:

This image illustrates a repave workflow using new cache devices:

REST API POST calls to execute the repave process

Establish a session

`http://{{delphix_engine_url}}/resources/json/delphix/session`

Establish an API session with Delphix, which is required before calling repave APIs.

CODE

{
               "type": "APISession",
               "version": {
                              "type": "APIVersion",
                              "major": {{api_version_major}},
                              "minor": {{api_version_minor}},
                              "micro": {{api_version_micro}}
               }
}

You do not need to establish a session using the CLI.

http://{{delphix_engine_url}}/resources/json/delphix/login

Log in as sysadmin, which is required before calling repave APIs.

CODE

{
   "type": "LoginRequest",
   "username": "{{sysadmin_user}}",
   "password": "{{sysadmin_pwd}}"
}

The CLI command for login requires logging into the Delphix engine host using the sysadmin user:

ssh sysadmin@<delphix_engine_hostname>

Get the pool GUID from the repave GET API

Before initiating the repave prepare process on the source engine, the sysadmin needs to know the domain0PoolGUID value on the source engine that will be used during the repave apply phase.

The sysadmin can get the domain0PoolGUID value by executing the repave GET API call on the source engine, which is shown in the repave status section.

Prepare block storage devices used for cache

There are two options when configuring the block storage devices for cache:

use the existing, original (old) cache devices from the source engine, or
use new cache devices.

If planning on using the existing (old) cache devices from the source engine, make sure to note from the hypervisor layer which block devices will need to be moved to the target engine before the apply phase.

If planning on using new cache devices, the device names can be viewed on the target engine using the CLI command storage device ls. This list of device names is needed for the parameter RepaveCacheDevicesNew during the repave apply command. repave apply command.

Repave prepare

http://{{delphix_engine_url}}/resources/json/delphix/repave/prepare

CLI commands:

CODE

               repave/prepare
               commit

Introduction

Delphix sysadmin calls repave/prepare to start preparing for repave on the source engine. During the repave/prepare phase:

All the sources will be disabled.
All datasets and required metadata will be transferred to cloud storage.
The Delphix management service will be shut down.

Request parameters

ignoreDisableSourcesFailures
If true, a failure to disable sources will not block the repave. The default value is false, if not provided.

enableSourcesOnFailure
If true, when repave fails, data source disabled by repave will be enabled again. The default value is false, if not provided.

Response

If successful, the API will return a job ID and an action ID.

Before starting the repave apply operation on the new target engine, verify the repave state is PREPARE_SUCCESSFUL on the source engine.

To check the repave state with the CLI:

ABAP

 repave
    get
==> state: PREPARE_SUCCESSFUL

Repave status

http://{{delphix_engine_url}}/resources/json/delphix/repave

CLI command:
repave/get

GET /repave will show:

Current state of the repave process.
Summary of the current engine.
Metadata of the current engine that will be migrated to the target engine.

Tips

Always use GET /repave before initiating repave prepare to see the engine summary and engine metadata. Copy the output to a saved text file for use later.
Always use GET /repave to check the repave progress.
When the Delphix management service is restarting, GET /repave might not respond, wait for a few minutes and try again.

Repave preview

http://{{delphix_engine_url}}/resources/json/delphix/repave/preview

Introduction

Repave/preview (optional) is for users to preview from the target engine, the summary and metadata of a source engine that will be applied to the target engine.
The APPLY_ELIGIBLE state indicates the target engine is eligible to apply repave.
The APPLY_CHECK_ELIGIBILITY_FAILED state indicates the current engine is not eligible to apply repave, the actual reason can be found from the stateDetail attribute.
Before calling this API ensure you have the domain0PoolGUID from the source engine and other object storage profile information and credentials used for the source engine.

Request parameters

Each cloud platform requires different parameters.

AWS S3 parameters
type: `S3ObjectStoreRepavePreviewParameters` accessCredentials : defined in repave apply section here: access bucket: S3 bucket name which is used on the source engine domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare endpoint: S3 endpoint/portal address. region: S3 bucket Region

Blob parameters
type: `BlobObjectStoreRepavePreviewParameters` accessCredentials: defined in repave apply section here: blob access container: blob container name which is used on the source engine. domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare. endpoint: blob endpoint address

GCP parameters
type: `GcpObjectStoreRepavePreviewParameters` bucket: GCP bucket name which is used on the source engine domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare

OCI parameters
type: `OciObjectStoreRepavePreviewParameters` bucket: OCI bucket name which is used on the source engine domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare

Response

The engine summary and metadata of the source engine.

CLI example commands on the target engine for repave/preview using an AWS instance profile

CODE

> repave/preview 
repave preview *> set type=S3ObjectStoreRepavePreviewParameters 
repave preview *> set accessCredentials.type=S3ObjectStoreAccessInstanceProfile 
repave preview *> set bucket=repave-elastic-source-27-0 
repave preview *> set domain0PoolGUID=10998343740256899999 
repave preview *> set endpoint=https://s3-us-west-2.amazonaws.com 
repave preview *> set region=us-west-2 
repave preview *> commit 

Output: 
    state: APPLY_ELIGIBLE 
    stateDetail: The engine is eligible to apply repave.

For AWS access key credentials, the CLI commands are below. Replace the accessCredentials.type value with the first command and add the second and third commands.

repave preview *> set accessCredentials.type=S3ObjectStoreAccessKey
repave preview *> set accessCredentials.accessId=**************
repave preview *> set accessCredentials.accessKey=******************************

Repave apply

`http://{{delphix_engine_url}}/resources/json/delphix/repave/apply`

Introduction

Delphix sysadmin calls repave/apply on the new engine. The Delphix management service will be restarted, and all previously disabled data sources will be enabled again.
Before calling this API:
- Verify old cache devices are attached to the new target engine if you want to use the same cache devices. You must detach the original (old) devices from the source engine and attach them to the target engine.
- If you don’t want to use the old cache devices, make sure new block devices are connected to the target engine to use as cache.
- Make sure you have domain0PoolGUID from the source engine and other object storage profile information and credentials from the source engine.

Request parameters

Each cloud will have a different parameter required to perform repave apply.

AWS S3/ S3 Compatible Parameters

type: S3ObjectStoreRepaveApplyParameters
accessCredentials : Bucket credential type

In case you have accessKey and accessID for S3 bucket:
- type: S3ObjectStoreAccessKey
- accessId : S3 Bucket access ID
- accessKey: S3 Bucket access Key
  
  In case of Instance Profile:
- type: S3ObjectStoreAccessInstanceProfile

bucket: S3 bucket name which was used on the source engine
cacheDevices: Possible two types whether you are using old cache devices or new cache devices.
- New Cache:
  - type: RepaveCacheDevicesNew
  - devices: list of new storage devices to use as object store cache.
- Old Cache:
  - type: RepaveCacheDevicesOld
  - NOTE: no need to add devices here.
domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare
endpoint: S3 endpoint/portal address.
region: S3 bucket Region

Blob Parameters

type: BlobObjectStoreRepaveApplyParameters
accessCredentials: Blob access credential type

In case of Managed Identity:
- type: BlobObjectStoreAccessManagedIdentities
  
  In case of Access based:
- type: BlobObjectStoreAccessKey
- azureAccount: Azure account for the object store.
- azureKey: Account Key

cacheDevices: Possible two types whether you are using old cache devices or new cache devices.
- New Cache:
  - type: RepaveCacheDevicesNew
  - devices: List of new storage devices to use as object store cache.
- Old Cache:
  - type: RepaveCacheDevicesOld
  - NOTE: no need to add devices here.
container: blob container name which was used on the source engine.
domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare
endpoint: blob endpoint address

GCP Parameters

type: GcpObjectStoreRepaveApplyParameters
bucket: GCP bucket name which is used on the source engine
cacheDevices: Possible two types whether you are using old cache devices or new cache devices.
- New Cache:
  - type: RepaveCacheDevicesNew
  - devices: List of new storage devices to use as object store cache.
- Old Cache:
  - type: RepaveCacheDevicesOld
  - NOTE: no need to add devices here.
domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare

OCI Parameters

type: OciObjectStoreRepaveApplyParameters
Bucket: Oci bucket name which is used on the source engine
cacheDevices: Possible two types whether you are using old cache devices or new cache devices.
- New Cache:
  - type: RepaveCacheDevicesNew
  - devices: List of new storage devices to use as object store cache.
- Old Cache:
  - type: RepaveCacheDevicesOld
  - NOTE: no need to add devices here.
domain0PoolGUID: the domain0 pool GUID, which has been noted from the engine summary before initiating repave prepare

Response

A job id and action id will be returned if the API is called successfully.

The Delphix management stack will restart when repave apply is executed. Wait until the management stack restarts and then log into the target engine.

CLI example commands for repave/apply using OLD cache devices

The following is an example of CLI commands needed to execute repave apply for an AWS instance profile with old cache devices from the source engine now attached to the target engine:

CODE

> repave/apply
repave apply *> set type=S3ObjectStoreRepaveApplyParameters
repave apply *> set accessCredentials.type=S3ObjectStoreAccessInstanceProfile
repave apply *> set bucket=repave-elastic-source-27-0
repave apply *> set cacheDevices.type=RepaveCacheDevicesOld
repave apply *> set domain0PoolGUID=10998343740256853264
repave apply *> set endpoint=https://s3-us-west-2.amazonaws.com
repave apply *> set region=us-west-2
repave apply *> commit

Output:
REPAVE_APPLY: A job has been dispatched to apply repave on the engine. Management stack might restart to finalize repave, it will take a few minutes, please wait patiently.
    Dispatched job JOB-1
    REPAVE_APPLY_INITIATE job started.
Invalid response returned from server. The management service may be unavailable, please wait and try again. If the problem persists, please contact Delphix support.

The Delphix management stack will restart when repave apply is executed via the CLI. Wait until the management stack restarts and then log back into the engine using the CLI and execute repave/get to verify the APPLY_SUCCESSFUL state, which indicates that the repave apply operation was successful.

CODE

> repave/get
Output:
state: APPLY_SUCCESSFUL
stateDetail: Congrats! The engine has applied repave successfully.

For AWS access key credentials, the CLI commands are below. Replace the accessCredentials.type value with the first command and add the second and third commands.

repave apply *> set accessCredentials.type=S3ObjectStoreAccessKey
repave apply *> set accessCredentials.accessId=**************
repave apply *> set accessCredentials.accessKey=********************************

CLI example commands for repave/apply using NEW cache devices

The following is an example of CLI commands needed to execute repave apply for an AWS instance profile with new cache devices on the target engine:

CODE

> repave/apply
repave apply *> set type=S3ObjectStoreRepaveApplyParameters
repave apply *> set accessCredentials.type=S3ObjectStoreAccessInstanceProfile
repave apply *> set bucket=repave-elastic-source-27-0
repave apply *> set cacheDevices.type=RepaveCacheDevicesNew
repave apply *> set cacheDevices.devices=xvdb
repave apply *> set domain0PoolGUID=12424137104599998999
repave apply *> set endpoint=https://s3.us-west-2.amazonaws.com
repave apply *> set region=us-west-2
repave apply *> commit

Output:
    REPAVE_APPLY: A job has been dispatched to apply repave on the engine. Management stack might restart to finalize repave, it will take a few minutes, please wait patiently.
    Dispatched job JOB-1
    REPAVE_APPLY_INITIATE job started.
Invalid response returned from server. The management service may be unavailable, please wait and try again. If the problem persists, please contact Delphix support.

NOTE: the Delphix management stack will restart when repave apply is executed via the CLI. Wait until the management stack restarts and then log back into the engine using the CLI and execute repave/get to verify the APPLY_SUCCESSFUL state, which indicates that the repave apply operation was successful.

CODE

> repave/get
Output:
state: APPLY_SUCCESSFUL
stateDetail: Congrats! The engine has applied repave successfully.

For AWS access key credentials, the CLI commands are below. Replace the accessCredentials.type value with the first command and add the second and third commands.

repave apply *> set accessCredentials.type=S3ObjectStoreAccessKey
repave apply *> set accessCredentials.accessId=**************
repave apply *> set accessCredentials.accessKey=********************************

Prerequisites

How to repave a Delphix Elastic Data Engine

Repave API calls

REST API POST calls to execute the repave process

Establish a session

http://{{delphix_engine_url}}/resources/json/delphix/session

Login

Get the pool GUID from the repave GET API

Prepare block storage devices used for cache

Repave prepare

Repave status

Tips

Repave preview

Introduction

Request parameters

AWS S3 parameters

Blob parameters

OCI parameters

Response

Repave apply

http://{{delphix_engine_url}}/resources/json/delphix/repave/apply

Introduction

Request parameters

AWS S3/ S3 Compatible Parameters

Blob Parameters

GCP Parameters

OCI Parameters

Response

`http://{{delphix_engine_url}}/resources/json/delphix/session`

`http://{{delphix_engine_url}}/resources/json/delphix/repave/apply`