doc: endpoints

doc/blockstore/endpoints/endpoints.md

@@ -0,0 +1,35 @@
+# purpose
+
+Endpoint is an abstraction for interaction with existing volumes.
+StartEndpoint creates unix socket which is used for communitcation
+between nbs server and client to confgiure specified device(e.g. nbd/vhost)
+
+# grpc api
+
+Available methods:
+
+1. ListEndpoints
+2. StartEndpoint
+3. StopEndpoint
+4. DescribeEndpoint
+5. RefreshEndpoint - reconfigure device with new volume size
+6. KickEndpoint - implementation of this method calls StartEndpoint for existing endpoint.
+keyring id is used to find the endpoint.
+
+* UnixSocketPath is mandatory parameter to start new endpoint.
+* UnixSocketPath is used as an "endpoint id" for
+StopEndpoint, DescribeEndpoint, RefreshEndpoint methods
+
+[proto file](https://github.com/ydb-platform/nbs/blob/main/cloud/blockstore/public/api/protos/endpoints.proto)
+
+# restoring endpoints
+
+NBS server restores all active endpoints in case of server restart.
+Information about active endpoints are stored in the file or keyring.
+
+ListEndpoints response contains additional flag EndpointsWereRestored to specify
+that endpoints are restored already.
+
+# mount conflicts
+It is not possible to start two different Read-Write endpoints for the same volume.
+In this case StartEndpoint returns MOUNT_CONFLICT error.