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.

1.2. Upgrading 3scale API Management

To upgrade 3scale API Management from 2.3 to 2.4 follow the steps in the order listed below:

1.2.1. Creating the system master route

To 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

1.2.2. Migrating the system database secret

To migrate the system database secret into the new ‘system-database’ OpenShift secret:

  1. Get the existing MySQL environment variables:

    MYSQL_ROOT_PASSWORD=$(oc set env dc/system-mysql --list | grep MYSQL_ROOT_PASSWORD | cut -d'=' -f2)
    MYSQL_DATABASE=$(oc set env dc/system-mysql --list | grep MYSQL_DATABASE | cut -d'=' -f2)
  2. Get the APP_LABEL environment variable:

    APP_LABEL=$(oc get dc backend-listener -o json | jq -r)
  3. Confirm that you have correctly set the following environment variables:

    echo ${MYSQL_DATABASE}
    echo ${APP_LABEL}
  4. Create the file containing the system-database secret:

    cat > system-database-secret.yaml <<EOF
    apiVersion: v1
    kind: Secret
      creationTimestamp: null
        3scale.component: system
        app: ${APP_LABEL}
      name: system-database
      URL: mysql2://root:${MYSQL_ROOT_PASSWORD}@system-mysql/${MYSQL_DATABASE}
    type: Opaque
  5. Create the secret:

    oc create -f system-database-secret.yaml
  6. Update the system-sphinx DeploymentConfig to gather the database information of system from the new secret:

    oc patch dc/system-sphinx -p '{"spec":{"template":{"spec":{"containers":[{"name":"system-sphinx","env":[{"name":"DATABASE_URL","value":"","valueFrom":{"secretKeyRef":{"key":"URL","name":"system-database"}}}]}]}}}}'
  7. Update the system-sidekiq DeploymentConfig to gather the database information of system from the new secret:

    oc patch dc/system-sidekiq -p '{"spec":{"template":{"spec":{"containers":[{"name":"system-sidekiq","env":[{"name":"DATABASE_URL","value":"","valueFrom":{"secretKeyRef":{"key":"URL","name":"system-database"}}}]}]}}}}'
  8. Patch the system-app pre-hook pod in these steps:

    1. Edit the system-app DeploymentConfig:

      oc edit dc system-app
    2. Go to the .spec.strategy.rollingParams.pre.execNewPod.env section, find the DATABASE_URL environment variable array element, and replace it by the following element:

      name: DATABASE_URL
            key: URL
            name: system-database
      1. Save the changes and exits.
  9. Patch the system-app DeploymentConfig containers:

    oc patch dc/system-app -p '{"spec":{"template":{"spec":{"containers":[{"name":"system-master","env":[{"name":"DATABASE_URL","value":"","valueFrom":{"secretKeyRef":{"key":"URL","name":"system-database"}}}]},{"name":"system-provider","env":[{"name":"DATABASE_URL","value":"","valueFrom":{"secretKeyRef":{"key":"URL","name":"system-database"}}}]},{"name":"system-developer","env":[{"name":"DATABASE_URL","value":"","valueFrom":{"secretKeyRef":{"key":"URL","name":"system-database"}}}]}]}}}}'

1.2.3. Patching image streams

  1. Patch the amp-system image stream:

    • If 3scale API Management is deployed with Oracle Database,

      1. Update the system image 2.4.0 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"}}}]'
      2. Update the build configuration for 3scale-amp-oracle to fetch from the 2.4 tag:

        oc patch bc 3scale-amp-system-oracle --type json -p '[{"op": "replace", "path": "/spec/strategy/dockerStrategy/from/name", "value": "amp-system:2.4.0"}]'
      3. Run the build:

        oc start-build 3scale-amp-system-oracle --from-dir=.
    • If 3scale API Management is deployed with a different database, use the following commands:

      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"}}}]'
  2. 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"}}}]'
  3. 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"}}}]'
  4. 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"}}}]'

1.2.4. Configuring DeploymentConfigs

  1. Patch the system-memcache DeploymentConfig:

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

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

    oc set env dc/system-sidekiq RAILS_MAX_THREADS=25
  4. 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 -f 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 rollout latest 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.