spec

spec

Terminology

Objective

Define a standard that will enable storage vendors (SP) to develop controllers/plugins for DR or to talk to the different CO systems.

Goals in MVP

The new standard will

• Provide API at volume level granularity.
• Enable SP authors to write one replication compliant plugin that “just works” across all COs that implement RPC.
• Define API (RPCs) that enable:
  • Enable/Disable volume replication.
  • Promote/Demote volume.
  • Resync volume to solve the issue before using the volume.

Non-Goals in MVP

• Replication at different granular levels
• Replication of volume snapshots.

Solution Overview

This specification defines an interface along with the minimum operational and packaging recommendations for a storage provider (SP) to implement a Replication compatible plugin. The interface declares the RPCs that a plugin MUST expose.

Architecture

RPC Interface

• Controller Service: The Controller plugin MUST implement these sets of RPCs.

syntax = "proto3";
package replication;

import "google/protobuf/descriptor.proto";
import "google/protobuf/timestamp.proto";

option go_package = ".;replication";

extend google.protobuf.FieldOptions {
  // Indicates that this field is OPTIONAL and part of an experimental
  // API that may be deprecated and eventually removed between minor
  // releases.
  bool alpha_field = 1100;
}

// Controller holds the RPC methods for replication and all the methods it
// exposes should be idempotent.
service Controller {
  // EnableVolumeReplication RPC call to enable the volume replication.
  rpc EnableVolumeReplication (EnableVolumeReplicationRequest)
  returns (EnableVolumeReplicationResponse) {}
  // DisableVolumeReplication RPC call to disable the volume replication.
  rpc DisableVolumeReplication (DisableVolumeReplicationRequest)
  returns (DisableVolumeReplicationResponse) {}
  // PromoteVolume RPC call to promote the volume.
  rpc PromoteVolume (PromoteVolumeRequest)
  returns (PromoteVolumeResponse) {}
  // DemoteVolume RPC call to demote the volume.
  rpc DemoteVolume (DemoteVolumeRequest)
  returns (DemoteVolumeResponse) {}
  // ResyncVolume RPC call to resync the volume.
  rpc ResyncVolume (ResyncVolumeRequest)
  returns (ResyncVolumeResponse) {}
  // GetVolumeReplicationInfo RPC call to get the volume replication
  // information.
  rpc GetVolumeReplicationInfo (GetVolumeReplicationInfoRequest)
  returns (GetVolumeReplicationInfoResponse) {}
}

EnableVolumeReplication

// EnableVolumeReplicationRequest holds the required information to enable
// replication on a volume.
message EnableVolumeReplicationRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // The identifier for the replication.
  // Plugin specific parameters passed in as opaque key-value pairs.
  map<string, string> parameters = 2;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 3 [(replication_secret) = true];
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 4 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 5;
}

// EnableVolumeReplicationResponse holds the information to send when
// replication is successfully enabled on a volume.
message EnableVolumeReplicationResponse {
}

Error Scheme

DisableVolumeReplication

// DisableVolumeReplicationRequest holds the required information to disable
// replication on a volume.
message DisableVolumeReplicationRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // Plugin specific parameters passed in as opaque key-value pairs.
  map<string, string> parameters = 2;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 3 [(replication_secret) = true];
  // The identifier for the replication.
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 4 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 5;
}

// DisableVolumeReplicationResponse holds the information to send when
// replication is successfully disabled on a volume.
message DisableVolumeReplicationResponse {
}

Error Scheme

PromoteVolume

// PromoteVolumeRequest holds the required information to promote volume as a
// primary on local cluster.
message PromoteVolumeRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // This field is optional.
  // Default value is false, force option to Promote the volume.
  bool force = 2;
  // Plugin specific parameters passed in as opaque key-value pairs.
  map<string, string> parameters = 3;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 4 [(replication_secret) = true];
  // The identifier for the replication.
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 5 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 6;
}

// PromoteVolumeResponse holds the information to send when
// volume is successfully promoted.
message PromoteVolumeResponse{
}

Error Scheme

DemoteVolume

// DemoteVolumeRequest holds the required information to demote volume on local
// cluster.
message DemoteVolumeRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // This field is optional.
  // Default value is false, force option to Demote the volume.
  bool force = 2;
  // Plugin specific parameters passed in as opaque key-value pairs.
  map<string, string> parameters = 3;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 4 [(replication_secret) = true];
  // The identifier for the replication.
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 5 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 6;
}

// DemoteVolumeResponse holds the information to send when
// volume is successfully demoted.
message DemoteVolumeResponse{
}

Error Scheme

ResyncVolume

// ResyncVolumeRequest holds the required information to resync volume.
message ResyncVolumeRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // This field is optional.
  // Default value is false, force option to Resync the volume.
  bool force = 2;
  // Plugin specific parameters passed in as opaque key-value pairs.
  map<string, string> parameters = 3;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 4 [(replication_secret) = true];
  // The identifier for the replication.
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 5 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 6;
}

// ResyncVolumeResponse holds the information to send when
// volume is successfully resynced.
message ResyncVolumeResponse{
  // Indicates that the volume is ready to use.
  // The default value is false.
  // This field is REQUIRED.
  bool ready = 1;
}

Error Scheme

GetVolumeReplicationInfo

// GetVolumeReplicationInfoRequest holds the required information to get
// the Volume replication information.
message GetVolumeReplicationInfoRequest {
  // The identifier for this volume, generated by the plugin during
  // CreateVolume CSI RPC call.
  // This field is REQUIRED.
  // This field MUST contain enough information to uniquely identify
  // this specific volume vs all other volumes supported by this plugin.
  // This field SHALL be used by the CO in subsequent calls to refer to
  // this volume.
  string volume_id = 1;
  // Secrets required by the plugin to complete the request.
  map<string, string> secrets = 2 [(replication_secret) = true];
  // The identifier for the replication.
  // This field is OPTIONAL.
  // This field MUST contain enough information, together with volume_id,
  // to uniquely identify this specific replication
  // vs all other replications supported by this plugin.
  string replication_id = 3 [(alpha_field) = true];
  // If specified, this field will contain volume or volume group id
  // for replication.
  ReplicationSource replication_source = 4;
}

// GetVolumeReplicationInfoResponse holds the information to send the
// volume replication information.
message GetVolumeReplicationInfoResponse {
  // Holds the last sync time.
  // This field is REQUIRED.
  .google.protobuf.Timestamp last_sync_time = 1;
}

Error Scheme

ReplicationSource

// Specifies what source the replication will be created from. One of the
// type fields MUST be specified.
message ReplicationSource {
  message VolumeSource {
    // Contains identity information for the existing volume.
    // This field is REQUIRED.
    string volume_id = 1;
  }

  message VolumeGroupSource {
    // Contains identity information for the existing volume group.
    // This field is REQUIRED.
    string volume_group_id = 1;
  }

  oneof type {
    // Volume group source type
    VolumeGroupSource volumegroup = 1;
    // Volume source type
    VolumeSource volume = 2;
  }
}