Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Migrating 3scale

Red Hat 3scale API Management 2.12

Migrate or upgrade 3scale API Management and its components

Red Hat Customer Content Services

Abstract

Migrate 3scale from a template to an operator-based installation. Also, find the information to upgrade 3scale and its components to the latest version.

Preface
Copy link

This guide provides the information to migrate Red Hat 3scale API Management from a template to an operator-based installation, the details required to upgrade your 3scale installation from 2.10 to 2.11, as well as the steps to upgrade APIcast in an operator-based deployment.

To migrate from a template-based to an operator-based deployment, refer to the procedures listed in the 3scale migration guide.

To upgrade your 3scale On-premises deployment from 2.10 to 2.11, refer to one of the following guides depending on the installation type:

To upgrade APIcast in an operator-based deployment, refer to the steps listed in the APIcast upgrade guide.

Making open source more inclusive
Copy link

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

This section contains information about migrating Red Hat 3scale API Management from a template-based deployment using Red Hat OpenShift 3.11, to an operator-based deployment using Red Hat OpenShift 4.x.

Warning

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

1.1. Prerequisites to perform the migration
Copy link

Before migrating your 3scale installation from a template to an operator-based deployment, confirm that your deployment is supported by consulting the following guides:

The basic setup before migration is that 3scale points to the OCP3 domain: 3scale.example.com → ocp3.example.com

To migrate 3scale from a template-based deployment using Red Hat OpenShift 3.11 to an operator-based deployment using Red Hat OpenShift 4.1, follow these steps:

  1. Create a 3scale backup from the template-based deployment.
  2. Deploy 3scale using the operator.
  3. Restore the backup in the operator-based deployment.
  4. Point the 3scale WILDCARD_DOMAIN, in this case 3scale.example.com, to ocp4.example.com.

After you have performed all the listed steps, 3scale migration from a template to an operator-based deployment is now complete.

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

Important

This is the last release supporting upgrades of 3scale deployed with templates on OpenShift 3.11. You should follow the 3scale migration guide: from template to operator-based deployments to stay supported in future releases.

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.

2.1. Prerequisites to perform the upgrade
Copy link

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

2.1.1. Configurations
Copy link

  • 3scale supports upgrade paths from 2.11 to 2.12 with templates on OpenShift 3.11.

2.1.2. Preliminary tasks
Copy link

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

2.1.3. Tools
Copy link

You need these tools to perform the upgrade:

  • 3scale 2.11 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.

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

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

$ oc project <3scale-project>
Copy to Clipboard Toggle word wrap

Then, follow these steps in this order:

  1. Creating a backup of the 3scale project
  2. Removing unused AMP_RELEASE variables
  3. Upgrading the MySQL configuration
  4. Upgrading 3scale images
  5. Additional image changes
  6. Confirm image URLs
  7. Removing unused MessageBus variables

2.2.1. Creating a backup of the 3scale project
Copy link

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

Next step

Removing unused AMP_RELEASE variables

2.2.2. Removing unused AMP_RELEASE variables
Copy link

Previous step

Creating a backup of the 3scale project

Current step

This step removes unused AMP_RELEASE variables from system-app containers, the system-app pre hook, and then verifies that AMP_RELEASE does not exist.

Procedure

  1. Remove the variable from the system-app containers:

    • Note the dash char after the variable name. 

      $ oc set env dc/system-app AMP_RELEASE-
      Copy to Clipboard Toggle word wrap

  2. Remove the variable from the system-app pre hook: 

    $ INDEX=$(oc get dc system-app -o json | jq '.spec.strategy.rollingParams.pre.execNewPod.env | map(.name == "AMP_RELEASE") | index(true)')
oc patch dc/system-app --type=json -p "[{'op': 'remove', 'path': '/spec/strategy/rollingParams/pre/execNewPod/env/$INDEX'}]"
    Copy to Clipboard Toggle word wrap

  3. Verify AMP_RELEASE does not exist: 

    $ oc get dc system-app -o yaml | grep AMP_RELEASE
    Copy to Clipboard Toggle word wrap

