Creating file shares with customer-managed encryption

Create File Storage for VPC shares with customer-managed encryption by using root keys stored in Key Protect for BYOK data protection.

You can't change the encryption type after the file share is created.

By default, File Storage for VPC shares are encrypted with IBM-managed encryption. For more information about envelope encryption, see Protecting data with envelope encryption.

Before you begin

To create file shares with customer-managed encryption, you must have your own customer root key. You can provision a key management service (KMS), and create or import your customer root key (CRK). You can choose between Key Protect Single or Multi Tenant instances. Then, create a service-to-service authorization between File Storage for VPC and the KMS instance that you created.

The Hyper Protect Crypto Services are deprecated. Customers can use existing instances until 20 March 2027. For more information, see Deprecation of IBM Cloud Hyper Protect Crypto Services. For continued protection, consider migrating your existing encryption keys to a Dedicated Key Protect instance. For more information, see the Migration guide.

It's also possible to use a customer root key from another account. In IBM Cloud, the KMS can be either located in the same or in another account as the service that is using an encryption key. This deployment pattern allows enterprises to centrally manage encryption keys for all corporate accounts. For more information, see Encryption key management.

Generally, the account administrator or another privileged user of the account that owns the CRK, invites the user of the second account and creates the authorization for sharing the CRK. For more information, see Granting access to keys with Key Protect. Then, the user from the second account can use the CRK to encrypt data in IBM Cloud.

Configure all required service-to-service authorizations service-to-service authorizations service-to-service authorizations service-to-service authorizations between File Storage for VPC (source service) and the KMS instance (target service) that holds the customer root key. If you're provisioning volumes with a CRK of another account, ask that account's administrator to set up the authorization in their account and to share the CRN of the root key.

Creating file shares with customer-managed encryption in the console

Follow this procedure to specify customer-managed encryption when you create a file share.

In the IBM Cloud console, go to the menu icon > Infrastructure > Storage > File storage shares.
Click Create.

Enter the following information.

Values for creating a file share.
Field	Value
Availability	Select availability If you're a customer with special access to preview the new regional file share offering, you can choose between Regional and Single zone data availability. You can't change this property after the share is created. If your account is not allow-listed, this field does not appear. Select the location for your zonal file share.
Location	Select availability If you chose Single zone availability, use the Zone menu to select a zone. The menu is grouped by geography (for example, NORTH AMERICA). Under each geography, metro locations are listed alphabetically. Click the arrow next to a metro name to expand its zones, then click a zone to select it. For example, expand Dallas (us-south) and select us-south-2. If you chose regional availability, use the Region menu to select a region. The menu is grouped by geography. Under each geography, metro locations are listed alphabetically. Click the arrow next to a metro name to expand its regions, then click a region to select it. For example, expand Dallas and select us-south.
Details
Name	Specify a meaningful name for your file share. The file share name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. You can later edit the name if you want.
Resource Group	Use the default resource group or specify a Resource group. Resource groups help organize your account resources for access control and billing purposes.
Tags (optional)	Enter any user tags to apply to this file share. As you type, existing tags appear that you can select. For more information about tags, see Add user tags to a file share.
Access Management Tags (optional)	Enter access management tags that you created in IAM to apply them to this file share. For more information about access management tags, see Access management tags for file shares.
Profile	The profile is auto-populated based on your data availability selection. For more information, see file Storage profiles. If you chose Single zone availability, your file share uses the `dp2` profile. Select the size and IOPS for your file share. You can increase the capacity later, and you can also adjust the IOPS as needed. Select availability If you chose regional availability, your file share uses the `rfs` profile. Select the size and bandwidth for your file share. 800 Mbps is the default bandwidth allocation for all file shares at no extra cost. You can increase the capacity later, and you can also adjust the bandwidth as needed.

