Chapter 1. Upgrade 3scale API Management 2.2 to 2.3

The 2.3 version of 3scale API Management only updates the APIcast component of the product.

Perform the steps in this document to upgrade the APIcast to version 2.3.

1.1. Prerequisites

  • You must be running 3scale On-Premises 2.2
  • OpenShift CLI
Warning

Red Hat recommends that you establish a maintenance window when performing the upgrade because this process may cause a disruption in service.

1.2. Select the Project

  1. From a terminal session, log in to your OpenShift cluster using the following command. Here, <YOUR_OPENSHIFT_CLUSTER> is the URL of your OpenShift cluster.

    oc login https://<YOUR_OPENSHIFT_CLUSTER>:8443
  2. Select the project you want to upgrade using the following command. Here, <3scale-22-project> is the name of your project.

    oc project <3scale-22-project>

1.3. Gather the Needed Values

  1. Gather the following values from the APIcast component of your current 2.2 deployment:

    • APICAST_MANAGEMENT_API
    • OPENSSL_VERIFY
    • APICAST_RESPONSE_CODES
  2. Export these values from the current deployment into the active shell.

    export `oc env dc/apicast-production --list | grep -E '^(APICAST_MANAGEMENT_API|OPENSSL_VERIFY|APICAST_RESPONSE_CODES)=' | tr "\n" ' ' `
  3. Optionally, to query individual values from the OpenShift CLI, run the following oc get command, where <variable_name> is the name of the variable you want to query.

    oc get "-o=custom-columns=NAMES:.spec.template.spec.containers[0].env[?(.name==\"<variable_name>\")].value" dc/apicast-production
  4. Set the value for the new version of the 3scale API Management release.

    export AMP_RELEASE=2.3.0
  5. Set the values for the new environment variables.

    export AMP_APICAST_IMAGE=registry.access.redhat.com/3scale-amp23/apicast-gateway
  6. Set the APICAST_ACCESS_TOKEN environment variable with the valid Access Token for Account Management API. You can extract it from the THREESCALE_PORTAL_ENDPOINT environment variable.

    oc env dc/apicast-production --list | grep THREESCALE_PORTAL_ENDPOINT

    This will return the following output:

    THREESCALE_PORTAL_ENDPOINT=http://<ACCESS_TOKEN>@system-master:3000/master/api/proxy/configs
  7. Export the <ACCESS_TOKEN> value to the environment variable APICAST_ACCESS_TOKEN.

    export APICAST_ACCESS_TOKEN=<ACCESS_TOKEN>
  8. Confirm that the necessary values are exported to the active shell.

    echo AMP_RELEASE=$AMP_RELEASE
    echo AMP_APICAST_IMAGE=$AMP_APICAST_IMAGE
    echo APICAST_ACCESS_TOKEN=$APICAST_ACCESS_TOKEN
    echo APICAST_MANAGEMENT_API=$APICAST_MANAGEMENT_API
    echo OPENSSL_VERIFY=$OPENSSL_VERIFY
    echo APICAST_RESPONSE_CODES=$APICAST_RESPONSE_CODES