Next step

Upgrading the MySQL configuration

2.2.3. Upgrading your MySQL configuration
Copy link

Note

If your 3scale deployment has the external databases mode enabled and uses MySQL 8.0, set the authentication plugin to mysql_native_password for 3scale 2.12.

Add the following to the MySQL configuration file: 

[mysqld]
default_authentication_plugin=mysql_native_password
Copy to Clipboard Toggle word wrap

Previous step

Removing unused AMP_RELEASE variables

Current step

This step patches the MySQL configuration configmap to enable upgrade to MySQL 8.0.

Note

Only follow this procedure if a system-mysql deployment exists in your current 3scale installation.

Procedure

  1. Patch the configmap: 

    $ oc patch configmap/mysql-extra-conf --type merge -p '{"data": {"mysql-default-authentication-plugin.cnf": "[mysqld]\ndefault_authentication_plugin=mysql_native_password"}}'
    Copy to Clipboard Toggle word wrap

  2. Verify the configmap is updated: 

    $ oc get cm mysql-extra-conf -o jsonpath='{.data.mysql-default-authentication-plugin\.cnf}'
    Copy to Clipboard Toggle word wrap

    • Should return: 

      [mysqld]
default_authentication_plugin=mysql_native_password
      Copy to Clipboard Toggle word wrap

Next step

Upgrading 3scale images

2.2.4. Upgrading 3scale images
Copy link

Previous step

Upgrading your MySQL configuration

Current step

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

2.2.4.1. Patch the system image
Copy link

  1. Create the new image stream tag: 

    $ oc patch imagestream/amp-system --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP system 2.12"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/system-rhel7:3scale2.12"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

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

  1. To start patching the system image of 3scale with an Oracle Database, you must build the system image:

    • Download 3scale OpenShift templates from the GitHub repository and extract the archive: 

      tar -xzf 3scale-amp-openshift-templates-3scale-2.12.0-GA.tar.gz
      Copy to Clipboard Toggle word wrap
    • Place your Oracle Database Instant Client Package files into the 3scale-amp-openshift-templates-3scale-2.12.0-GA/amp/system-oracle/oracle-client-files directory.

    • Run the oc process command with the -f option and specify the build.yml OpenShift template with the oc apply command and the -f option to override the existing build: 

      $ oc process -f build.yml | oc apply -f -
      Copy to Clipboard Toggle word wrap

    • 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

  2. Patch the system-app ImageChangeTrigger:

    1. Remove the old 2.11-oracle trigger: 

      $ oc set triggers dc/system-app --from-image=amp-system:2.11-oracle --containers=system-master,system-developer,system-provider --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-app --from-image=amp-system:2.12-oracle --containers=system-master,system-developer,system-provider
      Copy to Clipboard Toggle word wrap

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

  3. Patch the system-sidekiq ImageChange trigger:

    1. Remove the old 2.11-oracle trigger: 

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.11-oracle --containers=system-sidekiq,check-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.12-oracle --containers=system-sidekiq,check-svc
      Copy to Clipboard Toggle word wrap

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

  4. Patch the system-sphinx ImageChange trigger:

    1. Remove the old 2.11-oracle trigger: 

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.11-oracle --containers=system-sphinx,system-master-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.12-oracle --containers=system-sphinx,system-master-svc
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of system-sphinx. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

  5. Scale 3scale back if you scaled it down.

  1. Patch the system-app ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-app --from-image=amp-system:2.11 --containers=system-master,system-developer,system-provider --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-app --from-image=amp-system:2.12 --containers=system-master,system-developer,system-provider
      Copy to Clipboard Toggle word wrap

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

  2. Patch the system-sidekiq ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.11 --containers=system-sidekiq,check-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.12 --containers=system-sidekiq,check-svc
      Copy to Clipboard Toggle word wrap

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

  3. Patch the system-sphinx ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.11 --containers=system-sphinx,system-master-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.12 --containers=system-sphinx,system-master-svc
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of system-sphinx. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