The creation of mount targets is optional. You can skip this step if you do not want to create a mount target now. However, you need one to mount your file share on a compute host. A file share can have multiple mount targets so you can access it from multiple VPCs. You can create one mount target per VPC per file share. To create it, click Create. Define the mount target by providing the following information:
1. Provide a mount target name. The name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. You can later edit the name if you want.
2. Select an available VPC. The list includes only those VPCs with a subnet in the selected location. The location selection is inherited from the file share (for example, us-south-2).
3. A default virtual network interface is generated. You can customize it by clicking the Edit icon . You can change the name or subnet if you have multiple subnets available in the location. You can also select an existing VNI to attach to the mount target. The list of available VNIs in the VPC and location are displayed. As VNIs secondary IP addresses attached cannot be accepted as a file share mount target, they are filtered out of the list.
4. Click Next.
5. Encryption in transit is disabled by default for zonal shares, and it is enabled by default for regional shares. Click the toggle to change the preset value. For more information about this feature, see Encryption in transit - Securing mount connections between file share and host.
6. Then, click Next.
7. Review your selection, and either click Back to return and update your choices or click Create.
In the Encryption at rest section, all file shares are encrypted by IBM-managed keys by default. To use your own encryption key, click the toggle to enable customer-managed encryption. If you already have a KMS instance and root key, the system autoselects it for you. To change the key or instance, click the Edit icon to open the Configure encryption side panel. Select one of the following options to locate your encryption key:
- Locate by Instance: The panel has three steps:
  1. Select KMS instance: The list shows the name, ID, type (Standard or Dedicated), and location of each available Key Protect instance. Select an instance and click Select. If you don't have an instance yet, click Create to provision one.
  2. Associate key: The list shows the name, ID, last updated date, aliases, and key ring of each available root key. Select a key and click Select. If you don't have a key yet, click Create new key.
  3. Review: Confirm your selections, including the key management service, instance type, instance name, and key name. The Service authorization section shows whether the required authorization between File Storage for VPC and the KMS instance is already in place. If it is not, you can allow Key Protect to create the authorization automatically, or create one manually. For more information, see Establishing service-to-service authorizations for File Storage for VPC. Click Confirm to apply your selection and return to the file share provisioning page.
- Locate by CRN: Enter the CRN of the customer root key to be used for encrypting the share. Choose this option if you're using the CRK of another account. Click Select to proceed to the Review step described in the Locate by Instance option.
If you chose single-zone availability, the Disaster recovery section appears after the Encryption card. This step is optional. Use it to configure same-region asynchronous replication at provisioning time. Cross-regional replication, must be set up separately after the share is provisioned and in a stable status. For more information, see Adding replication to a file share.

To configure same-region replication, click the Asynchronous replication toggle. The replication fields expand inline. The replica inherits the source share's profile and encryption settings. Mount targets must be added separately.

Complete the following fields:
1. Zone: The geography and region are prepopulated based on the source share's location and cannot be changed. Select the zone for the replica from the dropdown. Only the zones that are valid for replication are shown.
2. Replica name: Enter a name for the replica share.
3. Max IOPS: Specify the maximum IOPS for the replica share.
4. Frequency: Select how often to synchronize changes from the source share to the replica, and configure the start time:
  - Every 15 minutes: Enter the minutes value for the start time.
  - Hourly: Enter the minutes value for the start time.
  - Daily: Enter the start time in UTC in HH:MM format, between 00:00 and 23:59.
  - Weekly: Select the day or days of the week on which replication runs, and enter the start time in UTC in HH:MM format, between 00:00 and 23:59.
  - Monthly: Enter the day of the month on which replication runs (1 - 31), and enter the start time in UTC in HH:MM format, between 00:00 and 23:59.
  - Cron expression: Enter a cron-spec expression in the format minute hour day month weekday. Replication must be scheduled no less than 15 minutes apart. For example, to replicate every day at 5:30 PM UTC, enter 30 17 * * *.
When all the required information is entered, click Create file share. You return to the File Storage for VPC page, where a message indicates that the file share is provisioning. When the transaction completes, the share status changes to Active.

If you created your key management service instance by using a private endpoint, root keys that were created by using that instance are not shown in the console. You must use the CLI or API to access and use those root keys.

Creating file shares with customer-managed encryption from the CLI

Before you can use the CLI, you must install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.

Gather the information that you need for provisioning a share, such as a unique name, location, the capacity, and performance characteristics that your file share must have. If you're creating a mount target with a virtual network interface, use the appropriate CLI commands to list the available subnets, reserved IP addresses in a subnet, and security groups. For more information, see Gathering information from the CLI.

For the encryption, retrieve the ID of your key management service and the CRN of the root key in that service.

List the available KMS instances with the ibmcloud resource service-instances command.

ibmcloud resource service-instances

