Migrating 3scale

Red Hat 3scale API Management 2.9

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

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.8 to 2.9, 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.8 to 2.9, refer to one of the following guides depending on the installation type:

Post-upgrade step for provisioning APIs in the Developer Portal.

  • After a successful upgrade to 3scale 2.9, if you already configured OpenAPI Specification 3.0 (OAS 3.0) in the Developer Portal of 3scale 2.8 and you want to continue using OAS 3.0, see the following: Updating the Developer Portal with OAS 3.0.

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

Chapter 1. 3scale migration guide: from template to operator-based deployments

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

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

1.2. Migrating 3scale template to operator-based deployments

The basic setup before migration is that 3scale points to the OCP3 domain: 3scale.example.comocp3.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:

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

Chapter 2. 3scale template-based upgrade guide: from 2.8 to 2.9.1

This section contains information about upgrading Red Hat 3scale API Management from version 2.8 to 2.9.1, in a template-based deployment.

Important considerations

  • 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.
  • If your 3scale template-based installation runs with Oracle Database, refer to the Support to Oracle Databases in the 3scale 2.9.1 Release Notes.

2.1. Prerequisites to perform the upgrade

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

2.1.1. Configurations

  • 3scale supports upgrade paths from 2.8 to 2.9.1 with templates on OpenShift 3.11.

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

2.1.3. Tools

You need these tools to perform the upgrade:

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

2.2. Upgrading from 2.8 to 2.9.1 in a template-based installation

Follow the procedure described in this section to upgrade 3scale 2.8 to 2.9.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:

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

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

2.2.2. Removing the BASE_URL field

Current step

This section explains how to remove the BASE_URL field from the system-master-apicast secret. This field is removed because no component uses it in 3scale 2.9

  1. Run the following command:

    oc patch secret system-master-apicast --type=json -p='[{"op": "remove", "path": "/data/BASE_URL"}]'
  2. Confirm that the BASE_URL field has been successfully removed:

    oc get secret system-master-apicast -o json | jq .data

2.2.3. Updating 3scale version number

Current step

This step updates the 3scale release version number from 2.8 to 2.9 in the system-environment ConfigMap. AMP_RELEASE is a ConfigMap entry referenced in some DeploymentConfig container environments.

  1. To patch AMP_RELEASE, run this command:

    oc patch cm system-environment --patch '{"data": {"AMP_RELEASE": "2.9"}}'
  2. Confirm that the AMP_RELEASE key in the system-environment ConfigMap has the 2.9 value:

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

2.2.4. Upgrading 3scale images

Current step

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

2.2.4.1. Patch the system image

  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.9"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/system-rhel7:3scale2.9"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
  2. To continue the procedure, consider the database used with your 3scale deployment:

2.2.4.1.1. Patching the system image: 3scale with Oracle Database
  1. To start patching the system image of 3scale with an Oracle Database, perform one of the procedures below according to your database version:

  2. Patch the system-app ImageChangeTrigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-app --from-image=amp-system:latest --containers=system-master,system-developer,system-provider --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-app --from-image=amp-system:2.9-oracle --containers=system-master,system-developer,system-provider

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

    3. Remove the :latest tag from the ImageStream:

      oc tag -d amp-system:latest
  3. Patch the system-sidekiq ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-sidekiq --from-image=amp-system:latest --containers=system-sidekiq,check-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-sidekiq --from-image=amp-system:2.9-oracle --containers=system-sidekiq,check-svc

      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 latest trigger:

      oc set triggers dc/system-sphinx --from-image=amp-system:latest --containers=system-sphinx,system-master-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-sphinx --from-image=amp-system:2.9-oracle --containers=system-sphinx,system-master-svc

      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.
2.2.4.1.2. Patching the system image: 3scale with other databases
  1. Patch the system-app ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-app --from-image=amp-system:latest --containers=system-master,system-developer,system-provider --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-app --from-image=amp-system:2.9 --containers=system-master,system-developer,system-provider

      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 latest trigger:

      oc set triggers dc/system-sidekiq --from-image=amp-system:latest --containers=system-sidekiq,check-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-sidekiq --from-image=amp-system:2.9 --containers=system-sidekiq,check-svc

      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 latest trigger:

      oc set triggers dc/system-sphinx --from-image=amp-system:latest --containers=system-sphinx,system-master-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-sphinx --from-image=amp-system:2.9 --containers=system-sphinx,system-master-svc

      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

  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.9"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.9"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
  2. Patch the apicast-staging ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/apicast-staging --from-image=amp-apicast:latest --containers=apicast-staging --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/apicast-staging --from-image=amp-apicast:2.9 --containers=apicast-staging

      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 latest trigger:

      oc set triggers dc/apicast-production --from-image=amp-apicast:latest --containers=apicast-production,system-master-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/apicast-production --from-image=amp-apicast:2.9 --containers=apicast-production,system-master-svc

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

    3. Remove the :latest tag from the ImageStream:

      oc tag -d amp-apicast:latest

