Prerequisites for creating an RDS Custom for Oracle DB instance Step 1: Create or reuse a symmetric encryption AWS KMS key Step 2: Download and install the AWS CLI Step 3: Configure IAM and your Amazon VPC Step 4: Grant required permissions to your IAM user or role

Setting up your environment for Amazon RDS Custom for Oracle

Before you create an Amazon RDS Custom for Oracle DB instance, perform the following tasks.

Topics

Prerequisites for creating an RDS Custom for Oracle DB instance
Step 1: Create or reuse a symmetric encryption AWS KMS key
Step 2: Download and install the AWS CLI
Step 3: Configure IAM and your Amazon VPC
Step 4: Grant required permissions to your IAM user or role

Prerequisites for creating an RDS Custom for Oracle DB instance

Before creating an RDS Custom for Oracle DB instance, make sure that you meet the following prerequisites:

You have access to My Oracle Support and Oracle Software Delivery Cloud to download the supported list of installation files and patches for the Enterprise Edition of any of the following Oracle Database releases:
- Oracle Database 19c
- Oracle Database 18c
- Oracle Database 12c Release 2 (12.2)
- Oracle Database 12c Release 1 (12.1)
If you use an unknown patch, custom engine version (CEV) creation fails. In this case, contact the RDS Custom support team and ask it to add the missing patch.

For more information, see Step 2: Download your database installation files and patches from Oracle Software Delivery Cloud.
You have access to Amazon S3. This service is required for the following reasons:
- You upload your Oracle installation files to S3 buckets. You use the uploaded installation files to create your RDS Custom CEV.
- RDS Custom for Oracle uses scripts downloaded from internally defined S3 buckets to perform actions on your DB instances. These scripts are necessary for onboarding and RDS Custom automation.
- RDS Custom for Oracle uploads certain files to S3 buckets located in your customer account. These buckets use the following naming format: do-not-delete-rds-custom-account_id-region-six_character_alphanumeric_string. For example, you might have a bucket named do-not-delete-rds-custom-123456789012-us-east-1-12a3b4.
For more information, see Step 3: Upload your installation files to Amazon S3 and Creating a CEV.
You supply your own virtual private cloud (VPC) and security group configuration. For more information, see Step 3: Configure IAM and your Amazon VPC.
The AWS Identity and Access Management (IAM) user that creates a CEV or RDS Custom DB instance has the required permissions for IAM, CloudTrail, and Amazon S3.

For more information, see Step 4: Grant required permissions to your IAM user or role.

For each task, the following sections describe the requirements and limitations specific to the task. For example, when you create your RDS Custom DB for Oracle instance, use either the db.m5 or db.r5 instance classes running Oracle Linux 7 Update 9. For general requirements that apply to RDS Custom, see RDS Custom for Oracle requirements and limitations.

Step 1: Create or reuse a symmetric encryption AWS KMS key

Customer managed keys are AWS KMS keys in your AWS account that you create, own, and manage. A customer managed symmetric encryption KMS key is required for RDS Custom. When you create an RDS Custom for Oracle DB instance, you supply the KMS key identifier. For more information, see Configuring a DB instance for Amazon RDS Custom for Oracle.

You have the following options:

If you have an existing customer managed KMS key in your AWS account, you can use it with RDS Custom. No further action is necessary.
If you already created a customer managed symmetric encryption KMS key for a different RDS Custom engine, you can reuse the same KMS key. No further action is necessary.
If you don't have an existing customer managed symmetric encryption KMS key in your account, create a KMS key by following the instructions in Creating keys in the AWS Key Management Service Developer Guide.
If you're creating a CEV or RDS Custom DB instance, and your KMS key is in a different AWS account, make sure to use the AWS CLI. You can't use the AWS console with cross-account KMS keys.

Important

RDS Custom doesn't support AWS managed KMS keys.