Retrieving instances with type service_instance in all resource groups in all locations under account Test Account as test.user@ibm.com...
OK
Name             Location   State    Type               Resource Group ID
KeyProtect-ki    us-south   active   service_instance   db8e8d865a83e0aae03f25a492c5b39e
schematics       us-south   active   service_instance   db8e8d865a83e0aae03f25a492c5b39e

Use the ibmcloud resource service-instance command to get the instance ID. The ID is the last string in the CRN after the account number.

ibmcloud resource service-instance KeyProtect-ki -location us-south --id

Retrieving service instance KeyProtect-ki in all resource groups under account Test Account as test.user@ibm.com...
crn:v1:bluemix:public:kms:us-south:a/a1234567:: 22e573bd-c02c-4d7f-81e2-2aa867da176d

Use the ID in the ibmcloud kp keys command to retrieve the key information.

ibmcloud kp keys -c --instance-id 22e573bd-c02c-4d7f-81e2-2aa867da176d

Targeting endpoint: https://qa.us-south.kms.cloud.ibm.com
Retrieving keys...
OK
Key ID                                 Key Name      CRN
2fb8d675-bde3-4780-b127-3d0b413631c1   my-file-key   crn:v1:bluemix:public:kms:us-south:a/a1234567:22e573bd-c02c-4d7f-81e2-2aa867da176d:key:2fb8d675-bde3-4780-b127-3d0b413631c1

If you plan to use the encryption key of another account, the previous steps must be performed on the other account. You can't list the resources of another account even if you are authorized to use them.

If you are a customer with special access to preview the regional file share profile, you can use the rfs profile to create a file share. To be able to create and manage a regional file share from the CLI, set the appropriate environmental variable with the following command.
```
export IBMCLOUD_IS_FEATURE_SHARE_DENALI_REGIONAL_AVAILABILITY=true
```
The CLI returns the properties for "Allowed Access Protocols", "Availability Mode", "Bandwidth", and "Storage Generation" only when this environmental variable is set to "true".

Specify the ibmcloud is share-create command with the --encryption-key option to create a file share with customer-managed encryption. The encryption_key option must be followed by a valid CRN for the root key in the key management service. If you want to enable encryption in transit, too, specify that in the mount target JSON. The security groups that you associate with a mount target must allow inbound access for the TCP protocol on the NFS port from all servers where you want to mount the share.

The following example creates a file share with customer-managed encryption, security group access mode, and a mount target with a virtual network interface. Encryption in transit is not enabled.

ibmcloud is share-create --name my-encrypted-file-share --zone us-south-2 --profile dp2 --size 500 --iops 2000  --user-tags env:dev --encryption-key crn:v1:bluemix:public:kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1 --mount-targets '[{"name":"my-new-mount-target","virtual_network_interface": {"name":"my-vni-2","subnet": {"id":"r006-298acd6c-e71e-4204-a04f-fe4a4dd89805"},"security_groups":[{"id":"r006-7f369ca2-ca49-4053-b007-5cab79b9873b"}]}}]'

Creating file share my-encrypted-file-share under account Test Account as user test.user@ibm.com...

ID                           r006-d44298fe-aced-4f55-a690-8a3830e9fd90
Name                         my-encrypted-file-share
CRN                          crn:v1:bluemix:public:is:us-south-2:a/a1234567::share:r006-d44298fe-aced-4f55-a690-8a3830e9fd90
Lifecycle state              pending
Access control mode          security_group
Accessor binding role        none
Zone                         us-south-2
Profile                      dp2
Size(GB)                     500
IOPS                         2000
User Tags                    env:dev
Encryption                   user_managed
Mount Targets                ID                                          Name
                             r006-00432317-436e-4940-ab7d-8b26c186b00f   my-new-mount-target

Resource group               ID                                 Name
                             db8e8d865a83e0aae03f25a492c5b39e   Default

Created                      2023-10-19T21:16:27+00:00
Encryption key               crn:v1:bluemix:public:kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1
Replication role             none
Replication status           none
Replication status reasons   Status code   Status message
                             -             -
Snapshot count               10
Snapshot size                10
Source snapshot              -

ibmcloud is share-mount-targets my-encrypted-file-share

Listing share mount target of my-encrypted-file-share 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-00432317-436e-4940-ab7d-8b26c186b00f   my-new-mount-target   my-vpc   stable            none