2.2.4.3. Patch the backend image

  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.9"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/backend-rhel7:3scale2.9"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
  2. Patch the backend-listener ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/backend-listener --from-image=amp-backend:latest --containers=backend-listener --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/backend-listener --from-image=amp-backend:2.9 --containers=backend-listener

      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 latest trigger:

      oc set triggers dc/backend-worker --from-image=amp-backend:latest --containers=backend-worker,backend-redis-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/backend-worker --from-image=amp-backend:2.9 --containers=backend-worker,backend-redis-svc

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

    3. Remove the :latest tag from the ImageStream:

      oc tag -d amp-backend:latest
  4. Patch the backend-cron ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/backend-cron --from-image=amp-backend:latest --containers=backend-cron,backend-redis-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/backend-cron --from-image=amp-backend:2.9 --containers=backend-cron,backend-redis-svc

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

2.2.4.4. Patch the zync image

  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.9"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/zync-rhel7:3scale2.9"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
  2. Patch the zync ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/zync --from-image=amp-zync:latest --containers=zync,zync-db-svc --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/zync --from-image=amp-zync:2.9 --containers=zync,zync-db-svc

      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 latest trigger:

      oc set triggers dc/zync-que --from-image=amp-zync:latest --containers=que --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/zync-que --from-image=amp-zync:2.9 --containers=que

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

    3. Remove the :latest tag from the ImageStream:

      oc tag -d amp-zync:latest

2.2.4.5. Patch the system-memcached image

  1. Patch the system-memcached ImageStream:

    oc patch imagestream/system-memcached --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.9 Memcached"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/memcached-rhel7:3scale2.9"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
  2. Patch the system-memcache ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-memcache --from-image=system-memcached:latest --containers=memcache --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-memcache --from-image=system-memcached:2.9 --containers=memcache

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d system-memcached:latest

2.2.4.6. Patch the zync-database-postgresql image

  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.9 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'
    • This patch command updates the zync-database-postgresql image stream to contain the 2.9 tag. You can verify that the 2.9 tag has been created with these steps:

      1. Run this command:

        oc get is zync-database-postgresql
      2. Check that the Tags column shows the 2.9 tag.
  2. Patch the zync-database ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/zync-database --from-image=zync-database-postgresql:latest --containers=postgresql --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/zync-database --from-image=zync-database-postgresql:2.9 --containers=postgresql

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d zync-database-postgresql:latest

2.2.4.7. Additional image changes

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

2.2.4.7.1. 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.9 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-32-rhel7:3.2"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'

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

    oc get is backend-redis
  2. Patch the backend-redis ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/backend-redis --from-image=backend-redis:latest --containers=backend-redis --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/backend-redis --from-image=backend-redis:2.9 --containers=backend-redis

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d backend-redis:latest
2.2.4.7.2. 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.9 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-32-rhel7:3.2"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'

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

    oc get is system-redis
  2. Patch the system-redis ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-redis --from-image=system-redis:latest --containers=system-redis --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-redis --from-image=system-redis:2.9 --containers=system-redis

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d system-redis:latest
2.2.4.7.3. 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.9 MySQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/mysql-57-rhel7:5.7"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'

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

    oc get is system-mysql
  2. Patch the system-mysql ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-mysql --from-image=system-mysql:latest --containers=system-mysql --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-mysql --from-image=system-mysql:2.9 --containers=system-mysql

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d system-mysql:latest
2.2.4.7.4. 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.9 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.9", "referencePolicy": {"type": "Source"}}}]'

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

    oc get is system-postgresql
  2. Patch the system-postgresql ImageChange trigger:

    1. Remove the latest trigger:

      oc set triggers dc/system-postgresql --from-image=system-postgresql:latest --containers=system-postgresql --remove
    2. Add the new version-specific trigger:

      oc set triggers dc/system-postgresql --from-image=system-postgresql:2.9 --containers=system-postgresql

      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.

    3. Remove the :latest tag from the ImageStream:

      oc tag -d system-postgresql:latest

2.2.4.8. Confirm image URLs

Previous step

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

Next step

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

2.3. Upgrading 3scale with an Oracle Database in a template-based installation

This section explains how to upgrade 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 one of the procedures below according to your database version:

