From 41ed087328bdc04e5a071df99e7f62f8bbf88221 Mon Sep 17 00:00:00 2001 From: Alexander Ding Date: Mon, 17 Oct 2022 18:40:07 +0000 Subject: [PATCH] doc: document API group interface methods --- pkg/disk/disk.go | 15 +++++++++++++++ pkg/filesystem/filesystem.go | 18 +++++++++++++++++- pkg/iscsi/iscsi.go | 26 ++++++++++++++++++++++++++ pkg/smb/smb.go | 3 +++ pkg/system/system.go | 11 +++++++++++ pkg/volume/volume.go | 24 ++++++++++++++++++++++++ 6 files changed, 96 insertions(+), 1 deletion(-) diff --git a/pkg/disk/disk.go b/pkg/disk/disk.go index 76336513..8095e8f4 100644 --- a/pkg/disk/disk.go +++ b/pkg/disk/disk.go @@ -17,13 +17,28 @@ type Interface interface { DiskStats(context.Context, *DiskStatsRequest) (*DiskStatsResponse, error) GetAttachState(context.Context, *GetAttachStateRequest) (*GetAttachStateResponse, error) GetDiskNumberByName(context.Context, *GetDiskNumberByNameRequest) (*GetDiskNumberByNameResponse, error) + // GetDiskState gets the offline/online state of a disk. GetDiskState(context.Context, *GetDiskStateRequest) (*GetDiskStateResponse, error) + + // GetDiskStats returns the stats of a disk (currently it returns the disk size). GetDiskStats(context.Context, *GetDiskStatsRequest) (*GetDiskStatsResponse, error) + + // ListDiskIDs returns a map of DiskID objects where the key is the disk number. ListDiskIDs(context.Context, *ListDiskIDsRequest) (*ListDiskIDsResponse, error) + + // ListDiskLocations returns locations of all + // disk devices enumerated by the host. ListDiskLocations(context.Context, *ListDiskLocationsRequest) (*ListDiskLocationsResponse, error) + + // PartitionDisk initializes and partitions a disk device with the GPT partition style + // (if the disk has not been partitioned already) and returns the resulting volume device ID. PartitionDisk(context.Context, *PartitionDiskRequest) (*PartitionDiskResponse, error) + + // Rescan refreshes the host's storage cache. Rescan(context.Context, *RescanRequest) (*RescanResponse, error) SetAttachState(context.Context, *SetAttachStateRequest) (*SetAttachStateResponse, error) + + // SetDiskState sets the offline/online state of a disk. SetDiskState(context.Context, *SetDiskStateRequest) (*SetDiskStateResponse, error) } diff --git a/pkg/filesystem/filesystem.go b/pkg/filesystem/filesystem.go index fdddec6b..0e9b2e0c 100644 --- a/pkg/filesystem/filesystem.go +++ b/pkg/filesystem/filesystem.go @@ -12,14 +12,31 @@ type Filesystem struct { } type Interface interface { + // CreateSymlink creates a symbolic link called target_path that points to source_path + // in the host filesystem (target_path is the name of the symbolic link created, + // source_path is the existing path). CreateSymlink(context.Context, *CreateSymlinkRequest) (*CreateSymlinkResponse, error) IsMountPoint(context.Context, *IsMountPointRequest) (*IsMountPointResponse, error) + + // IsSymlink checks if a given path is a symlink. IsSymlink(context.Context, *IsSymlinkRequest) (*IsSymlinkResponse, error) LinkPath(context.Context, *LinkPathRequest) (*LinkPathResponse, error) + + // Mkdir creates a directory at the requested path in the host filesystem. Mkdir(context.Context, *MkdirRequest) (*MkdirResponse, error) + + // PathExists checks if the requested path exists in the host filesystem. PathExists(context.Context, *PathExistsRequest) (*PathExistsResponse, error) + + // PathValid checks if the given path is accessible. PathValid(context.Context, *PathValidRequest) (*PathValidResponse, error) + + // Rmdir removes the directory at the requested path in the host filesystem. + // This may be used for unlinking a symlink created through CreateSymlink. Rmdir(context.Context, *RmdirRequest) (*RmdirResponse, error) + + // RmdirContents removes the contents of a directory in the host filesystem. + // Unlike Rmdir it won't delete the requested path, it'll only delete its contents. RmdirContents(context.Context, *RmdirContentsRequest) (*RmdirContentsResponse, error) } @@ -50,7 +67,6 @@ func (f *Filesystem) PathExists(ctx context.Context, request *PathExistsRequest) }, err } -// PathValid checks if the given path is accessible. func (f *Filesystem) PathValid(ctx context.Context, request *PathValidRequest) (*PathValidResponse, error) { klog.V(2).Infof("Request: PathValid with path %q", request.Path) valid, err := f.hostAPI.PathValid(request.Path) diff --git a/pkg/iscsi/iscsi.go b/pkg/iscsi/iscsi.go index d31bd6e5..8b0ba419 100644 --- a/pkg/iscsi/iscsi.go +++ b/pkg/iscsi/iscsi.go @@ -15,13 +15,39 @@ type IsCSI struct { } type Interface interface { + // AddTargetPortal registers an iSCSI target network address for later + // discovery. + // AddTargetPortal currently does not support selecting different NICs or + // a different iSCSI initiator (e.g a hardware initiator). This means that + // Windows will select the initiator NIC and instance on its own. AddTargetPortal(context.Context, *AddTargetPortalRequest) (*AddTargetPortalResponse, error) + + // ConnectTarget connects to an iSCSI Target ConnectTarget(context.Context, *ConnectTargetRequest) (*ConnectTargetResponse, error) + + // DisconnectTarget disconnects from an iSCSI Target DisconnectTarget(context.Context, *DisconnectTargetRequest) (*DisconnectTargetResponse, error) + + // DiscoverTargetPortal initiates discovery on an iSCSI target network address + // and returns discovered IQNs. DiscoverTargetPortal(context.Context, *DiscoverTargetPortalRequest) (*DiscoverTargetPortalResponse, error) + + // GetTargetDisks returns the disk addresses that correspond to an iSCSI + // target GetTargetDisks(context.Context, *GetTargetDisksRequest) (*GetTargetDisksResponse, error) + + // ListTargetPortal lists all currently registered iSCSI target network + // addresses. ListTargetPortals(context.Context, *ListTargetPortalsRequest) (*ListTargetPortalsResponse, error) + + // RemoveTargetPortal removes an iSCSI target network address registration. RemoveTargetPortal(context.Context, *RemoveTargetPortalRequest) (*RemoveTargetPortalResponse, error) + + // SetMutualChapSecret sets the default CHAP secret that all initiators on + // this machine (node) use to authenticate the target on mutual CHAP + // authentication. + // NOTE: This method affects global node state and should only be used + // with consideration to other CSI drivers that run concurrently. SetMutualChapSecret(context.Context, *SetMutualChapSecretRequest) (*SetMutualChapSecretResponse, error) } diff --git a/pkg/smb/smb.go b/pkg/smb/smb.go index 4ac2ff5d..12fc80f1 100644 --- a/pkg/smb/smb.go +++ b/pkg/smb/smb.go @@ -16,7 +16,10 @@ type Smb struct { } type Interface interface { + // NewSmbGlobalMapping creates an SMB mapping on the SMB client to an SMB share. NewSmbGlobalMapping(context.Context, *NewSmbGlobalMappingRequest) (*NewSmbGlobalMappingResponse, error) + + // RemoveSmbGlobalMapping removes the SMB mapping to an SMB share. RemoveSmbGlobalMapping(context.Context, *RemoveSmbGlobalMappingRequest) (*RemoveSmbGlobalMappingResponse, error) } diff --git a/pkg/system/system.go b/pkg/system/system.go index 8e08e122..88bfc817 100644 --- a/pkg/system/system.go +++ b/pkg/system/system.go @@ -12,9 +12,20 @@ type System struct { } type Interface interface { + // GetBIOSSerialNumber returns the device's serial number GetBIOSSerialNumber(context.Context, *GetBIOSSerialNumberRequest) (*GetBIOSSerialNumberResponse, error) + + // GetService queries a Windows service state GetService(context.Context, *GetServiceRequest) (*GetServiceResponse, error) + + // StartService starts a Windows service + // NOTE: This method affects global node state and should only be used + // with consideration to other CSI drivers that run concurrently. StartService(context.Context, *StartServiceRequest) (*StartServiceResponse, error) + + // StopService stops a Windows service + // NOTE: This method affects global node state and should only be used + // with consideration to other CSI drivers that run concurrently. StopService(context.Context, *StopServiceRequest) (*StopServiceResponse, error) } diff --git a/pkg/volume/volume.go b/pkg/volume/volume.go index 03d14164..5733f510 100644 --- a/pkg/volume/volume.go +++ b/pkg/volume/volume.go @@ -15,19 +15,43 @@ type Volume struct { type Interface interface { DismountVolume(context.Context, *DismountVolumeRequest) (*DismountVolumeResponse, error) + // FormatVolume formats a volume with NTFS. FormatVolume(context.Context, *FormatVolumeRequest) (*FormatVolumeResponse, error) + + // GetClosestVolumeIDFromTargetPath gets the closest volume id for a given target path + // by following symlinks and moving up in the filesystem, if after moving up in the filesystem + // we get to a DriveLetter then the volume corresponding to this drive letter is returned instead. GetClosestVolumeIDFromTargetPath(context.Context, *GetClosestVolumeIDFromTargetPathRequest) (*GetClosestVolumeIDFromTargetPathResponse, error) + + // GetDiskNumberFromVolumeID gets the disk number of the disk where the volume is located. GetDiskNumberFromVolumeID(context.Context, *GetDiskNumberFromVolumeIDRequest) (*GetDiskNumberFromVolumeIDResponse, error) GetVolumeDiskNumber(context.Context, *VolumeDiskNumberRequest) (*VolumeDiskNumberResponse, error) GetVolumeIDFromMount(context.Context, *VolumeIDFromMountRequest) (*VolumeIDFromMountResponse, error) + + // GetVolumeIDFromTargetPath gets the volume id for a given target path. GetVolumeIDFromTargetPath(context.Context, *GetVolumeIDFromTargetPathRequest) (*GetVolumeIDFromTargetPathResponse, error) + + // GetVolumeStats gathers total bytes and used bytes for a volume. GetVolumeStats(context.Context, *GetVolumeStatsRequest) (*GetVolumeStatsResponse, error) + + // IsVolumeFormatted checks if a volume is formatted. IsVolumeFormatted(context.Context, *IsVolumeFormattedRequest) (*IsVolumeFormattedResponse, error) + + // ListVolumesOnDisk returns the volume IDs (in \\.\Volume{GUID} format) for all volumes from a + // given disk number and partition number (optional) ListVolumesOnDisk(context.Context, *ListVolumesOnDiskRequest) (*ListVolumesOnDiskResponse, error) + + // MountVolume mounts the volume at the requested global staging path. MountVolume(context.Context, *MountVolumeRequest) (*MountVolumeResponse, error) + + // ResizeVolume performs resizing of the partition and file system for a block based volume. ResizeVolume(context.Context, *ResizeVolumeRequest) (*ResizeVolumeResponse, error) + + // UnmountVolume flushes data cache to disk and removes the global staging path. UnmountVolume(context.Context, *UnmountVolumeRequest) (*UnmountVolumeResponse, error) VolumeStats(context.Context, *VolumeStatsRequest) (*VolumeStatsResponse, error) + + // WriteVolumeCache write volume cache to disk. WriteVolumeCache(context.Context, *WriteVolumeCacheRequest) (*WriteVolumeCacheResponse, error) }