Skip to main content

file_systems

Creates, updates, deletes, gets or lists a file_systems resource.

Overview​

Namefile_systems
TypeResource
Idaws.fsx.file_systems

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
administrative_actionsarrayA list of administrative actions for the file system that are in process or waiting to be processed. Administrative actions describe changes to the Amazon FSx system that you have initiated using the UpdateFileSystem operation.
creation_timestring (date-time)The time that the file system was created, in seconds (since 1970-01-01T00:00:00Z), also known as Unix time.
dns_namestringThe Domain Name System (DNS) name for the file system. (pattern: <code>^((fs|fc)i?-[0-9a-f]{8,}..{4,253})$</code>)
failure_detailsobjectA structure providing details of any failures that occurred.
file_system_idstringThe system-generated, unique 17-digit ID of the file system. (pattern: <code>^(fs-[0-9a-f]{8,})$</code>)
file_system_typestringThe type of Amazon FSx file system, which can be LUSTRE, WINDOWS, ONTAP, or OPENZFS. (WINDOWS, LUSTRE, ONTAP, OPENZFS)
file_system_type_versionstringThe Lustre version of the Amazon FSx for Lustre file system, which can be 2.10, 2.12, or 2.15. (pattern: <code>^[0-9](.[0-9])$</code>)
kms_key_idstringSpecifies the ID of the Key Management Service (KMS) key to use for encrypting data on Amazon FSx file systems, as follows: Amazon FSx for Lustre PERSISTENT_1 and PERSISTENT_2 deployment types only. SCRATCH_1 and SCRATCH_2 types are encrypted using the Amazon FSx service KMS key for your account. Amazon FSx for NetApp ONTAP Amazon FSx for OpenZFS Amazon FSx for Windows File Server If a KmsKeyId isn't specified, the Amazon FSx-managed KMS key for your account is used. For more information, see Encrypt in the Key Management Service API Reference. (pattern: <code>^.{1,2048}$</code>)
lifecyclestringThe lifecycle status of the file system. The following are the possible values and what they mean: AVAILABLE - The file system is in a healthy state, and is reachable and available for use. CREATING - Amazon FSx is creating the new file system. DELETING - Amazon FSx is deleting an existing file system. FAILED - An existing file system has experienced an unrecoverable failure. When creating a new file system, Amazon FSx was unable to create the file system. MISCONFIGURED - The file system is in a failed but recoverable state. MISCONFIGURED_UNAVAILABLE - (Amazon FSx for Windows File Server only) The file system is currently unavailable due to a change in your Active Directory configuration. UPDATING - The file system is undergoing a customer-initiated update. (AVAILABLE, CREATING, FAILED, DELETING, MISCONFIGURED, UPDATING, MISCONFIGURED_UNAVAILABLE)
lustre_configurationobjectThe configuration for the Amazon FSx for Lustre file system.
network_interface_idsarrayThe IDs of the elastic network interfaces from which a specific file system is accessible. The elastic network interface is automatically created in the same virtual private cloud (VPC) that the Amazon FSx file system was created in. For more information, see Elastic Network Interfaces in the Amazon EC2 User Guide. For an Amazon FSx for Windows File Server file system, you can have one network interface ID. For an Amazon FSx for Lustre file system, you can have more than one.
network_typestringThe network type of the file system. (IPV4, DUAL)
ontap_configurationobjectThe configuration for this Amazon FSx for NetApp ONTAP file system.
open_zfs_configurationobjectThe configuration for this Amazon FSx for OpenZFS file system.
owner_idstringThe Amazon Web Services account that created the file system. If the file system was created by a user in IAM Identity Center, the Amazon Web Services account to which the IAM user belongs is the owner. (pattern: <code>^\d{12}$</code>)
resource_arnstringThe Amazon Resource Name (ARN) of the file system resource. (pattern: <code>^arn:(?=[^:]+:fsx:[^:]+:\d{12}:)((|(?=[a-z0-9-.]{1,63})(?!\d{1,3}(.\d{1,3}){3})(?![^:]-{2})(?![^:]-.)(?![^:].-)[a-z0-9].(?<!-)):){4}(?!/).{0,1024}$</code>)
storage_capacityintegerThe storage capacity of the file system in gibibytes (GiB). Amazon FSx responds with an HTTP status code 400 (Bad Request) if the value of StorageCapacity is outside of the minimum or maximum values.
storage_typestringThe type of storage the file system is using. If set to SSD, the file system uses solid state drive storage. If set to HDD, the file system uses hard disk drive storage. If set to INTELLIGENT_TIERING, the file system uses fully elastic, intelligently-tiered storage. (SSD, HDD, INTELLIGENT_TIERING)
subnet_idsarraySpecifies the IDs of the subnets that the file system is accessible from. For the Amazon FSx Windows and ONTAP MULTI_AZ_1 file system deployment type, there are two subnet IDs, one for the preferred file server and one for the standby file server. The preferred file server subnet identified in the PreferredSubnetID property. All other file systems have only one subnet ID. For FSx for Lustre file systems, and Single-AZ Windows file systems, this is the ID of the subnet that contains the file system's endpoint. For MULTI_AZ_1 Windows and ONTAP file systems, the file system endpoint is available in the PreferredSubnetID.
tagsarrayA list of Tag values, with a maximum of 50 elements.
vpc_idstringThe ID of the primary virtual private cloud (VPC) for the file system. (pattern: <code>^(vpc-[0-9a-f]{8,})$</code>)
windows_configurationobjectThe configuration for this Amazon FSx for Windows File Server file system.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_file_systemsselectregionReturns the description of specific Amazon FSx file systems, if a FileSystemIds value is provided for that file system. Otherwise, it returns descriptions of all file systems owned by your Amazon Web Services account in the Amazon Web Services Region of the endpoint that you're calling. When retrieving all file system descriptions, you can optionally specify the MaxResults parameter to limit the number of descriptions in a response. If more file system descriptions remain, Amazon FSx returns a NextToken value in the response. In this case, send a later request with the NextToken request parameter set to the value of NextToken from the last response. This operation is used in an iterative process to retrieve a list of your file system descriptions. DescribeFileSystems is called first without a NextTokenvalue. Then the operation continues to be called with the NextToken parameter set to the value of the last NextToken value until a response has no NextToken. When using this operation, keep the following in mind: The implementation might return fewer than MaxResults file system descriptions while still including a NextToken value. The order of file systems returned in the response of one DescribeFileSystems call and the order of file systems returned across the responses of a multicall iteration is unspecified.
create_file_systeminsertregion, FileSystemType, SubnetIdsCreates a new, empty Amazon FSx file system. You can create the following supported Amazon FSx file systems using the CreateFileSystem API operation: Amazon FSx for Lustre Amazon FSx for NetApp ONTAP Amazon FSx for OpenZFS Amazon FSx for Windows File Server This operation requires a client request token in the request that Amazon FSx uses to ensure idempotent creation. This means that calling the operation multiple times with the same client request token has no effect. By using the idempotent operation, you can retry a CreateFileSystem operation without the risk of creating an extra file system. This approach can be useful when an initial call fails in a way that makes it unclear whether a file system was created. Examples are if a transport level timeout occurred, or your connection was reset. If you use the same client request token and the initial call created a file system, the client receives success as long as the parameters are the same. If a file system with the specified client request token exists and the parameters match, CreateFileSystem returns the description of the existing file system. If a file system with the specified client request token exists and the parameters don't match, this call returns IncompatibleParameterError. If a file system with the specified client request token doesn't exist, CreateFileSystem does the following: Creates a new, empty Amazon FSx file system with an assigned ID, and an initial lifecycle state of CREATING. Returns the description of the file system in JSON format. The CreateFileSystem call returns while the file system's lifecycle state is still CREATING. You can check the file-system creation status by calling the DescribeFileSystems operation, which returns the file system state along with other information.
update_file_systemupdateregion, FileSystemIdUse this operation to update the configuration of an existing Amazon FSx file system. You can update multiple properties in a single request. For FSx for Windows File Server file systems, you can update the following properties: AuditLogConfiguration AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DiskIopsConfiguration SelfManagedActiveDirectoryConfiguration StorageCapacity StorageType ThroughputCapacity WeeklyMaintenanceStartTime For FSx for Lustre file systems, you can update the following properties: AutoImportPolicy AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DataCompressionType FileSystemTypeVersion LogConfiguration LustreReadCacheConfiguration LustreRootSquashConfiguration MetadataConfiguration PerUnitStorageThroughput StorageCapacity ThroughputCapacity WeeklyMaintenanceStartTime For FSx for ONTAP file systems, you can update the following properties: AddRouteTableIds AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DiskIopsConfiguration EndpointIpv6AddressRange FsxAdminPassword HAPairs RemoveRouteTableIds StorageCapacity ThroughputCapacity ThroughputCapacityPerHAPair WeeklyMaintenanceStartTime For FSx for OpenZFS file systems, you can update the following properties: AddRouteTableIds AutomaticBackupRetentionDays CopyTagsToBackups CopyTagsToVolumes DailyAutomaticBackupStartTime DiskIopsConfiguration EndpointIpv6AddressRange ReadCacheConfiguration RemoveRouteTableIds StorageCapacity ThroughputCapacity WeeklyMaintenanceStartTime
delete_file_systemdeleteregionDeletes a file system. After deletion, the file system no longer exists, and its data is gone. Any existing automatic backups and snapshots are also deleted. To delete an Amazon FSx for NetApp ONTAP file system, first delete all the volumes and storage virtual machines (SVMs) on the file system. Then provide a FileSystemId value to the DeleteFileSystem operation. Before deleting an Amazon FSx for OpenZFS file system, make sure that there aren't any Amazon S3 access points attached to any volume. For more information on how to list S3 access points that are attached to volumes, see Listing S3 access point attachments. For more information on how to delete S3 access points, see Deleting an S3 access point attachment. By default, when you delete an Amazon FSx for Windows File Server file system, a final backup is created upon deletion. This final backup isn't subject to the file system's retention policy, and must be manually deleted. To delete an Amazon FSx for Lustre file system, first unmount it from every connected Amazon EC2 instance, then provide a FileSystemId value to the DeleteFileSystem operation. By default, Amazon FSx will not take a final backup when the DeleteFileSystem operation is invoked. On file systems not linked to an Amazon S3 bucket, set SkipFinalBackup to false to take a final backup of the file system you are deleting. Backups cannot be enabled on S3-linked file systems. To ensure all of your data is written back to S3 before deleting your file system, you can either monitor for the AgeOfOldestQueuedMessage metric to be zero (if using automatic export) or you can run an export data repository task. If you have automatic export enabled and want to use an export data repository task, you have to disable automatic export before executing the export data repository task. The DeleteFileSystem operation returns while the file system has the DELETING status. You can check the file system deletion status by calling the DescribeFileSystems operation, which returns a list of file systems in your account. If you pass the file system ID for a deleted file system, the DescribeFileSystems operation returns a FileSystemNotFound error. If a data repository task is in a PENDING or EXECUTING state, deleting an Amazon FSx for Lustre file system will fail with an HTTP status code 400 (Bad Request). The data in a deleted file system is also deleted and can't be recovered by any means.
release_file_system_nfs_v3_locksexecregion, FileSystemIdReleases the file system lock from an Amazon FSx for OpenZFS file system.
start_misconfigured_state_recoveryexecregion, FileSystemIdAfter performing steps to repair the Active Directory configuration of an FSx for Windows File Server file system, use this action to initiate the process of Amazon FSx attempting to reconnect to the file system.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Returns the description of specific Amazon FSx file systems, if a FileSystemIds value is provided for that file system. Otherwise, it returns descriptions of all file systems owned by your Amazon Web Services account in the Amazon Web Services Region of the endpoint that you're calling. When retrieving all file system descriptions, you can optionally specify the MaxResults parameter to limit the number of descriptions in a response. If more file system descriptions remain, Amazon FSx returns a NextToken value in the response. In this case, send a later request with the NextToken request parameter set to the value of NextToken from the last response. This operation is used in an iterative process to retrieve a list of your file system descriptions. DescribeFileSystems is called first without a NextTokenvalue. Then the operation continues to be called with the NextToken parameter set to the value of the last NextToken value until a response has no NextToken. When using this operation, keep the following in mind: The implementation might return fewer than MaxResults file system descriptions while still including a NextToken value. The order of file systems returned in the response of one DescribeFileSystems call and the order of file systems returned across the responses of a multicall iteration is unspecified.