Make sure that your symmetric encryption key grants access to the kms:Decrypt and kms:GenerateDataKey operations to the AWS Identity and Access Management (IAM) role in your IAM instance profile. If you have a new symmetric encryption key in your account, no changes are required. Otherwise, make sure that your symmetric encryption key's policy grants access to these operations.

For more information, see Step 3: Configure IAM and your Amazon VPC.

For more information about configuring IAM for RDS Custom for Oracle, see Step 3: Configure IAM and your Amazon VPC.

Step 2: Download and install the AWS CLI

AWS provides you with a command-line interface to use RDS Custom features. You can use either version 1 or version 2 of the AWS CLI.

For information about downloading and installing the AWS CLI, see Installing or updating the latest version of the AWS CLI.

Skip this step if either of the following is true:

You plan to access RDS Custom only from the AWS Management Console.
You have already downloaded the AWS CLI for Amazon RDS or a different RDS Custom DB engine.

Step 3: Configure IAM and your Amazon VPC

You use an IAM role or IAM user (known as an IAM entity) to create an RDS Custom DB instance using the console or AWS CLI. This IAM entity must have the necessary permissions for instance creation.

Your RDS Custom DB instance is in a virtual private cloud (VPC) based on the Amazon VPC service, just like an Amazon EC2 instance or Amazon RDS instance. You provide and configure your own VPC. Thus, you have full control over your instance networking setup.

You can configure your IAM identity and virtual private cloud (VPC) using either of the following techniques:

Configure IAM and your VPC using AWS CloudFormation (recommended)
Follow the procedures in Create your IAM role and instance profile manually and Configure your VPC manually

We strongly recommend that you configure your RDS Custom for Oracle environment using AWS CloudFormation. This technique is the easiest and least error-prone.

Configure IAM and your VPC using AWS CloudFormation

A CloudFormation stack is a collection of AWS resources that you can manage as a single unit. To simplify RDS Custom configuration, you can use the AWS CloudFormation template files to create CloudFormation stacks. For more information, see Creating a stack on the AWS CloudFormation console in AWS CloudFormation User Guide.

AWS CloudFormation configuration steps

IAM and VPC resources created by CloudFormation
Step 1: Download the CloudFormation template files
Step 2: Configure IAM using CloudFormation
Step 3: Configure your VPC using CloudFormation

IAM and VPC resources created by CloudFormation

When you use the CloudFormation templates, they create stacks that includes the following resources in your AWS account:

An Amazon EC2 instance profile named AWSRDSCustomInstanceProfile-region
An IAM role named AWSRDSCustomInstanceRole-region
A DB subnet group named rds-custom-private
The following VPC endpoints, which are necessary for your DB instance to communicate with dependent AWS services:
- com.amazonaws.region.ec2messages
- com.amazonaws.region.events
- com.amazonaws.region.logs
- com.amazonaws.region.monitoring
- com.amazonaws.region.s3
- com.amazonaws.region.secretsmanager
- com.amazonaws.region.ssm
- com.amazonaws.region.ssmmessages

Unlike RDS Custom for SQL Server, RDS Custom for Oracle doesn't create an access control list or security groups. You must attach you own security group, subnets, and route tables.

Step 1: Download the CloudFormation template files

A CloudFormation template is a declaration of the AWS resources that make up a stack. The template is stored as a JSON file.

To download the CloudFormation template files

Open the context (right-click) menu for the link custom-oracle-iam.zip and choose Save Link As.
Save the file to your computer.
Repeat the previous steps for the link custom-vpc.zip.

If you already configured your VPC for RDS Custom, skip this step.

Step 2: Configure IAM using CloudFormation

When you use the CloudFormation template for IAM, it creates the following required resources:

An instance profile named AWSRDSCustomInstanceProfile-region
A service role named AWSRDSCustomInstanceRole-region
An access policy named AWSRDSCustomIamRolePolicy that is attached to the service role

To configure IAM using CloudFormation

