Oracle Cloud Infrastructure Documentation

Cloning File Systems

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.

You can perform the following cloning tasks:

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 Creating an Export 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. For more information, see Getting a File System's 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 Getting a File System's Details for more information.

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 Policy Reference for more information.

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