Chapter 1. Setting up your 3scale system image with an Oracle Database

This section explains how a Red Hat 3scale API Management administrator sets up the 3scale system image with an Oracle Database. By default, 3scale has a component called system that stores configuration data in a MySQL database. You can override the default database and store your information in an external Oracle Database. Follow the steps in this chapter to build a custom system container image with your own Oracle Database client binaries and deploy 3scale to OpenShift.

Prerequisites

A supported version of the following Oracle software components:

  • Oracle Instant Client Package: Basic or Basic Light
  • Oracle Instant Client Package: SDK
  • Oracle Instant Client Package: ODBC

Example packages

  • instantclient-basiclite-linux.x64-12.2.0.1.0.zip or instantclient-basic-linux.x64-12.2.0.1.0.zip
  • instantclient-sdk-linux.x64-12.2.0.1.0.zip
  • instantclient-odbc-linux.x64-12.2.0.1.0-2.zip

To set up your 3scale system image with and Oracle Database, perform the steps outlined in the following sections:

1.1. Preparing the Oracle Database

This section provides steps for preparing your Oracle Database.

Prerequisites

  • A supported version of Oracle Database accessible from your OpenShift cluster
  • Access to the Oracle Database system user for installation procedures
  • The 3scale 2.5 amp.yml template

Procedure

  1. Create a new database.

    The following settings are required for the Oracle Database to work with 3scale: 

    ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
ALTER SYSTEM SET compatible='12.2.0.1' SCOPE=SPFILE;

  2. Collect the database details.

    Get the following information that will be needed for 3scale configuration:

    • Oracle Database URL
    • Oracle Database service name

    • Oracle Database system password

      The DATABASE_URL parameter must follow this format: oracle-enhanced://${user}:${password}@${host}:${port}/${database}`

Example

DATABASE_URL="oracle-enhanced://user:password@my-oracle-database.com:1521/threescalepdb"

Additional resources

For information on creating a new database in Oracle Database, see the Oracle documentation.

1.2. Building the system image

Note

After you download the system Oracle build.yml file, you will have to manually change the AMP_RELEASE value from 2.4.0 to 2.5.0.

This section provides steps to build the system image.

Prerequisites

Procedure

  1. Clone the 3scale OpenShift Templates GitHub repository. Use the following command: 

    git clone --branch 2.5.0.GA https://github.com/3scale/3scale-amp-openshift-templates.git
  2. Place your Oracle Database Instant Client Package files into the 3scale-amp-openshift-templates/amp/system-oracle/oracle-client-files directory.
  3. Download the 3scale 2.5 amp.yml template.

  4. Run the oc new-app command with the -f option and specify the build.yml OpenShift template: 

    $ oc new-app -f build.yml

  5. Run the oc new-app command with the -f option to indicate the amp.yml OpenShift template, and the -p option to specify the WILDCARD_DOMAIN parameter with the domain of your OpenShift cluster: 

    $ oc new-app -f amp.yml -p WILDCARD_DOMAIN=mydomain.com

  6. Enter the following oc patch commands, replacing SYSTEM_PASSWORD with the Oracle Database system password you set up in Section 1.1, “Preparing the Oracle Database”: 

    $ oc patch dc/system-app -p '[{"op": "add", "path": "/spec/strategy/rollingParams/pre/execNewPod/env/-", "value": {"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}}]' --type=json

$ oc patch dc/system-app -p '{"spec": {"strategy": {"rollingParams": {"post":{"execNewPod": {"env": [{"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}]}}}}}}'

  7. Enter the following command, replacing DATABASE_URL to point to your Oracle Database, specified in Section 1.1, “Preparing the Oracle Database”: 

    $ oc patch secret/system-database -p '{"stringData": {"URL": "DATABASE_URL"}}'

  8. Link the pull secret to the builder with the following command: 

    oc secrets link builder threescale-registry-auth

  9. Enter the oc start-build command to build the new system image: 

    oc start-build 3scale-amp-system-oracle --from-dir=.

Additional resources