Open the CloudFormation console at https://console.aws.amazon.com/cloudformation.
Start the Create Stack wizard, and choose Create Stack.
On the Create stack page, do the following:
1. For Prepare template, choose Template is ready.
2. For Template source, choose Upload a template file.
3. For Choose file, navigate to, then choose custom-oracle-iam.json.
4. Choose Next.
On the Specify stack details page, do the following:
1. For Stack name, enter custom-oracle-iam.
2. Choose Next.
On the Configure stack options page, choose Next.
On the Review custom-oracle-iam page, do the following:
1. Select the I acknowledge that AWS CloudFormation might create IAM resources with custom names check box.
2. Choose Submit.
CloudFormation creates the IAM roles that RDS Custom for Oracle requires. In the left panel, when custom-oracle-iam shows CREATE_COMPLETE, proceed to the next step.
In the left panel, choose custom-oracle-iam. In the right panel, do the following:
1. Choose Stack info. Your stack has an ID in the format arn:aws:cloudformation:region:account-no:stack/custom-oracle-iam/identifier.
2. Choose Resources. You should see the following:
  - An instance profile named AWSRDSCustomInstanceProfile-region
  - A service role named AWSRDSCustomInstanceRole-region
  When you create your RDS Custom DB instance, you need to supply the instance profile ID.

Step 3: Configure your VPC using CloudFormation

If you've already configured your VPC for a different RDS Custom engine, and want to reuse the existing VPC, skip this step. This section assumes that the following:

You've already used CloudFormation to create your IAM instance profile and role.
You know your route table ID.

For a DB instance to be private, it must be in a private subnet. For a subnet to be private, it must not be associated with a route table that has a default internet gateway. For more information, see Configure route tables in the Amazon VPC User Guide.

When you use the CloudFormation template for your VPC, it creates the following required resources:

A private VPC
A subnet group named rds-custom-private
VPC endpoints that use the naming format vpce-string

To configure your VPC using CloudFormation

Open the CloudFormation console at https://console.aws.amazon.com/cloudformation.
Start the Create Stack wizard, and choose Create Stack and then With new resources (standard).
On the Create stack page, do the following:
1. For Prepare template, choose Template is ready.
2. For Template source, choose Upload a template file.
3. For Choose file, navigate to, then choose custom-vpc.json.
4. Choose Next.
On the Specify stack details page, do the following:
1. For Stack name, enter custom-vpc.
2. For Parameters, choose the private subnets to use for RDS Custom DB instances.
3. Choose the private VPC ID to use for RDS Custom DB instances.
4. Enter the route table associated with the private subnets.
5. Choose Next.
On the Configure stack options page, choose Next.
On the Review custom-vpc page, choose Submit.

CloudFormation configures your private VPC. In the left panel, when custom-vpc shows CREATE_COMPLETE, proceed to the next step.
(Optional) Review the details of your VPC. In the Stacks pane, choose custom-vpc. In the right pane, do the following:
1. Choose Stack info. Your stack has an ID in the format arn:aws:cloudformation:region:account-no:stack/custom-vpc/identifier.
2. Choose Resources. You should see a subnet group named rds-custom-private and several VPC endpoints that use the naming format vpce-string. Each endpoint corresponds to an AWS service that RDS Custom needs to communicate with.
3. Choose Parameters. You should see the private subnets, private VPC, and the route table that you specified when you created the stack. When you create a DB instance, you need to supply the VPC ID and subnet group.

Create your IAM role and instance profile manually

Configuration is easiest when you use CloudFormation. However, you can also configure IAM manually. For manual setup, you create the following resources:

An IAM instance profile named AWSRDSCustomInstanceProfile-region, where region is the AWS Region where you plan to deploy your DB instances.
An IAM role AWSRDSCustomInstanceRole-region for the instance profile.

The following steps show how to create the instance profile and role and then add the role to your profile.

To create the RDS Custom instance profile and add the necessary role to it

