Updating and Patching an Instance

You perform an upgrade or patch from the virtual machine (VM) hosting the administration server. You can access this VM through an SSH connection using an account with administrative privileges to run the upgrade and patch scripts. You will need to modify some environmental values in the scripts before running, but these changes are mostly instance specific. As part of provisioning, the scripts for upgrades and patches are deployed to the administration server VM. Each time a subsequent new release is created, or if a patch is needed, the necessary binaries and schema SQL scripts are uploaded into cloud storage for the new version or patch. Using the scripts deployed on the administration server VM, you can download the new binaries and SQL scripts and upgrade or patch the current version.

Topics

Upgrading Gateway Nodes to Release 18.1.5

If you are upgrading from release 18.1.3 to release 18.1.5, the gateway node upgrade is not supported.

To use 18.1.5 features for the gateway nodes, you must install new gateway nodes using the 18.1.5 ApicsGatewayInstaller.zip and join to the same logical gateways. The older gateway nodes will continue functioning for the API traffic and the generated analytics will be uploaded to the management service. No new API deployments or subscriptions will be pushed to the gateway nodes.

See Installing a Gateway Node and Register a Node to a Logical Gateway for more information.

You must also turn off polling manually for all nodes in the system before starting the management tier upgrade. Turning off polling does not affect the analytics push.

Updating a Provisioned Instance

For all provisioned instances, the update script location, middleware home, and gateway installer locations are the same.

Do not modify any scripts unless specifically noted.

Provisioned Instance Defaults

The values are stored in setEnv.sh of the update scripts.

Value	Location
Update Script	`/u01/app/oracle/tools/paas/state/homes/oracle/run/update`
Middleware Home	`/u01/app/oracle/middleware`
Gateway Installer	`/u01/app/oracle/tools/paas/state/homes/oracle/run/downloads`
API Platform Home	`/u01/app/oracle/suite/apip`

Example 2-1 Default values in setEnv.sh

# patch location variables, editable
APICS_SCRIPT_DIR=/u01/app/oracle/tools/paas/state/homes/oracle/run/update
export APICS_SCRIPT_DIR
.
# standard environment variables
GATEWAY_INSTALLER_LOC=/u01/app/oracle/tools/paas/state/homes/oracle/run/downloads
export GATEWAY_INSTALLER_LOC

MW_HOME=/u01/app/oracle/middleware
export MW_HOME

# APIP_ORACLE_HOME=${MW_HOME}/../suite
export APIP_ORACLE_HOME

Instance-Specific Values

Update the setEnv.sh script with instance specific values for the Storage URL, Management Portal URL, and the WLS administrator user name.

These values must be modified for the update to succeed.

User Values

The values are stored in setEnv.sh of the update scripts.

Storage Location URL — This is the location where the upgrade files are stored in the cloud, https://storage.us2.oraclecloud.com/v1/jaascdc1-usoracledevop09525/jcs/APICS.
Management Portal URL — This is the endpoint for the API Platform Cloud Service Manager Portal, for example https://example/apiplatform.
Weblogic Administrator — Created during original provisioning.
DBA User (user name for the associated DBaaS service)

Example 2-2 User values in setEnv.sh

# storage URL where upgrade bits are stored
STORAGE_URL=<storageUrl>
export STORAGE_URL

# URL for API Manager Portal
MGR_URL=<managerPortalUrl>
export MGR_URL

# WLS administrator created at initial provisioning
WLS_ADMIN=<wlsAdmin>
export WLS_ADMIN

DBA_USER_NAME=<dbaUser>
export DBA_USER_NAME

Pre-Update Steps

Perform these pre-upgrade steps before upgrading your instance.

Download the apics_suite.zip file for the version you’re upgrading to (such as 18.1.3) from the registered PCAR in cloud storage.
Make a backup of the original /u01/app/oracle/tools/paas/state/homes/oracle/run/update folder.
Unzip the contents of the scripts/update folder contained in apics_suite.zip. It is very important that the /u01/app/oracle/tools/paas/state/homes/oracle/run/update folder contains the scripts from scripts/update in apics_suite.zip or the upgrade process will fail.
Note: The update folder must be moved from the scripts folder to the run folder.
Verify all the shell scripts (*.sh) permissions allow execute permissions.

Update Process

Steps to perform the upgrade or patch:

Confirm that a backup of the API Platform Cloud Service and DBaaS instances were performed.
Provision an instance script for future upgrade or patch to be deployed to the administration server virtual machine (VM).
Connect to the administration server VM through an SSH connection.
```
$ ssh -i privateKey opc@xxx.xxx.x.x
```
Change to the oracle user for administrative privileges:
```
$ sudo su - oracle
```