2.3.1. Upgrading 3scale with Oracle 19c

This procedure guides you through changing from Oracle Database 12c to Oracle Database 19c, for 3scale 2.9.1 from an existing 3scale 2.8 installation.

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

Prerequisites

  • A 3scale 2.8 installation
  • An Oracle Database 12c installation.

Procedure

  1. Scale 3scale down to 0 (zero), with the following considerations:

    1. The 3scale connection to the database fails because it is disconnected from Oracle 12c.
  2. Upgrade Oracle 12c to Oracle 19c.

    1. To perform the upgrade, follow the official Oracle Database Upgrade Guide.
  3. Clone the OpenShift Templates for 3scale 2.9.1

    $ git clone --branch 2.9.1.GA https://github.com/3scale/3scale-amp-openshift-templates.git
  4. Place your Oracle Database Instant Client Package files into the 3scale-amp-openshift-templates/amp/system-oracle/oracle-client-files directory.
  5. Run the oc process command with the -f option and specify the build.yml OpenShift template:

    $ oc process -f build.yml | oc apply -f -
  6. Enter the oc start-build command to build the new system image:

    $ oc start-build 3scale-amp-system-oracle --from-dir=.
  7. 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.

2.3.2. Upgrading 3scale with Oracle 12c

This procedure guides you through an Oracle Database 12c update for 3scale 2.9.1 from an existing 3scale 2.8 installation.

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

Prerequisites

  • A 3scale 2.8 installation.
  • An Oracle Database 12c installation.

Procedure

  1. Clone the OpenShift Templates for 3scale 2.9.1

    $ git clone --branch 2.9.1.GA https://github.com/3scale/3scale-amp-openshift-templates.git
  2. Place your Oracle Database Instant Client Package files into the 3scale-amp-openshift-templates/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. Enter the oc start-build command to build the new system image:

    $ oc start-build 3scale-amp-system-oracle --from-dir=.
  5. 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.

Additional resources

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

Chapter 3. 3scale operator-based upgrade guide: from 2.8 to 2.9

This section contains information about upgrading Red Hat 3scale API Management from version 2.8 to 2.9, in an operator-based deployment.

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

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

  • 3scale 2.8 previously deployed via the 3scale operator.
  • An OpenShift Container Platform (OCP) 4.x cluster with administrator access.

3.2. Upgrading from 2.8 to 2.9 in an operator-based installation

To upgrade 3scale from version 2.8 to 2.9 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.9 and save the changes.

    • This will start the upgrade process.
    • Wait until the upgrade process finishes for APIManager.
  6. Query the pods status on the project:

    oc get pods
    • Wait until all the new versions are running and ready without errors.
    • They might have temporary errors during the upgrade process.

      Note

      Times can vary from 5-10 minutes approximately. Be sure to keep checking the state of the pods until all of them are running, ready, and without errors.

Confirm the upgrade process has been successful, by logging in to the 3scale Admin Portal and check that it works as expected.

  1. Check the status of the APIManager objects and get the YAML content by running the following command:

    oc get apimanager <myapimanager> -o yaml
    • The new annotations with the values should be as follows:

      apps.3scale.net/apimanager-threescale-version: "2.9"
      apps.3scale.net/threescale-operator-version: "0.6.0"

After you have performed all the listed steps, 3scale upgrade from 2.8 to 2.9 in an operator-based deployment is now complete.

Chapter 4. APIcast operator-based upgrade guide: from 2.8 to 2.9

This section contains information about upgrading APIcast from version 2.8 to 2.9, in an operator-based deployment.

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

This section describes the required configurations to upgrade APIcast from 2.8 to 2.9 in an operator-based installation.

  • APIcast 2.8 previously deployed via the APIcast operator.
  • An OpenShift Container Platform (OCP) 4.x cluster with administrator access.

4.2. Upgrading APIcast from 2.8 to 2.9 in an operator-based installation

To upgrade APIcast from version 2.8 to 2.9 in an operator-based deployment:

  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.9 channel and save the changes.

    • This will start the upgrade process.
    • Wait until the upgrade process finishes for APIcast.
  6. Query the pods status on the project:

    oc get pods
    • Wait until all the new versions are running and ready without errors.
    • They might have temporary errors during the upgrade process.

      Note

      Times can vary from 5-10 minutes approximately. Be sure to keep checking the state of the pods until all of them are running, ready, and without errors.

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

    oc get apicast <myapicast> -o yaml
    • The new annotations with the values should be as follows:

      apicast.apps.3scale.net/operator-version: “0.3.0”

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

Legal Notice

Copyright © 2022 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.