Add goal state data model doc (#106)

docs/visionary_design/goal_state_model.adoc

@@ -1 +1,202 @@
-= Goal State Data Model
+= Goal State Data Model
+Liguang Xie <lxie@futurewei.com>
+v0.1, 2019-10-15
+:toc: right
+
+=== Overview
+
+This goal state data model is mainly used for communication channel between Regional Controller and Host Agent.
+It support programming of groups of network resources to the same host in one message.
+The resource grouping could have various combinations including:
+
+* Multiple resource instances (e.g., 100 ports for the same host)
+* Multiple resource types (e.g., security group + port)
+* Multiple resource operation types (e.g., security group update + port creation)
+* Across VPC and subnet boundaries (security group update in VPC 1 + port creation in VPC 2)
+
+
+=== Messaging APIs
+
+*src/schema/proto3/goalstateprovisioner.proto*
+
+[source,java]
+------------------------------------------------------------
+syntax = "proto3";
+
+package alcorcontroller;
+
+option java_package = "com.futurewei.alcor.controller.service";
+
+import "common.proto";
+import "goalstate.proto";
+
+service GoalStateProvisioner {
+
+    // Push a group of network resource states
+    //
+    // Input: a GoalState object consists of a list of operation requests, and each request contains an operation type and a resource configuration
+    // Results consist of a list of operation statuses, and each status is a response to one operation request in the input
+    //
+    // Note: It is a NoOps for Control Agents when the operation type is INFO or GET.
+    //       Use RetrieveNetworkResourceStates for state query.
+    rpc PushNetworkResourceStates (GoalState) returns (GoalStateOperationReply) {
+    }
+
+    // Retrieve a group of network resource states (stored as a steam of GoalState objects)
+    rpc RetrieveNetworkResourceStates (GoalStateRequest) returns (stream GoalState) {
+    }
+}
+------------------------------------------------------------
+
+
+=== Message Format
+
+* Goal state message.
+The goal state message allows any combination of VpcState, SubnetState, PortState and SecurityGroupState, and grouping of them.
+For example, one message could consists of one subnet state update with 1000 ports creation to a data-plane switch, or two VPC update to a single VM/container host.
+
+*src/schema/proto3/goalstate.proto*
+
+[source,java]
+------------------------------------------------------------
+syntax = "proto3";
+
+package alcorcontroller;
+
+option java_package = "com.futurewei.alcor.controller.schema";
+
+import "vpc.proto";
+import "subnet.proto";
+import "port.proto";
+import "securitygroup.proto";
+
+message GoalState {
+    repeated VpcState vpc_states = 1;
+    repeated SubnetState subnet_states = 2;
+    repeated PortState port_states = 3;
+    repeated SecurityGroupState security_group_states = 4;
+}
+------------------------------------------------------------
+
+* VpcState message.
+OperationType includes CREATE, UPDATE, GET, DELETE, INFO, FINALIZE, CREATE_UPDATE_SWTICH, CREATE_UPDATE_ROUTER to cover various scenarios in network resource CURD operations.
+
+*src/schema/proto3/vpc.proto*
+
+[source,java]
+------------------------------------------------------------
+syntax = "proto3";
+
+package alcorcontroller;
+
+option java_package = "com.futurewei.alcor.controller.schema";
+option java_outer_classname = "Vpc";
+
+import "common.proto";
+
+message VpcState {
+    OperationType operation_type = 1;
+    VpcConfiguration configuration = 2;
+}
+
+------------------------------------------------------------
+
+
+* VpcConfiguration message
+
+[source,java]
+------------------------------------------------------------
+syntax = "proto3";
+
+package alcorcontroller;
+
+option java_package = "com.futurewei.alcor.controller.schema";
+option java_outer_classname = "Vpc";
+
+import "common.proto";
+
+message VpcConfiguration {
+    int32 version = 1;
+
+    string project_id = 2;
+    string id = 3;
+    string name = 4;
+    string cidr = 5;
+    int64 tunnel_id = 6;
+
+    message SubnetId {
+        string id = 1;
+    }
+
+    message Route {
+        string destination = 1;
+        string next_hop = 2;
+    }
+
+    message TransitRouter {
+        string vpc_id = 1;
+        string ip_address = 2;
+        string mac_address = 3;
+    }
+
+    repeated SubnetId subnet_ids = 7;
+    repeated Route routes = 8;
+    repeated TransitRouter transit_routers = 9;
+}
+------------------------------------------------------------
+
+
+* Common enum including ResourceType and OperationType
+
+*src/schema/proto3/common.proto*
+
+[source,java]
+------------------------------------------------------------
+
+syntax = "proto3";
+
+package alcorcontroller;
+
+option java_package = "com.futurewei.alcor.controller.schema";
+option java_outer_classname = "Common";
+
+enum ResourceType {
+    VPC = 0;
+    SUBNET = 1;
+    PORT = 2;
+    SECURITYGROUP = 3;
+}
+
+enum OperationType {
+    CREATE = 0;
+    UPDATE = 1;
+    GET = 2;
+    DELETE = 3;
+    INFO = 4;
+    FINALIZE = 5;
+    CREATE_UPDATE_SWITCH = 6;
+    CREATE_UPDATE_ROUTER = 7;
+    CREATE_UPDATE_GATEWAY = 8;
+}
+
+enum OperationStatus {
+    SUCCESS = 0;
+    FAILURE = 1;
+    INVALID_ARG = 2;
+}
+
+enum EtherType {
+    IPV4 = 0;
+    IPV6 = 1;
+}
+
+enum Protocol {
+    TCP = 0;
+    UDP = 1;
+    ICMP = 2;
+    HTTP = 3;
+    ARP = 4;
+}
+------------------------------------------------------------
+
+* Please refer to src/schema/proto3/* for more message format.