Menu
Amazon Relational Database Service
User Guide (API Version 2014-10-31)

Authorizing Amazon Aurora to Access Other AWS Services on Your Behalf

Note

Integration with other AWS services is available for Amazon Aurora version 1.8 and later. For more information on Aurora versions, see Amazon Aurora Database Engine Updates.

For your Aurora DB cluster to access other services on your behalf, you must create and configure an AWS Identity and Access Management (IAM) role to authorize database users in your DB cluster to access other AWS services. You must also configure your Aurora DB cluster to allow outbound connections to the target AWS service. If you do so, your database users can perform these actions using other AWS services:

Setting Up IAM Roles to Access Amazon S3 Resources

To permit your Aurora DB cluster to access another AWS service, do the following:

  1. Create an IAM policy that grants permission to the AWS service. For more information, see Allowing Amazon Aurora to Access Amazon S3 Resources or Allowing Amazon Aurora to Access AWS Lambda Resources.

  2. Create an IAM role and attach the policy that you created. For more information, see Creating an IAM Role to Allow Amazon Aurora to Access AWS Services.

  3. Associate that IAM role with your Aurora DB cluster. For more information, see Associating an IAM Role with a DB Cluster.

Allowing Amazon Aurora to Access Amazon S3 Resources

You can use the following steps to create an IAM policy that provides the minimum required permissions for Aurora to access an Amazon Simple Storage Service (Amazon S3) bucket on your behalf. To allow Aurora to access all of your Amazon S3 buckets, you can skip these steps and use the predefined AmazonS3ReadOnlyAccess policy instead of creating your own.

