Chapter 2. Upgrading 3scale version 2.10 to version 2.11 using templates

Procedure

1. Depending on the database used with 3scale, set ${SYSTEM_DB} with one of the following values:

   • If the database is MySQL, SYSTEM_DB=system-mysql.
   • If the database is PostgreSQL, SYSTEM_DB=system-postgresql.

2. Create a backup file with the existing DeploymentConfigs:

   $ THREESCALE_DC_NAMES="apicast-production apicast-staging backend-cron backend-listener backend-redis backend-worker system-app system-memcache ${SYSTEM_DB} system-redis system-sidekiq system-sphinx zync zync-database zync-que"
   
   for component in ${THREESCALE_DC_NAMES}; do oc get --export -o yaml dc ${component} > ${component}_dc.yml ; done

   Copy to Clipboard Toggle word wrap

3. Backup all existing OpenShift resources in the project that are exported through the export all command:

   $ oc get -o yaml --export all > threescale-project-elements.yaml

   Copy to Clipboard Toggle word wrap

4. Create a backup file with the additional elements that are not exported with the export all command:

   $ for object in rolebindings serviceaccounts secrets imagestreamtags cm rolebindingrestrictions limitranges resourcequotas pvc templates cronjobs statefulsets hpa deployments replicasets poddisruptionbudget endpoints
   do
     oc get -o yaml --export $object > $object.yaml
   done

   Copy to Clipboard Toggle word wrap
5. Verify that all of the generated files are not empty, and that all of them have the expected content.

Procedure

1. To patch AMP_RELEASE, run this command:

   $ oc patch cm system-environment --patch '{"data": {"AMP_RELEASE": "2.11"}}'

   Copy to Clipboard Toggle word wrap

2. Confirm that the AMP_RELEASE key in the system-environment ConfigMap has the 2.11 value:

   $ oc get cm system-environment -o json | jq '.data["AMP_RELEASE"]'

   Copy to Clipboard Toggle word wrap

Procedure

1. Update the variable in the system-app pre-hook pod by editing the system-app DeploymentConfig:

   $ oc edit dc system-app

   Copy to Clipboard Toggle word wrap

   You will enter an interactive editor session. Find the BACKEND_ROUTE environment variable in the .spec.strategy.rollingParams.pre.execNewPod.env array section.

   1. Replace the following entry:

      - name: BACKEND_ROUTE
        valueFrom:
          secretKeyRef:
            key: route_endpoint
            name: backend-listener

      Copy to Clipboard Toggle word wrap

   2. With this entry:

      - name: BACKEND_ROUTE
        value: http://backend-listener:3000/internal/

      Copy to Clipboard Toggle word wrap

      Save your changes and exit the interactive editor session.

2. Update the entry on system-app containers:

   $ oc set env dc/system-app BACKEND_ROUTE="http://backend-listener:3000/internal/"

   Copy to Clipboard Toggle word wrap

   This command triggers a redeployment of system-app. Wait until it is redeployed, its corresponding new pods are ready, and the previous pods are terminated.

3. Update it on system-sidekiq container:

   $ oc set env dc/system-sidekiq BACKEND_ROUTE="http://backend-listener:3000/internal/"

   Copy to Clipboard Toggle word wrap

   This command triggers a redeployment of system-sidekiq. Wait until it is redeployed, its corresponding new pods are ready, and the previous pods are terminated.

Procedure

1. Take note of the current values for the prometheus.io/port and prometheus.io/scrape annotations by running:

   $ oc get dc zync -o json | jq .metadata.annotations

   Copy to Clipboard Toggle word wrap

2. Add the annotations to zync DeploymentConfig’s PodTemplate annotations. If the prometheus.io/port and prometheus.io/scrape annotation values are different than the ones shown in the command below replace them with the values that are currently set in the zync DeploymentConfig as shown by the previous command:

   $ oc patch dc zync --patch '{"spec":{"template":{"metadata":{"annotations":{"prometheus.io/port":"9393","prometheus.io/scrape":"true"}}}}}'

   Copy to Clipboard Toggle word wrap

3. Remove the original annotations from the zync DeploymentConfig annotations:

   $ oc annotate dc zync prometheus.io/scrape-
   $ oc annotate dc zync prometheus.io/port-

   Copy to Clipboard Toggle word wrap

   This command triggers a redeployment of zync. Wait until it is redeployed, its corresponding new pods are ready, and the previous pods are terminated.

Procedure

1. Check the current resource requirements set for backend-cron with the following command:

   $ oc get dc backend-cron -o json | jq .spec.template.spec.containers[0].resources

   Copy to Clipboard Toggle word wrap

   If the output is empty or null it means no resource requirements are set.

2. To increase the current backend-cron resource requirements, run the following command:

   $ oc patch dc backend-cron --patch '{"spec":{"template":{"spec":{"containers":[{"name":"backend-cron","resources":{"limits":{"memory":"500Mi", "cpu": "500m"}, "requests":{"memory":"100Mi", "cpu": "100m"}}}]}}}}'

   Copy to Clipboard Toggle word wrap

   This command triggers a redeployment of backend-cron. Wait until it is redeployed, its corresponding new pods are ready, and the previous pods are terminated.

Procedure

1. 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

   Copy to Clipboard Toggle word wrap
2. 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.

3. Run the oc process command with the -f option and specify the build.yml OpenShift template:

   $ oc process -f build.yml | oc apply -f -

   Copy to Clipboard Toggle word wrap

4. 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

   Copy to Clipboard Toggle word wrap
   Note

   The following steps are optional. Use them if you remove ORACLE_SYSTEM_PASSWORD after the installation or a system upgrade.

5. 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"}]}}}}}}'

   Copy to Clipboard Toggle word wrap

6. 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"}}'

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

8. 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}"

   Copy to Clipboard Toggle word wrap
   1. Wait until the build is in a Complete state.

9. 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-

   Copy to Clipboard Toggle word wrap