Amazon EFS integration
Amazon Elastic File System (Amazon EFS) provides serverless, fully elastic file storage so that you can share
file data without provisioning or managing storage capacity and performance. With Amazon EFS, you
can create a file system and then mount it in your VPC through the NFS versions 4.0 and 4.1
(NFSv4) protocol. Then you can use the EFS file system like any other POSIX-compliant file
system. For general information, see What is Amazon Elastic File System? and the AWS
blog Integrate Amazon RDS for Oracle with Amazon EFS
Topics
- Overview of Amazon EFS integration
- Configuring network permissions for RDS for Oracle integration with Amazon EFS
- Configuring IAM permissions for RDS for Oracle integration with Amazon EFS
- Adding the EFS_INTEGRATION option
- Configuring Amazon EFS file system permissions
- Transferring files between RDS for Oracle and an Amazon EFS file system
- Removing the EFS_INTEGRATION option
- Troubleshooting Amazon EFS integration
Overview of Amazon EFS integration
With Amazon EFS, you can transfer files between your RDS for Oracle DB instance and an EFS file system. For example, you can use EFS to support the following use cases:
-
Share a file system between applications and multiple database servers.
-
Create a shared directory for migration-related files, including transportable tablespace data files. For more information, see Migrating using Oracle transportable tablespaces.
-
Store and share archived redo log files without allocating additional storage space on the server.
-
Use Oracle Database utilities such as
UTL_FILE
to read and write files.
Advantages to Amazon EFS integration
When you choose an EFS file system over alternative data transfer solutions, you get the following benefits:
-
You can transfer Oracle Data Pump files between Amazon EFS and your RDS for Oracle DB instance. You don’t need to copy these files locally because Data Pump imports directly from the EFS file system. For more information, see Importing data into Oracle on Amazon RDS.
-
Data migration is faster than using a database link.
-
You avoid allocating storage space on your RDS for Oracle DB instance to hold the files.
-
An EFS file systems can automatically scale storage without requiring you to provision it.
-
Amazon EFS integration has no minimum fees or setup costs. You pay only for what you use.
Requirements for Amazon EFS integration
Make sure that you meet the following requirements:
-
Your database runs database version 19.0.0.0.ru-2022-07.rur-2022-07.r1 or later.
-
Your DB instance and your EFS file system are in the same AWS Region and the same VPC.
-
Your VPC has the
enableDnsSupport
attribute enabled. For more information, see DNS attributes in your VPC in the Amazon Virtual Private Cloud User Guide. -
Your EFS file system uses the Standard or Standard-IA storage class.
-
To be able to use a DNS name in the
mount
command, the following must be true:-
The connecting DB instance is inside a VPC and is configured to use the DNS server provided by Amazon. Custom DNS servers aren't supported.
-
The VPC of the connecting instance must have both DNS Resolution and DNS Hostnames enabled.
-
The connecting instance must be inside the same VPC as the EFS file system.
-
-
You use non-RDS solutions to back up your EFS file system. RDS for Oracle doesn't support automated backups or manual DB snapshots of an EFS file system. For more information, see Backing up your Amazon EFS file systems.
Configuring network permissions for RDS for Oracle integration with Amazon EFS
For RDS for Oracle to integrate with Amazon EFS, make sure that your DB instance has network access to an EFS file system. For more information, see Controlling network access to Amazon EFS file systems for NFS clients in the Amazon Elastic File System User Guide.
Topics
Controlling network access with security groups
You can control your DB instance access to EFS file systems using network layer security mechanisms such as VPC security groups. To allow access to an EFS file system for your DB instance, make sure that your EFS file system meets the following requirements:
-
An EFS mount target exists in every Availability Zone used by an RDS for Oracle DB instance.
An EFS mount target provides an IP address for an NFSv4 endpoint at which you can mount an EFS file system. You mount your file system using its DNS name, which resolves to the IP address of the EFS mount target in the used by the Availability Zone of your DB instance.
You can configure DB instances in different AZs to use the same EFS file system. For Multi-AZ, you need a mount point for each AZ in your deployment. You might need to move a DB instance to a different AZ. For these reasons, we recommend that you create an EFS mount point in each AZ in your VPC. By default, when you create a new EFS file system using the console, RDS creates mount targets for all AZs.
-
A security group is attached to the mount target.
-
The security group has an inbound rule to allow the network subnet or security group of the RDS for Oracle DB instance on TCP/2049 (Type NFS).
For more information, see Creating Amazon EFS file systems and Creating and managing EFS mount targets and security groups in the Amazon Elastic File System User Guide.
Controlling network access with file system policies
Amazon EFS integration with RDS for Oracle works with the default (empty) EFS file system policy. The default policy doesn't use IAM to authenticate. Instead, it grants full access to any anonymous client that can connect to the file system using a mount target. The default policy is in effect whenever a user-configured file system policy isn't in effect, including at file system creation. For more information, see Default EFS file system policy in the Amazon Elastic File System User Guide.
To strengthen access to your EFS file system for all clients, including RDS for Oracle, you can configure IAM permissions. In this approach, you create a file system policy. For more information, see Creating file system policies in the Amazon Elastic File System User Guide.
Configuring IAM permissions for RDS for Oracle integration with Amazon EFS
For RDS for Oracle to integrate with Amazon EFS, your DB instance must have IAM permissions to access an Amazon EFS file system.
Topics
Step 1: Create an IAM role for your DB instance and attach your policy
In this step, you create a role for your RDS for Oracle DB instance to allow Amazon RDS to access your EFS file system.
To create an IAM role to allow Amazon RDS access to an EFS file system
-
Open the IAM Management Console
. -
In the navigation pane, choose Roles.
-
Choose Create role.
-
For AWS service, choose RDS.
-
For Select your use case, choose RDS – Add Role to Database.
-
Choose Next.
-
Don't add any permissions policies. Choose Next.
-
Set Role name to a name for your IAM role, for example
rds-efs-integration-role
. You can also add an optional Description value. -
Choose Create role.
To limit the service's permissions to a specific resource, we recommend using the
aws:SourceArn
and aws:SourceAccount
global condition
context keys in resource-based trust relationships. This is the most effective way
to protect against the confused deputy problem.
You might use both global condition context keys and have the
aws:SourceArn
value contain the account ID. In this case, the
aws:SourceAccount
value and the account in the
aws:SourceArn
value must use the same account ID when used in the
same statement.
-
Use
aws:SourceArn
if you want cross-service access for a single resource. -
Use
aws:SourceAccount
if you want to allow any resource in that account to be associated with the cross-service use.
In the trust relationship, make sure to use the aws:SourceArn
global
condition context key with the full Amazon Resource Name (ARN) of the resources
accessing the role.
The following AWS CLI command creates the role named
for this
purpose.rds-efs-integration-role
Example
For Linux, macOS, or Unix:
aws iam create-role \ --role-name
rds-efs-integration-role
\ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount":my_account_ID
, "aws:SourceArn": "arn:aws:rds:Region
:my_account_ID
:db:dbname
" } } } ] }'
For Windows:
aws iam create-role ^ --role-name
rds-efs-integration-role
^ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount":my_account_ID
, "aws:SourceArn": "arn:aws:rds:Region
:my_account_ID
:db:dbname
" } } } ] }'
For more information, see Creating a role to delegate permissions to an IAM user in the IAM User Guide.
Step 2: Create a file system policy for your Amazon EFS file system
In this step, you create a file system policy for your EFS file system.
To create or edit an EFS file system policy
-
Open the EFS Management Console
. -
Choose File Systems.
-
On the File systems page, choose the file system that you want to edit or create a file system policy for. The details page for that file system is displayed.
-
Choose the File system policy tab.
If the policy is empty, then the default EFS file system policy is in use. For more information, see Default EFS file system policy in the Amazon Elastic File System User Guide.
-
Choose Edit. The File system policy page appears.
-
In Policy editor, enter a policy such as the following, and then choose Save.
{ "Version": "2012-10-17", "Id": "ExamplePolicy01", "Statement": [ { "Sid": "ExampleStatement01", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::
123456789012
:role/rds-efs-integration-role" }, "Action": [ "elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite", "elasticfilesystem:ClientRootAccess" ], "Resource": "arn:aws:elasticfilesystem:us-east-1
:123456789012
:file-system/fs-1234567890abcdef0
" } ] }
Step 3: Associate your IAM role with your RDS for Oracle DB instance
In this step, you associate your IAM role with your DB instance. Be aware of the following requirements:
-
You must have access to an IAM role with the required Amazon EFS permissions policy attached to it.
-
You can associate only one IAM role with your RDS for Oracle DB instance at a time.
-
The status of your instance must be Available.
For more information, see Identity and access management for Amazon EFS in the Amazon Elastic File System User Guide.
To associate your IAM role with your RDS for Oracle DB instance
Sign in to the AWS Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/
. -
Choose Databases.
-
If your database instance is unavailable, choose Actions and then Start. When the instance status shows Started, go to the next step.
-
Choose the Oracle DB instance name to display its details.
-
On the Connectivity & security tab, scroll down to the Manage IAM roles section at the bottom of the page.
-
Choose the role to add in the Add IAM roles to this instance section.
-
For Feature, choose EFS_INTEGRATION.
-
Choose Add role.
The following AWS CLI command adds the role to an Oracle DB instance named
.mydbinstance
Example
For Linux, macOS, or Unix:
aws rds add-role-to-db-instance \ --db-instance-identifier
mydbinstance
\ --feature-name EFS_INTEGRATION \ --role-arnyour-role-arn
For Windows:
aws rds add-role-to-db-instance ^ --db-instance-identifier
mydbinstance
^ --feature-name EFS_INTEGRATION ^ --role-arnyour-role-arn
Replace
with the role ARN
that you noted in a previous step. your-role-arn
EFS_INTEGRATION
must be specified
for the --feature-name
option.
Adding the EFS_INTEGRATION option
To integrate Amazon RDS for Oracle with Amazon EFS, your DB instance must be associated with an option
group that includes the EFS_INTEGRATION
option.
Multiple Oracle DB instances that belong to the same option group share the same EFS file system. Different DB instances can access the same data, but access can be divided by using different Oracle directories. For more information see Transferring files between RDS for Oracle and an Amazon EFS file system.
To configure an option group for Amazon EFS integration
-
Create a new option group or identify an existing option group to which you can add the
EFS_INTEGRATION
option.For information about creating an option group, see Creating an option group.
-
Add the
EFS_INTEGRATION
option to the option group. You need to specify theEFS_ID
file system ID and set theUSE_IAM_ROLE
flag.For more information, see Adding an option to an option group.
-
Associate the option group with your DB instance in either of the following ways:
-
Create a new Oracle DB instance and associate the option group with it. For information about creating a DB instance, see Creating an Amazon RDS DB instance.
-
Modify an Oracle DB instance to associate the option group with it. For information about modifying an Oracle DB instance, see Modifying an Amazon RDS DB instance.
-
To configure an option group for EFS integration
-
Create a new option group or identify an existing option group to which you can add the
EFS_INTEGRATION
option.For information about creating an option group, see Creating an option group.
-
Add the
EFS_INTEGRATION
option to the option group.For example, the following AWS CLI command adds the
EFS_INTEGRATION
option to an option group namedmyoptiongroup
.Example
For Linux, macOS, or Unix:
aws rds add-option-to-option-group \ --option-group-name
myoptiongroup
\ --options "OptionName=EFS_INTEGRATION,OptionSettings=\ [{Name=EFS_ID,Value=fs-1234567890abcdef0},{Name=USE_IAM_ROLE,Value=TRUE}]"For Windows:
aws rds add-option-to-option-group ^ --option-group-name
myoptiongroup
^ --options "OptionName=EFS_INTEGRATION,OptionSettings=^ [{Name=EFS_ID,Value=fs-1234567890abcdef0},{Name=USE_IAM_ROLE,Value=TRUE}]" -
Associate the option group with your DB instance in either of the following ways:
-
Create a new Oracle DB instance and associate the option group with it. For information about creating a DB instance, see Creating an Amazon RDS DB instance.
-
Modify an Oracle DB instance to associate the option group with it. For information about modifying an Oracle DB instance, see Modifying an Amazon RDS DB instance.
-
Configuring Amazon EFS file system permissions
By default, only the root user (UID 0
) has read, write, and execute
permissions for a newly created EFS file system. For other users to modify the file system,
the root user must explicitly grant them access. The user for the RDS for Oracle DB instance is in
the others
category. For more information, see Working with users, groups, and
permissions at the Network File System (NFS) Level in the Amazon Elastic File System
User Guide.
To allow your RDS for Oracle DB instance to read and write files on an EFS file system, do the following:
-
Mount an EFS file system locally on your Amazon EC2 or on-premises instance.
-
Configure fine grain permissions.
For example, to grant other
users permissions to write to the EFS file system
root, run chmod 777
on this directory. For more information, see Example Amazon EFS file system use cases and permissions in the Amazon Elastic File System
User Guide.
Transferring files between RDS for Oracle and an Amazon EFS file system
To transfer files between an RDS for Oracle instance and an Amazon EFS file system, create at least one Oracle directory and configure EFS file system permissions to control DB instance access.
Creating an Oracle directory
To create an Oracle directory, use the procedure
rdsadmin.rdsadmin_util.create_directory_efs
. The procedure has the
following parameters.
Parameter name | Data type | Default | Required | Description |
---|---|---|---|---|
|
VARCHAR2 |
– |
Yes |
The name of the Oracle directory. |
|
VARCHAR2 |
– |
Yes |
The path on the EFS file system. The prefix of the path name uses
the pattern For example, if your EFS file system is named
|
Assume that you create a subdirectory named /datapump1
on the EFS file
system fs-1234567890abcdef0
. The following example creates an Oracle
directory DATA_PUMP_DIR_EFS
that points to the /datapump1
directory on the EFS file system. The file system path value for the
p_path_on_efs
parameter is prefixed with the string
/rdsefs-
.
BEGIN rdsadmin.rdsadmin_util.create_directory_efs( p_directory_name => 'DATA_PUMP_DIR_EFS', p_path_on_efs => '/rdsefs-
fs-1234567890abcdef0
/datapump1
'); END; /
Transferring data to and from an EFS file system: examples
The following example uses Oracle Data Pump to export the table named
MY_TABLE
to file datapump.dmp
. This file resides on an EFS
file system.
DECLARE v_hdnl NUMBER; BEGIN v_hdnl := DBMS_DATAPUMP.OPEN(operation => 'EXPORT', job_mode => 'TABLE', job_name=>null); DBMS_DATAPUMP.ADD_FILE( handle => v_hdnl, filename => 'datapump.dmp', directory => 'DATA_PUMP_DIR_EFS', filetype => dbms_datapump.ku$_file_type_dump_file); DBMS_DATAPUMP.ADD_FILE( handle => v_hdnl, filename => 'datapump-exp.log', directory => 'DATA_PUMP_DIR_EFS', filetype => dbms_datapump.ku$_file_type_log_file); DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'NAME_EXPR','IN (''MY_TABLE'')'); DBMS_DATAPUMP.START_JOB(v_hdnl); END; /
The following example uses Oracle Data Pump to import the table named
MY_TABLE
from file datapump.dmp
. This file resides on an
EFS file system.
DECLARE v_hdnl NUMBER; BEGIN v_hdnl := DBMS_DATAPUMP.OPEN( operation => 'IMPORT', job_mode => 'TABLE', job_name => null); DBMS_DATAPUMP.ADD_FILE( handle => v_hdnl, filename => 'datapump.dmp', directory => 'DATA_PUMP_DIR_EFS', filetype => dbms_datapump.ku$_file_type_dump_file ); DBMS_DATAPUMP.ADD_FILE( handle => v_hdnl, filename => 'datapump-imp.log', directory => 'DATA_PUMP_DIR_EFS', filetype => dbms_datapump.ku$_file_type_log_file); DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'NAME_EXPR','IN (''MY_TABLE'')'); DBMS_DATAPUMP.START_JOB(v_hdnl); END; /
For more information, see Importing data into Oracle on Amazon RDS.
Removing the EFS_INTEGRATION option
To remove the EFS_INTEGRATION
option from an RDS for Oracle DB instance, do one of
the following:
-
To remove the
EFS_INTEGRATION
option from multiple DB instances, remove theEFS_INTEGRATION
option from the option group to which the DB instances belong. This change affects all DB instances that use the option group. For more information, see Removing an option from an option group. -
To remove the
EFS_INTEGRATION
option from a single DB instance, modify the instance and specify a different option group that doesn't include theEFS_INTEGRATION
option. You can specify the default (empty) option group or a different custom option group. For more information, see Modifying an Amazon RDS DB instance.
Troubleshooting Amazon EFS integration
Your RDS for Oracle DB instance monitors the connectivity to an Amazon EFS file system. When monitoring detects an issue, it might try to correct the issue and publish an event in the RDS console. For more information, see Viewing Amazon RDS events.
Use the information in this section to help you diagnose and fix common issues when you work with Amazon EFS integration.
Notification | Description | Action |
---|---|---|
|
The DB instance can't communicate with the EFS file system. |
Make sure of the following:
|
|
An error occurred during the installation of the
|
Make sure of the following:
|
|
An error occurred during the installation of the
|
Make sure that you associated an IAM role with your RDS for Oracle DB instance. |
|
This error can occur when you're using a version of RDS for Oracle that doesn't support Amazon EFS. |
Make sure that you are using RDS for Oracle DB instance version 19.0.0.0.ru-2022-07.rur-2022-07.r1 or higher. |
|
Your DB instance can't read the EFS file system. |
Make sure that your EFS file system allows read access through the IAM role or on the EFS file system level. |
N/A |
Your DB instance can't write to the EFS file system. |
Take the following steps:
|
The |
You're using a custom DNS server. |
To be able to use a DNS name in the
|