1.4. Patch APIcast

  1. To patch the apicast-staging deployment configuration, run the following oc patch command.

    oc patch dc/apicast-staging -p "
    metadata:
      name: apicast-staging
      labels:
        app: APIcast
        3scale.component: apicast
        3scale.component-element: staging
    spec:
      replicas: 1
      selector:
        deploymentConfig: apicast-staging
      strategy:
        rollingParams:
          intervalSeconds: 1
          maxSurge: 25%
          maxUnavailable: 25%
          timeoutSeconds: 1800
          updatePeriodSeconds: 1
        type: Rolling
      template:
        metadata:
          labels:
            deploymentConfig: apicast-staging
            app: APIcast
            3scale.component: apicast
            3scale.component-element: staging
          annotations:
            prometheus.io/scrape: 'true'
            prometheus.io/port: '9421'
        spec:
          containers:
          - env:
            - name: THREESCALE_PORTAL_ENDPOINT
              value: \"http://${APICAST_ACCESS_TOKEN}@system-master:3000/master/api/proxy/configs\"
            - name: APICAST_CONFIGURATION_LOADER
              value: \"lazy\"
            - name: APICAST_CONFIGURATION_CACHE
              value: \"0\"
            - name: THREESCALE_DEPLOYMENT_ENV
              value: \"sandbox\"
            - name: APICAST_MANAGEMENT_API
              value: \"${APICAST_MANAGEMENT_API}\"
            - name: BACKEND_ENDPOINT_OVERRIDE
              value: http://backend-listener:3000
            - name: OPENSSL_VERIFY
              value: '${APICAST_OPENSSL_VERIFY}'
            - name: APICAST_RESPONSE_CODES
              value: '${APICAST_RESPONSE_CODES}'
            - name: REDIS_URL
              value: \"redis://system-redis:6379/2\"
            image: amp-apicast:latest
            imagePullPolicy: IfNotPresent
            name: apicast-staging
            resources:
              limits:
                cpu: 100m
                memory: 128Mi
              requests:
                cpu: 50m
                memory: 64Mi
            livenessProbe:
              httpGet:
                path: /status/live
                port: 8090
              initialDelaySeconds: 10
              timeoutSeconds: 5
              periodSeconds: 10
            readinessProbe:
              httpGet:
                path: /status/ready
                port: 8090
              initialDelaySeconds: 15
              timeoutSeconds: 5
              periodSeconds: 30
            ports:
            - containerPort: 8080
              protocol: TCP
            - containerPort: 8090
              protocol: TCP
            - name: metrics
              containerPort: 9421
              protocol: TCP
      triggers:
      - type: ConfigChange
      - type: ImageChange
        imageChangeParams:
          automatic: true
          containerNames:
          - apicast-staging
          from:
            kind: ImageStreamTag
            name: amp-apicast:latest
    "
  2. To patch the apicast-production deployment configuration, run the following oc patch command.

    oc patch dc/apicast-production -p "
    metadata:
      name: apicast-production
      labels:
        app: APIcast
        3scale.component: apicast
        3scale.component-element: production
    spec:
      replicas: 1
      selector:
        deploymentConfig: apicast-production
      strategy:
        rollingParams:
          intervalSeconds: 1
          maxSurge: 25%
          maxUnavailable: 25%
          timeoutSeconds: 1800
          updatePeriodSeconds: 1
        type: Rolling
      template:
        metadata:
          labels:
            deploymentConfig: apicast-production
            app: APIcast
            3scale.component: apicast
            3scale.component-element: production
          annotations:
            prometheus.io/scrape: 'true'
            prometheus.io/port: '9421'
        spec:
          initContainers:
          - name: system-master-svc
            image: amp-apicast:latest
            command: ['sh', '-c', 'until \$(curl --output /dev/null --silent --fail --head http://system-master:3000/status); do sleep $SLEEP_SECONDS; done']
            activeDeadlineSeconds: 1200
            env:
            - name: SLEEP_SECONDS
              value: \"1\"
          containers:
          - env:
            - name: THREESCALE_PORTAL_ENDPOINT
              value: \"http://${APICAST_ACCESS_TOKEN}@system-master:3000/master/api/proxy/configs\"
            - name: APICAST_CONFIGURATION_LOADER
              value: \"boot\"
            - name: APICAST_CONFIGURATION_CACHE
              value: \"300\"
            - name: THREESCALE_DEPLOYMENT_ENV
              value: \"production\"
            - name: APICAST_MANAGEMENT_API
              value: \"${APICAST_MANAGEMENT_API}\"
            - name: BACKEND_ENDPOINT_OVERRIDE
              value: http://backend-listener:3000
            - name: OPENSSL_VERIFY
              value: '${APICAST_OPENSSL_VERIFY}'
            - name: APICAST_RESPONSE_CODES
              value: '${APICAST_RESPONSE_CODES}'
            - name: REDIS_URL
              value: \"redis://system-redis:6379/1\"
            image: amp-apicast:latest
            imagePullPolicy: IfNotPresent
            name: apicast-production
            resources:
              limits:
                cpu: 1000m
                memory: 128Mi
              requests:
                cpu: 500m
                memory: 64Mi
            livenessProbe:
              httpGet:
                path: /status/live
                port: 8090
              initialDelaySeconds: 10
              timeoutSeconds: 5
              periodSeconds: 10
            readinessProbe:
              httpGet:
                path: /status/ready
                port: 8090
              initialDelaySeconds: 15
              timeoutSeconds: 5
              periodSeconds: 30
            ports:
            - containerPort: 8080
              protocol: TCP
            - containerPort: 8090
              protocol: TCP
            - name: metrics
              containerPort: 9421
              protocol: TCP
      triggers:
      - type: ConfigChange
      - type: ImageChange
        imageChangeParams:
          automatic: true
          containerNames:
          - system-master-svc
          - apicast-production
          from:
            kind: ImageStreamTag
            name: amp-apicast:latest
    "
  3. To patch the amp-apicast image stream, run the following oc patch command.

    oc patch is/amp-apicast -p "
    metadata:
      name: amp-apicast
      labels:
        app: APIcast
        3scale.component: apicast
      annotations:
        openshift.io/display-name: AMP APIcast
    spec:
      tags:
      - name: latest
        annotations:
          openshift.io/display-name: AMP APIcast (latest)
        from:
          kind: ImageStreamTag
          name: "${AMP_RELEASE}"
      - name: "${AMP_RELEASE}"
        annotations:
          openshift.io/display-name: AMP APIcast ${AMP_RELEASE}
        from:
          kind: DockerImage
          name: ${AMP_APICAST_IMAGE}
        importPolicy:
          insecure: false
    "
  4. Set importPolicy.insecure to true if the server is allowed to bypass certificate verification or connect directly over HTTP during image import.

