Menu Close

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

Note

This section explains how a Red Hat 3scale API Management administrator sets up the 3scale system image with an Oracle Database. By default, 3scale 2.10 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

Oracle 19c example packages

  • Oracle Instant Client Package - Basic or Basic Light: instantclient-basic-linux.x64-19.8.0.0.0dbru.zip or instantclient-basiclite-linux.x64-19.8.0.0.0dbru.zip
  • Oracle Instant Client Package - SDK: instantclient-sdk-linux.x64-19.8.0.0.0dbru.zip
  • Oracle Instant Client Package - ODBC: instantclient-odbc-linux.x64-19.8.0.0.0dbru.zip

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

9.1. Preparing the Oracle Database

This section provides steps for preparing your Oracle Database.

Prerequisites

  • A supported version of the Oracle Database accessible from your OpenShift cluster.
  • Access to the Oracle Database system user for installation procedures.

Procedure

  1. Create a new database.

    To configure 3scale with Oracle Database, use the following settings:

    ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
  2. Collect the database details.

    You need the following information for 3scale configuration:

    • The Oracle Database URL address.
    • The Oracle Database. service name
    • The 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

9.2. Building the system image

This section provides steps to build the system image.

Prerequisites

Procedure

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

    git clone --branch 3scale-2.10.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.10 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 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 Preparing the Oracle Database:

    $ oc patch secret/system-database -p '{"stringData": {"URL": "DATABASE_URL"}}'
  8. Enter the oc start-build command to build the new system image:

    $ oc start-build 3scale-amp-system-oracle --from-dir=.
  9. Wait until the build completes. To see the state of the build, run the following command:

    $ oc get build <build-name> -o jsonpath="{.status.phase}"
    1. Wait until the build is in a Complete state.

9.2.1. Updating ImageChange triggers

Update the ImageChange triggers of the DeploymentConfigs that use the System image so they use the new Oracle-based System image.

Prerequisites

Procedure

  1. Save the current 3scale release in an environment variable:

    $ export THREESCALE_RELEASE=2.10
  2. Update the system-app ImageChange trigger:

    $ oc set triggers dc/system-app --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-master,system-developer,system-provider --remove
    
    $ oc set triggers dc/system-app --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-master,system-developer,system-provider

    This triggers a redeployment of the system-app DeploymentConfig. Wait until it is redeployed, its corresponding new pods are ready, and the old ones have stopped.

  3. Update the system-sidekiq ImageChange trigger:

    $ oc set triggers dc/system-sidekiq --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-sidekiq,check-svc --remove
    
    $ oc set triggers dc/system-sidekiq --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-sidekiq,check-svc

    This triggers a redeployment of the system-sidekiq DeploymentConfig. Wait until it is redeployed, its corresponding new pods are ready, and the old ones have stopped.

  4. Update the system-sphinx ImageChange trigger:

    $ oc set triggers dc/system-sphinx --from-image=amp-system:${THREESCALE_RELEASE} --containers=system-sphinx,system-master-svc --remove
    
    $ oc set triggers dc/system-sphinx --from-image=amp-system:${THREESCALE_RELEASE}-oracle --containers=system-sphinx,system-master-svc

    This triggers a redeployment of the system-sphinx DeploymentConfig. Wait until it is redeployed, its corresponding new pods are ready, and the old ones have stopped.

    Note

    The following step is optional. Use it to remove ORACLE_SYSTEM_PASSWORD after the installation of 3scale.

  5. Once you have set up your 3scale system image with your Oracle Database, remove ORACLE_SYSTEM_PASSWORD from the system-app DeploymentConfig. It is not necessary again until you upgrade to a new version of 3scale.

    $ oc set env dc/system-app ORACLE_SYSTEM_PASSWORD-

Additional resources

For more information about 3scale and Oracle Database support, see Red Hat 3scale API Management Supported Configurations.