2.2.4.2. Patch the apicast image
Copy link

  1. Patch the amp-apicast image stream: 

    $ oc patch imagestream/amp-apicast --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP APIcast 2.12"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.12"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

  2. Patch the apicast-staging ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/apicast-staging --from-image=amp-apicast:2.11 --containers=apicast-staging --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/apicast-staging --from-image=amp-apicast:2.12 --containers=apicast-staging
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of apicast-staging. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

  3. Patch the apicast-production ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/apicast-production --from-image=amp-apicast:2.11 --containers=apicast-production,system-master-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/apicast-production --from-image=amp-apicast:2.12 --containers=apicast-production,system-master-svc
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of apicast-production. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

2.2.4.3. Patch the backend image
Copy link

  1. Patch the amp-backend image stream: 

    $ oc patch imagestream/amp-backend --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP Backend 2.12"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/backend-rhel8:3scale2.12"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

  2. Patch the backend-listener ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/backend-listener --from-image=amp-backend:2.11 --containers=backend-listener --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/backend-listener --from-image=amp-backend:2.12 --containers=backend-listener
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of backend-listener. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

  3. Patch the backend-worker ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/backend-worker --from-image=amp-backend:2.11 --containers=backend-worker,backend-redis-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/backend-worker --from-image=amp-backend:2.12 --containers=backend-worker,backend-redis-svc
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of backend-worker. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

  4. Patch the backend-cron ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/backend-cron --from-image=amp-backend:2.11 --containers=backend-cron,backend-redis-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/backend-cron --from-image=amp-backend:2.12 --containers=backend-cron,backend-redis-svc
      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.

2.2.4.4. Patch the zync image
Copy link

  1. Patch the amp-zync image stream: 

    $ oc patch imagestream/amp-zync --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP Zync 2.12"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/zync-rhel8:3scale2.12"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

  2. Patch the zync ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/zync --from-image=amp-zync:2.11 --containers=zync,zync-db-svc --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/zync --from-image=amp-zync:2.12 --containers=zync,zync-db-svc
      Copy to Clipboard Toggle word wrap

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

  3. Patch the zync-que ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/zync-que --from-image=amp-zync:2.11 --containers=que --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/zync-que --from-image=amp-zync:2.12 --containers=que
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of zync-que. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

2.2.4.5. Patch the system-memcached image
Copy link

  1. Patch the system-memcached image stream: 

    $ oc patch imagestream/system-memcached --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.12 Memcached"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/memcached-rhel7:3scale2.12"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

  2. Patch the system-memcache ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-memcache --from-image=system-memcached:2.11 --containers=memcache --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-memcache --from-image=system-memcached:2.12 --containers=memcache
      Copy to Clipboard Toggle word wrap

      This triggers a redeployment of the system-memcache DeploymentConfig. Wait until it is redeployed, its corresponding new pods are ready, and the old ones terminated.

2.2.4.6. Patch the zync-database-postgresql image
Copy link

  1. Patch the zync-database-postgresql image stream: 

    $ oc patch imagestream/zync-database-postgresql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "Zync 2.12 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

    • This patch command updates the zync-database-postgresql image stream to contain the 2.12 tag. You can verify that the 2.12 tag has been created with these steps:

      1. Run this command: 

        $ oc get is zync-database-postgresql
        Copy to Clipboard Toggle word wrap
      2. Check that the Tags column shows the 2.12 tag.

  2. Patch the zync-database ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/zync-database --from-image=zync-database-postgresql:2.11 --containers=postgresql --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/zync-database --from-image=zync-database-postgresql:2.12 --containers=postgresql
      Copy to Clipboard Toggle word wrap

      In case there are new updates on the image, this patch might also trigger a redeployment of the zync-database DeploymentConfig. If this happens, wait until the new pods are redeployed and ready, and the old pods are terminated.

