Cloning File Systems

This topic describes how to create a clone of an existing file system.

Overview

A clone is a new file system  that is created based on a snapshot  of an existing file system. Snapshots preserve the state of the data of a file system at a particular point in time. If you take snapshots of a file system at regular intervals, you can create clones of the file system as it existed at multiple points in its lifetime.

A snapshot provides the initial blueprint for a clone. You can clone a parent file system, or you can clone a clone, as long as there's at least one snapshot available. At the point of creation, the data included in the clone is identical to the data in the snapshot. After creation, data changes in the clone aren't included in the original file system. Conversely, any data changes to the original file system aren’t included in the clone. All file systems operate independently of each other, regardless of whether they are parent file systems, clones, or clones of clones.

Clones are space and time efficient because creating a clone doesn't replicate or move any data from the parent file system to the clone. Instead, the clone references the parent file system for any data they share. A file system that is a clone of a clone also references the original parent file system for any shared data.

When you create a clone, initially only the metadata incurs storage costs. Clone data usage is metered only against differentiated data. Data that the clone references from the parent file system isn't metered against the clone, just the parent. For more information, see File System Usage and Metering.

Note

Clones count against your tenancy's service limits the same way regular file systems do.
See Service Limits for a list of applicable limits and instructions for requesting a limit increase.

You can use clones for testing, patching, and faster application provisioning. If failed testing or patching causes the data to become unrecoverable, create a new clone from the original file system snapshot, delete the old clone, and restart your operation.

Cloning Concepts

PARENT FILE SYSTEM

A parent file system is a file system that contains data referenced by one or many clones. When you create a clone, you must specify which file system snapshot is used as the blueprint for the clone directory hierarchy and file data. The file system that contains this snapshot is the initial parent of the clone. The clone continues to reference the parent file system for any data they share in common.

