[Storage] az storage share/directory/file: support NFS FileShares, add az storage file hard-link create (#31050)

* update storage multiapi to 1.4.0, fileshare to api version 2025-05-05

* fix version in setup

* add nfs file share support, add `az storage file hard-link create`

* lint, style

Author: calvinhzy

src/azure-cli-core/azure/cli/core/profiles/_shared.py

@@ -216,7 +216,7 @@ def default_api_version(self):
         ResourceType.DATA_STORAGE: '2018-11-09',
         ResourceType.DATA_STORAGE_BLOB: '2022-11-02',
         ResourceType.DATA_STORAGE_FILEDATALAKE: '2021-08-06',
-        ResourceType.DATA_STORAGE_FILESHARE: '2024-08-04',
+        ResourceType.DATA_STORAGE_FILESHARE: '2025-05-05',
         ResourceType.DATA_STORAGE_QUEUE: '2018-03-28',
         ResourceType.DATA_COSMOS_TABLE: '2017-04-17',
         ResourceType.MGMT_SERVICEBUS: '2022-10-01-preview',

src/azure-cli/azure/cli/command_modules/storage/_help.py

@@ -1800,6 +1800,11 @@
 helps['storage directory create'] = """
 type: command
 short-summary: Create a new directory under the specified share or parent directory.
+examples:
+  - name: Create a new directory under the specified NFS share with file-mode, owner, group
+    text: |
+        az storage directory create --account-name mystorageaccount --name dir --share-name myshare
+        --file-mode rwxr--r-- --owner 1 --group 2
 """
 
 helps['storage directory delete'] = """
@@ -1914,7 +1919,7 @@
 
 helps['storage file'] = """
 type: group
-short-summary: Manage file shares that use the SMB 3.0 protocol.
+short-summary: Manage file shares.
 """
 
 helps['storage file copy'] = """
@@ -1947,6 +1952,12 @@
     - name: Copy a file asynchronously from file snapshot to destination storage account with sas token.
       text: |
         az storage file copy start --source-account-name srcaccount --source-account-key 00000000 --source-path <srcpath-to-file> --source-share srcshare --file-snapshot "2020-03-02T13:51:54.0000000Z" --destination-path <destpath-to-file> --destination-share destshare --account-name destaccount --sas-token <destination-sas>
+    - name: Copy a file with the source file-mode, group, owner.
+      text: |
+        az storage file copy start --source-account-name srcaccount --source-path srcpath --source-share srcshare --destination-path dstpath --destination-share dstshare --owner-copy-mode Source --file-mode-copy-mode Source
+    - name: Copy a file with the overridden file-mode, group, owner.
+      text: |
+        az storage file copy start --source-account-name srcaccount --source-path srcpath --source-share srcshare --destination-path dstpath --destination-share dstshare --owner-copy-mode Override --file-mode-copy-mode Override --file-mode rw-rw-rw- --owner 4 --group 5
 """
 
 helps['storage file copy start-batch'] = """
@@ -2165,12 +2176,12 @@
 
 helps['storage file upload'] = """
 type: command
-short-summary: Upload a file to a share that uses the SMB 3.0 protocol.
+short-summary: Upload a file to a share.
 long-summary: Creates or updates an Azure file from a source path with automatic chunking and progress notifications.
 examples:
   - name: Upload to a local file to a share.
     text: az storage file upload -s MyShare --source /path/to/file
-  - name: Upload a file to a share that uses the SMB 3.0 protocol. (autogenerated)
+  - name: Upload a file to a share.
     text: |
         az storage file upload --account-key 00000000 --account-name MyStorageAccount --path path/file.txt --share-name MyShare --source /path/to/file
     crafted: true
@@ -2994,6 +3005,9 @@
     text: |
         az storage share create --account-name MyAccount --name MyFileShare
     crafted: true
+  - name: Creates a new share under the specified account for NFS.
+    text: |
+        az storage share create --account-name MyAccount --name MyFileShare --protocol nfs
 """
 
 helps['storage share exists'] = """
@@ -3161,3 +3175,17 @@
 type: group
 short-summary: Manage shared access policies of a storage table.
 """
+
+helps['storage file hard-link'] = """
+    type: group
+    short-summary: Manage storage file hard-link.
+"""
+
+helps['storage file hard-link create'] = """
+    type: command
+    short-summary: NFS only. Create a hard link to the file specified by path.
+    examples:
+      - name: Create a hard link to an NFS file specified by path.
+        text: |
+            az storage file hard-link create --account-name MyAccount --share-name share --path link_path --target original_path
+"""

src/azure-cli/azure/cli/command_modules/storage/_params.py

@@ -1778,6 +1778,10 @@ def load_arguments(self, _):  # pylint: disable=too-many-locals, too-many-statem
                                          'default.')
         c.argument('quota', type=int, help='Specifies the maximum size of the share, in gigabytes. Must be greater '
                                            'than 0, and less than or equal to 5TB (5120).')