2.2.4.7. Additional image changes
Copy link

If one or more of the following DeploymentConfigs are available in your 3scale 2.11 installation, click the links that apply to obtain more information on how to proceed:

backend-redis DeploymentConfig

If the backend-redis DeploymentConfig exists in your current 3scale installation, patch the redis image for backend-redis:

  1. Patch the backend-redis image stream: 

    $ oc patch imagestream/backend-redis --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "Backend 2.12 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-5-rhel7:5"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

    This patch updates the backend-redis image stream to contain the 2.12 tag. With the command below, you can confirm that the tag has been created if the Tags column shows 2.12: 

    $ oc get is backend-redis
    Copy to Clipboard Toggle word wrap

  2. Patch the backend-redis ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/backend-redis --from-image=backend-redis:2.11 --containers=backend-redis --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/backend-redis --from-image=backend-redis:2.12 --containers=backend-redis
      Copy to Clipboard Toggle word wrap

      In case there are new updates on the image, this patch might also trigger a redeployment of the backend-redis DeploymentConfig. If this happens, wait until the new pods are redeployed and ready, and the old pods are terminated.

system-redis DeploymentConfig

If the system-redis DeploymentConfig exists in your current 3scale installation, patch the redis image for system-redis.

  1. Patch the system-redis image stream: 

    $ oc patch imagestream/system-redis --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.12 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-5-rhel7:5"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

    This patch updates the system-redis image stream to contain the 2.12 tag. With the command below, you can confirm that the tag has been created if the Tags column shows 2.12: 

    $ oc get is system-redis
    Copy to Clipboard Toggle word wrap

  2. Patch the system-redis ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-redis --from-image=system-redis:2.11 --containers=system-redis --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-redis --from-image=system-redis:2.12 --containers=system-redis
      Copy to Clipboard Toggle word wrap

      In case there are new updates on the image, this patch might also trigger a redeployment of the system-redis DeploymentConfig. If this happens, wait until the new pods are redeployed and ready, and the old pods are terminated.

system-mysql DeploymentConfig

If the system-mysql DeploymentConfig exists in your current 3scale installation, patch the MySQL image for system-mysql.

  1. Patch the system-mysql image stream: 

    $ oc patch imagestream/system-mysql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.12 MySQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhel8/mysql-80:1"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

    This patch updates the system-mysql image stream to contain the 2.12 tag. With the command below, you can confirm that the tag has been created if the Tags column shows 2.12: 

    $ oc get is system-mysql
    Copy to Clipboard Toggle word wrap

  2. Patch the system-mysql ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-mysql --from-image=system-mysql:2.11 --containers=system-mysql --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-mysql --from-image=system-mysql:2.12 --containers=system-mysql
      Copy to Clipboard Toggle word wrap

      In case there are new updates on the image, this patch might also trigger a redeployment of the system-mysql DeploymentConfig. If this happens, wait until the new pods are redeployed and ready, and the old pods are terminated.

system-postgresql DeploymentConfig

If the system-postgresql DeploymentConfig exists in your current 3scale installation, patch the PostgreSQL image for system-postgresql.

  1. Patch the system-postgresql image stream: 

    $ oc patch imagestream/system-postgresql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.12 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.12", "referencePolicy": {"type": "Source"}}}]'
    Copy to Clipboard Toggle word wrap

    This patch updates the system-postgresql image stream to contain the 2.12 tag. With the command below, you can confirm that the tag has been created if the Tags column shows 2.12: 

    $ oc get is system-postgresql
    Copy to Clipboard Toggle word wrap

  2. Patch the system-postgresql ImageChange trigger:

    1. Remove the old 2.11 trigger: 

      $ oc set triggers dc/system-postgresql --from-image=system-postgresql:2.11 --containers=system-postgresql --remove
      Copy to Clipboard Toggle word wrap

    2. Add the new version-specific trigger: 

      $ oc set triggers dc/system-postgresql --from-image=system-postgresql:2.12 --containers=system-postgresql
      Copy to Clipboard Toggle word wrap

      In case there are new updates on the image, this patch might also trigger a redeployment of the system-postgresql DeploymentConfig. If this happens, wait until the new pods are redeployed and ready, and the old pods are terminated.

