doc: endpoints

doc/blockstore/endpoints/endpoints.md

@@ -0,0 +1,37 @@
+# purpose
+
+Endpoint is an abstraction for interaction with existing volumes.
+StartEndpoint creates unix socket which is used for communication
+between nbs server and client to configure 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 endpoints can be persistent if Persistent flag is set in StartEndpoint.
+NBS server can use [file storage](https://github.com/ydb-platform/nbs/blob/main/cloud/storage/core/libs/endpoints/fs/fs_endpoints.h) or [keyring storage](https://github.com/ydb-platform/nbs/blob/main/cloud/storage/core/libs/endpoints/keyring/keyring_endpoints.h) to store information about endpoints.
+
+NBS server restores all active persistence endpoints after server restart.
+
+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.