SELECT
administrative_actions,
creation_time,
dns_name,
failure_details,
file_system_id,
file_system_type,
file_system_type_version,
kms_key_id,
lifecycle,
lustre_configuration,
network_interface_ids,
network_type,
ontap_configuration,
open_zfs_configuration,
owner_id,
resource_arn,
storage_capacity,
storage_type,
subnet_ids,
tags,
vpc_id,
windows_configuration
FROM aws.fsx.file_systems
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates a new, empty Amazon FSx file system. You can create the following supported Amazon FSx file systems using the CreateFileSystem API operation: Amazon FSx for Lustre Amazon FSx for NetApp ONTAP Amazon FSx for OpenZFS Amazon FSx for Windows File Server This operation requires a client request token in the request that Amazon FSx uses to ensure idempotent creation. This means that calling the operation multiple times with the same client request token has no effect. By using the idempotent operation, you can retry a CreateFileSystem operation without the risk of creating an extra file system. This approach can be useful when an initial call fails in a way that makes it unclear whether a file system was created. Examples are if a transport level timeout occurred, or your connection was reset. If you use the same client request token and the initial call created a file system, the client receives success as long as the parameters are the same. If a file system with the specified client request token exists and the parameters match, CreateFileSystem returns the description of the existing file system. If a file system with the specified client request token exists and the parameters don't match, this call returns IncompatibleParameterError. If a file system with the specified client request token doesn't exist, CreateFileSystem does the following: Creates a new, empty Amazon FSx file system with an assigned ID, and an initial lifecycle state of CREATING. Returns the description of the file system in JSON format. The CreateFileSystem call returns while the file system's lifecycle state is still CREATING. You can check the file-system creation status by calling the DescribeFileSystems operation, which returns the file system state along with other information.

