Menu Close

Chapter 3. Upgrading 3scale version 2.11.0 to version 2.11.1 using templates

You can upgrade Red Hat 3scale API Management from version 2.11.0 to version 2.11.1 using a template-based deployment on OpenShift 3.11.

Important

To understand the required conditions and procedures, be sure to read the entire upgrade guide before applying the listed steps. The upgrade process disrupts the provision of the service until the procedure finishes. Due to this disruption, be sure to have a maintenance window.

3.1. Prerequisites to perform the upgrade

This section describes the required configurations, tasks, and tools to upgrade 3scale from 2.11.0 to 2.11.1 in a template-based installation.

3.1.1. Configurations

  • 3scale supports upgrade paths from 2.11.0 to 2.11.1 with templates on OpenShift 3.11.

3.1.2. Preliminary tasks

  • Ensure your OpenShift CLI tool is configured in the same project where 3scale is deployed.
  • Perform a backup of the database you are using with 3scale. The procedure of the backup is specific to each database type and setup.

3.1.3. Tools

You need these tools to perform the upgrade:

  • 3scale 2.11.0 deployed with templates in an OpenShift 3.11 project.
  • Bash shell: To run the commands detailed in the upgrade procedure.
  • base64: To encode and decode secret information.
  • jq: For JSON transformation purposes.

3.2. Upgrading from 3scale 2.11.0 to 2.11.1 in a template-based installation

Follow the procedure described in this section to upgrade 3scale 2.11.0 to 2.11.1 in a template-based installation.

To start with the upgrade, go to the project where 3scale is deployed.

$ oc project <3scale-project>

Then, follow these steps in this order:

3.2.1. Creating a backup of the 3scale project

Previous step

None.

Current step

This step lists the actions necessary to create a backup of the 3scale project.

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.

3.2.2. Increasing backend-cron DeploymentConfig resource requirements

Current step

In this release backend-cron DeploymentConfig has potentially more resources usage. Use this procedure to increase the resource requirements from the currently set values.

The required backend-cron resource in 3scale 2.11.1 are:

{
  "limits": {
	"cpu": "500m",
	"memory": "500Mi"
  },
  "requests": {
	"cpu": "100m",
	"memory": "100Mi"
  }
}

If the current backend-cron deployment has no memory limits or the resource requirements are higher, you do not need to complete the following procedure.

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.

3.2.3. Upgrading 3scale images

Current step

This step updates the 3scale images required for the upgrade process.

3.2.3.1. Patch the system image

  1. To continue the procedure, consider the database used with your 3scale deployment:

3.2.3.2. Patching the system image: 3scale with Oracle Database

  1. To start patching the system image of 3scale with an Oracle Database, perform steps 1, 2, 4, and 8 in Building the system image.
  2. Import the latest amp-system Oracle Database image:

    oc import-image amp-system:2.11-oracle

3.2.3.3. Patching the system image: 3scale with other databases

Import the latest system-app image:

oc import-image amp-system:2.11

3.2.3.4. Patch the apicast image

Import the latest amp-apicast image:

oc import-image amp-apicast:2.11

3.2.3.5. Patch the backend image

Import the latest amp-backend image:

oc import-image amp-backend:2.11

3.2.3.6. Patch the zync image

Import the latest amp-zync image:

oc import-image amp-zync:2.11

3.2.3.7. Patch the system-memcached image

Import the latest system-memcached image:

oc import-image system-memcached:2.11

Next step

None. After you have performed all the listed steps, 3scale upgrade from 2.11.0 to 2.11.1 in a template-based deployment is now complete.