The following example creates a file share with customer-managed encryption, security group access mode, and a mount target with a virtual network interface, and encryption-in-transit enabled.

ibmcloud is share-create --name my-encrypted-eit-file-share --zone us-south-2 --profile dp2 --size 500 --iops 2000  --user-tags env:dev --encryption_key crn:v1:bluemix:public::kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1 --mount-targets '[{"name":"my-new-mount-target","transit_encryption": "user_managed","virtual_network_interface": {"name":"my-vni-3","subnet": {"id":"r006-298acd6c-e71e-4204-a04f-fe4a4dd89805"},"security_groups":[{"id":"r006-7f369ca2-ca49-4053-b007-5cab79b9873b"}]}}]'

The response looks similar to the following example.

Creating file share my-encrypted-eit-file-share under account Test Account as user test.user@ibm.com...

ID                           r006-f6bf049e-f46c-4160-b548-4a36d27256ac
Name                         my-encrypted-eit-file-share
CRN                          crn:v1:bluemix:public::is:us-south-2:a/a1234567::share:r006-f6bf049e-f46c-4160-b548-4a36d27256ac
Lifecycle state              pending
Access control mode          security_group
Accessor binding role        none
Zone                         us-south-2
Profile                      dp2
Size(GB)                     500
IOPS                         2000
User Tags                    env:dev
Encryption                   user_managed
Mount Targets                ID                                          Name
                             r006-e6bd52b8-c656-4ba6-8749-1bb41bfa2c3c   my-new-mount-target

Resource group               ID                                 Name
                             db8e8d865a83e0aae03f25a492c5b39e   Default

Created                      2023-10-20T03:05:38+00:00
Encryption key               crn:v1:bluemix:public:kms:us-south:a/a1234567-c02c-4d7f-81e2-2aa867da176d:key:2fb8d675-bde3-4780-b127-3d0b413631c1
Replication role             none
Replication status           none
Replication status reasons   Status code   Status message
                             -             -

Snapshot count               0
Snapshot size                0
Source snapshot              -

ibmcloud is share-mount-targets my-encrypted-eit-file-share

The response looks similar to the following example.

Listing share mount target of my-encrypted-eit-file-share 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-e6bd52b8-c656-4ba6-8749-1bb41bfa2c3c   my-new-mount-target   my-vpc   stable            user_managed

The following example creates a regional file share with customer-managed encryption, security group access mode, and encryption-in-transit enabled.

ibmcloud is share-create --name my-regional-file-share --profile rfs --size 40 --bandwidth 800 --atem stunnel,none --encryption-key crn:v1:bluemix:public::kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1

The response looks similar to the following example.

Creating file share my-file-share1 under account Test Account as user test.user@ibm.com...

ID                                 r006-9ae55188-610e-4cf9-9350-d0b675026ff8
Name                               my-regional-file-share
CRN                                crn:v1:bluemix:public:is:us-south:a/a1234567::share:r006-9ae55188-610e-4cf9-9350-d0b675026ff8
Lifecycle state                    pending
Access control mode                security_group
Accessor binding role              none
Allowed transit encryption modes   stunnel,none
Zone                               -
Profile                            rfs
Size(GB)                           40
IOPS                               35000
Encryption                         user_managed
Mount Targets                      ID                          Name
                                   No mounted targets found.

Resource group                     ID                                 Name
                                   11caaa983d9c4beb82690daab08717e9   Default

Created                            2025-09-22T21:17:23+05:30
Encryption key                     crn:v1:bluemix:public:kms:us-south:a/a1234567-c02c-4d7f-81e2-2aa867da176d:key:2fb8d675-bde3-4780-b127-3d0b413631c1

Replication role                   none
Replication status                 none
Replication status reasons         Status code   Status message
                                   -             -

Snapshot count                     0
Snapshot size                      0
Source snapshot                    -
Allowed Access Protocols           nsf4
Availability Mode                  regional
Bandwidth(Mbps)                    800
Storage Generation                 2

For more information about the command options, see ibmcloud is share-create.

Creating file shares with customer-managed encryption with the API

You can create file shares with customer-managed encryption by calling the Virtual Private Cloud (VPC) API.

Make a POST /shares request and specify the encryption_key parameter to identify your customer root key (CRK). It is shown in the example as crn:[...key:...].