A clone’s parent file system can change after the clone is created. For example, if you delete a clone’s parent file system, the file system parent’s parent (the clone's grandparent) becomes the clone’s new parent. The clone's data references are transferred to the new parent.

SOURCE SNAPSHOT
The snapshot used as a blueprint to create a clone. A snapshot is a point-in-time reference of a file system. You can take as many snapshots of a file system as you like, as often as you like. A parent file system can have snapshots available for many points along its lifetime. You can create a clone of your file system as it exists today, or as it existed in the past, as long as snapshots were taken of the file system at those times. For more information, see Managing Snapshots.
FILE SYSTEM CLONE
A clone is a new file system that is created based on a snapshot of existing file system. A clone automatically inherits the directory hierarchy and file data of the file system. All snapshots that exist in the parent file system are inherited by the clone, up to and including the snapshot that is used as the source of the clone. The timeCreated field of inherited snapshots are set to the time the clone operation was initiated. You can choose to keep or delete these snapshots.
File system properties such as compartment, tags, display name, keys, and mount target export information are not copied over from the parent. These properties must be specified manually. You can access the clone by creating an export for it and mounting it to an instance in the same manner as any other file system. See To create an export for a file system and Mounting File Systems.
When a clone is created, it is assigned a unique OCID. A clone also contains the following information on its Details page to let you track its relationships to other file systems and snapshots:
  • Hydration: Indicates whether the clone is currently copying metadata from the source.
  • Source snapshot: A link to the snapshot used to create the clone.
  • Parent File System: A link to the parent file system of the clone.
  • Root: Indicates whether this file system is the root of a clone tree.
  • Descendants: Indicates whether this file system has been cloned.

Cloned file systems are managed in the same way that any other file system is managed. See Managing File Systems for information on how view the clone's Details page, edit its properties, or delete the clone.

CLONE TREE
A clone tree is a group of clones that all descend from the same root file system. There is a transitive relationship between the root and the descendant clones. To delete the root of a clone tree, all its descendants must first be deleted.
In this diagram, B, C, D, E, F, G are all clones. A→ B→ C→D and A→ B→ E→ F→ G are all part of a clone tree. File system A is the root of this clone tree, and it is the parent of file system B.
This diagram shows a clone tree.
BRANCH
A clone tree branch is a set of clones whose data diverges from a common ancestor in the clone tree. In the example above, C and D are one branch of the clone tree, and E, F, and G are a second branch of the clone tree.
Depth is a term used to describe how many clones are between one file system and another in a clone tree. In the example above, the depth from G to E is 2, and the depth from G to A is 4.
Size is a term used to describe how many clones descend from a single parent. In the example above, the size of the clone tree from clone A is 6, but the size of the clone tree from F is only 1.
HYDRATION
Hydration is the process of copying metadata from the source to the clone. Hydration is an asynchronous process that starts when the clone is created. The clone is immediately available on creation and can be used for regular operations while hydration is in progress. You can see whether a clone is still in the process of hydration by visiting its Details page. See To view file system details.

Limitations and Considerations

Logical Organization

You can only create a clone in the same availability domain as its parent file system. See About Regions and Availability Domains for more information.

Clone Hydration

Performance

Creating a clone is instantaneous and you can immediately access the clone for both READ and WRITE operations. However, there is a minor performance impact on both the parent and clone when accessing shared data while hydration is in progress. Performance impact is more significant on the clone than the parent. The duration of impact depends on the size of the source.

If the clone and parent are concurrently hydrating, hydration can affect the performance of the clone tree root. When creating clones, we recommend that you do not have more than 10 clones hydrating within a clone tree concurrently.

In this diagram, file system A is the root of the clone tree. File systems B, C, D, E, F, and G are all concurrently hydrating, so the performance of file system A might be impacted.

This diagram shows a clone tree hydrating.

After hydration is complete, there is no further impact to the parent file system or clone tree root. You can see if hydration is in progress on a clone by viewing its Details page. See To view file system details.

Clone Tree Size and Depth

The number of clones in a clone tree that can hydrate concurrently is limited based on the following two values:
  • Maximum Size: 10 This value represents the maximum allowed number of clones in a clone tree concurrently hydrating from a single parent file system.
  • Maximum Depth: 5 This value represents the maximum number of unhydrated clones on a clone tree branch between the clone you're creating and its last hydrated ancestor.

Exceeding these limits causes the cloning operation to fail. Wait until enough clones complete hydration, and then try the operation again.

Deleting Resources

File Systems

You can delete a file system if it is not the root of a clone tree. If a file system is the root of a clone tree, all descendant clones must first be deleted.

If a clone parent is deleted while any of its descendants are still hydrating, the parent remains in the DELETING state until hydration is complete. The metered space associated with the clone parent remains in use until all hydration is complete for all descendant clones. While a file system is still in a DELETING state, its parent, children, and siblings cannot be deleted. A file system in a DELETING state cannot be cloned. However, you can still clone its siblings or children.

After deletion is complete, the parent of the deleted file system becomes the new parent of the descendant clones.

Source Snapshot

You can delete the source snapshot of a clone. If the source snapshot is deleted while a clone of it is being hydrated, the source snapshot remains in the DELETING state until hydration is complete.

Parent Snapshots

A clone inherits all snapshots from the parent. If you delete a snapshot within a parent file system while hydration is in progress, the snapshot remains in the DELETING state until hydration is complete. After hydration is complete, you can delete any snapshot in the parent or clone file system at any time.

See instructions for deleting file systems in Managing File Systems

See instructions for deleting snapshots in Managing Snapshots.

Metering and Billing

A parent file system is metered for all the data shared with its descendant clones. A clone is metered for its metadata and incremental changes made to its data. When a clone is deleted, all blocks that are referenced solely by that clone are reclaimed. If another clone is hydrating from the deleted clone, the referenced blocks are reclaimed after hydration is complete.

If you delete a parent clone, any data blocks shared by descendant clones cannot be released. Allocated blocks referenced by descendant clones are transferred to the new clone parent (the clone parent's parent) for metering purposes. You are not metered more than once for data shared between multiple file systems. For more information, see File System Usage and Metering.

Required IAM Service Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: Cloning a file system uses the CreateFileSystem API operation and requires the FILE_SYSTEM_CLONE permission. The policy in Let users create, manage, and delete file systems allows users to clone file systems. See the Policy Reference for more information.

If you're new to policies, see Getting Started with Policies and Common Policies.

Using the Console

To clone a file system

Before you can clone a file system, at least one snapshot must exist for the file system. See To create a snapshot for more information.

  1. Open the navigation menu and click Storage. Under File Storage, click File Systems.
  2. In the List Scope section, select a compartment.

  3. Find the file system you want to clone, click the Actions menu, and then click View File System Details.

  4. In the Snapshots list, find the snapshot you want to use as the source of the clone, click the Actions menu, and then click Clone.

    The clone is a copy of the file system data as it exists at the date and time that the selected snapshot was taken.

  5. In the Create Clone page, specify the details about the clone that aren't inherited from the parent file system. You can choose to accept the provided system defaults, or change them by clicking Edit Details. For a detailed description of each file system property and its defaults, see File System Information.

  6. Click Create.

Hydration begins immediately upon instantiation of the clone.

Cloned file systems are managed in the same way that any other file system is managed. See Managing File Systems for more information.

To view the clone's hydration status, source snapshot, parent file system, and other cloning information, visit the Details page of the cloned file system. See To view file system details.

Next Steps:

You can export, mount, and use the clone immediately for READ or WRITE operations after you create it. See To create an export for a file system and Mounting File Systems for more information.

Using the Command Line Interface (CLI)

To create a file system clone

To create a file system clone, use the file-system create command, and include the OCID of the file system snapshot you want to use as a source for the clone.

For example:
oci fs file-system create --availability-domain AAbC:US-ASHBURN-AD-1 --display-name "Clone_1" --compartment-id ocid1.compartment.oc1..<unique_id> --kms-key-id --kms-key-id ocid1.key.oc1.iad.<unique_id> --source-snapshot-id ocid1.snapshot.oc1..<unique_id>
To find all clones created from a specific source snapshot or parent file system

Open a command prompt and run oci fs file-system list to list all the file systems in a specified availability domain and compartment. Include either --source-snapshot-id or --parent-file-system-id.

An example using --source-snapshot-id.
oci fs file-system list --availability-domain <target_availability_domain> --compartment-id <target_compartment_id> --source-snapshot-id <snapshot_id>
An example using --parent-file-system-id.
oci fs file-system list --availability-domain <target_availability_domain> --compartment-id <target_compartment_id> --parent-filesystem-id <parent_filesystem_id>

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to create file system clones:

To create a cloned file system instead of a new file system, the CreateFileSystem operation requires the sourceSnapshotId parameter. For example:

POST /20171215/fileSystems
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
    "availabilityDomain": "pWEh:PHX-AD-2",
    "compartmentId": "ocid1.compartment.oc1..<unique_ID>",
    "displayName": "Clone_1",
    "freeformTags": {},
    "definedTags": {},
    "kmsKeyId": "ocid1.key.oc1..<unique_ID>", 
    "sourceSnapshotId": "ocid1.snapshot.oc1..<unique_ID>"
}

If you have issues managing clones, see Troubleshooting File System Clones.