/*
Copyright 2019 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

syntax = 'proto3';

package k8scloudoperator;

import "github.com/container-storage-interface/spec/csi.proto";

// Interface exported by the server
service K8sCloudOperator {
   /*
   * GetPodVMUUIDAnnotation gets the PV by querying the API server refering to the volumeID in the request.
   * Retrieves the PVC name and Namespace from the PV spec.
   *
   * It then gets the vmuuid annotation from the pod satisfying the below conditions
   * 1. Pod Scheduled on node with name "nodeName"
   * 2. Pod is in pending state in the same namespace as pvc specified using "pvcNamespace"
   * 3. Pod has a volume with name "pvcName" associated with it
   *
   * The annotation might not be available immediately when the Pod is created.
   * So polling the Pod periodically every pollInterval seconds to check if annotation is available.
   * If annotation is not available after a timeout period, the function errors out.
   */
   rpc GetPodVMUUIDAnnotation(PodListenerRequest) returns (PodListenerResponse) {}

   /*
    * GetHostAnnotation gets the annotation value by querying the API server referring to the annotation key
    * and the host specified in the HostAnnotationRequest
    */
   rpc GetHostAnnotation(HostAnnotationRequest) returns (HostAnnotationResponse) {}

   /*
    * Placement API in PlacePersistenceVolumeClaim selects target storage pool to place the given PVC based on its profile and the topology information.
    * If the given PVC should not be handled by PlacePersistenceVolumeClaim like on vSAN or SPBM based cases, this API is a no-op and returns immediately with PVCPlacementRequest.placeSuccess set to true
    * If the PVC has a mapped storage pool, PlacePersistenceVolumeClaim return true
    * If the placement is successful, the PVC will be annotated with the selected storage pool and the PVCPlacementRequest.placeSuccess is set to true.
    * For unsuccessful placement, the PVCPlacementRequest.placeSuccess will be set to false
    */
   rpc PlacePersistenceVolumeClaim(PVCPlacementRequest) returns (PVCPlacementResponse) {}

   /*
    * To decommission a vSAN Direct datastore we need to migrate all the PSP volumes to other vSAN Direct datastores mounted on the same host.
    * GetStorageVMotionPlan creates a storage vMotion plan as a map where keys are PVs residing in the specified vSAN Direct Datastore
    * and values are other vSAN Direct Datastores into which the PV should be migrated.
    *
    * The outcome of the below service can be one of the two below:
    * 1. All the PSP PVs are mapped to a corresponding datastore. We return storage vMotion plan as response with no error.
    * 2. Some (or all) of the PSP PVs cannot be mapped (may be due to lack of capacity). We return with
    *    appropriate error and return vMotion plan as nil.
    */
   rpc GetStorageVMotionPlan(StorageVMotionRequest) returns (StorageVMotionResponse) {}
}

message PodListenerRequest {
   // The volumeID that needs to be attached to the node. 
   string volumeID = 1;

   // Name of the node where the Pod is running.
   string nodeName = 2;
}

message PodListenerResponse {
   // VM UUID annotation of the pod.
   string vmuuidAnnotation = 1;
}

message HostAnnotationRequest {
    // Name of the host
    string hostName = 1;
    // Name of the annotation key of interest
    string annotationKey = 2;
}

message HostAnnotationResponse {
    // Value of the annotation key on the node `hostName`
    string annotationValue = 2;
}

message PVCPlacementRequest {
    // Name of the PVC to place
    string name = 1;
    // Namespace of the PVC to place
    string namespace = 2;
    // Topology in AccessibilityRequirements to place a PVC
    csi.v1.TopologyRequirement accessibility_requirements = 3;
}

message PVCPlacementResponse {
    //Succeed or not for placement engine to find proper storage pool
    bool placeSuccess = 1;
}

message StorageVMotionRequest {
    // name of the Storage-Pool
    string storage_pool_name = 1;
    // Type of maintenance mode, either "ensureAccessibility"/"evacuateAll".
    string maintenance_mode = 2;
}

message StorageVMotionResponse {
    // svMotion plan is returned to caller as a map of PV name to StoragePool name
    map<string, string> sv_motion_plan = 1;
}
