cloud/blockstore/config/disk.proto - main - githubmirror/nbs

cloud/blockstore/config/disk.proto
435 строк14 KB
Pavel Misko
[NBS] Add Disk Agent journalled device tcp endpoint (#6502)
20 июл 2026, 12:37
20 июл 2026, 12:37877425c
syntax = "proto2";

import "cloud/blockstore/config/rdma.proto";
import "cloud/blockstore/config/spdk.proto";
import "cloud/blockstore/public/api/protos/disk.proto";

package NCloud.NBlockStore.NProto;

option go_package = "github.com/ydb-platform/nbs/cloud/blockstore/config";

////////////////////////////////////////////////////////////////////////////////
// Device erase method

enum EDeviceEraseMethod
{
    DEVICE_ERASE_METHOD_ZERO_FILL = 0;
    DEVICE_ERASE_METHOD_USER_DATA_ERASE = 1;
    DEVICE_ERASE_METHOD_CRYPTO_ERASE = 2;
    DEVICE_ERASE_METHOD_NONE = 3;
    DEVICE_ERASE_METHOD_DEALLOCATE = 4;
}

////////////////////////////////////////////////////////////////////////////////
// Backends for Disk agent.

enum EDiskAgentBackendType
{
    DISK_AGENT_BACKEND_SPDK = 0;
    DISK_AGENT_BACKEND_AIO = 1;
    DISK_AGENT_BACKEND_NULL = 2;
    DISK_AGENT_BACKEND_IO_URING = 3;
    DISK_AGENT_BACKEND_IO_URING_NULL = 4;
}

////////////////////////////////////////////////////////////////////////////////
// The policy of critical events reporting when chaos generates an error.

enum EChaosCritEventReportingPolicy
{
    CCERP_FIRST_ERROR = 0;
    CCERP_ALL_ERRORS = 1;
}

////////////////////////////////////////////////////////////////////////////////

message TMemoryDeviceArgs
{
    optional string Name = 1;
    optional uint64 BlocksCount = 2;
    optional uint32 BlockSize = 3;

    // Device identifier. Must be globally unique.
    optional string DeviceId = 4;

    // Device pool name.
    optional string PoolName = 5;
}

////////////////////////////////////////////////////////////////////////////////

message TFileDeviceArgs
{
    optional string Path = 1;
    optional uint32 BlockSize = 2;

    // Device identifier. Must be globally unique.
    optional string DeviceId = 3;

    // Device pool name.
    optional string PoolName = 4;

    // Serial number. For caching purposes.
    optional string SerialNumber = 5;

    // Data offset relative to the beginning of the file.
    optional uint64 Offset = 6;
    // File size override.
    optional uint64 FileSize = 7;

    // Device model.
    optional string DeviceModel = 8;
}

////////////////////////////////////////////////////////////////////////////////

message TNVMeDeviceArgs
{
    optional string BaseName = 1;
    optional string TransportId = 2;

    // Device identifier. Must be globally unique.
    repeated string DeviceIds = 3;

    // Device pool name.
    optional string PoolName = 4;
}

////////////////////////////////////////////////////////////////////////////////

message TNVMeTargetArgs
{
    optional string Nqn = 1;
    repeated string TransportIds = 2;
}

////////////////////////////////////////////////////////////////////////////////

message TStorageDiscoveryConfig
{
    enum EHashScheme
    {
        // Uses the device number to calculate the hash of the device id.
        HS_LEGACY = 0;

        // Uses the full path to the device to calc hash for device id.
        HS_FULL_PATH = 1;
    }

    message TLayout
    {
        // Reserved space at the beginning of the file.
        optional uint64 HeaderSize = 1;

        // Space between devices.
        optional uint64 DevicePadding = 2;

        // The size of each device.
        optional uint64 DeviceSize = 3;
    };

    message TPoolConfig
    {
        optional string PoolName = 1;

        // The minimum allowed size of a device.
        // If MinSize == 0 and Layout is specified then the minimum allowed size
        // is Layout.HeaderSize + Layout.DeviceSize.
        optional uint64 MinSize = 2;

        // The maximum allowed size of a device. If not specified, then the
        // maximum size of the device is not limited.
        optional uint64 MaxSize = 3;

        optional TLayout Layout = 4;

        // Used to calculate the device ids.
        optional string HashSuffix = 5;

        // The maximum number of devices.
        optional uint32 MaxDeviceCount = 6;

        // Block size.
        optional uint32 BlockSize = 7;

        // Device id hash scheme.
        optional EHashScheme HashScheme = 8;
    }

    message TPathConfig
    {
        // The path regexp (e.g. /dev/disk/by-partlabel/NVMECOMPUTE([0-9]{2}))
        // it must have at least one group of digits that will be used to
        // calculate device ids.
        optional string PathRegExp = 1;

        // The maximum number of devices that can be discovered by a given path.
        optional uint32 MaxDeviceCount = 2;

        repeated TPoolConfig PoolConfigs = 3;

        // Default block size.
        optional uint32 BlockSize = 4;
    }

    repeated TPathConfig PathConfigs = 1;
}

////////////////////////////////////////////////////////////////////////////////

message TDiskAgentThrottlingConfig
{
    // Host limits.
    optional string InfraThrottlingConfigPath = 1;
    optional uint32 DefaultNetworkMbitThroughput = 2;

    // Fraction of network throughput utilized for migrations and shadow
    // disk fill.
    optional double DirectCopyBandwidthFraction = 3;

    // Maximum bandwidth for one device in MiB/s.
    optional uint64 MaxDeviceBandwidthMiB = 4;
}

////////////////////////////////////////////////////////////////////////////////

message TChaosConfig
{
    // The policy of critical events reporting when chaos generates an error.
    optional EChaosCritEventReportingPolicy CritEventReportingPolicy = 1;

    // The probability of getting an error on the request start and finish.
    optional double ChaosProbability = 2;

    // Error codes that the chaos will generate. When empty E_REJECTED is used.
    repeated uint32 ErrorCodes = 3;

    // The probability of data corruption when responding with an error.
    optional double DataDamageProbability = 4;

    // The probability of a response immediately upon receipt of the request.
    optional double ImmediateReplyProbability = 5;
}

////////////////////////////////////////////////////////////////////////////////

message TDiskAgentConfig
{
    optional bool Enabled = 1;

    // Attached devices.
    repeated TMemoryDeviceArgs MemoryDevices = 2;
    repeated TFileDeviceArgs FileDevices = 3;
    repeated TNVMeDeviceArgs NvmeDevices = 4;

    // NVMe-oF target setup.
    optional TNVMeTargetArgs NvmeTarget = 5;

    // Disk Agent Id which is used for registration in Disk registry.
    optional string AgentId = 6;

    // Allocator.
    optional uint32 PageSize = 7;
    optional uint32 MaxPageCount = 8;
    optional uint32 PageDropSize = 9;

    // Timeout (in milliseconds) before retry register agent at Disk Registry.
    optional uint32 RegisterRetryTimeout = 10;

    // Backend to perform IO.
    optional EDiskAgentBackendType Backend = 11;

    // If set, i/o won't work without acquire.
    optional bool AcquireRequired = 12;

    // Device secure erase method.
    optional EDeviceEraseMethod DeviceEraseMethod = 13;

    // Devices can be acquired by another writer after this time interval.
    optional uint32 ReleaseInactiveSessionsTimeout = 14;

    // Open device file without directIO flag. Used with AIO backend & RAM drive.
    optional bool DirectIoFlagDisabled = 15;

    // Agent generation number which is used for registration in Disk registry.
    optional uint64 SeqNumber = 16;

    // Use disk-agent in dedicated process.
    optional bool DedicatedDiskAgent = 17;

    // Timeout (in seconds) before aborting NVM format command.
    optional uint32 SecureEraseTimeout = 18;

    // SPDK config used by dedicated disk agent.
    optional TSpdkEnvConfig SpdkEnvConfig = 19;

    // RDMA target config.
    optional TRdmaTarget RdmaTarget = 20;   // deprecated

    // Use flock to lock devices on agent initialization.
    optional bool DeviceLockingEnabled = 21;

    // Disables random device block reads to check device health (background
    // device scrubbing).
    optional bool DeviceHealthCheckDisabled = 22;

    // After this interval (in milliseconds) disk agent will return E_IO error
    // for the request.
    optional uint32 DeviceIOTimeout = 23;

    // Disables device IO timeout -> E_IO error conversion logic.
    optional bool DeviceIOTimeoutsDisabled = 24;

    // During shutdown, the disk agent will wait for I/O requests to complete
    // during this interval (in milliseconds).
    optional uint32 ShutdownTimeout = 25;

    // Storage discovery config.
    optional TStorageDiscoveryConfig StorageDiscoveryConfig = 26;

    // The path where Disk Agent will store the cached config.
    optional string CachedConfigPath = 27;

    // The path where Disk Agent will store active sessions.
    optional string CachedSessionsPath = 28;

    // Flag which indicates that the agent was launched as a temporary one
    // during blue-green deployment.
    optional bool TemporaryAgent = 29;

    // Offload protobuf parsing of IO requests to a special actor.
    optional uint32 IOParserActorCount = 30;

    // Offload the parsing of all IO requests (by default offloads only write requests).
    optional bool OffloadAllIORequestsParsingEnabled = 31;

    // When enabled, the Disk Agents checks that devices were found either in
    // the "CachedConfigPath", in the "FileDevices", or with the
    // "StorageDiscoveryConfig". If none were found, the process falls in the
    // deep idle state without even registering in the NodeBroker.
    // WARNING: CMS configs can only be retrieved after registering in the
    // NodeBroker. Enabling this option completely disables them if there were
    // no devices found.
    optional bool DisableNodeBrokerRegistrationOnDevicelessAgent = 32;

    // Max. count of concurrently processing operations (io_setup).
    optional uint32 MaxAIOContextEvents = 33;

    // Number of paths per each FileIOService.
    // 0 means that only one IO service will be created.
    // 1 means that one IO service per file path will be created.
    // 2 means that one IO service will be created for every two file paths.
    // etc.
    optional uint32 PathsPerFileIOService = 34;

    // List of device UUIDs with suspended I/O.
    // I/O operations for such a device will result in errors.
    // Is used for the config cache file only.
    repeated string DevicesWithSuspendedIO = 35;

    // Disable devices that have been recognized as broken by the DR
    optional bool DisableBrokenDevices = 36;

    // Path to serial number mapping. For testing purposes only.
    message TPathToSerialNumber
    {
        required string Path = 1;
        required string SerialNumber = 2;
    }

    repeated TPathToSerialNumber PathToSerialNumberMapping = 37;

    // Settings for traffic shaping.
    optional TDiskAgentThrottlingConfig ThrottlingConfig = 38;

    // If enabled, IOParserActor allocates a storage buffer and copies the
    // request data into it.
    optional bool IOParserActorAllocateStorageEnabled = 39;

    // Max secure erase can be run in parallel.
    // For devices with the same name, only one secure erase is run at a time.
    optional uint32 MaxParallelSecureErasesAllowed = 40;

    // Use a separate thread to submit requests to all FileIOServices.
    optional bool UseLocalStorageSubmissionThread = 41;

    // When a volume with a higher generation sends an Acquire request,
    // we kick out the old client (from older generations)
    // and acquire a device for the new client.
    optional bool KickOutOldClientsEnabled = 42;

    // Use one submission thread per AIO service.
    optional bool UseOneSubmissionThreadPerAIOServiceEnabled = 43;

    // Enables data integrity validation for the DR-based disks.
    // See "EnableDataIntegrityClient" in server.proto for more details.
    // Deprecated. Use "DataIntegrityValidationPolicyForDrBasedDisks" instead.
    optional bool EnableDataIntegrityValidationForDrBasedDisks = 44;

    // DANGER! It is used to generate errors during chaos testing.
    optional TChaosConfig ChaosConfig = 45;

    // Allows to control data integrity validation for DR-based disks.
    optional EDataIntegrityValidationPolicy DataIntegrityValidationPolicyForDrBasedDisks = 46;

    // The ratio of the validated blocks after deallocation.
    // 1000 means every thousandth or 0.1%.
    optional uint32 ValidatedBlocksRatio = 47;

    // Timeout (in milliseconds) before aborting admin command.
    optional uint32 NVMeAdminCmdTimeout = 48;

    // Listen address for the Journalled Device TCP server.
    // If set, the Disk Agent starts a TCP server to handle Journalled Device requests.
    optional string JournalledDeviceTcpServerListenAddress = 49;
}

////////////////////////////////////////////////////////////////////////////////

message TDiskAgentDeviceSession
{
    // Owner of the session.
    optional string ClientId = 1;

    // List of device UUIDs.
    repeated string DeviceIds = 2;

    // Access mode.
    optional bool ReadOnly = 3;

    // MountSeqNumber from volume state.
    optional uint64 MountSeqNumber = 4;

    // Disk id.
    optional string DiskId = 5;

    // Volume generation.
    optional uint32 VolumeGeneration = 6;

    // Last activity timestamp of the session (in microseconds).
    optional uint64 LastActivityTs = 7;
};

message TDiskAgentDeviceSessionCache
{
    repeated TDiskAgentDeviceSession Sessions = 1;
}

////////////////////////////////////////////////////////////////////////////////

message TDiskRegistryProxyConfig
{
    optional uint64 Owner = 1;
    optional uint64 OwnerIdx = 2;

    // Timeout (in milliseconds) for lookup/create DR tablet request.
    optional uint32 LookupTimeout = 3;

    // Timeout (in milliseconds) for retrying a retriable error for
    // lookup/create DR tablet request.
    optional uint32 RetryLookupTimeout = 4;

    // Disk registry proxy will not ask Hive for tablet id when this is set.
    optional uint64 DiskRegistryTabletId = 5;

}