1.5. Verify Upgrade

After you have performed the upgrade procedure, verify the success of the upgrade by making test API calls to the updated APIcast.

Note

It may take some time for the redeployment operations to complete in OpenShift.

1.6. Upgrade APIcast in OpenShift

If you deployed APIcast outside of the complete 3scale API Management on-premises installation using the apicast.yml OpenShift template, take the following steps to upgrade your deployment. The steps assume that the name of the deployment configuration is apicast, which is the default value in the apicast.yml template of the 3scale version 2.2. If you used a different name, you must adjust the commands accordingly.

  1. Update the container image

    oc patch dc/apicast --patch='{"spec":{"template":{"spec":{"containers":[{"name": "apicast", "image":"registry.access.redhat.com/3scale-amp23/apicast-gateway"}]}}}}'
  2. Add the port definition for port 9421 used for Prometheus metrics

    oc patch dc/apicast --patch='{"spec": {"template": {"spec": {"containers": [{"name": "apicast","ports": [{"name": "metrics", "containerPort": 9421, "protocol": "TCP"}]}]}}}}'
  3. Add Prometheus annotations

    oc patch dc/apicast --patch='{"spec": {"template": {"metadata": {"annotations": {"prometheus.io/scrape": "true", "prometheus.io/port": "9421"}}}}}'
  4. Remove the APICAST_WORKERS environment variable

    oc env dc/apicast APICAST_WORKERS-

APICAST_WORKERS allows specifying the value for the directive worker_processes. By default, APIcast uses the value auto, which triggers auto-detection of the best number of workers, when running in OpenShift or Kubernetes environments. Thus, it is recommended not set the APICAST_WORKERS value explicitly and let APIcast perform auto-detection.

Note

The APICAST_WORKERS parameter is no longer present in the apicast.yml OpenShift template. In case you are using scripts that deploy the template with APICAST_WORKERS parameter, make sure you remove this parameter from the scripts, otherwise the deployment will fail with the following error: error: unexpected parameter name "APICAST_WORKERS"