+        t_share_protocols_type = self.get_sdk('_models#ShareProtocols',
+                                              resource_type=ResourceType.DATA_STORAGE_FILESHARE)
+        c.extra('protocols', options_list=['--protocol'], arg_type=get_enum_type(t_share_protocols_type),
+                help='The protocol to enable for the share.')
 
     with self.argument_context('storage share url') as c:
         c.extra('unc', action='store_true', help='Output UNC network path.')
@@ -1941,6 +1945,16 @@ def load_arguments(self, _):  # pylint: disable=too-many-locals, too-many-statem
 
     with self.argument_context('storage directory create') as c:
         c.argument('fail_on_exist', help='Throw an exception if the directory already exists.')
+        c.extra('file_mode',
+                help='Only applicable to NFS Directory. The mode permissions to be set on the directory. '
+                     'Symbolic (rwxrw-rw-) is supported. The sticky bit is also supported and its represented '
+                     'either by the letter t or T in the final character-place depending on whether the execution '
+                     'bit for the others category is set or unset respectively, absence of t or T indicates sticky '
+                     'bit not set."')
+        c.extra('owner', help='Only applicable to NFS Directory. The owner user identifier (UID) to be set on the '
+                              'directory. The default value is 0 (root).')
+        c.extra('group', help='Only applicable to NFS Directory. The owner group identifier (GID) to be set on the '
+                              'directory. The default value is 0 (root group).')
 
     with self.argument_context('storage directory delete') as c:
         c.argument('fail_not_exist', help='Throw an exception if the directory does not exist.')
@@ -1969,6 +1983,33 @@ def load_arguments(self, _):  # pylint: disable=too-many-locals, too-many-statem
                 help='Metadata in space-separated key=value pairs. This overwrites any existing metadata.',
                 validator=validate_metadata)
         c.extra('timeout', help='Request timeout in seconds. Applies to each call to the service.', type=int)
+        c.extra('file_mode',
+                help='The mode permissions to be set on the file. Only applicable to NFS Files. '
+                     'Only work together with parameter `--file-mode-copy-mode Override`. '
+                     'Symbolic (rwxrw-rw-) is supported. '
+                     'The sticky bit is also supported and its represented '
+                     'either by the letter t or T in the final character-place depending on whether the execution '
+                     'bit for the others category is set or unset respectively, absence of t or T indicates sticky '
+                     'bit not set."')
+        c.extra('owner', help='Only applicable to NFS Files. Only work together with parameter '
+                              '`--owner-copy-mode Override`. The owner user identifier (UID) '
+                              'to be set on the directory. The default value is 0 (root).')
+        c.extra('group', help='Only applicable to NFS Files. Only work together with parameter '
+                              '`--owner-copy-mode Override`. The owner group identifier (GID) '
+                              'to be set on the directory. The default value is 0 (root group).')
+        t_file_mode_copy_mode_type = self.get_sdk('_generated.models._azure_file_storage_enums#ModeCopyMode',
+                                                  resource_type=ResourceType.DATA_STORAGE_FILESHARE)
+        c.extra('file_mode_copy_mode',
+                arg_type=get_enum_type(t_file_mode_copy_mode_type),
+                help='Only applicable to NFS Files. Applicable only when the copy source is a File. '
+                     'Determines the copy behavior of the mode bits of the destination file. '
+                     'If not populated, the destination file will have the default File Mode.')
+        t_owner_copy_mode_type = self.get_sdk('_generated.models._azure_file_storage_enums#OwnerCopyMode',
+                                              resource_type=ResourceType.DATA_STORAGE_FILESHARE)
+        c.extra('owner_copy_mode', arg_type=get_enum_type(t_owner_copy_mode_type),
+                help='Only applicable to NFS Files. Applicable only when the copy source is a File. '
+                     'Determines the copy behavior of the owner and group of the destination file. '
+                     'If not populated, the destination file will have the default Owner and Group.')
 
     with self.argument_context('storage file copy cancel') as c:
         c.register_path_argument(options_list=('--destination-path', '-p'))
