Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

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:

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 Amazon KMS key

Customer managed keys are Amazon KMS keys in your Amazon 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:

Make sure that your symmetric encryption key grants access to the kms:Decrypt and kms:GenerateDataKey operations to the Amazon 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 Amazon CLI

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

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

Skip this step if either of the following is true:

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 Amazon 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:

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

Configure IAM and your VPC using Amazon CloudFormation

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

IAM and VPC resources created by CloudFormation

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

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 Amazon resources that make up a stack. The template is stored as a JSON file.

Step 2: Configure IAM using CloudFormation

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

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:

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

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:

The following steps show how to create the instance profile and role and then add the role to your 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 Amazon Web Services 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:

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-cn:logs:'$REGION':*:log-group:rds-custom-instance*"
            ]
        },
        {
            "Sid": "4",
            "Effect": "Allow",
            "Action": [
                "s3:putObject",
                "s3:getObject",
                "s3:getObjectVersion"
            ],
            "Resource": [
                "arn:aws-cn: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-cn:secretsmanager:'$REGION':'$ACCOUNT_ID':secret:do-not-delete-rds-custom-*"
            ]
        },
        {
           "Sid": "8",
           "Effect": "Allow",
           "Action": [
             "s3:ListBucketVersions"
           ],
           "Resource": [
             "arn:aws-cn: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-cn: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 Amazon Web Services 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 Amazon Web Services 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 Amazon CloudFormation, you can configure your VPC endpoints manually.

Create VPC endpoints for dependent Amazon Web Services

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

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 Amazon services.

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

RDS Custom relies on Amazon 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 Amazon 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:

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:

IAM permissions required for Amazon S3 and Amazon KMS

To create CEVs or RDS Custom for Oracle DB instances, the IAM identity needs to access Amazon S3 and Amazon 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 Amazon 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-cn:s3:::my-custom-installation-files",
                "arn:aws-cn: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 Amazon 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-cn:cloudtrail:*:*:trail/do-not-delete-rds-custom-*"
        }
    ]
}