INSERT INTO aws.fsx.file_systems (
ClientRequestToken,
FileSystemType,
StorageCapacity,
StorageType,
SubnetIds,
SecurityGroupIds,
Tags,
KmsKeyId,
WindowsConfiguration,
LustreConfiguration,
OntapConfiguration,
FileSystemTypeVersion,
OpenZFSConfiguration,
NetworkType,
region
)
SELECT 
'{{ ClientRequestToken }}',
'{{ FileSystemType }}' /* required */,
{{ StorageCapacity }},
'{{ StorageType }}',
'{{ SubnetIds }}' /* required */,
'{{ SecurityGroupIds }}',
'{{ Tags }}',
'{{ KmsKeyId }}',
'{{ WindowsConfiguration }}',
'{{ LustreConfiguration }}',
'{{ OntapConfiguration }}',
'{{ FileSystemTypeVersion }}',
'{{ OpenZFSConfiguration }}',
'{{ NetworkType }}',
'{{ region }}'
RETURNING
file_system
;

UPDATE examples​

Use this operation to update the configuration of an existing Amazon FSx file system. You can update multiple properties in a single request. For FSx for Windows File Server file systems, you can update the following properties: AuditLogConfiguration AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DiskIopsConfiguration SelfManagedActiveDirectoryConfiguration StorageCapacity StorageType ThroughputCapacity WeeklyMaintenanceStartTime For FSx for Lustre file systems, you can update the following properties: AutoImportPolicy AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DataCompressionType FileSystemTypeVersion LogConfiguration LustreReadCacheConfiguration LustreRootSquashConfiguration MetadataConfiguration PerUnitStorageThroughput StorageCapacity ThroughputCapacity WeeklyMaintenanceStartTime For FSx for ONTAP file systems, you can update the following properties: AddRouteTableIds AutomaticBackupRetentionDays DailyAutomaticBackupStartTime DiskIopsConfiguration EndpointIpv6AddressRange FsxAdminPassword HAPairs RemoveRouteTableIds StorageCapacity ThroughputCapacity ThroughputCapacityPerHAPair WeeklyMaintenanceStartTime For FSx for OpenZFS file systems, you can update the following properties: AddRouteTableIds AutomaticBackupRetentionDays CopyTagsToBackups CopyTagsToVolumes DailyAutomaticBackupStartTime DiskIopsConfiguration EndpointIpv6AddressRange ReadCacheConfiguration RemoveRouteTableIds StorageCapacity ThroughputCapacity WeeklyMaintenanceStartTime

