This section explains how to install and configure Customer Managed Oracle REST Data Services (ORDS) on Autonomous Database.
3.1 About Customer Managed Oracle REST Data Services on Autonomous Database
When you provision an Autonomous Database instance, by default Oracle REST Data Services (ORDS) is preconfigured and available for the instance. With the default ORDS, Oracle performs any required configuration, patching, and maintenance. Additionally, you can also configure Autonomous Database to use ORDS running in a customer managed environment.
When you use the default ORDS on Autonomous Database, you cannot modify any of the ORDS configuration options.
For example, with the default configuration, the JDBC connection pools have a maximum of
100 connections and the connections for ORDS are preconfigured to use the
LOW database service. Use a customer managed environment if you
want manual control of the configuration and management of Oracle REST Data Services. For example, use this option when your applications require
larger connection pools or if you need more control over the ORDS configuration
When ORDS runs in a customer managed environment, you are responsible for configuration, patching, and maintenance of ORDS in the customer managed environment. After you configure Autonomous Database to use your customer managed ORDS in addition to the existing autonomously managed ORDS, you can route ORDS HTTPS traffic through your environment. The default Autonomous Database web server and ORDS are still running and ORDS traffic goes to the ORDS running in the customer managed environment. This provides an additional and alternative HTTPS solution for Autonomous Database.
Installing and configuring a customer managed environment for ORDS allows you to run ORDS with configuration options that are not possible using the default Oracle managed ORDS available with Autonomous Database.
- Oracle REST Data Services 19.4.6 or higher is required to use a customer managed environment for ORDS with Autonomous Database.
- Installing and configuring a customer managed environment for ORDS is currently only supported with Autonomous Database on Shared Exadata Infrastructure.
3.2 Downloading Wallet and Verifying Connection to Autonomous Database
You need to configure ORDS to connect to the Autonomous Database. With Oracle REST Data Services (ORDS) running in a customer managed environment, you need to obtain the Autonomous Database wallet on the system that runs the customer managed ORDS. Perform the following steps to download the wallet and verify the connection to the Autonomous Database:
- Download the wallet for the Autonomous Database instance. Alternatively you can use the OCI CLI to generate the wallet. See generate-wallet for information on using the CLI.
- Convert the
wallet.zipfrom the previous step to text. The
base64command encodes binary strings into text representations using the base64 encoding format. For example, run the following command:
base64 -w 0 wallet_NAME.zip > wallet_NAME.zip.b64
This step prepares the wallet as a text file as required for use in the ORDS configuration (instructions for this follow).
- Verify that you can connect from the customer managed environment where you are
installing and configuring ORDS to your Autonomous Database. For example, using
SQLcland the wallet you download in Step 1, verify the connection as follows:
- Connect with SQLcl.
- View the database services and connect to your Autonomous Database from the
customer managed environment.
SQL> show tns TNS_ADMIN set to: /var/folders/4r/path/T/oracle_cloud_config_path Available TNS Entries --------------------- dbname_high dbname_low dbname_medium SQL> conn admin@dbname_low Password? (**********?) ***************** Connected. SQL>
3.3 Creating Customer Managed Oracle REST Data Services User Role
To use Autonomous Database
with Oracle REST Data Services (ORDS) running in a customer managed environment on your Autonomous Database, you must create a user, grant
privileges to the user, and run the procedure
Perform the following steps to create a user for the ORDS JDBC Connection Pool and prepare the Autonomous Database instance for using Oracle REST Data Services in a customer managed environment:
- Connect to your Autonomous Database as the ADMIN user.
- Create a new ORDS user and grant the required privileges to the new user as
CREATE USER "ORDS_PUBLIC_USER2" IDENTIFIED BY "password"; GRANT "CONNECT" TO "ORDS_PUBLIC_USER2";
The new user name
ORDS_PUBLIC_USER2is the recommended user name. This name is not required and you can choose a different user name. If you choose a different user name, then all the corresponding user names in these steps need to use the name you choose, rather than
- Create a database user with the ORDS Developer role, so that it can act as an
ORDS Runtime user. Additional changes to the ORDS configuration are required to
use a user other than ORDS_PUBLIC_USER. As the ADMIN user, run the following procedure:
BEGIN ORDS_ADMIN.PROVISION_RUNTIME_ROLE( p_user => 'ORDS_PUBLIC_USER2', p_proxy_enabled_schemas => TRUE); END; /
Following are the parameters:
p_user: The name of the user to be configured.
p_proxy_enabled_schemas: When set to
true, proxy grants are added for any REST enabled schemas.
3.4 Downloading and Configuring Oracle REST Data Services
To use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment you need to install ORDS.
Note:Oracle REST Data Services 19.4.6 or higher is required for a customer managed environment with Autonomous Database.
Depending on where you install Oracle REST Data Services for your customer managed environment, do the following:
If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then use an Oracle YUM repository and perform a YUM install of ORDS.
If your customer managed environment for Oracle REST Data Services runs in some other environment, then download ORDS from the Oracle REST Data Services Download page. See Installing Oracle REST Data Services for more information.
- In the location where ORDS is installed, create an ORDS configuration folder
(this creates a folder and sets up the ORDS configuration environment and
settings). For example:
java -jar ords.war configdir ./ORDSConfig_2
On Oracle Cloud Infrastructure with Linux with a YUM repository the ORDS configuration folder is:
- Edit the ORDS configuration file created in the preceding step
./ords/conf/apex_pu.xmlto add or update the following:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <entry key="db.username">ORDS_PUBLIC_USER2</entry> <entry key="db.password">!password</entry> <entry key="db.wallet.zip.service">dbname_low</entry> <entry key="db.wallet.zip"><![CDATA[contents_of_wallet_NAME.zip.b64]]></entry> </properties>
The extra "
!" in front of the password causes the password to be encrypted the next time the ORDS service starts.
db.wallet.zipentry (contents_of_wallet_NAME.zip.b64) includes the contents of the
base64encoded wallet archive that you prepared previously. Ensure that this text is enclosed in a CDATA block (this is a long string of characters). See Downloading Wallet and Verifying Connection to Autonomous Database for details on how to create the
db.username, specified as ORDS_PUBLIC_USER2 is the database username you previously defined. See Creating Customer Managed Oracle REST Data Services User Role for more information.
./ords/defaults.xmlas required for your ORDS installation. See Understanding Configurable Parameters for more information.
- Ensure the plsql gateway is enabled for APEX support:
If you want use ORDS with APEX, then you need to enable the PL/SQL gateway in ORDS.
3.5 Preparing and Starting ORDS
To use customer managed Oracle REST Data Services (ORDS) on Autonomous Database, on the system where ORDS runs you need to perform additional configuration steps and then start ORDS.
Note:For ORDS running with APEX, perform all the steps starting from Step 1. For ORDS running without APEX, perform the steps starting from Step 3.
- In the location where ORDS is installed, install the APEX images.
Note:To use your customer managed ORDS environment for APEX, you need to download the APEX images of the APEX version that is currently pre-deployed in Oracle Autonomous Database. You can download the APEX images from Download APEX Images.
- Edit the standalone properties to add or edit the static images property:
- Create a wallet_cache folder, so that ORDS stores the Autonomous Database
wallet on this folder and uses it while connecting to JDBC. For example:
- Start ORDS.
If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then start the ORDS service as follows:
If your customer managed environment for Oracle REST Data Services runs in the directory where ORDS is installed, then start the ORDS service as follows:
java -Duser.timezone=UTC -Ddb.wallet.cache=wallet_cache -jar ords.war standalone --apex-images images --port 8088