Chapter 1. Upgrading 3scale API Management 2.3 to 2.4

This section contains information about upgrading 3scale API Management from version 2.3 to 2.4. Optionally, you can also change the impersonation of administrator data.


This process can cause disruption in the service. Make sure to have a maintenance window.

1.1. Prerequisites

  • 3scale API Management 2.3 deployed in a project.
  • 3scale API Management 2.4 templates.

1.2. Migrating 3scale API Management 2.3 to 2.4

To migrate 3scale API Management from 2.3 to 2.4 follow the steps below.

  1. Create the system master route:

    1. Replace ${MASTER_NAME} by the MASTER_DOMAIN environment variable in your current dc/system-app.
    2. Replace ${THREESCALE_SUPERDOMAIN} by the THREESCALE_SUPERDOMAIN environment variable in your current dc/system-app:

      oc create route edge system-master --service=system-master --hostname=${MASTER_NAME}.${THREESCALE_SUPERDOMAIN} --port=http
      oc delete route system-master-admin
  2. Patch the amp-system image stream.

    oc patch imagestream/amp-system --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP system 2.4.0"}, "from": { "kind": "DockerImage", "name": ""}, "name": "2.4.0", "referencePolicy": {"type": "Source"}}}]'
    oc patch imagestream/amp-system --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP system (latest)"}, "from": { "kind": "ImageStreamTag", "name": "2.4.0"}, "name": "latest", "referencePolicy": {"type": "Source"}}}]'
  3. Patch the amp-apicast image stream.

    oc patch imagestream/amp-apicast --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP APIcast 2.4.0"}, "from": { "kind": "DockerImage", "name": ""}, "name": "2.4.0", "referencePolicy": {"type": "Source"}}}]'
    oc patch imagestream/amp-apicast --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP APIcast (latest)"}, "from": { "kind": "ImageStreamTag", "name": "2.4.0"}, "name": "latest", "referencePolicy": {"type": "Source"}}}]'
  4. Patch the amp-backend image stream.

    oc patch imagestream/amp-backend --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP Backend 2.4.0"}, "from": { "kind": "DockerImage", "name": ""}, "name": "2.4.0", "referencePolicy": {"type": "Source"}}}]'
    oc patch imagestream/amp-backend --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP Backend (latest)"}, "from": { "kind": "ImageStreamTag", "name": "2.4.0"}, "name": "latest", "referencePolicy": {"type": "Source"}}}]'
  5. Patch the amp-zync image stream.

    oc patch imagestream/amp-zync --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP Zync 2.4.0"}, "from": { "kind": "DockerImage", "name": ""}, "name": "2.4.0", "referencePolicy": {"type": "Source"}}}]'
    oc patch imagestream/amp-zync --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"": "AMP Zync (latest)"}, "from": { "kind": "ImageStreamTag", "name": "2.4.0"}, "name": "latest", "referencePolicy": {"type": "Source"}}}]'
  6. Patch the system-memcache deployment configuration.

    oc patch dc/system-memcache --patch='{"spec":{"template":{"spec":{"containers":[{"name": "memcache", "image":""}]}}}}'
  7. Delete the system-resque deployment configuration.

    oc delete dc/system-resque
  8. Set environment variables to increase system-sidekiq concurrency to the recommended levels.

    oc set env dc/system-sidekiq RAILS_MAX_THREADS=25
  9. Set environment variable to update the visible release version.

    oc set env dc/system-app AMP_RELEASE=2.4.0

1.3. Changing Administrator Impersonation (Optional)

As 3scale API Management is open source, impersonation data is publicly disclosed. For this reason, you might want to change some data:

  • The unique username for the impersonation of administrators.
  • The domain of the email of the impersonation for the administrator user.

As an example, assume that username:<your-username> and domain:<>. To change the impersonation of the administrator, you need to follow these steps:

  1. Create a file locally called system-impersonation-secret.yml with the following content:

    apiVersion: v1
    kind: Secret
      creationTimestamp: null
        3scale.component: system
        app: 3scale-api-management
      name: system-impersonation
      username: "<your-username>"
      domain: "<>"
    type: Opaque
  2. Change <your-username> and <> to the chosen user name and domain.
  3. Create a secret:

    oc create secret --file system-impersonation-secret.yml
  4. Set the environment variables from this secret with:

    oc set env --from=secret/system-impersonation --prefix=IMPERSONATION_ADMIN dc/system-app
  5. Redeploy system-app:

    oc deploy --latest dc/system-app
  6. Connect to the system-master container of system-app deployment:

    oc rsh -c system-master "$(oc get pods --selector deploymentconfig=system-app -o name)"
  7. In this container execute, changing <your-username> and <> accordingly:

    bundle exec rake "impersonation_admin_user:update[<your-username>,<>]"

    You should be able to impersonate a tenant from the user interface now.