Create the IAM role that uses the naming format AWSRDSCustomInstanceRole-region with a trust policy that Amazon EC2 can use to assume this role.
Add an access policy to AWSRDSCustomInstanceRole-region.
Create an IAM instance profile for RDS Custom that uses the naming format AWSRDSCustomInstanceProfile-region.
Add the AWSRDSCustomInstanceRole-region IAM role to the instance profile.

Step 1: Create the role AWSRDSCustomInstanceRoleForRdsCustomInstance

In this step, you create the role using the naming format AWSRDSCustomInstanceRole-region. Using the trust policy, Amazon EC2 can assume the role. The following example assumes that you have set the environment variable $REGION to the AWS Region in which you want to create your DB instance.


aws iam create-role \
  --role-name AWSRDSCustomInstanceRole-$REGION \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Effect": "Allow",
          "Principal": {
              "Service": "ec2.amazonaws.com"
          }
        }
      ]
    }'

Step 2: Add an access policy to AWSRDSCustomInstanceRoleForRdsCustomInstance

When you embed an inline policy in an IAM role, the inline policy is used as part of the role's access (permissions) policy. You create the AWSRDSCustomIamRolePolicy policy that permits Amazon EC2 to send and receive messages and perform various actions.

The following example creates the access policy named AWSRDSCustomIamRolePolicy, and adds it to the IAM role AWSRDSCustomInstanceRole-region. This example assumes that you have set the following environment variables:

$REGION: Set this variable to the AWS Region in which you plan to create your DB instance.
$ACCOUNT_ID: Set this variable to your AWS account number.
$KMS_KEY: Set this variable to the Amazon Resource Name (ARN) of the AWS KMS key that you want to use for your RDS Custom DB instances. To specify more than one KMS key, add it to the Resources section of statement ID (Sid) 11.


aws iam put-role-policy \
  --role-name AWSRDSCustomInstanceRole-$REGION \
  --policy-name AWSRDSCustomIamRolePolicy \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "1",
            "Effect": "Allow",
            "Action": [
                "ssm:DescribeAssociation",
                "ssm:GetDeployablePatchSnapshotForInstance",
                "ssm:GetDocument",
                "ssm:DescribeDocument",
                "ssm:GetManifest",
                "ssm:GetParameter",
                "ssm:GetParameters",
                "ssm:ListAssociations",
                "ssm:ListInstanceAssociations",
                "ssm:PutInventory",
                "ssm:PutComplianceItems",
                "ssm:PutConfigurePackageResult",
                "ssm:UpdateAssociationStatus",
                "ssm:UpdateInstanceAssociationStatus",
                "ssm:UpdateInstanceInformation",
                "ssm:GetConnectionStatus",
                "ssm:DescribeInstanceInformation",
                "ssmmessages:CreateControlChannel",
                "ssmmessages:CreateDataChannel",
                "ssmmessages:OpenControlChannel",
                "ssmmessages:OpenDataChannel"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "2",
            "Effect": "Allow",
            "Action": [
                "ec2messages:AcknowledgeMessage",
                "ec2messages:DeleteMessage",
                "ec2messages:FailMessage",
                "ec2messages:GetEndpoint",
                "ec2messages:GetMessages",
                "ec2messages:SendReply"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "3",
            "Effect": "Allow",
            "Action": [
                "logs:PutRetentionPolicy",
                "logs:PutLogEvents",
                "logs:DescribeLogStreams",
                "logs:DescribeLogGroups",
                "logs:CreateLogStream",
                "logs:CreateLogGroup"
            ],
            "Resource": [
                "arn:aws:logs:'$REGION':*:log-group:rds-custom-instance*"
            ]
        },
        {
            "Sid": "4",
            "Effect": "Allow",
            "Action": [
                "s3:putObject",
                "s3:getObject",
                "s3:getObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::do-not-delete-rds-custom-*/*"
            ]
        },
        {
            "Sid": "5",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:PutMetricData"
            ],
            "Resource": [
                "*"
            ],
            "Condition": {
                "StringEquals": {
                    "cloudwatch:namespace": [
                        "RDSCustomForOracle/Agent"
                    ]
                }
            }
        },
        {
            "Sid": "6",
            "Effect": "Allow",
            "Action": [
                "events:PutEvents"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "7",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": [
                "arn:aws:secretsmanager:'$REGION':'$ACCOUNT_ID':secret:do-not-delete-rds-custom-*"
            ]
        },
        {
           "Sid": "8",
           "Effect": "Allow",
           "Action": [
             "s3:ListBucketVersions"
           ],
           "Resource": [
             "arn:aws:s3:::do-not-delete-rds-custom-*"
           ]
         },
         {
            "Sid": "9",
            "Effect": "Allow",
            "Action": "ec2:CreateSnapshots",
            "Resource": [
                "arn:aws:ec2:*:*:instance/*",
                "arn:aws:ec2:*:*:volume/*"
            ],
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/AWSRDSCustom": "custom-oracle"
                }
            }
          },
          {
            "Sid": "10",
            "Effect": "Allow",
            "Action": "ec2:CreateSnapshots",
            "Resource": [
                "arn:aws:ec2:*::snapshot/*"
            ]
          },
          {
            "Sid": "11",
            "Effect": "Allow",
            "Action": [
              "kms:Decrypt",
              "kms:GenerateDataKey"
            ],
            "Resource": [
              "arn:aws:kms:'$REGION':'$ACCOUNT_ID':key/'$KMS_KEY'"
            ]
          },
          {
            "Sid": "12",
            "Effect": "Allow",
            "Action": "ec2:CreateTags",
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "ec2:CreateAction": [
                        "CreateSnapshots"
                    ]
                }
            }
        }
    ]
}'

