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

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

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

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

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"]'

Procedure

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

   $ oc edit dc system-app

   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

   2. With this entry:

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

      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/"

   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/"

   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

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

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

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

   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

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

   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

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 -

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

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

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

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

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

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

   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-