此内容没有您所选择的语言版本。
Chapter 1. Upgrade 3scale 2.1 to 2.2
Perform the steps in this document to upgrade Red Hat 3scale API Management on-premises deployment from version 2.1 to 2.2.
1.1. Prerequisites: 复制链接链接已复制到粘贴板!
- 3scale On-Premises 2.1
- OpenShift CLI
- 3scale AMP 2.2 templates
- Access and permissions to your OpenShift server and project
- A persistent volume with enough space to hold a backup of the MySQL database
This process can cause disruption in the service. Make sure to have a maintenance window.
1.2. Select the Project 复制链接链接已复制到粘贴板!
- Take a backup of your OpenShift cluster.
From a terminal session, log in to your OpenShift cluster:
oc login https://<YOUR_OPENSHIFT_CLUSTER>:8443
oc login https://<YOUR_OPENSHIFT_CLUSTER>:8443
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Select the project that you want to upgrade:
oc project <YOUR_AMP_21_PROJECT>
oc project <YOUR_AMP_21_PROJECT>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. Gather the Needed Values 复制链接链接已复制到粘贴板!
You need the following parameters for the new 3scale API Management 2.2 Multitenancy feature. You may choose to either specify new values for these parameters or keep the default ones.
Parameter | Description |
---|---|
MASTER_USER | Username for the Master Admin Portal. Default: "master" |
MASTER_PASSWORD | Password for the Master Admin Portal. Automatically generated if not specified |
MASTER_ACCESS_TOKEN | Access Token for master automatically generated during the upgrade. However, MASTER_ACCESS_TOKEN is not added to the system seed by default. |
APICAST_REGISTRY_URL | The URL to point to APIcast policies registry management. Default: http://apicast-staging:8090/policies |
Gather the following values from the system components of your current 2.1 deployment:
- DATABASE_URL
- THREESCALE_SUPERDOMAIN
- TENANT_NAME
- APICAST_ACCESS_TOKEN
- ADMIN_ACCESS_TOKEN
- USER_LOGIN
- USER_PASSWORD
- EVENTS_SHARED_SECRET
- APICAST_BACKEND_ROOT_ENDPOINT
- CONFIG_INTERNAL_API_USER
- CONFIG_INTERNAL_API_PASSWORD
- SECRET_KEY_BASE
- BACKEND_ROUTE
Export them from the current deployment into the active shell:
export `oc env dc/system-app --list | grep -E '^(DATABASE_URL|THREESCALE_SUPERDOMAIN|TENANT_NAME|APICAST_ACCESS_TOKEN|ADMIN_ACCESS_TOKEN|USER_LOGIN|USER_PASSWORD|EVENTS_SHARED_SECRET|APICAST_BACKEND_ROOT_ENDPOINT|CONFIG_INTERNAL_API_USER|CONFIG_INTERNAL_API_PASSWORD|SECRET_KEY_BASE|BACKEND_ROUTE)=' | tr "\n" ' ' `
export `oc env dc/system-app --list | grep -E '^(DATABASE_URL|THREESCALE_SUPERDOMAIN|TENANT_NAME|APICAST_ACCESS_TOKEN|ADMIN_ACCESS_TOKEN|USER_LOGIN|USER_PASSWORD|EVENTS_SHARED_SECRET|APICAST_BACKEND_ROOT_ENDPOINT|CONFIG_INTERNAL_API_USER|CONFIG_INTERNAL_API_PASSWORD|SECRET_KEY_BASE|BACKEND_ROUTE)=' | tr "\n" ' ' `
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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/system-app
oc get "-o=custom-columns=NAMES:.spec.template.spec.containers[0].env[?(.name==\"<variable_name>\")].value" dc/system-app
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Gather the following values from the
system-mysql
component of your current 2.1 deployment:- MYSQL_USER
- MYSQL_PASSWORD
- MYSQL_DATABASE
- MYSQL_ROOT_PASSWORD
Export these values from the current deployment into the active shell:
export `oc env dc/system-mysql --list | grep -E '^(MYSQL_USER|MYSQL_PASSWORD|MYSQL_DATABASE|MYSQL_ROOT_PASSWORD)=' | tr "\n" ' ' `
export `oc env dc/system-mysql --list | grep -E '^(MYSQL_USER|MYSQL_PASSWORD|MYSQL_DATABASE|MYSQL_ROOT_PASSWORD)=' | tr "\n" ' ' `
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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/system-mysql
oc get "-o=custom-columns=NAMES:.spec.template.spec.containers[0].env[?(.name==\"<variable_name>\")].value" dc/system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Gather the following values from the APIcast component of your current 2.1 deployment:
- APICAST_MANAGEMENT_API
- OPENSSL_VERIFY
- APICAST_RESPONSE_CODES
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" ' ' `
export `oc env dc/apicast-production --list | grep -E '^(APICAST_MANAGEMENT_API|OPENSSL_VERIFY|APICAST_RESPONSE_CODES)=' | tr "\n" ' ' `
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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
oc get "-o=custom-columns=NAMES:.spec.template.spec.containers[0].env[?(.name==\"<variable_name>\")].value" dc/apicast-production
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.4. Configure New Variable Values 复制链接链接已复制到粘贴板!
Set the value for the new version of the AMP release:
export AMP_RELEASE=2.2.0
export AMP_RELEASE=2.2.0
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set the values for the new optional parameters introduced in AMP 2.2. These parameters are described in the beginning of the gather needed values section. Use the
export
command, replacing the values in the parenthesis:export MASTER_ACCESS_TOKEN=<MASTER_ACCESS_TOKEN> export APICAST_REGISTRY_URL=<APICAST_REGISTRY_URL>
export MASTER_ACCESS_TOKEN=<MASTER_ACCESS_TOKEN> export APICAST_REGISTRY_URL=<APICAST_REGISTRY_URL>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Regarding MASTER_USER and MASTER_PASSWORD, consider the following:
- If you want to use the default values, no action is required.
If you have specified values for these environment variables, export them with the following commands:
export MASTER_USER=<MASTER_USER> export MASTER_PASSWORD=<MASTER_PASSWORD>
export MASTER_USER=<MASTER_USER> export MASTER_PASSWORD=<MASTER_PASSWORD>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Confirm that the necessary values gathered in the gather needed values section are exported to the active shell and that the new values are set in this section:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.5. Upgrade the database pod 复制链接链接已复制到粘贴板!
To upgrade the database, create a backup of the pod and deploy a new pod.
1.5.1. Create the backup 复制链接链接已复制到粘贴板!
- Create a persistent volume with enough storage to hold the MySQL database.
To create a persistent volume claim with enough storage to hold the MySQL database, run the following command, replacing the
<size>
value with an appropriate size for your database:Copy to Clipboard Copied! Toggle word wrap Toggle overflow This command crates a persistent volume claim named
mysql-backup
.To create a pod to house the backup database, run the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Wait until the pod is created and log in to it using the following
oc rsh
command and take the backup:oc rsh mysql-backup /opt/rh/rh-mysql57/root/usr/bin/mysqldump -h system-mysql -u ${MYSQL_USER} -p${MYSQL_PASSWORD} system -r /backup/backup.sql
oc rsh mysql-backup /opt/rh/rh-mysql57/root/usr/bin/mysqldump -h system-mysql -u ${MYSQL_USER} -p${MYSQL_PASSWORD} system -r /backup/backup.sql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To verify the contents of your backup, check the backup file size against the original file size by running the following
oc rsh
command:oc rsh mysql-backup ls -lha /backup/backup.sql
oc rsh mysql-backup ls -lha /backup/backup.sql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
If in the next steps you experience a failure, you can redeploy your database from your backup by using the following oc rsh
command:
oc rsh mysql-backup /bin/bash -c "/usr/bin/cat /backup/backup.sql | /opt/rh/rh-mysql57/root/usr/bin/mysql -h system-mysql -uroot -p${MYSQL_ROOT_PASSWORD} system"
oc rsh mysql-backup /bin/bash -c "/usr/bin/cat /backup/backup.sql | /opt/rh/rh-mysql57/root/usr/bin/mysql -h system-mysql -uroot -p${MYSQL_ROOT_PASSWORD} system"
1.5.2. Perform the upgrade 复制链接链接已复制到粘贴板!
Delete the system service with the following
oc delete
command. Note that your application will be down from this point because the application loses connection with the database:oc delete service system-mysql
oc delete service system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the MySQL DeploymentConfig, run the following
oc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Ensure that the new pod is deployed successfully before continuing.
To fetch the new pod details, run the following
oc get
commands:To fetch the pod name:
oc get pods -l deploymentconfig=system-mysql
oc get pods -l deploymentconfig=system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To fetch the pod IP address:
oc get pods -o=custom-columns=IP:.status.podIP -l deploymentconfig=system-mysql
oc get pods -o=custom-columns=IP:.status.podIP -l deploymentconfig=system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Log in to the pod using the following
oc rsh
command, substitute the <pod_name> and <pod_ip> with the name and IP address from the preceding steps:oc rsh <pod_name> /opt/rh/rh-mysql57/root/usr/bin/mysql_upgrade -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD}
oc rsh <pod_name> /opt/rh/rh-mysql57/root/usr/bin/mysql_upgrade -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD}
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the mysql Deployment Config with the changes done on the 2.2 version, run the following
oc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.5.3. Change the MySQL character set and collation 复制链接链接已复制到粘贴板!
To create the
mysql-extra-conf
ConfigMap with the mysql-charset.cnf config file, run the followingoc create
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To create the
mysql-main-conf
ConfigMap, run the followingoc create
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To configure system-mysql starting with the created configmaps on last steps, run the following
oc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Wait until the deployment is complete on system-mysql and run the following
oc get
command to fetch the new MySQL pod name:oc get pods -l deploymentconfig=system-mysql
oc get pods -l deploymentconfig=system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To fetch the new MySQL pod IP address, run the following
oc get
command:oc get pods -o=custom-columns=IP:.status.podIP -l deploymentconfig=system-mysql
oc get pods -o=custom-columns=IP:.status.podIP -l deploymentconfig=system-mysql
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To change the character set on the database and all the tables, run the
oc rsh
command, specifying the previously fetched<pod_name>
and<pod_ip>
:oc rsh <pod_name> /bin/bash -c "echo ALTER DATABASE system CHARACTER SET utf8 COLLATE utf8_general_ci | mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8" oc rsh <pod_name> /bin/bash -c "/opt/rh/rh-mysql57/root/usr/bin/mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8 -B -N -e 'SHOW TABLES' system | awk '{print \"SET foreign_key_checks = 0; ALTER TABLE\", \$1, \"CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci; SET foreign_key_checks = 1; \"}' | /opt/rh/rh-mysql57/root/usr/bin/mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8 system"
oc rsh <pod_name> /bin/bash -c "echo ALTER DATABASE system CHARACTER SET utf8 COLLATE utf8_general_ci | mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8" oc rsh <pod_name> /bin/bash -c "/opt/rh/rh-mysql57/root/usr/bin/mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8 -B -N -e 'SHOW TABLES' system | awk '{print \"SET foreign_key_checks = 0; ALTER TABLE\", \$1, \"CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci; SET foreign_key_checks = 1; \"}' | /opt/rh/rh-mysql57/root/usr/bin/mysql -h <pod_ip> -u root -p${MYSQL_ROOT_PASSWORD} --default-character-set=utf8 system"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow To create the
system-mysql
service, run the followingoc create
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.5.4. Delete the backups 复制链接链接已复制到粘贴板!
- Verify the updated database and ensure that the pods are running.
To delete the backup pod and persistent volume claim, run the following
oc delete
command:oc delete pod/mysql-backup oc delete pvc/mysql-backup
oc delete pod/mysql-backup oc delete pvc/mysql-backup
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.6. Create new routes and services for system 复制链接链接已复制到粘贴板!
After you have configured the new variable values, run the following oc create
command to create new routes and services:
1.7. Patch System Components 复制链接链接已复制到粘贴板!
Continue your in-place upgrade using the oc patch
command. The oc patch
command allows you to patch your deployment configurations, image streams and ConfigMaps.
In this section of the upgrade, you must patch the system config map. You must also patch deployment configurations for the following pods:
- system-app
- system-resque
- system-sidekiq
- system-sphinx
Follow these steps to patch config maps and deployment configurations:
To patch the
system
ConfigMap, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
system-resque
deployment configuration, consider the following:-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
oc patch
command below. Alternatively, if you want to specify values for MASTER_USER and MASTER_PASSWORD, include them in the
oc patch
command below.Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
To patch the
system-sidekiq
deployment configuration, consider the following:-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
oc patch
command below. Alternatively, if you want to specify values for MASTER_USER and MASTER_PASSWORD, include them in the
oc patch
command below.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
To patch the
system-app
deployment configuration, consider the following:-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
oc patch
command below. Alternatively, if you want to specify values for MASTER_USER and MASTER_PASSWORD, include them in the
oc patch
command below.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
If you want to use the default values for MASTER_USER and MASTER_PASSWORD environment variables, do not describe them in the
To patch the
amp-system
image, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
system-sphinx
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
system-redis
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
system-memcache
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.8. Patch Backend Components 复制链接链接已复制到粘贴板!
To patch the
backend-cron
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
backend-worker
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
backend-listener
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
amp-backend
image stream, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
backend-redis
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.9. Patch APIcast 复制链接链接已复制到粘贴板!
To patch the
apicast-staging
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
apicast-production
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
amp-apicast
image stream, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
apicast-wildcard-router
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
amp-wildcard-router
image stream, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.10. Patch Zync components 复制链接链接已复制到粘贴板!
To patch the
zync-database
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
zync
deployment configuration, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow To patch the
zync
image stream, run the followingoc patch
command:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.11. Verify Upgrade 复制链接链接已复制到粘贴板!
After you have performed the upgrade procedure, verify the success of your upgrade operation by checking the version number in the lower-right corner of your 3scale Admin Portal.
It may take some time for your redeployment operations to complete in OpenShift.