Chapter 9. Setting up your 3scale system image with an Oracle Database
- The Oracle Database is only supported with OpenShift Container Platform (OCP) 3.11 when you are performing a template-based installation of 3scale.
- If you are performing a 3scale deployment with the operator using the Oracle Database, see Installing 3scale with the operator using the Oracle Database.
- As of 3scale 2.10, Oracle Database 12c is no longer supported.
- For more information about supported configurations, see the Red Hat 3scale API Management Supported Configurations page.
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.11 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
From the Instant Client Downloads page, download:
- A client: It can be either basic-lite or basic.
- The ODBC driver.
The SDK for Oracle Database 19c.
- For 3scale, use Instant Client Downloads for Linux x86-64 (64-bit)
- For ppc64le and 3scale, use Oracle Instant Client Downloads for Linux on Power Little Endian (64-bit)
Check the Red Hat 3scale API Management Supported Configurations for 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 package name | Compressed file name |
---|---|
Basic | instantclient-basic-linux.x64-19.8.0.0.0dbru.zip |
Basic Light | instantclient-basiclite-linux.x64-19.8.0.0.0dbru.zip |
SDK | instantclient-sdk-linux.x64-19.8.0.0.0dbru.zip |
ODBC | instantclient-odbc-linux.x64-19.8.0.0.0dbru.zip |
Oracle 19c package name | Compressed file name |
---|---|
Basic | instantclient-basic-linux.leppc64.c64-19.3.0.0.0dbru.zip |
Basic Light | instantclient-basiclite-linux.leppc64.c64-19.3.0.0.0dbru.zip |
SDK | instantclient-sdk-linux.leppc64.c64-19.3.0.0.0dbru.zip |
ODBC | instantclient-odbc-linux.leppc64.c64-19.3.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
Create a new database.
To configure 3scale with Oracle Database, use the following settings:
ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
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
- For information on creating a new database in Oracle Database, see the Oracle documentation.
9.2. Building the system image
This section provides steps to build the system image.
Prerequisites
- You should have already carried out the steps in Preparing the Oracle Database.
Procedure
Download 3scale OpenShift templates from the GitHub repository and extract the archive:
tar -xzf 3scale-amp-openshift-templates-3scale-2.11.1-GA.tar.gz
-
Place your Oracle Database Instant Client Package files into the
3scale-amp-openshift-templates-3scale-2.11.1-GA/amp/system-oracle/oracle-client-files
directory. - Download the 3scale 2.11 amp.yml template.
Run the
oc new-app
command with the-f
option and specify thebuild.yml
OpenShift template:$ oc new-app -f build.yml
Run the
oc new-app
command with the-f
option to indicate theamp.yml
OpenShift template, and the-p
option to specify theWILDCARD_DOMAIN
parameter with the domain of your OpenShift cluster:$ oc new-app -f amp.yml -p WILDCARD_DOMAIN=mydomain.com
Enter the following
oc patch
commands, replacingSYSTEM_PASSWORD
with the Oracle Databasesystem
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"}]}}}}}}'
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"}}'
Enter the
oc start-build
command to build the new system image:$ oc start-build 3scale-amp-system-oracle --from-dir=.
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}"
- 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
- First carry out the steps in Building the system image.
Procedure
Save the current 3scale release in an environment variable:
$ export THREESCALE_RELEASE=2.11
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.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.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.NoteThe following step is optional. Use it to remove
ORACLE_SYSTEM_PASSWORD
after the installation of 3scale.Once you have set up your 3scale system image with your Oracle Database, remove
ORACLE_SYSTEM_PASSWORD
from thesystem-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.