From 1693e94b13da190145a3826b4c7cc477f208358a Mon Sep 17 00:00:00 2001 From: Anton Myagkov Date: Wed, 13 Nov 2024 15:01:45 +0000 Subject: [PATCH] doc: endpoints --- doc/blockstore/endpoints/endpoints.md | 37 +++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 doc/blockstore/endpoints/endpoints.md diff --git a/doc/blockstore/endpoints/endpoints.md b/doc/blockstore/endpoints/endpoints.md new file mode 100644 index 00000000000..fe81619ecd6 --- /dev/null +++ b/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.