IBM Cloud Docs
Creating replica file shares

Creating replica file shares

Create a replica file share in the UI, from the CLI, with the API, or with Terraform. Replica file shares can be created in another zone of the same metro region as the primary share's zone, or a zone of a different metro region in the same geography.

The following table shows which metro regions can replicate with each other within each geography.

Table 1 - This table shows the metro regions that can replicate with each other in each geography. Every geography is a separate column.
Americas Europe Asia
  • Dallas, TX / us-south
  • Sao Paulo / br-sao
  • Toronto / ca-tor
  • Washington, DC / us-east
  • Frankfurt / eu-de
  • London / eu-gb
  • Madrid / eu-es
  • Tokyo / jp-tok
  • Osaka/ jp-osa
  • Sydney / au-syd

The specified source file share must not have another replica already, and must not be a replica of another share.

If you want to create a replica in another region, you need to establish service-to-service authorizations first. Both file service instances must belong to the same account. Cross-account replication is not supported. For more information, see Establishing service-to-service authorizations for File Storage for VPC.

Adding replication to a file share in the UI

You can create a replica of your file share from the list of all file shares or the file share details page. If you don't already have a source file share, provision one as described in Create a file share and mount target in the UI. When the file share appears as "stable" on the File shares for VPC page, click the ellipsis Actions icon and click Create replica.

On the File share replica create page, review the source file share details, and complete the replica details.

  1. Name - Provide a unique name for the replica share.

  2. Replica location - The geography is preselected and cannot be changed. Select the metro (region) and zone in which the replica share is to be created. The UI presents the available options in the menu.

  3. Resource group - Select the resource group from the list.

  4. Tags - Optionally, specify user tags. The tags that you apply to the replica can be the same as or different from the source share's tags.

  5. Profile - The dp2 profile is preselected, even if the source file share is based on a profile from a previous release. Specify the maximum value for IOPS. It determines the performance that you get on the replica after you perform a failover.

  6. Mount Targets - Optionally, create a mount target for the replica share. You can skip this step if you do not want to create a mount target now. Otherwise, click Create. You can create one mount target per VPC per file share. Depending on the mount target access mode of the share, the Create mount target form looks different.

    • If you selected security group as the access mode, enter the information as described in the Table 2. This action creates and attaches a virtual network interface to your mount target that identifies the file share with a reserved IP address and applies the rules of the selected Security group. This mount target supports encryption-in-transit and cross-zone mounting.

      Table 2. Values for creating a mount target.
      Field Value
      Details
      Mount target name Specify 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.
      Zone Zone is inherited from the file share (for example, Dallas 2).
      VPC Select an available VPC. The list includes only those VPCs with a subnet in the selected zone.
      Subnet Select a subnet from the list.
      Reserved IP address Required for the mount target. The IP address cannot be changed afterward. However, you can delete the mount target and create another one with a different IP address.
      Reserving method You can have the file service select an IP address for you. The reserved IP becomes visible after the mount target is created. Or, specify your own IP.
      Auto-release Releases the IP address when you delete the mount target. Enabled by default.
      Security groups The default security group for the VPC is selected. You can use it or select another security group from the list.
      Encryption in transit Disabled by default, click the toggle to enable. For more information about this feature, see Encryption in transit - Securing mount connections between file share and host.

    • If you selected VPC as the access mode, provide a name for the mount target and select a VPC from the list. This mount target can be used to mount the file share on any virtual server instance of the selected VPC in the same zone as the file share. Cross-zone mounting is not supported.

  7. Sync frequency - Specify how often you want to synchronize changes from the primary file share to the replica share. The Summary shows the selections that you made. For Frequency, the options are hourly, daily, weekly, monthly, or by cron-spec expression:

    • For hourly replication, enter a value in the range 0 - 60 to specify exactly how many minutes past the hour, every hour, every day the replication is to start.
    • For daily replication, specify the starting time in hours and minutes in Coordinated Universal Time. Enter a value between 00:00 and 23:59. For your convenience, the Coordinated Universal Time value is converted into your local time.
    • For weekly replication, specify the days of the week you want replication to run and the start time in Coordinated Universal Time. Enter a value between 00:00 and 23:59.
    • For monthly replication, choose a Day 1 - 28. For the start time, enter a value between 00:00 and 23:59.
    • If you specify a cron-spec expression, replications must be scheduled not less than 1 hour. Enter the replication frequency in cron-spec format: minute, hour, day, month, and weekday. For example, to replicate every day at 5:30 PM you need to enter 30 17 * * *.

  8. Replication

    • When you replicate to another zone of the same region, the encryption is inherited from the primary share. If you specified customer-managed encryption, the key management system is shown along with the root key. You can't encrypt a replica share with a different key.
    • When you replicate to another region, the encryption type (provider-managed vs customer-managed) of the replica must match the source share. However, it is not inherited from the source, and you must select a Customer Root Key for your replica if the source share is protected by customer-managed encryption.
    Table 2. Values for customer-managed encryption for file shares.
    Field Value
    Encryption Select either Key Protect or Hyper Protect Crypto Services.
    Encryption service instance If you provisioned multiple KMS instances in your account, select the one that includes the root key that you want to use for customer-managed encryption. Ensure that service-to-service authorizations between the file service and the target KMS are in place.
    Key name Select the root key within the KMS instance that you want to use for encrypting the share.
    Key ID The field shows the key ID that is associated with the data encryption key that you selected.

  9. In the side panel, review your estimated cost, and apply a discount code, if you have one.

  10. Click Create file share.