Step 3: Create your RDS Custom instance profile

An instance profile is a container that includes a single IAM role. RDS Custom uses the instance profile to pass the role to the instance.

If you use the CLI to create a role, you create the role and instance profile as separate actions, with potentially different names. Create your IAM instance profile as follows, naming it using the format AWSRDSCustomInstanceProfile-region. The following example assumes that you have set the environment variable $REGION to the AWS Region in which you want to create your DB instance.


aws iam create-instance-profile \
    --instance-profile-name AWSRDSCustomInstanceProfile-$REGION

Step 4: Add AWSRDSCustomInstanceRoleForRdsCustomInstance to your RDS Custom instance profile

Add your IAM role to the instance profile that you previously created. The following example assumes that you have set the environment variable $REGION to the AWS Region in which you want to create your DB instance.


aws iam add-role-to-instance-profile \
    --instance-profile-name AWSRDSCustomInstanceProfile-$REGION \
    --role-name AWSRDSCustomInstanceRole-$REGION

Configure your VPC manually

If you don't want to use AWS CloudFormation, you can configure your VPC endpoints manually.

Topics

Create VPC endpoints for dependent AWS services
Configure the instance metadata service

Create VPC endpoints for dependent AWS services

RDS Custom sends communication from your DB instance to other AWS services. To make sure that RDS Custom can communicate, it validates network connectivity to the following AWS services:

Amazon CloudWatch
Amazon CloudWatch Logs
Amazon CloudWatch Events
Amazon EC2
Amazon EventBridge
Amazon S3
AWS Secrets Manager
AWS Systems Manager

If RDS Custom can't communicate with the necessary services, it publishes the following event:


Database instance in incompatible-network. SSM Agent connection not available. Amazon RDS can't connect to the dependent AWS services.

To avoid incompatible-network errors, make sure that VPC components involved in communication between your RDS Custom DB instance and AWS services satisfy the following requirements:

The DB instance can make outbound connections on port 443 to other AWS services.
The VPC allows incoming responses to requests originating from your RDS Custom DB instance.
RDS Custom can correctly resolve the domain names of endpoints for each AWS service.

RDS Custom relies on AWS Systems Manager connectivity for its automation. For information about how to configure VPC endpoints, see Creating VPC endpoints for Systems Manager. For the list of endpoints in each Region, see AWS Systems Manager endpoints and quotas in the Amazon Web Services General Reference.