You must provide the generation parameter and specify generation=2. For more information, see Generation in the Virtual Private Cloud API reference.

The following example creates a zonal file share with a mount target, and specifies the CRN of the root key for customer-managed encryption.

curl -X POST \
"$vpc_api_endpoint/v1/shares?version=2024-11-05&generation=2" -H "Authorization: Bearer $iam_token" \
-d '{
     "name": "my-encrypted-share",
     "mount_targets": [
         {
           "name": "docs-mount-1",
           "virtual_network_interface": {
             "name": "my-virtual-network-interface-1",
             "allow_ip_spoofing": false,
             "auto_delete": true,
             "enable_infrastructure_nat": true,
             "primary_ip": {"auto_delete": true},
             "subnet": {"id": "0727-267015ac-7b12-4f62-bda9-52fcb9483fc4"},
             "ips": [],
             "security_groups": [{"id": "r006-bf9475c2-6846-4c39-b392-587643b2e2f8"}],
             "protocol_state_filtering_mode": "auto"
          },
          "transit_encryption": "none"
         }
       ],
     "profile": {"name": "dp2"},
     "size": 100,
     "zone": {"name": "us-south-2"},
     "iops": 3000,
     "allowed_transit_encryption_modes": ["none","user_managed"],
     "encryption_key": {"crn": "crn:v1:bluemix:public:kms:us-south:a/a1234567-c02c-4d7f-81e2-2aa867da176d:key:2fb8d675-bde3-4780-b127-3d0b413631c1"},
     "resource_group": {"id": "db00a952a88945a987b7be1980fdae8e"},
     "access_control_mode": "security_group"
   }'

The following example creates a regional file share without a mount target, and specifies the CRN of the root key for customer-managed encryption.

curl -X POST \
"$vpc_api_endpoint/v1/shares?version=2025-09-02&generation=2" -H "Authorization: Bearer $iam_token" \
-d '{
     "name": "my-encrypted-regional-share",
     "profile": {"name": "rfs"},
     "size": 1000,
     "bandwidth": 800,
     "allowed_transit_encryption_modes": ["none","stunnel"],
     "encryption_key": {"crn": "crn:v1:bluemix:public:kms:us-south:a/a1234567-c02c-4d7f-81e2-2aa867da176d:key:2fb8d675-bde3-4780-b127-3d0b413631c1"},
     "resource_group": {"id": "db00a952a88945a987b7be1980fdae8e"},
     "access_control_mode": "security_group"
   }'

You can also specify the CRN of a root key from a different account in the POST /shares call. If you want to do that, contact the other account's administrator to ensure that the service-to-service authorizations are in place and to get the CRN of the encryption key.

Creating file shares with customer-managed encryption with Terraform

To create a file share, use the ibm_is_share resource. The following example creates a zonal file share with 800 GiB capacity and the dp2 performance profile. The file share is encrypted by using a key that is identified by its CRN. The example also specifies a new mount target with a virtual network interface.

resource "ibm_is_share" "share4" {
   zone                = "us-south-2"
   size                = "800"
   iops                = "3000"
   name                = "my-share4"
   profile             = "dp2"
   encryption_key      = "crn:v1:bluemix:public:kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1"
   access_control_mode = "security_group"
   mount_target {
       name = "target"
       security_groups = [<security_group_ids>]
       virtual_network_interface {
         primary_ip {
           address     = "10.240.64.5"
           auto_delete = true
           name        = "my-example-pip"
         }
       }
   }
}

The following example creates a regional file share with 1000 GiB capacity and the rfs performance profile. The file share is encrypted by using a key that is identified by its CRN.

resource "ibm_is_share" "regional-share" {
   size                = "1000"
   name                = "my-regional-share"
   profile             = "rfs"
   bandwidth           = "800"
   encryption_key      = "crn:v1:bluemix:public:kms:us-south:a/a1234567:key:2fb8d675-bde3-4780-b127-3d0b413631c1"
   access_control_mode = "security_group"
   }

For more information about the arguments and attributes, see ibm_is_share.

Next steps

Use the IBM Cloud File Share Mount Helper utility to mount your encrypted file share to an authorized Compute instance.
Manage the root keys that are protecting your file share by rotating, disabling, or deleting keys.
Consider setting up replication for your share. For more information, see About file share replication.
Learn about Sharing and mounting a file share from another account.