If you're not ready to order yet or just looking for pricing information, you can add the information that you see in the side panel to an Estimate. For more information about how this feature works, see Estimating your costs.

Adding replication to file share from the CLI

You can use the CLI to create a file share with a replica share in another zone or region, or to create a replica share for an existing file share.

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.

Creating a file share with a replica from the CLI

When you use the ibmcloud is share-create command to create your share, you can create a replica share at the same time by specifying values for the options --replica-share-name, --replica-share-profile, --replica-share-cron-spec,--replica-share-zone. For more information about the command options, see ibmcloud is share-create.

In the following example, a share my-source-file-share is created in us-south-2 with a replica file share my-replica-file-share in us-south-1. In this example, only one mount target is created for the source file share, but you can also create the mount target for the replica share by using the same JSON syntax with the --replica-share-mount-targets option.

$ ibmcloud is share-create --name my-source-file-share --zone us-south-2 --profile dp2 --size 1500 --iops 2000  --user-tags env:dev --mount-targets '[{"name":"my-source-mount-target","virtual_network_interface": {"name":"my-source-vni","subnet": {"id":"0717-298acd6c-e71e-4204-a04f-fe4a4dd89805"}}}]' --replica-share-name my-replica-file-share --replica-share-profile dp2 --replica-share-cron-spec '55 09 * * *' --replica-share-zone us-south-1
Creating file share my-source-file-share under account Test Account as user test.user@ibm.com...
                                
ID                           r006-e4acfa9b-88b0-4f90-9320-537e6fa3482a   
Name                         my-source-file-share   
CRN                          crn:v1:bluemix:public:is:us-south-2:a/a1234567::share:r006-e4acfa9b-88b0-4f90-9320-537e6fa3482a   
Lifecycle state              pending
Access control mode          security_group   
Zone                         us-south-2   
Profile                      dp2   
Size(GB)                     1500   
IOPS                         2000   
User Tags                    env:dev   
Encryption                   provider_managed   
Mount Targets                ID                                          Name      
                             r006-fdbffc45-618c-49f1-bb08-ec530d7be378   my-source-mount-target      
                                
Resource group               ID                                 Name      
                             db8e8d865a83e0aae03f25a492c5b39e   Default      
                                
Created                      2023-10-19T15:42:53+00:00   
Latest job                   Job status    Job status reasons
                             running       -

                             
Replication share            ID                                          Name                    Resource type      
                             r006-dc6a644d-c7da-4c91-acf0-d66b47fc8516   my-replica-file-share   share      
                                
Replication role             source   
Replication status           none   
Replication status reasons   Status code   Status message      
                             -             -

Creating a replica for an existing file share from the CLI

  1. Locate your source file share from the CLI by listing your 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-925214bc-ded5-4626-9d8e-bc4e2e579232   my-new-file-share   stable            us-south-2   dp2       500        Default          none   
r006-97733317-35c3-4726-9c28-1159de30012e   my-file-share-8     stable            us-south-1   dp2       40         Default          none   
r006-b1707390-3825-41eb-a5bb-1161f77f8a58   my-vpc-file-share   stable            us-south-2   dp2       1000       Default          none   
r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6   my-file-share       stable            us-south-2   dp2       1000       Default          none

  2. View the details of the file share that you want to use as your source with the ibmcloud is share command. You can use the share's name or ID when you create a replica in the same region. If you create the replica in another region, take note of the CRN of the source file share.

    $ ibmcloud is share my-file-share
Getting file share my-file-share under account Test Account as user test.user@ibm.com...
                             