2.2.4.8. Confirm image URLs
Copy link

Confirm that all the image URLs of the DeploymentConfigs contain the new image registry URLs with a hash added at the end of each URL address: 

THREESCALE_DC_NAMES="apicast-production apicast-staging backend-cron backend-listener backend-redis backend-worker system-app system-memcache system-mysql system-redis system-sidekiq system-sphinx zync zync-database zync-que"
for component in ${THREESCALE_DC_NAMES}; do echo -n "${component} image: " && oc get dc $component -o json | jq .spec.template.spec.containers[0].image ; done
Copy to Clipboard Toggle word wrap

Next step

Removing unused MessageBus variables

2.2.5. Removing unused MessageBus variables
Copy link

Previous step

Upgrading 3scale images

Current step

This step removes unused MESSAGE_BUS_REDIS_* variables.

  1. Remove MESSAGE_BUS_REDIS_* variables from the system-app containers:

    • Note the dash char after the variable name. 

      $ oc set env dc/system-app MESSAGE_BUS_REDIS_URL-
$ oc set env dc/system-app MESSAGE_BUS_REDIS_NAMESPACE-
$ oc set env dc/system-app MESSAGE_BUS_REDIS_SENTINEL_HOSTS-
$ oc set env dc/system-app MESSAGE_BUS_REDIS_SENTINEL_ROLE-
      Copy to Clipboard Toggle word wrap

  2. Remove MESSAGE_BUS_REDIS_* variables from the system-app pre hook: 

    $ INDEX=$(oc get dc system-app -o json | jq '.spec.strategy.rollingParams.pre.execNewPod.env | map(.name == "MESSAGE_BUS_REDIS_URL") | index(true)')
oc patch dc/system-app --type=json -p "[{'op': 'remove', 'path': '/spec/strategy/rollingParams/pre/execNewPod/env/$INDEX'}]"

$ INDEX=$(oc get dc system-app -o json | jq '.spec.strategy.rollingParams.pre.execNewPod.env | map(.name == "MESSAGE_BUS_REDIS_NAMESPACE") | index(true)')
oc patch dc/system-app --type=json -p "[{'op': 'remove', 'path': '/spec/strategy/rollingParams/pre/execNewPod/env/$INDEX'}]"

$ INDEX=$(oc get dc system-app -o json | jq '.spec.strategy.rollingParams.pre.execNewPod.env | map(.name == "MESSAGE_BUS_REDIS_SENTINEL_HOSTS") | index(true)')
oc patch dc/system-app --type=json -p "[{'op': 'remove', 'path': '/spec/strategy/rollingParams/pre/execNewPod/env/$INDEX'}]"

$ INDEX=$(oc get dc system-app -o json | jq '.spec.strategy.rollingParams.pre.execNewPod.env | map(.name == "MESSAGE_BUS_REDIS_SENTINEL_ROLE") | index(true)')
oc patch dc/system-app --type=json -p "[{'op': 'remove', 'path': '/spec/strategy/rollingParams/pre/execNewPod/env/$INDEX'}]"
    Copy to Clipboard Toggle word wrap

  3. Verify MESSAGE_BUS_REDIS_* environment variables do not exist: 

    $ oc get dc system-app -o yaml | grep MESSAGE_BUS_REDIS
    Copy to Clipboard Toggle word wrap

  1. Remove MESSAGE_BUS_REDIS_* variables from the system-sidekiq containers:

    • Note the dash char after the variable name. 

      $ oc set env dc/system-sidekiq MESSAGE_BUS_REDIS_URL-