To create an IAM policy to grant access to your Amazon S3 resources

  1. Open the IAM Console.

  2. In the navigation pane, choose Policies.

  3. Choose Create Policy.

  4. For Policy Generator, choose Select.

  5. In Edit Permissions, set the following values:

    • EffectAllow

    • AWS ServiceAmazon S3

    • ActionsListBucket

      ListBucket is a permission for a bucket operation, and needs to be granted on either a wildcard (*) or a bucket. For more information about permissions for bucket operations in Amazon S3, see Specifying Permissions in a Policy.

    • Set Amazon Resource Name (ARN) to the ARN of the Amazon S3 bucket to allow access to. For instance, if you want to allow Aurora to access the Amazon S3 bucket named example-bucket, then set the ARN value to arn:aws:s3:::example-bucket.

  6. Choose Add Statement.

  7. In Edit Permissions, set the following values:

    • EffectAllow

    • AWS ServiceAmazon S3

    • ActionsGetObject and GetObjectVersion

      GetObject and GetObjectVersion are permissions for object operations, and need to be granted for objects in a bucket, not the bucket itself. For more information about permissions for object operations in Amazon S3, see Specifying Permissions in a Policy.

    • Set Amazon Resource Name (ARN) to the ARN of the Amazon S3 bucket to allow access to. For instance, if you want to allow Aurora to access all of the files in the Amazon S3 bucket named example-bucket, then set the ARN value to arn:aws:s3:::example-bucket/*.

    Note

    You can set Amazon Resource Name (ARN) to a more specific ARN value in order to allow Aurora to access only specific files or folders in an Amazon S3 bucket. For more information about how to define an access policy for Amazon S3, see Managing Access Permissions to Your Amazon S3 Resources.

  8. Choose Add Statement.

    Note

    The pair of statements added to the access policy by this and the previous three steps represent the minimum permissions required to enable the LOAD DATA FROM S3 and LOAD XML FROM S3 commands to read from an Amazon S3 bucket.

    You can repeat this and the previous three steps to add a corresponding pair of statements to your policy for each Amazon S3 bucket that you want Aurora to access. Optionally, you can also grant access to all buckets and objects in Amazon S3.

  9. Choose Next Step.

  10. Set Policy Name to a name for your IAM policy, for example AllowAuroraToExampleBucket. You will use this name when you create an IAM role to associate with your Aurora DB cluster. You can also add an optional Description value.

  11. Choose Create Policy.

Allowing Amazon Aurora to Access AWS Lambda Resources

You can use the following steps to create an IAM policy that provides the minimum required permissions for Aurora to invoke an AWS Lambda function on your behalf. To allow Aurora to invoke all of your AWS Lambda functions, you can skip these steps and use the predefined AWSLambdaRole policy instead of creating your own.

To create an IAM policy to grant invoke to your AWS Lambda functions:

  1. Open the IAM Console.

  2. In the navigation pane, choose Policies.

  3. Choose Create Policy.

  4. For the Policy Generator option, choose Select.

  5. In Edit Permissions, set the following values:

    • EffectAllow

    • AWS ServiceAWS Lambda

    • ActionsInvokeFunction

      These permissions are the minimum required to enable Amazon Aurora to invoke an AWS Lambda function.

  6. Set Amazon Resource Name (ARN) to the ARN of the Lambda function to allow access to. For instance, if you want to allow Aurora to access a Lambda function named example_function, then set the ARN value to arn:aws:lambda:::function:example_function.

    For more information on how to define an access policy for AWS Lambda, see Authentication and Access Control for AWS Lambda.

  7. Choose Add Statement.

    You can repeat this and the previous step to add multiple ARNs to your policy and allow Aurora to invoke more than one Lambda function.

  8. Choose Next Step.

  9. Set the Policy Name to a name for your IAM policy, for example AllowAuroraToExampleFunction. You will use this name when you create an IAM role to associate with your Aurora DB cluster. You can also add an optional Description value.

  10. Choose Create Policy.

Creating an IAM Role to Allow Amazon Aurora to Access AWS Services

To create an IAM role to permit your Amazon RDS cluster to communicate with other AWS services on your behalf, take the following steps.

To create an IAM role to allow Amazon RDS to access AWS services

  1. Open the IAM Console.

  2. In the navigation pane, choose Roles.

  3. Choose Create New Role.

  4. For Role Name, type a name for your role, for example RDSLoadFromS3. Choose Next Step.

  5. Choose AWS Service Roles, and then scroll to Amazon RDS. Choose Select.

  6. Choose Next Step

  7. Review the information, and then choose Create Role.

  8. In the list of IAM roles, select your newly created role. Choose the Permissions tab, and then choose Attach Policy.

  9. Select the policy that you defined earlier in either Allowing Amazon Aurora to Access Amazon S3 Resources or Allowing Amazon Aurora to Access AWS Lambda Resources.

  10. Choose Attach Policy.

Associating an IAM Role with a DB Cluster

To permit database users in an Amazon Aurora DB cluster to access other AWS services, you associate the role that you created in Creating an IAM Role to Allow Amazon Aurora to Access AWS Services with that DB cluster.

To associate an IAM role with a DB cluster you do two things:

  • Add the role to the list of associated roles for a DB cluster by using the RDS console, the add-role-to-db-cluster AWS CLI command, or the AddRoleToDBCluster RDS API action.

    You can add a maximum of five IAM roles for each Aurora DB cluster.

  • Set the cluster-level parameter for the related AWS service to the ARN for the associated IAM role.

    The cluster-level parameter name for the IAM role for accessing an Amazon S3 bucket from your DB cluster is aws_default_s3_role. The cluster-level parameter name for the IAM role for invoking a Lambda function from your DB cluster is aws_default_lambda_role.

To associate an IAM role with an Aurora DB cluster using the console

  1. Open the RDS console at https://console.aws.amazon.com/rds/.

  2. Choose Clusters.

  3. Choose the Aurora DB cluster that you want to associate an IAM role with, and then choose Manage IAM Roles.

    
                            Manage IAM Roles for a DB cluster
  4. In Manage IAM Roles, choose the role to associate with your DB cluster from Available roles.

    
                            Associate an IAM role with a DB cluster
  5. (Optional) To stop associating an IAM role with a DB cluster and remove the related permission, choose Delete for the role.

  6. Choose Done.

  7. In the RDS console, choose Parameter Groups in the navigation pane.

  8. If you are already using a custom DB parameter group, you can select that group to use instead of creating a new DB cluster parameter group. If you are using the default DB cluster parameter group, you will need to create a new DB cluster parameter group, as described in the following steps:

    1. Choose Create Parameter Group.

      
                                    Create a DB cluster parameter group

      For Parameter Group Family, choose aurora5.6.

    2. For Type, choose DB cluster parameter group.

    3. For Group Name, type the name of your new DB cluster parameter group.

    4. For Description, type a description for your new DB cluster parameter group.

    5. Choose Create.

  9. Select your DB cluster parameter group and choose Edit Parameters.

  10. Set the aws_default_s3_role and aws_default_lambda_role parameters to the related IAM role ARN values. For example, you can set just the aws_default_s3_role parameter to arn:aws:iam::123456789012:role/AllowAuroraS3Role.

  11. Choose Save Changes.

  12. Choose Instances, and then select the primary instance for your Aurora DB cluster.

  13. Choose Instance Actions and then choose Modify.

  14. Set the DB Cluster Parameter Group to the new DB cluster parameter group that you created. Select Apply Immediately. Choose Continue.

  15. Verify your changes and then choose Modify DB Instance.

  16. The primary instance for your DB cluster will still be selected in the list of instances. Choose Instance Actions, and then choose Reboot.

    When the instance has rebooted, your IAM roles will be associated with your DB cluster.

    For more information about cluster parameter groups, see DB Cluster and DB Instance Parameters.

To associate an IAM role with a DB cluster by using the AWS CLI

  1. Call the add-role-to-db-cluster command from the AWS CLI to add the ARNs for your IAM roles to the DB cluster, as shown following.

    Copy
    PROMPT> aws rds add-role-to-db-cluster --db-cluster-identifier my-cluster --role-arn arn:aws:iam::123456789012:role/AllowAuroraS3Role PROMPT> aws rds add-role-to-db-cluster --db-cluster-identifier my-cluster --role-arn arn:aws:iam::123456789012:role/AllowAuroraLambdaRole
  2. If you are using the default DB cluster parameter group, you will need to create a new DB cluster parameter group. If you are already using a custom DB parameter group, you can use that group instead of creating a new DB cluster parameter group.

    To create a new DB cluster parameter group, call the create-db-cluster-parameter-group command from the AWS CLI, as shown following.

    Copy
    PROMPT> aws rds create-db-cluster-parameter-group --db-cluster-parameter-group-name AllowAWSAccess \ --db-parameter-group-family aurora5.6 --description "Allow access to Amazon S3 and AWS Lambda"
  3. Set the cluster-level parameter or parameters and the related IAM role ARN values in your DB cluster parameter group, as shown following.

    Copy
    PROMPT> aws rds modify-db-cluster-parameter-group --db-cluster-parameter-group-name AllowAWSAccess \ --parameters "name=aws_default_s3_role,value=arn:aws:iam::123456789012:role/AllowAuroraS3Role,method=pending-reboot" \ --parameters "name=aws_default_lambda_role,value=arn:aws:iam::123456789012:role/AllowAuroraLambdaRole,method=pending-reboot"
  4. Modify the DB cluster to use the new DB cluster parameter group and then reboot the cluster, as shown following.

    Copy
    PROMPT> aws rds modify-db-cluster --db-cluster-identifier my-cluster --db-cluster-parameter-group-name AllowAWSAccess PROMPT> aws rds reboot-db-instance --db-instance-identifier my-cluster-primary

    When the instance has rebooted, your IAM roles will be associated with your DB cluster.

    For more information about cluster parameter groups, see DB Cluster and DB Instance Parameters.

Restricting an IAM Role to an AWS Region

You can restrict an IAM role to only be accessible in a certain AWS Region. By default, IAM roles are not restricted to any single region. Restricting an IAM role to specific AWS regions is optional.

To restrict use of an IAM role by region, take the following steps.

To identify permitted regions for an IAM role

  1. Open the IAM Console at https://console.aws.amazon.com.

  2. In the navigation pane, choose Roles.

  3. Choose the role that you want to modify with specific regions.

  4. Choose the Trust Relationships tab, and then choose Edit Trust Relationship. A new IAM role that allows Amazon Aurora to access other AWS services on your behalf will have a trust relationship as follows.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  5. Modify the Service list for the Principal with the list of the specific regions that you want to permit use of the role for. Each region in the Service list must be in the following format: rds.region.amazonaws.com.

    For example, the following edited trust relationship permits the use of the IAM role in the us-east-1 and us-west-2 regions only.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "rds.us-east-1.amazonaws.com", "rds.us-west-2.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] }
  6. Choose Update Trust Policy.

Enabling Network Communication from Amazon Aurora to Other AWS Services

To invoke AWS Lambda functions or load files from Amazon S3, the network configuration of your Aurora DB cluster must allow outbound connections to endpoints for those services. Aurora returns the following error messages if it can't connect to a service endpoint.

Copy
ERROR 1871 (HY000): S3 API returned error: Network Connection
Copy
ERROR 1873 (HY000): Lambda API returned error: Network Connection. Unable to connect to endpoint

If you encounter these messages while invoking AWS Lambda functions or loading files from Amazon S3, check if your Aurora DB cluster is public or private. If your Aurora DB cluster is private, you must configure it to enable connections.

For an Aurora DB cluster to be public, it must be marked as publicly accessible. If you look at the details for the DB cluster in the AWS Management Console, Publicly Accessible is Yes if this is the case. The DB cluster must also be in an Amazon VPC public subnet. For more information about publicly accessible DB instances, see Working with an Amazon RDS DB Instance in a VPC. For more information about public Amazon VPC subnets, see Your VPC and Subnets.

If your Aurora DB cluster isn’t publicly accessible and in a VPC public subnet, it is private. If your DB cluster is private and you want to invoke AWS Lambda functions or access Amazon S3 files, configure the cluster so it can connect to Internet addresses through Network Address Translation (NAT). As an alternative for Amazon S3, you can instead configure the VPC to have a VPC endpoint for Amazon S3 associated with the DB cluster’s route table. For more information about configuring NAT in your VPC, see NAT Gateways. For more information about configuring VPC endpoints, see VPC Endpoints.

Related Topics