ID                           r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6   
Name                         my-file-share   
CRN                          crn:v1:bluemix:public:is:us-south-2:a/a1234567::share:r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6   
Lifecycle state              stable   
Access control mode          security_group   
Zone                         us-south-2   
Profile                      dp2   
Size(GB)                     1000   
IOPS                         1000   
Encryption                   provider_managed   
Mount Targets                ID                                          Name      
                             r006-dd497561-c7c9-4dfb-af0a-c84eeee78b61   my-cli-share-mount-target-1      
                             
Resource group               ID                                 Name      
                             db8e8d865a83e0aae03f25a492c5b39e   Default      
                             
Created                      2023-10-18T22:15:15+00:00   
Replication role             none   
Replication status           none   
Replication status reasons   Status code   Status message      
                             -             -

  3. Create a replica share by running the ibmcloud is share-create command in the region where the replica share is created. Specify the source share by name, ID, or CRN. Provide values to define where the replica file share is going to be created, and the profile of the replica share. Specify the replication schedule with a cron expression. If the source file share has user_managed encryption, you must provide the --encryption_key. The --encryption_key property must not be specified otherwise.

    ibmcloud is share-replica-create --name my-replica-share --zone us-south-3 --profile dp2 --replication-cron-spec '10 05 * * *' --source-share my-file-share
Creating replica file share my-replica-share under account Test Account as user test.user@ibm.com...
                             
ID                           r006-6d1719da-f790-45cc-9f68-896fd5673a1a   
Name                         my-replica-share   
CRN                          crn:v1:bluemix:public:is:us-south-3:a/a1234567::share:r006-6d1719da-f790-45cc-9f68-896fd5673a1a   
Lifecycle state              pending   
Access control mode          security_group   
Zone                         us-south-3   
Profile                      dp2   
Size(GB)                     1000   
IOPS                         100   
Encryption                   provider_managed   
Mount Targets                ID                          Name      
                             No mounted targets found.      
                             
Resource group               ID                                 Name      
                             db8e8d865a83e0aae03f25a492c5b39e   Default      
                             
Created                      2023-10-19T15:13:18+00:00   
Latest job                   Job status   Job status reasons      
                             running      -      
                             
Replication cron spec        10 05 * * *   
Replication role             replica   
Replication status           initializing   
Replication status reasons   Status code   Status message      
                             -             -      
                             
Source share                 ID                                          Name            Resource type      
                             r006-b696742a-92ee-4f6a-bfd7-921d6ddf8fa6   my-file-share   share

When you create a replica of a file share in another region, you must use the CRN of the source file share. If the source file share has user_managed encryption, you must provide the encryption_key. The encryption_key value must not be specified otherwise. See the following example.

   ibmcloud is share-cross-regional-replica-create --name my-replica-share --zone us-east-1 --profile dp2 --replication-cron-spec '5 * * * *' --source-share crn:v1:bluemix:public:is:us-south-1:a/a1234567::share:r006-d8c8821c-a227-451d-a9ed-0c0cd2358829 --encryption-key crn:v1:bluemix:public:kms:us-south:a/a1234567:1be45161-6dae-44ca-b248-837f98004057:key:3dd21cc5-cc20-4f7c-bc62-8ec9a8a3d1bd
   Creating replica file share my-cross-regional-replica-share under account Test Account as user test.user@ibm.com...
                                
   ID                           r006-6d1719da-g687-45ac-9f68-896fd76843a1b    
   Name                         my-cross-regional-replica-share   
   CRN                          crn:v1:bluemix:public:is:us-east-1:a/a1234567::share:r006-6d1719da-g687-45ac-9f68-896fd76843a1b   
   Lifecycle state              pending   
   Access control mode          security_group   
   Zone                         us-east-1   
   Profile                      dp2   
   Size(GB)                     1000   
   IOPS                         100   
   Encryption                   user_managed   
   Mount Targets                ID                          Name      
                                No mounted targets found.      
                                
   Resource group               ID                                 Name      
                                db8e8d865a83e0aae03f25a492c5b39e   Default      
                                
   Created                      2023-11-16T15:13:18+00:00   
   Encryption key               crn:v1:bluemix:public:kms:us-south:a/a1234567:1be45161-6dae-44ca-b248-837f98004057:key:3dd21cc5-cc20-4f7c-bc62-8ec9a8a3d1bd
   Latest job                   Job status   Job status reasons      
                                running      -      
                                
   Replication cron spec        5 * * * *   
   Replication role             replica   
   Replication status           initializing   
   Replication status reasons   Status code   Status message      
                                -             -      
                                
   Source share                 ID                                          Name       Resource type  Remote
                                r006-d8c8821c-a227-451d-a9ed-0c0cd2358829   my-share   share          us-south

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