$ oc set env dc/system-sidekiq MESSAGE_BUS_REDIS_NAMESPACE-
$ oc set env dc/system-sidekiq MESSAGE_BUS_REDIS_SENTINEL_HOSTS-
$ oc set env dc/system-sidekiq MESSAGE_BUS_REDIS_SENTINEL_ROLE-
      Copy to Clipboard Toggle word wrap

  2. Remove MESSAGE_BUS_REDIS_* variables from the system-sidekiq init-container: 

    $ INDEX=$(oc get dc system-sidekiq -o json | jq '.spec.template.spec.initContainers[].env | map(.name == "MESSAGE_BUS_REDIS_URL") | index(true)')
oc patch dc/system-sidekiq --type=json -p "[{'op': 'remove', 'path': '/spec/template/spec/initContainers/0/env/$INDEX'}]"

$ INDEX=$(oc get dc system-sidekiq -o json | jq '.spec.template.spec.initContainers[].env | map(.name == "MESSAGE_BUS_REDIS_NAMESPACE") | index(true)')
oc patch dc/system-sidekiq --type=json -p "[{'op': 'remove', 'path': '/spec/template/spec/initContainers/0/env/$INDEX'}]"

$ INDEX=$(oc get dc system-sidekiq -o json | jq '.spec.template.spec.initContainers[].env | map(.name == "MESSAGE_BUS_REDIS_SENTINEL_HOSTS") | index(true)')
oc patch dc/system-sidekiq --type=json -p "[{'op': 'remove', 'path': '/spec/template/spec/initContainers/0/env/$INDEX'}]"

$ INDEX=$(oc get dc system-sidekiq -o json | jq '.spec.template.spec.initContainers[].env | map(.name == "MESSAGE_BUS_REDIS_SENTINEL_ROLE") | index(true)')
oc patch dc/system-sidekiq --type=json -p "[{'op': 'remove', 'path': '/spec/template/spec/initContainers/0/env/$INDEX'}]"
    Copy to Clipboard Toggle word wrap

  3. Verify MESSAGE_BUS_REDIS_* environment variables do not exist: 

    $ oc get dc system-sidekiq -o yaml | grep MESSAGE_BUS_REDIS
    Copy to Clipboard Toggle word wrap

  1. Remove MESSAGE_BUS_REDIS_* variables from the system-sphinx containers:

    • Note the dash char after the variable name. 

      $ oc set env dc/system-sphinx MESSAGE_BUS_REDIS_URL-
$ oc set env dc/system-sphinx MESSAGE_BUS_REDIS_NAMESPACE-
$ oc set env dc/system-sphinx MESSAGE_BUS_REDIS_SENTINEL_HOSTS-
$ oc set env dc/system-sphinx MESSAGE_BUS_REDIS_SENTINEL_ROLE-
      Copy to Clipboard Toggle word wrap

  2. Verify MESSAGE_BUS_REDIS_* environment variables do not exist: 

    $ oc get dc system-sphinx -o yaml | grep MESSAGE_BUS_REDIS
    Copy to Clipboard Toggle word wrap

  1. Remove MESSAGE_BUS_REDIS_* variables from the system-redis secret: 

    $ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_URL'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_NAMESPACE'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_SENTINEL_HOSTS'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_SENTINEL_ROLE'}]"
    Copy to Clipboard Toggle word wrap

  2. Verify MESSAGE_BUS_REDIS_* environment variables do not exist: 

    $ oc get secret system-redis -o yaml | grep MESSAGE_BUS
    Copy to Clipboard Toggle word wrap

This upgrade supports external system-database using PostgreSQL 10. You should complete your 3scale upgrade first, then upgrade to PostgreSQL 13.

Next step

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

This section explains how to update Red Hat 3scale API Management when you are using a 3scale system image with an Oracle Database, in a template-based installation with OpenShift 3.11.

