# Managing metadata performance
You can update the metadata configuration of your FSx for Lustre file system without any disruption to your end users or applications by using the Amazon FSx console, Amazon FSx API, or AWS Command Line Interface (AWS CLI). The update procedure increases the number of provisioned Metadata IOPS for your file system.
**Note**
Enhanced metadata is available only for 2.15 file systems. You can increase metadata performance only on FSx for Lustre file systems created with the Persistent 2 deployment type and a metadata configuration specified. You cannot add or update the metadata configuration for an FSx for Lustre file system if the metadata configuration is not specified at the time of file system creation. This also applies to file systems restored from backups of 2.12 file systems which did not support enhanced metadata performance, or from 2.15 file systems which had no metadata configuration specified.
The increased metadata performance of your file system is available for use within minutes. You can update the metadata performance at anytime, as long as metadata performance increase requests are at least 6 hours apart. While scaling metadata performance, the file system may be unavailable for a few minutes. File operations issued by clients while the file system is unavailable will transparently retry and eventually succeed after metadata performance scaling is complete. You will be billed for the new metadata performance increase after it becomes available to you.
You can track the progress of a metadata performance increase at any time by using the Amazon FSx console, CLI, and API. For more information, see [Monitoring metadata configuration updates](monitoring-metadata-performance-increase.md).
**Topics**
+ [Lustre metadata performance configuration](#metadata-configuration)
+ [Considerations when increasing metadata performance](#metadata-scaling-considerations)
+ [When to increase metadata performance](#when-to-modify-metadata-performance)
+ [Increasing metadata performance](modify-metadata-performance.md)
+ [Changing the metadata configuration mode](switch-provisioning-mode.md)
+ [Monitoring metadata configuration updates](monitoring-metadata-performance-increase.md)
## Lustre metadata performance configuration
The number of provisioned Metadata IOPS determines the maximum rate of metadata operations that can be supported by the file system.
When you create the file system, you choose a metadata configuration mode:
+ For SSD file systems, you can choose Automatic mode if you want Amazon FSx to automatically provision and scale the Metadata IOPS on your file system based on your file system's storage capacity. Note that Intelligent-Tiering file systems don't support Automatic mode.
+ For SSD file systems, you can choose User-provisioned if you want to specify the number of Metadata IOPS to provision for your file system.
+ For Intelligent-Tiering file systems, you must choose User-provisioned mode. With User-provisioned mode, you can specify the number of Metadata IOPS to provision for your file system.
On SSD file systems, you can switch from Automatic mode to User-provisioned mode at any time. You can also switch from User-provisioned to Automatic mode if the number of Metadata IOPS provisioned on your file system matches the default number of Metadata IOPS provisioned in Automatic mode. Intelligent-Tiering file systems only support User-provisioned mode, so you can't switch metadata configuration modes.
Valid Metadata IOPS values are as follows:
+ For SSD file systems, valid Metadata IOPS values are 1500, 3000, 6000, and multiples of 12000 up to a maximum of 192000.
+ For Intelligent-Tiering file systems, valid Metadata IOPS values are 6000 and 12000.
If the metadata performance of your workload exceeds the number of Metadata IOPS provisioned in Automatic mode, you can use User-provisioned mode to increase the Metadata IOPS value for your file system.
You can view the current value of the file system's metadata server configuration as follows:
+ Using the console – On the **Summary** panel of the file system details page, the **Metadata IOPS** field shows the current value of the provisioned Metadata IOPS and the current metadata configuration mode of the file system.
+ Using the CLI or API – Use the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) CLI command or the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API operation, and look for the `MetadataConfiguration` property.
## Considerations when increasing metadata performance
Here are a few important considerations when increasing your metadata performance:
+ **Metadata performance increase only** – You can only *increase* the number of Metadata IOPS for a file system; you cannot decrease the number of Metadata IOPS.
+ **Specifying Metadata IOPS in Automatic mode not supported** – You can't specify the number of Metadata IOPS on a file system that is in Automatic mode. You'll have to switch to User-provisioned mode and then make the request. For more information, see [Changing the metadata configuration mode](switch-provisioning-mode.md).
+ **Metadata IOPS for data written before scaling** – When scaling Metadata IOPS beyond 12000, FSx for Lustre adds new metadata servers to your file system. New metadata is automatically distributed across all servers for improved performance. However, existing metadata and subdirectories created before scaling remain on original servers, with no increase in Metadata IOPS.
+ **Time between increases** – You can't make further metadata performance increases on a file system until 6 hours after the last increase was requested.
+ **Concurrent metadata performance and SSD storage increases** – You cannot scale metadata performance and file system storage capacity concurrently.
## When to increase metadata performance
Increase the number of Metadata IOPS when you need to run workloads that require higher levels of metadata performance than is provisioned by default on your file system. You can monitor your metadata performance on the AWS Management Console by using the `Metadata IOPS Utilization` graph which provides the percentage of provisioned metadata server performance you are consuming on your file system.
You can also monitor your metadata performance using more granular CloudWatch metrics. CloudWatch metrics include `DiskReadOperations` and `DiskWriteOperations`, which provide the volume of metadata server operations that require disk IO, as well as granular metrics for metadata operations including file and directory creation, stats, reads, and deletes. For more information, see [FSx for Lustre metadata metrics](fs-metrics.md#fs-metadata-metrics).
# Increasing metadata performance
You can increase a file system's metadata performance by using the Amazon FSx console, the AWS CLI, or the Amazon FSx API.
## To increase metadata performance for a file system (console)
1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/).
1. In the left navigation pane, choose **File systems**. In the **File systems** list, choose the FSx for Lustre file system that you want to increase metadata performance for.
1. For **Actions**, choose **Update Metadata IOPS**. Or, in the **Summary** panel, choose **Update** next to the file system's **Metadata IOPS** field.
The **Update Metadata IOPS** dialog box appears.
1. Choose **User-provisioned**.
1. For **Desired Metadata IOPS**, choose the new Metadata IOPS value. The value you enter must be greater than or equal to the current Metadata IOPS value.
+ For SSD file systems, valid values are `1500`, `3000`, `6000`, `12000`, and multiples of `12000` up to a maximum of `192000`.
+ For Intelligent-Tiering file systems, valid values are `6000` and `12000`.
1. Choose **Update**.
## To increase metadata performance for a file system (CLI)
To increase the metadata performance for an FSx for Lustre file system, use the AWS CLI command [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html) (UpdateFileSystem is the equivalent API action). Set the following parameters:
+ Set `--file-system-id` to the ID of the file system that you are updating.
+ To increase your metadata performance, use the `--lustre-configuration MetadataConfiguration` property. This property has two parameters, `Mode` and `Iops`.
1. If your file system is in USER\$1PROVISIONED mode, using `Mode` is optional (if used, set `Mode` to `USER_PROVISIONED`).
If your SSD file system is in AUTOMATIC mode, set `Mode` to `USER_PROVISIONED` (which switches the file system mode to USER\$1PROVISIONED in addition to increasing the Metadata IOPS value).
1. For SSD file systems, set `Iops` to a value of `1500`, `3000`, `6000`, `12000`, or multiples of `12000` up to a maximum of `192000`. For Intelligent-Tiering file systems, set `Iops` to `6000` or `12000`. The value you enter must be greater than or equal to the current Metadata IOPS value.
The following example updates the provisioned Metadata IOPS to 12000.
```
aws fsx update-file-system \
--file-system-id fs-0123456789abcdef0 \
--lustre-configuration 'MetadataConfiguration={Mode=USER_PROVISIONED,Iops=12000}'
```
# Changing the metadata configuration mode
For SSD-based file systems, you can change the metadata configuration mode of an existing file system using the AWS console and CLI, as explained in the following procedures.
When switching from Automatic mode to User-provisioned mode, you must provide a Metadata IOPS value greater than or equal to the current file system Metadata IOPS value.
If you request to switch from User-provisioned to Automatic mode and the current Metadata IOPS value is greater than the automated default, Amazon FSx rejects the request, because downscaling Metadata IOPS is not supported. To unblock mode switch, you must increase storage capacity to match your current Metadata IOPS in Automatic mode in order to enable mode switch again.
You can change a file system's metadata configuration mode by using the Amazon FSx console, the AWS CLI, or the Amazon FSx API.
## To change the metadata configuration mode for a file system (console)
1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/).
1. In the left navigation pane, choose **File systems**. In the **File systems** list, choose the FSx for Lustre file system that you want to change the metadata configuration mode for.
1. For **Actions**, choose **Update Metadata IOPS**. Or, in the **Summary** panel, choose **Update** next to the file system's **Metadata IOPS** field.
The **Update Metadata IOPS** dialog box appears.
1. Do one of the following.
+ To switch from User-provisioned mode to Automatic mode, choose **Automatic**.
+ To switch from Automatic mode to User-provisioned mode, choose **User-provisioned**. Then, for **Desired Metadata IOPS**, provide a Metadata IOPS value greater than or equal to the current file system Metadata IOPS value.
1. Choose **Update**.
## To change the metadata configuration mode for an SSD file system (CLI)
To change the metadata configuration mode for an SSD FSx for Lustre file system, use the AWS CLI command [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html) (UpdateFileSystem is the equivalent API action). Set the following parameters:
+ Set `--file-system-id` to the ID of the file system that you are updating.
+ To change the metadata configuration mode on SSD-based file systems, use the `--lustre-configuration MetadataConfiguration` property. This property has two parameters, `Mode` and `Iops`.
+ To switch your SSD file system from AUTOMATIC mode to USER\$1PROVISIONED mode, set `Mode` to `USER_PROVISIONED` and `Iops` to a Metadata IOPS value greater than or equal to the current file system Metadata IOPS value. For example:
```
aws fsx update-file-system \
--file-system-id fs-0123456789abcdef0 \
--lustre-configuration 'MetadataConfiguration={Mode=USER_PROVISIONED,Iops=96000}'
```
+ To switch from USER\$1PROVISIONED mode to AUTOMATIC mode, set `Mode` to `AUTOMATIC` and do not use the `Iops` parameter. For example:
```
aws fsx update-file-system \
--file-system-id fs-0123456789abcdef0 \
--lustre-configuration 'MetadataConfiguration={Mode=AUTOMATIC}'
```
# Monitoring metadata configuration updates
You can monitor the progress of metadata configuration updates by using the Amazon FSx console, the API, or the AWS CLI.
## Monitoring metadata configuration updates (console)
You can monitor metadata configuration updates in the **Updates** tab on the **File system details** page.
For metadata configuration updates, you can view the following information:
****Update type****
Supported types are **Metadata IOPS** and **Metadata configuration mode**.
****Target value****
The updated value for the file system's Metadata IOPS or Metadata configuration mode.
****Status****
The current status of the update. The possible values are as follows:
+ **Pending** – Amazon FSx has received the update request, but has not started processing it.
+ **In progress** – Amazon FSx is processing the update request.
+ **Completed** – The update finished successfully.
+ **Failed** – The update request failed. Choose the question mark (**?**) to see details on why the request failed.
****Request time****
The time that Amazon FSx received the update action request.
## Monitoring metadata configuration updates (CLI)
You can view and monitor metadata configuration update requests using the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) AWS CLI command and the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API operation. The `AdministrativeActions` array lists the 10 most recent update actions for each administrative action type. When you update a file system's metadata performance or metadata configuration mode, a `FILE_SYSTEM_UPDATE` `AdministrativeActions` is generated.
The following example shows an excerpt of the response of a `describe-file-systems` CLI command. The file system has a pending administrative action to increase the Metadata IOPS to 96000 and the metadata configuration mode to USER\$1PROVISIONED.
```
"AdministrativeActions": [
{
"AdministrativeActionType": "FILE_SYSTEM_UPDATE",
"RequestTime": 1678840205.853,
"Status": "PENDING",
"TargetFileSystemValues": {
"LustreConfiguration": {
"MetadataConfiguration": {
"Iops": 96000,
"Mode": USER_PROVISIONED
}
}
}
}
]
```
Amazon FSx processes the `FILE_SYSTEM_UPDATE` action, modifying the file system's Metadata IOPS and metadata configuration mode. When the new metadata resources are available to the file system the `FILE_SYSTEM_UPDATE` status changes to `COMPLETED`.
If the metadata configuration update request fails, the status of the `FILE_SYSTEM_UPDATE` action changes to `FAILED`, as shown in the following example. The `FailureDetails` property provides information about the failure.
```
"AdministrativeActions": [
{
"AdministrativeActionType": "FILE_SYSTEM_UPDATE",
"RequestTime": 1678840205.853,
"Status": "FAILED",
"TargetFileSystemValues": {
"LustreConfiguration": {
"MetadataConfiguration": {
"Iops": 96000,
"Mode": USER_PROVISIONED
}
}
},
"FailureDetails": {
"Message": "failure-message"
}
}
]
```