If you already configured a VPC for a different RDS Custom DB engine, you can reuse that VPC and skip this process.

Configure the instance metadata service

Make sure that your instance can do the following:

Access the instance metadata service using Instance Metadata Service Version 2 (IMDSv2).
Allow outbound communications through port 80 (HTTP) to the IMDS link IP address.
Request instance metadata from http://169.254.169.254, the IMDSv2 link.

For more information, see Use IMDSv2 in the Amazon EC2 User Guide for Linux Instances.

RDS Custom for Oracle automation uses IMDSv2 by default, by setting HttpTokens=enabled on the underlying Amazon EC2 instance. However, you can use IMDSv1 if you want. For more information, see Configure the instance metadata options in the Amazon EC2 User Guide for Linux Instances.

Step 4: Grant required permissions to your IAM user or role

Make sure that the IAM user or role that creates the CEV or RDS Custom DB instance has either of the following policies:

The AdministratorAccess policy
The AmazonRDSFullAccess policy with required permissions for Amazon S3 and AWS KMS (required for both CEV and DB creation), CEV creation, and DB instance creation.

Topics

IAM permissions required for Amazon S3 and AWS KMS
IAM permissions required for creating a CEV
IAM permissions required for creating a DB instance from a CEV

IAM permissions required for Amazon S3 and AWS KMS

To create CEVs or RDS Custom for Oracle DB instances, the IAM identity needs to access Amazon S3 and AWS KMS. The following sample JSON policy grants the required permissions.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CreateS3Bucket",
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:PutBucketPolicy",
                "s3:PutBucketObjectLockConfiguration",
                "s3:PutBucketVersioning"
            ],
            "Resource": "arn:aws:s3:::do-not-delete-rds-custom-*"
        },
        {
            "Sid": "CreateKmsGrant",
            "Effect": "Allow",
            "Action": [
                "kms:CreateGrant",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        }
    ]
}

For more information about the kms:CreateGrant permission, see AWS KMS key management.

IAM permissions required for creating a CEV

To create a CEV, the IAM identity needs the following additional permissions:


s3:GetObjectAcl
s3:GetObject
s3:GetObjectTagging
s3:ListBucket
mediaimport:CreateDatabaseBinarySnapshot

The following sample JSON policy grants the additional permissions necessary to access bucket my-custom-installation-files and its contents.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AccessToS3MediaBucket",
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectAcl",
                "s3:GetObject",
                "s3:GetObjectTagging",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::my-custom-installation-files",
                "arn:aws:s3:::my-custom-installation-files/*"
            ]
        },
        {
            "Sid": "PermissionForByom",
            "Effect": "Allow",
            "Action": [
                "mediaimport:CreateDatabaseBinarySnapshot"
            ],
            "Resource": "*"
        }
    ]
}

You can grant similar permissions for Amazon S3 to caller accounts using an S3 bucket policy.

IAM permissions required for creating a DB instance from a CEV

To create an RDS Custom for Oracle DB instance from an existing CEV, the IAM entity needs the following additional permissions.


iam:SimulatePrincipalPolicy
cloudtrail:CreateTrail
cloudtrail:StartLogging

The following sample JSON policy grants the permissions necessary to validate an IAM role and log information to an AWS CloudTrail.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ValidateIamRole",
            "Effect": "Allow",
            "Action": "iam:SimulatePrincipalPolicy",
            "Resource": "*"
        },
        {
            "Sid": "CreateCloudTrail",
            "Effect": "Allow",
            "Action": [
                "cloudtrail:CreateTrail",
                "cloudtrail:StartLogging"
            ],
            "Resource": "arn:aws:cloudtrail:*:*:trail/do-not-delete-rds-custom-*"
        }
    ]
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

RDS Custom for Oracle requirements and limitations

Working with CEVs for RDS Custom for Oracle