Prerequisites

A 3scale installation with the Oracle Database. See Setting up your 3scale system image with an Oracle Database.

To upgrade your 3scale system image with an Oracle Database in a template-based installation, perform the procedure below:

2.3.1. Upgrading 3scale with Oracle 19c
Copy link

This procedure guides you through an Oracle Database 19c update for 3scale 2.12 from an existing 3scale 2.11 installation.

IMPORTANT: Loss of connection to the database can potentially corrupt 3scale. Make a backup before proceeding to perform the upgrade. For more information see the Oracle Database documentation: Oracle Database Backup and Recovery User’s Guide.

Prerequisites

  • A 3scale 2.11 installation.

  • An Oracle Database 19c installation.

Procedure

  1. Download 3scale OpenShift templates from the GitHub repository and extract the archive: 

    tar -xzf 3scale-amp-openshift-templates-3scale-2.12.0-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.12.0-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

Verification for the open_cursors parameter setting

You must confirm that the open_cursors parameter in this database is set to a value that is greater than 1000.

To do this, log in to your Oracle Database as SYSTEM user and run the following command: 

show parameter open_cursors;
Copy to Clipboard Toggle word wrap

The return value should be at least 1000. If it is not, change the parameter to a value greater than 1000 by following Oracle’s documentation on open cursors.

If the open_cursors parameter was previously configured to some limit less than 1000, and you do not increase the value, you might see the following error in one of the OpenShift system-app pod logs: 

ORA-01000: maximum open cursors exceeded
Copy to Clipboard Toggle word wrap

Additional resources

For more information about 3scale and Oracle Database support, see Red Hat 3scale API Management Supported Configurations.

Upgrade Red Hat 3scale API Management from version 2.11 to 2.12, in an operator-based installation to manage 3scale on OpenShift 4.x.

To automatically obtain a micro-release of 3scale, make sure automatic updates is on. To check this, see Setting up the 3scale operator for micro releases.

Important

In order to understand the required conditions and procedure, 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, make sure to have a maintenance window.

3.1. Prerequisites to perform the upgrade
Copy link

This section describes the required configurations to upgrade 3scale from 2.11 to 2.12 in an operator-based installation.

  • An OpenShift Container Platform (OCP) 4.6, 4.7, 4.8, 4.9, or 4.10 cluster with administrator access.
  • 3scale 2.11 previously deployed via the 3scale operator.

  • Make sure the latest CSV of the threescale-2.11 channel is in use. To check it:

    • If the approval setting for the subscription is automatic you should already be in the latest CSV version of the channel.
    • If the approval setting for the subscription is manual make sure you approve all pending InstallPlans and have the latest CSV version.
    • Keep in mind if there is a pending install plan, there might be more pending install plans, which will only be shown after the existing pending plan has been installed.

To upgrade 3scale from version 2.11 to 2.12 in an operator-based deployment:

  1. Log in to the OCP console using the account with administrator privileges.
  2. Select the project where the 3scale-operator has been deployed.
  3. Click Operators > Installed Operators.
  4. Select Red Hat Integration - 3scale > Subscription > Channel.

  5. Edit the channel of the subscription by selecting threescale-2.12 and save the changes.

    This will start the upgrade process.

  6. Query the pods' status on the project until you see all the new versions are running and ready without errors: 

    $ oc get pods
    Copy to Clipboard Toggle word wrap
    Note
    • The pods might have temporary errors during the upgrade process.
    • The time required to upgrade pods can vary from 5-10 minutes.
  7. After new pod versions are running, confirm a successful upgrade by logging in to the 3scale Admin Portal and checking that it works as expected.

  8. Check the status of the APIManager objects and get the YAML content by running the following command. <myapimanager> represents the name of your APIManager: 

    $ oc get apimanager <myapimanager> -o yaml
    Copy to Clipboard Toggle word wrap

    • The new annotations with the values should be as follows: 

      apps.3scale.net/apimanager-threescale-version: "2.12"