Change to the folder where the update scripts reside:

cd /u01/app/oracle/tools/paas/state/homes/oracle/run/update

Make updates to setEnv.sh.
Launch the upgrade or patch script with necessary parameters (upgrade version or patch name and administrative user password).
```
# for upgrades
```
$ ./upgrade.sh <version>

# example:

$ ./upgrade.sh 18.1.3.0.0_25

The scripts execute the following actions:

Stops and restarts servers.

Creates a folder with the update script folder with the name of the upgrade version or patch name
Downloads upgrade or patch package from cloud storage.
Unzips the upgrade or patch package
Checks to see if there are any schema update SQL scripts
- Stops the managed servers if an update SQL script exists
- Runs the update SQL scripts using the rcuJDBCEngine utility
- Restarts the managed servers
Checks to see if there are any seeding SQL scripts for the artifacts and policies
- Runs the seeding SQL scripts for artifacts and policies
Checks to see if there are any updated binaries to be deployed (always for upgrades)
Copies new binaries into middleware home apip/lib folder
Stops and restarts the administration server and two managed servers

Update is complete. Complete any post-upgrade steps as necessary.

Upgrade logs are located on the administration server where the scripts are run at the directory /tmp/APICS_<timestamp>. If you need to view the logs, then when the upgrade completes, look at the last line, for example:

Upgrade complete 
[oracle@<admin_server_name>upg-wls-1 update]$

To see the logs, navigate to /tmp/APICS_2018-03-16T18:18:25 on the administrative server.

Post Upgrade Steps

Perform these steps to complete a successful upgrade.

Perform these steps as necessary.

Clean browser cache: To render the landing pages of both the Management and Developer Portals or Oracle API Platform Cloud Service - Classic correctly after upgrade, clean the browser cache and open a new browser window. You may need to do this twice.
Restart gateway node: To generate analytics from the EDR files, check whether there is TOKEN_ISSUER_URL exception in /<gateway node domain>/apics/logs/analytics.log. If it exists, restart the gateway node domain.
Messages not reflected in Analystics UI: If, after upgrading, messages are not reflected in the Analystics UI, perform the following tasks:
- Delete the timestamps file to force reprocessing. The command is rm <gateway-domain-name>/apics/analytics/timestamps.
- Check apics/analytics/logstash.out for the following string: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target. To resolve the issue, restart logstash.
```
cd apics/analytics 
./manageLogstash.sh stop 
```
  Wait for 30–60 seconds for logstash process to exit.
```
./manageLogstash.sh start 
```
  Note:
  The messages that are sent after upgrade and before the fix do not appear in the Analytics UI.

Update Folder Structure

The provisioned instance comes with the update scripts deployed in /u01/app/oracle/tools/paas/state/homes/oracle/run/update on the administration server VM.

$ ls
copyAppProps.py    deployApps.py            getStripeId.sh       rollbackApps.sh         shutdownTarget.sh
copyApps.py        deployApps.sh            patch.sh             rollbackProps.json      startTargetProps.py
copyApps.sh        getSchemaVersion.groovy  readme.txt           setEnv.sh               startTarget.py
createRollback.sh  getSchemaVersion.sh      rollbackAppProps.py  shutdownTargetProps.py  startTarget.sh
deployAppProps.py  getStripeId.groovy       rollbackApps.py      shutdownTarget.py       upgrade.sh

Other than the scripts mentioned above, the other scripts should not be modified. They are used in support of the upgrade and patch scripts.

Update Package Structure

The upgrade or patch package used for updating Oracle API Platform Cloud Service - Classic has the following structure:

upgrade.zip or <patchName>.zip

    deployProps.json - list of updated web applications to be deployed
    artifacts - folder containing seeding SQL scripts for the artifacts
        sql
            installer
                <seeding scripts for artifacts>
    gatewayInstaller - folder containing updated version of the Gateway Installer
        ApicsGatewayInstaller.zip - gateway installer
    lib
        <web application binaries>
    policies
        sql
            installer
                <seeding scripts for policies>
    sql
        apip - root folder for APIP schema updates
            apipSeeding.sh - script to launch artifact and policy seeding SQL scripts for APIP schema
            apipUpgrade.sh - script to launch schema upgrade SQL scripts for APIP schema
            upgrade - folder containing upgrade SQL scripts for APIP schema
                upgrade.properties - properties file associating upgrade SQL script to schema version and APIPCS version for APIP schema
                <schema upgrade SQL scripts> - name format is upgrade_<APIPCS version>.sql
                seeding - folder containing the SQL scripts referencing the SQL scripts that reside in artifacts and policies root folders
                    scripts
                        insertArtifacts.sql - launch SQL script for calling artifact seeding SQL scripts
                        insertPolicies.sql - launch SQL script for calling policy seeding SQL scripts
        apis - root folder for APIS schema updates
            apisSeeding.sh - script to launch artifact and policy seeding SQL scripts for APIS schema
            apisUpgrade.sh - script to launch schema upgrade SQL scripts for APIS schema
            upgrade - folder containing upgrade SQL scripts for APIS schema
                upgrade.properties - properties file associating upgrade SQL script to schema version and APIPCS version for APIS schema
                <schema upgrade SQL scripts> - name format is upgrade_<APIPCS version>.sql
                seeding - folder containing the SQL scripts referencing the SQL scripts that reside in artifacts and policies root folders
                    scripts
                        insertArtifacts.sql - launch SQL script for calling artifact seeding SQL scripts
                        insertPolicies.sql - launch SQL script for calling policy seeding SQL scripts

