Why do I get an RDS-EVENT-0198 error when I create a custom engine version of my Amazon RDS Custom for Oracle DB instance?

Short description

You can create an RDS Custom DB instance from a CEV. When the CEV is created, Amazon RDS Custom installs the media that you provide. This contains your database installation files and patches. The output is a binary volume snapshot of a database version and AMI.

If you don't meet the requirements, then your CEV creation fails with the following error. The error includes a message that details the reasons for the failure.

"RDS-EVENT-0198 Creation failed for custom engine version [name].[message]"

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, make sure that you use the most recent AWS CLI version.

Before you create a CEV, store your installation files and patches in an Amazon Simple Storage Service (Amazon S3) bucket. For example, you might use April 2023 RU for Oracle Database 19c, or any other valid combination of installation files and patches. For more information, see RDS Custom with RDS for Oracle.

Prepare the required information about your installation files and patches. Then, add the required permissions to your AWS Identity and Access Management (IAM) user or role.

Prepare your database installation files and patches

1.    Download the database installation files for an Oracle database to your local system. To do this, access the Oracle Software Delivery Cloud on the Oracle website. Search for Oracle Database Enterprise Edition to locate the download package for the base release.

2.    In the Patches & Updates tab, search by patch name or number. Then, download patches from My Oracle Support on the Oracle website. Check that your patch number is supported by RDS Custom for Oracle. Or, find the URLs for the patches in the readme files in the custom-oracle-manifest.zip provided by AWS.

3.    When you download the installation and patch files, note the digest of files that appear on the download webpage. Compare the checksum on the files with this digest to verify the integrity of the installation and patch files that you download. Run one of the following commands:

Windows:

certutil -hashfile  [SHA1|SHA256]

macOS:

certutil -hashfile  [SHA1|SHA256]

Linux:

sha1sum 

or

sha256sum 

If you use unknown patches or a newly released patch, then the CEV creation fails. To request that your patch is whitelisted, contact the Amazon RDS Custom for Oracle Support team.

Sometimes your patch files are in conflict with each other. Use the Oracle Support Conflict Checker tool on the Oracle website to check for conflicts. To resolve conflicts, see MOS documents 1321267.1 on the Oracle website or remove the conflicting patches, and then create the CEV again.

Upload your installation files to Amazon S3

Use the AWS CLI to upload your Oracle installation and patch files to Amazon S3.

Note: Make sure that the S3 bucket that contains your installation files is in the same Region as your CEV.

Run the following command to upload a single .zip file:

aws s3 cp  

Run the following command to upload a directory:

aws s3 sync  

Note: You S3 bucket might be encrypted with AWS Key Management Service (AWS KMS) keys (SSE-KMS). If so, then Amazon RDS Custom can't access the files in the bucket. Instead, use server-side encryption with Amazon S3-managed encryption keys (SSE-S3) for the files in the S3 bucket.

Prepare the CEV manifest

When you create a CEV, you specify the files and optional installation parameters in a JSON document called a CEV manifest. Prepare the CEV manifest as a JSON text file. Then, edit the CEV manifest template for CEV creation in the AWS Management Console or AWS CLI.

The CEV manifest lists the installation files in a specific order. Amazon RDS Custom applies the patches in this order. If you include JSON fields in your manifest, then make sure that they aren't empty.

If you include the psuRuPatchFileNames and OtherPatchFileNames fields, then patchFieldNames is also required and must precede these fields.

Review the CEV manifest examples for examples of a CEV manifest and the JSON fields for an Oracle Database 19c.

Grant the required permissions to your IAM user or role

Check that you have the following permissions in place to create a CEV file for your instance:

• Confirm that the IAM principal that creates the CEV has the AdministratorAccess and AmazonRDSFullAccess policies.

• Confirm also that the IAM principle has the required permissions for Amazon S3 and AWS KMS. This is a requirement for both DB instance and CEV creation.

• Make sure that the IAM entity has permissions for Amazon S3 and AWS KMS. Configure the following permissions:

  s3:CreateBucket
  s3:PutBucketPolicy
  s3:PutBucketObjectLockConfiguration
  s3:PutBucketVersioning
  kms:CreateGrant
  kms:DescribeKey

• Make sure that the IAM entity has the following permissions to create a CEV:

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

• The IAM entity requires the following permissions to create an RDS Custom for Oracle DB instance from an existing CEV:

  iam:SimulatePrincipalPolicy
  cloudtrail:CreateTrail
  cloudtrail:StartLogging

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

Note: Check if the account that contains your IAM principal is part of an organization in AWS Organizations. If so, then make sure that your service control policy explicitly allows the action to create a CEV and RDS Custom for Oracle DB instance.

Create a CEV

Use the Amazon RDS console or the AWS CLI to create a CEV.

Use the Amazon RDS console

1. Open the Amazon RDS console.

2. In the navigation pane, choose Custom engine versions. The Custom engine versions page shows all CEVs that currently exist in your account.

3. Choose Create custom engine version.

4. In Engine options, choose Oracle for Engine type.

5. For Architecture settings, choose Multitenant architecture. You can use this setting only to create RDS Custom for Oracle CDB instances. If you don't choose this option, then you can create only RDS Custom for Oracle non-CDB instances.

6. In Version details, enter a valid format name for your CEV similar to the following:

   major-engine-version.customized_string

7. For Installation media, enter the location of the S3 bucket that you uploaded your media files to.

8. For CEV manifest, enter the JSON manifest that you created.

9. Under KMS key, choose Enter a key ARN to list the available AWS KMS keys. A customer managed symmetric encryption AWS KMS key is required to create a CEV and RDS Custom DB instance. For more information, see Create or reuse a symmetric encryption AWS KMS key.

10. Choose Create custom engine version.

Use the AWS CLI

To use the AWS CLI to creating CEV, see create-custom-db-engine-version.

Related information

RDS Custom for Oracle workflow

Set up your environment for Amazon RDS Custom for Oracle