apps.3scale.net/threescale-operator-version: "0.9.0"
      Copy to Clipboard Toggle word wrap

After you have performed all steps, 3scale upgrade from 2.11 to 2.12 in an operator-based deployment is complete.

3.2.1. Upgrading the external MySQL version to 8.0
Copy link

If your 3scale deployment has the external databases mode enabled and uses MySQL 8.0, set the authentication plugin to mysql_native_password for 3scale 2.12.

Add the following to the MySQL configuration file. 

[mysqld]
default_authentication_plugin=mysql_native_password
Copy to Clipboard Toggle word wrap

3.2.2. Removing unused MessageBus variables
Copy link

If your 3scale deployment has the external databases mode enabled, you must manually remove the MESSAGE_BUS_* field from the system-redis secret.

  1. Remove MESSAGE_BUS_* fields from the system-redis secret. If the secret is not managed by external controller, update manually using the following commands: 

    $ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_URL'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_NAMESPACE'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_SENTINEL_HOSTS'}]"
$ oc patch secret/system-redis --type=json -p "[{'op': 'remove', 'path': '/data/MESSAGE_BUS_SENTINEL_ROLE'}]"
    Copy to Clipboard Toggle word wrap

  2. Verify MESSAGE_BUS_* fields do not exist. The following command should return empty: 

    $ oc get secret system-redis -o yaml | grep MESSAGE_BUS
    Copy to Clipboard Toggle word wrap

This upgrade supports external system-database using PostgreSQL 10. You should complete your 3scale upgrade first, then upgrade to PostgreSQL 13.

Upgrading APIcast from 2.11 to 2.12 in an operator-based installation helps you use the APIcast API gateway to integrate your internal and external API services with 3scale.

Important

In order to understand the required conditions and procedure, 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, make sure to have a maintenance window.

4.1. Prerequisites to perform the upgrade
Copy link

To perform the upgrade of APIcast from 2.11 to 2.12 in an operator-based installation, the following required prerequisites must already be in place:

  • An OpenShift Container Platform (OCP) 4.6, 4.8, 4.9, or 4.10 cluster with administrator access.
  • APIcast 2.11 previously deployed via the APIcast operator.

  • Make sure the latest CSV of the threescale-2.11 channel is in use. To check it:

    • If the approval setting for the subscription is automatic you should already be in the latest CSV version of the channel.
    • If the approval setting for the subscription is manual make sure you approve all pending InstallPlans and have the latest CSV version.
    • Keep in mind if there is a pending install plan, there might be more pending install plans, which will only be shown after the existing pending plan has been installed.

Upgrade APIcast from 2.11 to 2.12 in an operator-based installation so that APIcast can function as the API gateway in your 3scale installation.

Procedure

  1. Log in to the OCP console using the account with administrator privileges.
  2. Select the project where the APIcast operator has been deployed.
  3. Click Operators > Installed Operators.
  4. In Subscription > Channel, select Red Hat Integration - 3scale APIcast gateway.

  5. Edit the channel of the subscription by selecting the threescale-2.12 channel and save the changes.

    This will start the upgrade process.

  6. Query the pods status on the project until you see all the new versions are running and ready without errors: 

    $ oc get pods
    Copy to Clipboard Toggle word wrap
    Note
    • The pods might have temporary errors during the upgrade process.
    • The time required to upgrade pods can vary from 5-10 minutes.

  7. Check the status of the APIcast objects and get the YAML content by running the following command: 

    $ oc get apicast <myapicast> -o yaml
    Copy to Clipboard Toggle word wrap

    • The new annotations with the values should be as follows: 

      apicast.apps.3scale.net/operator-version: “0.6.0”
      Copy to Clipboard Toggle word wrap

After you have performed all the listed steps, APIcast upgrade from 2.11 to 2.12 in an operator-based deployment is now complete.

Legal Notice
Copy link

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat