Amazon EFS integration - Amazon Relational Database Service
Overview of Amazon EFS integrationConfiguring network permissionsConfiguring IAM permissionsAdding the EFS optionConfiguring EFS file system permissionsTransferring filesRemoving the optionTroubleshooting Amazon EFS

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.

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.

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.

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

  1. Open the IAM Management Console.

  2. In the navigation pane, choose Roles.

  3. Choose Create role.

  4. For AWS service, choose RDS.

  5. For Select your use case, choose RDS – Add Role to Database.

  6. Choose Next.

  7. Don't add any permissions policies. Choose Next.

  8. Set Role name to a name for your IAM role, for example rds-efs-integration-role. You can also add an optional Description value.

  9. 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 rds-efs-integration-role for this purpose.

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

  1. Open the EFS Management Console.

  2. Choose File Systems.

  3. 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.

  4. 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.

  5. Choose Edit. The File system policy page appears.

  6. 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

  1. Sign in to the AWS Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/.

  2. Choose Databases.

  3. If your database instance is unavailable, choose Actions and then Start. When the instance status shows Started, go to the next step.

  4. Choose the Oracle DB instance name to display its details.

  5. On the Connectivity & security tab, scroll down to the Manage IAM roles section at the bottom of the page.

  6. Choose the role to add in the Add IAM roles to this instance section.

  7. For Feature, choose EFS_INTEGRATION.

  8. 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-arn your-role-arn

For Windows:

aws rds add-role-to-db-instance ^
   --db-instance-identifier mydbinstance ^
   --feature-name EFS_INTEGRATION ^
   --role-arn your-role-arn

Replace your-role-arn with the role ARN that you noted in a previous step. 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

  1. 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.

  2. Add the EFS_INTEGRATION option to the option group. You need to specify the EFS_ID file system ID and set the USE_IAM_ROLE flag.

    For more information, see Adding an option to an option group.

  3. Associate the option group with your DB instance in either of the following ways:

To configure an option group for EFS integration

  1. 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.

  2. 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 named myoptiongroup.

    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}]"

  3. Associate the option group with your DB instance in either of the following ways:

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

p_directory_name

VARCHAR2

–

Yes

The name of the Oracle directory.

p_path_on_efs

VARCHAR2

–

Yes

The path on the EFS file system. The prefix of the path name uses the pattern /rdsefs-fsid/, where fsid is a placeholder for your EFS file system ID.

For example, if your EFS file system is named fs-1234567890abcdef0, and you create a subdirectory on this file system named mydir, you could specify the following value:

/rdsefs-fs-1234567890abcdef0/mydir

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 the EFS_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 the EFS_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 EFS for RDS Oracle instance instance_name isn't available on the primary host. NFS port 2049 of your EFS isn't reachable.

The DB instance can't communicate with the EFS file system.

Make sure of the following:

  • The EFS file system exists.

  • The security group that is attached to the EFS mount target has an inbound rule to allow the security group or network subnet of the RDS for Oracle DB instance on TCP/2049 (Type NFS).

The EFS isn't reachable.

An error occurred during the installation of the EFS_INTEGRATION option.

Make sure of the following:

  • The EFS file system exists.

  • The security group that is attached to the EFS mount target has an inbound rule to allow the security group or network subnet of the RDS for Oracle DB instance on TCP/2049 (Type NFS).

  • The enableDnsSupport attribute is turned on for your VPC.

  • You are using the Amazon provided DNS server in your VPC. Amazon EFS integration doesn't work with a custom DHCP DNS.

The associated role with your DB instance wasn't found.

An error occurred during the installation of the EFS_INTEGRATION option.

Make sure that you associated an IAM role with your RDS for Oracle DB instance.

PLS-00302: component 'CREATE_DIRECTORY_EFS' must be declared

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.

Read access of your EFS is denied. Check your file system policy.

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:

  1. Make sure that your EFS file system is mounted on an Amazon EC2 instance.

  2. Give the others group write access to your RDS user. The simplest technique is to run the chmod 777 command on the top directory of the EFS file system.

The host -s command returns hostname not found: 3(NXDOMAIN)

You're using a custom DNS server.

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.