Other than the scripts mentioned above, the other scripts should not be modified; They are used in support of the upgrade and patch scripts.

Example Folder Structure

Schemas do not necessarily have to upgrade with each upgrade of APIPCS, so there may not be a corresponding schema upgrade SQL script for the Oracle API Platform Cloud Service - Classic version. Once the upgrade or patch script is run, all work is done within the update script folder. The following shows an example of the folder structure if upgrading to version 17.2.5.0.0_20:

# contents of /u01/app/oracle/tools/paas/state/homes/oracle/run/update
17.2.5.0.0_20
copyAppProps.py
copyApps.py
copyApps.sh
createRollback.sh
deployAppProps.py
deployApps.py
deployApps.sh
getSchemaVersion.groovy
getSchemaVersion.sh
getStripeId.groovy
getStripeId.sh
patch.sh
readme.txt
rollbackAppProps.py
rollbackApps.py
rollbackApps.sh
rollbackProps.json
setEnv.sh
shutdownTargetProps.py
shutdownTarget.py
shutdownTarget.sh
startTargetProps.py
startTarget.py
startTarget.sh
test.txt
upgrade.sh
 
./17.2.5.0.0_20:
artifacts
deployProps.json
gatewayInstaller
lib
policies
sql
upgrade.zip
 
./17.2.5.0.0_20/artifacts:
sql
 
./17.2.5.0.0_20/artifacts/sql:
installer
 
./17.2.5.0.0_20/artifacts/sql/installer:
apics-analytics.logstash.config.zip.sql
   .
   .
oracle.apiplatform.analytics.agent.ear.tenant.sql
 
./17.2.5.0.0_20/gatewayInstaller:
ApicsGatewayInstaller.zip
 
./17.2.5.0.0_20/lib:
oracle.apiplatform.admin.app.ear
   .
   .
oracle.apiplatform.system.app.ear
 
./17.2.5.0.0_20/policies:
sql
 
./17.2.5.0.0_20/policies/sql:
installer
 
./17.2.5.0.0_20/policies/sql/installer:
oracle.apiplatform.policies.apiratelimiting.sql
   .
   .
oracle.apiplatform.policies.serviceresponse.tenant.sql
 
./17.2.5.0.0_20/sql:
apip
apis
 
./17.2.5.0.0_20/sql/apip:
apipSeeding.sh
apipUpgrade.sh
upgrade
 
./17.2.5.0.0_20/sql/apip/upgrade:
seeding
upgrade.properties
upgradeSchema_17.2.1.sql
upgradeSchema_17.2.3.sql
 
./17.2.5.0.0_20/sql/apip/upgrade/seeding:
scripts
 
./17.2.5.0.0_20/sql/apip/upgrade/seeding/scripts:
artifacts
policies
 
./17.2.5.0.0_20/sql/apip/upgrade/seeding/scripts/artifacts:
insertArtifacts.sql
 
./17.2.5.0.0_20/sql/apip/upgrade/seeding/scripts/policies:
insertPolicies.sql
 
./17.2.5.0.0_20/sql/apis:
apisSeeding.sh
apisUpgrade.sh
upgrade
 
./17.2.5.0.0_20/sql/apis/upgrade:
seeding
upgrade.properties
upgradeSchema_17.2.1.sql
 
./17.2.5.0.0_20/sql/apis/upgrade/seeding:
scripts
 
./17.2.5.0.0_20/sql/apis/upgrade/seeding/scripts:
artifacts
policies
 
./17.2.5.0.0_20/sql/apis/upgrade/seeding/scripts/artifacts:
insertArtifacts.sql
 
./17.2.5.0.0_20/sql/apis/upgrade/seeding/scripts/policies:
insertPolicies.sql