Managing file shares, accessor share bindings, and mount targets
Manage the file shares that you created. You can rename a file share. You can increase its capacity and modify its IOPS. You can add mount targets to a file share, and use the mount path to mount a file share from virtual server instances. You can rename or delete a mount target. Or you can delete a file share if you no longer need it.
File Storage for VPC service requires IAM permissions for role-based access control. For example, to create a file share, you need to have at least editor permissions. For more information, see Managing IAM access for VPC Infrastructure Services for file shares.
Managing file shares, accessor share bindings, and mount targets in the UI
In the console, you can:
- Rename a file share.
- Rename a mount target of a file share.
- Update a file share profile (not applicable for accessor shares).
- Update allowed transit encryption modes (not applicable for accessor shares).
- Delete mount target of a file share.
- Delete a file share.
- Add user tags to file shares.
In the console, you can manage normal file shares and accessor shares. Only the share owner can modify properties like access control mode, IOPS, and profile. The accessor account cannot edit the origin share, and can modify a smaller set of properties of the accessor share.
Renaming a mount target of a file share in the UI
- Go to the file shares details page.
- Click the Actions icon .
- Select Rename.
- Enter a new name and click Rename.
Valid mount target names can include a combination of lowercase alpha-numeric characters (a-z, 0-9) and the hyphen (-), up to 63 characters. Mount target names must begin with a lowercase letter.
Updating a file share profile in the UI
These instructions are for the previous generation of file share profiles (general purpose, 5-iops, 10-iops, or custom). To access the latest features, you must change the IOPS profile of your share to dp2. The profiles of file shares that were created with the dp2 profile cannot be changed.
You can change the profile for a file share from the current profile to another IOPS tier profile, to a custom profile, or to a high-performance dp2 profile. Your billing adjusts based on the type of profile that you choose.
- Go to the file shares details page.
- Click the Edit icon next to the current profile or use the Actions menu and select Edit IOPS profile. A side panel shows the current profile, file share size, and maximum IOPS.
- For a New profile, click the down arrow. You can select a new IOPS tier, a custom profile, or dp2. For Custom IOPS or dp2, specify a new max IOPS based on the file share size. The file share price is automatically calculated based on your selection.
- Click Save and continue.
Updating allowed transit encryption modes in the UI
The owner of share can change the allowed transit encryption modes. However, before this property can be changed, all bindings must be deleted. Deleting the bindings severs the network path between origin file share and accessor share, and puts the mount target that is attached to the accessor share in a failed state. For more information, see Removing access to a file share from other accounts.
- Select a file share from the list of file shares.
- On the File share details page, locate the allowed transit encryption modes.
- Click the Edit icon to change the current value.
Managing file shares, accessor share bindings, and mount targets from the CLI
By using the CLI, you can:
- Rename a file share.
- Rename a mount target of a file share.
- Update a file share profile (not applicable for accessor share).
- Update allowed transit encryption modes (not applicable for accessor share).
- Delete mount target of a file share.
- Delete a file share.
- Add user tags to file shares.
Renaming a mount target of a file share from the CLI
-
List the file shares in the region with the
ibmcloud is shares
command. Take a note of the file share's name and ID that has the mount target that you want to rename. -
Use the share's name or ID to find its mount targets with the
ibmcloud is share-mount-targets
command.$ ibmcloud is share-mount-targets r006-e4acfa9b-88b0-4f90-9320-537e6fa3482a Listing share mount target of r006-e4acfa9b-88b0-4f90-9320-537e6fa3482a in all resource groups and region us-south under account Test Account as user test.user@ibm.com... ID Name VPC Lifecycle state Transit Encryption r006-fdbffc45-618c-49f1-bb08-ec530d7be378 my-source-mount-target my-vpc stable none
-
To rename the mount target, run the
share-mount-target-update
command with the file share name or ID, and the mount target name. Specify a new mount target name with the--name
option.ibmcloud is share-mount-target-update r006-e4acfa9b-88b0-4f90-9320-537e6fa3482a r006-fdbffc45-618c-49f1-bb08-ec530d7be378 --name my-renamed-mount-target
Valid mount target names can include a combination of lowercase alpha-numeric characters (a-z, 0-9) and the hyphen (-), up to 63 characters. Mount target names must begin with a lowercase letter.
For more information about the command options, see ibmcloud is share-mount-target-update
.
Updating a file share profile in the CLI
These instructions are for the previous generation of file share profiles (general purpose, 5-iops, 10-iops, or custom). To access the latest features, you must change the IOPS profile of your share to dp2. The profiles of file shares that were created with the dp2 profile cannot be changed.
-
Locate the file share that you want to update by listing the file shares in the region with the
ibmcloud is shares
command.$ ibmcloud is shares Listing shares in all resource groups and region us-south under account Test Account as user test.user@ibm.com... ID Name Lifecycle state Zone Profile Size(GB) Resource group Replication role r006-52c68ba5-2754-4c9d-8345-1fe6aa930073 disposal-snare-revivable-chitchat stable us-south-3 dp2 10 defaults replica r006-46541dc4-9e73-453a-9075-90ced0d612c3 trapdoor-urgency-attitude-imposing stable us-south-1 dp2 10 defaults source r006-72604692-0dc5-49fb-8eca-08b16a6a4854 fiction-create-platter-decidable stable us-south-3 dp2 10 defaults replica r006-c23ce229-fee9-4d40-a509-44886b21bb69 prismoid-evergreen-chains-granola stable us-south-1 dp2 10 defaults source r006-89b34134-2be6-4281-ae8e-b1c625d533ae test-share stable us-south-1 dp2 10 defaults none r006-cc7ab6a0-bb71-4e03-8ef7-dcffca43717f my-old-file-share stable us-south-1 tier-3iops 40 defaults none
-
Use the
share-update
command with the--profile
parameter to indicate the new file share profile by name.$ ibmcloud is share-update my-old-file-share --profile dp2 --size 1000 --iops 3000 Updating file share my-file-share-8 under account Test Account as user test.user@ibm.com... ID r006-cc7ab6a0-bb71-4e03-8ef7-dcffca43717f Name my-old-file-share CRN crn:v1:bluemix:public:is:us-south-1:a/a1234567::share:r006-cc7ab6a0-bb71-4e03-8ef7-dcffca43717f Lifecycle state updating Access control mode vpc Zone us-south-1 Profile dp2 Size(GB) 1000 IOPS 3000 User Tags env:dev,env:prod Encryption provider_managed Mount Targets ID Name r006-c9d82a15-7ead-4388-abc8-88e81c12ed28 my-target121 Resource group ID Name 6edefe513d934fdd872e78ee6a8e73ef defaults Created 2023-03-27T20:43:36+00:00 Replication role none Replication status none Replication status reasons Status code Status message - -
For more information about the command options, see ibmcloud is share-update
.
Update allowed transit encryption modes from the CLI
The owner of the share can change the allowed transit encryption modes type to user_managed,none
,user_managed
or none
. However, before this property can be changed, all bindings and mount targets must be deleted.
Deleting the bindings severs the network path between origin file share and accessor share, and puts the mount target that is attached to the accessor share in a failed state. For more information, see Removing access to a file share from other accounts.
$ ibmcloud is share-update my-origin-share --allowed-transit-encryption-modes user_managed
Updating file share my-file-share under account Test Account as user test.user@ibm.com...
ID r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6
Name my-origin-share
CRN crn:v1:bluemix:public:is:us-south-2:a/1234567::share:r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6
Lifecycle state stable
Access control mode security_group
Accessor binding role origin
Allowed transit encryption modes user_managed
Origin share CRN Name Remote account Remote region
crn:v1:bluemix:public:is:us-south-2:a/7654321::share:r006-d73v40a6-e08f-4d07-99e1-d28cbf2188ed my-origin-share a7654321 -
Zone us-south-2
Profile dp2
Size(GB) 1000
IOPS 1000
Encryption provider_managed
Mount Targets ID Name
No mounted targets found.
Resource group ID Name
db8e8d865a83e0aae03f25a492c5b39e Default
Created 2024-06-25T22:15:15+00:00
Replication role none
Replication status none
Replication status reasons Status code Status message
- -
Managing file shares, accessor share bindings, and mount targets with the API
By using the API, you can:
- Rename a file share.
- Rename a mount target of a file share.
- Update a file share profile (not applicable for accessor shares).
- Update allowed transit encryption modes with the API (not applicable for accessor shares).
- Delete mount target of a file share.
- Delete a file share.
- Manage user tags for file shares.
To see information about the File Storage for VPC API methods, see the following section in the API reference.
Renaming a mount target of a file share with the API
Make a PATCH /shares/$share_id/mount_targets/$target_id
call to rename a mount target of a file share. See the following example.
curl -X PATCH \
"$vpc_api_endpoint/v1/shares/$share_id/mount_targets/$target_id?version=2023-08-08&generation=2"\
-H "Authorization: Bearer ${API_TOKEN}" \
-d '{"name": "target-renamed1"}
A successful response looks like the following example.
{
"access_control_mode": "vpc",
"created_at": "2023-07-18T23:31:59Z",
"href": "$vpc_api_endpoint/v1/shares/0995b8c6-c323-4e59-9ea9-fa14dd66bba8/mount_targets/9fdf4438-f5b4-4b6f-8bca-602494fd6c31",
"id": "9fdf4438-f5b4-4b6f-8bca-602494fd6c31",
"lifecycle_state": "stable",
"mount_path": "domain.com:/vol_xyz_2891fd0a_64ea_4deb_9ed5_1159e37cb5aa",
"name": "target-renamed1",
"resource_type": "share_target",
"transit_encryption": "none",
"vpc": {
"crn": "crn:[...]",
"href": "$vpc_api_endpoint/v1/vpcs8c95b3c1-fe3c-45c-97a6-e43d14088287",
"id": "82a7b841-9586-43b4-85dc-c0ab5e8b1c7a",
"name": "vpc-name1",
"resource_type": "vpc"
}
}
Valid mount target names can include a combination of lowercase alpha-numeric characters (a-z, 0-9) and the hyphen (-), up to 63 characters. Mount target names must begin with a lowercase letter.
Updating a file share profile with the API
These instructions are for the previous generation of file share profiles (general purpose, 5-iops, 10-iops, or custom). To access the latest features, you must change the IOPS profile of your share to dp2. The profiles of file shares that were created with the dp2 profile cannot be changed.
Make a PATCH /shares/{share_ID}
call and specify the profile name in the profile
property. The following example changes the profile to a dp2
profile.
curl -X PATCH "$vpc_api_endpoint/v1/shares/432f1a4d-4aac-4ba1-922c-76fdbcbeb1e3?version=2023-08-08&generation=2"\
-H "Authorization: $iam_token"\
-d '{"profile": {"name": "dp2"}}'
Updating allowed transit encryption modes with the API
The owner of share can change the allowed transit encryption modes. However, before this property can be changed, all bindings and must be deleted. Deleting the bindings severs the network path between origin file share and accessor share, and puts the mount target that is attached to the accessor share in a failed state. For more information, see Removing access to a file share from other accounts.
curl -X PATCH \
"$vpc_api_endpoint/v1/shares/$share_id?version=2023-08-08&generation=2"\
-H "Authorization: Bearer ${API_TOKEN}"
-d '{"allowed_transit_encryption_modes": "user-managed"}'
Managing file shares, accessor share bindings, and mount targets with Terraform
With Terraform, you can:
- Change file share attributes such as name, size, profile, tags,
- Add or remove a replica relationship.
- Change the name of a mount target.
- Delete a file share or a mount target.
Updating attributes of a mount target with Terraform
Update the is_share_target
resource to change the name of the mount target. When applied, the following resource changes the name of the mount target to my-new-share-target
.
resource "is_share_target" "is_share_target" {
share = is_share.is_share.id
subnet = ibm_is_subnet.example.id
name = "my-new-share-target"
}`
For more information about the arguments and attributes, see ibm_is_share_target.
Removing access to a file share from other accounts
Revoking access to a file share is a 2-step process.
-
Remove the IAM authorization between the accounts. Removal of IAM authorization prevents the other account or service from creating an accessor share and mount target.
-
Delete the share binding that connects the origin share with the accessor share. This action causes the mount target of the other account to enter a
failed
state.
Mounting and unmounting file shares on a virtual server instance
Mounting is a process by which a server's operating system makes files and directories on the storage device available for users to access through the server's file system. To mount a file share to a virtual server instance, locate the mount path information. The mount path is created when you create a mount target for the file share. See the following information for mounting on a few Linux operating systems. Other Linux distributions follow similar procedures.
Monitoring file shares
You can check the status and health states of your file share by using the console, the CLI, or the API. You can monitor the total throughput, the total IOPS, the number of mount targets, and capacity usage of your share over time in the IBM Cloud console. You can use IBM Cloud® Activity Tracker Event Routing to configure how to route auditing events for file shares. You can also configure IBM Cloud Logs Routing for handling logs. For more information, see Monitoring file share health states, lifecycle status, and events.
File shares can be integrated with IBM Cloud® Monitoring to gain operational visibility into the performance and health of your shares. In the Sysdig web UI you can view the throughput, IOPS, and capacity metrics in more detail, customize your dashboards, and set up alerts. For more information, see Monitoring metrics for File Storage for VPC.