Adding replication to file share with the API

You can programmatically set up replication by calling the /shares method in the VPC API as shown in the following sample requests.

Before you begin, first set up the API environment. For more information about the file shares VPC API, see the VPC API reference.

Creating a file share with a replica with the API

When you create a file share, you can specify that a replica file share is also created in a different zone. Make a POST /shares request and specify the replica_share property to define the replica file share.

The following example creates the replica test-replica-001 for the source share source-share-001. Mount targets, which are optional when you create a file share, are specified for the replica file share and source file share.

curl -X POST\
"$rias_endpoint/v1/shares?version=2023-08-08&generation=2"\
-H "Authorization: $iam_token"\
-d '{
    "name": "source-share-001",
    "profile":{"name":"dp2"},
    "size":100,
    "iops": 400,
    "mount-targets":[{"vpc":{"id":"08669c86-4c8a-4bfa-8ddc-37071f955c52"}],
    "zone":{"name":"us-south-1"},
    "replica_share":{
  	   "name": "test-replica-001",
      "profile":{"name":"dp2"},
      "replication_cron_spec":"*/1 * * * *",
      "zone":{"name":"us-south-3"},
      "mount-targets":[{"vpc":{"id":"9380990e-4b3b-4d79-80fe-ee052fb9772a"}}]
      }
   }'

Creating a replica for an existing file share with the API

To add replication to an existing file share, you need to create a replica share in a different zone of your region. In the POST /shares request, specify the replica share's name and profile, and specify the source_share by either its name, ID, or CRN. Other required properties are the zone, and replication_cron_spec, which provides the replication schedule.

The following example shows an API request that creates a replica share in the us-south-1 zone. In this example, the source share resides in another us-south zone and is identified by its ID.

curl -X POST \
"$rias_endpoint/v1/shares?version=2023-08-28&generation=2"\
  -H "Authorization: Bearer $iam_token" \
  -d '{
  "source_share": {"id": "4aafd9c9-5555-4bdb-902d-d63d4dcf5adc"},
  "mount_targets": [],
  "name": "my-replica-share",
  "profile": {"name": "dp2"},
  "size": 100,
  "zone": {"name": "us-south-1"},
  "iops": 300,
  "replication_cron_spec": "00 05 * * 0",
  "resource_group": {"id": "6edefe513d934fdd872e78ee6a8e73ef"},
  "access_control_mode": "security_group"
}'

When you create a replica of a file share in another region, you must use the CRN of the source file share. If the source file share has user_managed encryption, you must provide the encryption_key. The encryption_key value must not be specified otherwise.

You can use the API to verify that the replication succeeded, is pending, or failed. Make a GET /shares/{replica_id} call. Look at the latest_job property. For more information, see Verify replication with the API.

Adding replication to file share with Terraform

You can use the ibm_is_share resource in Terraform to create a file share with replication, or update a file share to include replication. The following example creates a replica share in the us-south-3 zone and associates it to the parent share that is specified by its ID ibm_is_share.example.id.

resource "ibm_is_share" "my-replica1" {
  zone                  = "us-south-3"
  source_share          = ibm_is_share.example.id
  name                  = "my-replica1"
  profile               = "dp2"
  replication_cron_spec = "0 */5 * * *"
}

The following example creates a file share in us-south-1 with a replica in us-south-3.

resource "ibm_is_share" "my-replica" {
  zone    = "us-south-1"
  size    = 220
  name    = "my-share"
  profile = "dp2"
  replica_share {
    name                  = "my-replica"
    replication_cron_spec = "0 */5 * * *"
    profile               = "dp2"
    zone                  = "us-south-3"
  }
}

When you create a replica of a file share in another region, you must use the CRN of the source file share. If the source file share has user_managed encryption, you must provide the encryption_key. The encryption_key value must not be specified otherwise. See the following example.

resource "ibm_is_share" "my-cross-regional-replica" {
  zone    = "us-east-1"
  source_share_crn = "crn:v1:bluemix:public:is:us-south-1:a/a1234567::share:r006-d8c8821c-a227-451d-a9ed-0c0cd2358829"
  encryption_key = "crn:v1:bluemix:public:kms:us-south:a/a1234567:1be45161-6dae-44ca-b248-837f98004057:key:3dd21cc5-cc20-4f7c-bc62-8ec9a8a3d1bd"
  replication_cron_spec = "5 * * * *"
  name    = "my-cross-regional-replica"
  profile = "dp2"
}

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

Next steps