@@ -2116,6 +2157,19 @@ def load_arguments(self, _):  # pylint: disable=too-many-locals, too-many-statem
                         'already validate. Note that this MD5 hash is not stored with the file.')
         c.extra('file_url', help='The full endpoint URL to the File, including SAS token if used.')
 
+    for cmd in ['file update', 'file upload']:
+        with self.argument_context(f'storage {cmd}') as c:
+            c.extra('file_mode',
+                    help='Only applicable to NFS Files. The mode permissions to be set on the file. '
+                         'Symbolic (rwxrw-rw-) is supported. The sticky bit is also supported and its represented '
+                         'either by the letter t or T in the final character-place depending on whether the execution '
+                         'bit for the others category is set or unset respectively, absence of t or T indicates sticky '
+                         'bit not set."')
+            c.extra('owner', help='Only applicable to NFS Files. The owner user identifier (UID) to be set on the '
+                                  'file. The default value is 0 (root).')
+            c.extra('group', help='Only applicable to NFS Files. The owner group identifier (GID) to be set on the '
+                                  'file. The default value is 0 (root group).')
+
     with self.argument_context('storage file url') as c:
         c.register_path_argument(fileshare=True)
         c.extra('share_name', share_name_type, required=True)
@@ -2701,3 +2755,13 @@ def load_arguments(self, _):  # pylint: disable=too-many-locals, too-many-statem
             c.extra('disallow_source_trailing_dot', arg_type=get_three_state_flag(), default=False,
                     options_list=["--disallow-source-trailing-dot", "--disallow-src-trailing"],
                     help="If true, the trailing dot will be trimmed from the source URI. Default to False")
+
+    with self.argument_context('storage file hard-link create') as c:
+        c.extra('share_name', share_name_type, required=True)
+        c.register_path_argument()
+        c.extra('target', required=True,
+                help='Specifies the path of the target file to which the link will be created, up to 2 KiB in length. '
+                     'It should be the full path of the target starting from the root. The target file must be in the '
+                     'same share and the same storage account.')
+        c.extra('lease',
+                help='Lease id, required if the file has an active lease.')

src/azure-cli/azure/cli/command_modules/storage/commands.py

@@ -723,6 +723,7 @@ def get_custom_sdk(custom_module, client_factory, resource_type=ResourceType.DAT
                                        exception_handler=file_related_exception_handler,
                                        transform=transform_file_show_result)
         g.storage_custom_command('download-batch', 'storage_file_download_batch', client_factory=cf_share_client)
+        g.storage_command_oauth('hard-link create', 'create_hardlink')
 
     with self.command_group('storage cors', get_custom_sdk('cors', multi_service_properties_factory)) as g:
         from ._transformers import transform_cors_list_output

src/azure-cli/azure/cli/command_modules/storage/operations/file.py

@@ -110,7 +110,8 @@ def list_share_files(cmd, client, directory_name=None, timeout=None, exclude_dir
 
 
 def storage_file_upload(client, local_file_path, content_settings=None,
-                        metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None):
+                        metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None,
+                        file_mode=None, owner=None, group=None):
     upload_args = {
         'content_settings': content_settings,
         'metadata': metadata,
@@ -130,6 +131,14 @@ def storage_file_upload(client, local_file_path, content_settings=None,
         if isinstance(response['content_md5'], bytearray):
             response['content_md5'] = ''.join(hex(x) for x in response['content_md5'])
 
+    if not (file_mode is None and owner is None and group is None):
+        nfs_args = {
+            'file_mode': file_mode,
+            'owner': owner,
+            'group': group
+        }
+        client.set_http_headers(content_settings, **nfs_args)
+
     return response