UPDATE aws.fsx.file_systems
SET 
FileSystemId = '{{ FileSystemId }}',
ClientRequestToken = '{{ ClientRequestToken }}',
StorageCapacity = {{ StorageCapacity }},
WindowsConfiguration = '{{ WindowsConfiguration }}',
LustreConfiguration = '{{ LustreConfiguration }}',
OntapConfiguration = '{{ OntapConfiguration }}',
OpenZFSConfiguration = '{{ OpenZFSConfiguration }}',
StorageType = '{{ StorageType }}',
FileSystemTypeVersion = '{{ FileSystemTypeVersion }}',
NetworkType = '{{ NetworkType }}'
WHERE 
region = '{{ region }}' --required
AND FileSystemId = '{{ FileSystemId }}' --required
RETURNING
file_system;

DELETE examples​

Deletes a file system. After deletion, the file system no longer exists, and its data is gone. Any existing automatic backups and snapshots are also deleted. To delete an Amazon FSx for NetApp ONTAP file system, first delete all the volumes and storage virtual machines (SVMs) on the file system. Then provide a FileSystemId value to the DeleteFileSystem operation. Before deleting an Amazon FSx for OpenZFS file system, make sure that there aren't any Amazon S3 access points attached to any volume. For more information on how to list S3 access points that are attached to volumes, see Listing S3 access point attachments. For more information on how to delete S3 access points, see Deleting an S3 access point attachment. By default, when you delete an Amazon FSx for Windows File Server file system, a final backup is created upon deletion. This final backup isn't subject to the file system's retention policy, and must be manually deleted. To delete an Amazon FSx for Lustre file system, first unmount it from every connected Amazon EC2 instance, then provide a FileSystemId value to the DeleteFileSystem operation. By default, Amazon FSx will not take a final backup when the DeleteFileSystem operation is invoked. On file systems not linked to an Amazon S3 bucket, set SkipFinalBackup to false to take a final backup of the file system you are deleting. Backups cannot be enabled on S3-linked file systems. To ensure all of your data is written back to S3 before deleting your file system, you can either monitor for the AgeOfOldestQueuedMessage metric to be zero (if using automatic export) or you can run an export data repository task. If you have automatic export enabled and want to use an export data repository task, you have to disable automatic export before executing the export data repository task. The DeleteFileSystem operation returns while the file system has the DELETING status. You can check the file system deletion status by calling the DescribeFileSystems operation, which returns a list of file systems in your account. If you pass the file system ID for a deleted file system, the DescribeFileSystems operation returns a FileSystemNotFound error. If a data repository task is in a PENDING or EXECUTING state, deleting an Amazon FSx for Lustre file system will fail with an HTTP status code 400 (Bad Request). The data in a deleted file system is also deleted and can't be recovered by any means.

DELETE FROM aws.fsx.file_systems
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Releases the file system lock from an Amazon FSx for OpenZFS file system.

EXEC aws.fsx.file_systems.release_file_system_nfs_v3_locks 
@region='{{ region }}' --required 
@@json=
'{
"FileSystemId": "{{ FileSystemId }}", 
"ClientRequestToken": "{{ ClientRequestToken }}"
}'
;
Last updated on