Installing 3scale

1. Create a new database.

   The following settings are required for the Oracle Database to work with 3scale:

   ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
   ALTER SYSTEM SET compatible='12.2.0.1' SCOPE=SPFILE;

2. Collect the database details.

   Get the following information that will be needed for 3scale configuration:

   • Oracle Database URL
   • Oracle Database service name

   • Oracle Database system password

     The DATABASE_URL parameter must follow this format:

Procedure

1. Clone the 3scale OpenShift Templates GitHub repository. Use the following command:

   $ git clone --branch 2.6.0.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. Download the 3scale 2.6 amp.yml template.

4. Run the oc new-app command with the -f option and specify the build.yml OpenShift template:

   $ oc new-app -f build.yml

5. Run the oc new-app command with the -f option to indicate the amp.yml OpenShift template, and the -p option to specify the WILDCARD_DOMAIN parameter with the domain of your OpenShift cluster:

   $ oc new-app -f amp.yml -p WILDCARD_DOMAIN=mydomain.com

6. Enter the following oc patch commands, replacing SYSTEM_PASSWORD with the Oracle Database system password you set up in Section 1.2, “Preparing Oracle Database”:

   $ oc patch dc/system-app -p '[{"op": "add", "path": "/spec/strategy/rollingParams/pre/execNewPod/env/-", "value": {"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}}]' --type=json
   
   $ oc patch dc/system-app -p '{"spec": {"strategy": {"rollingParams": {"post":{"execNewPod": {"env": [{"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}]}}}}}}'

7. Enter the following command, replacing DATABASE_URL to point to your Oracle Database, specified in Section 1.2, “Preparing Oracle Database”:

   $ oc patch secret/system-database -p '{"stringData": {"URL": "DATABASE_URL"}}'

8. Link the pull secret to the builder with the following command:

   $ oc secrets link builder threescale-registry-auth

9. Enter the oc start-build command to build the new system image:

   $ oc start-build 3scale-amp-system-oracle --from-dir=.

1. Install Red Hat Enterprise Linux (RHEL) on each of your nodes.
2. Register your nodes with Red Hat using the Red Hat Subscription Manager (RHSM), via the interface or the command line.
3. Attach your nodes to your 3scale subscription using RHSM.

4. Install OpenShift on your nodes, complying with the following requirements:

   • Use a supported OpenShift version.
   • Configure persistent storage on a file system that supports multiple writes.
5. Install the OpenShift command line interface.

6. Enable access to the rhel-7-server-3scale-amp-2.6-rpms repository using the subscription manager:

   sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2.6-rpms

7. Install the 3scale template called 3scale-amp-template. This will be saved at /opt/amp/templates.

   sudo yum install 3scale-amp-template

1. By default you are logged in as developer and can proceed to the next step.

   Otherwise login into OpenShift using the oc login command from the OpenShift Client tools you downloaded and installed in the previous step. The default login credentials are username = "developer" and password = "developer":

   oc login https://OPENSHIFT-SERVER-IP:8443

   You should see Login successful. in the output.

2. Create your project. This example sets the display name as gateway

   oc new-project "3scalegateway" --display-name="gateway" --description="3scale gateway demo"

   The response should look like this:

   Now using project "3scalegateway" on server "https://172.30.0.112:8443".

   Ignore the suggested next steps in the text output at the command prompt and proceed to the next step below.

3. Create a new secret to reference your project by replacing <access_token> and <domain> with your own credentials. See below for more information about the <access_token> and <domain>.

   oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<access_token>@<admin_portal_domain>  --type=kubernetes.io/basic-auth

   Here <access_token> is an Access Token (not a Service Token) for the 3scale Account Management API, and <domain>-admin.3scale.net is the URL of your 3scale Admin Portal.

   The response should look like this:

   secret/apicast-configuration-url-secret

4. Create an application for your APIcast gateway from the template, and start the deployment:

   oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.6.0.GA/apicast-gateway/apicast.yml

   You should see the following messages at the bottom of the output:

   --> Creating resources with label app=3scale-gateway ...
       deploymentconfig "apicast" created
       service "apicast" created
   --> Success
       Run 'oc status' to view your app.

1. Open the web console for your OpenShift cluster in your browser: https://OPENSHIFT-SERVER-IP:8443/console/

   Use the value specified in --public-hostname instead of OPENSHIFT-SERVER-IP if you started OpenShift cluster on a remote server.

   You should see the login screen:

   
   Note

   You may receive a warning about an untrusted web-site. This is expected, as you are trying to access the web console through secure protocol, without having configured a valid certificate. While you should avoid this in production environment, for this test setup you can go ahead and create an exception for this address.

2. Log in using the developer credentials created or obtained in the Setup OpenShift section above.

   You will see a list of projects, including the gateway project you created from the command line above.

   

   If you do not see your gateway project, you probably created it with a different user and will need to assign the policy role to to this user.

3. Click on the gateway link and you will see the Overview tab.

   OpenShift downloaded the code for APIcast and started the deployment. You may see the message Deployment #1 running when the deployment is in progress.

   When the build completes, the UI will refresh and show two instances of APIcast ( 2 pods ) that have been started by OpenShift, as defined in the template.

   

   Each APIcast instance, upon starting, downloads the required configuration from 3scale using the settings you provided on the Integration page of your 3scale Admin Portal.

   OpenShift will maintain two APIcast instances and monitor the health of both; any unhealthy APIcast instance will automatically be replaced with a new one.

4. To allow your APIcast instances to receive traffic, you need to create a route. Start by clicking on Create Route.

   

   Enter the same host you set in 3scale above in the section Public Base URL (without the http:// and without the port) , e.g. gateway.openshift.demo, then click the Create button.

   

   For every 3scale service you define, you must create a new route.

1. List all repositories: sudo yum repolist all.
2. Find the *-extras repository.
3. Enable the extras repository: sudo yum-config-manager --enable rhui-REGION-rhel-server-extras.
4. Install the Docker containerized environment package: sudo yum install docker.

1. Start the Docker daemon:

   sudo systemctl start docker.service.

2. Check if the Docker daemon is running:

   sudo systemctl status docker.service.

   You can download a ready to use Docker-formatted container image from the Red Hat registry:

   sudo docker pull registry.access.redhat.com/3scale-amp26/apicast-gateway.

3. Run APIcast in a Docker-formatted container:

   sudo docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<access_token>@<domain>-admin.3scale.net registry.access.redhat.com/3scale-amp26/apicast-gateway.

   Here, <access_token> is the Access Token for the 3scale Account Management API. You can use the Provider Key instead of the access token. <domain>-admin.3scale.net is the URL of your 3scale admin portal.

Procedure

1. In the OpenShift Container Platform console, log in using an account with administrator privileges.
2. Click Catalog > OperatorHub.
3. In the Filter by keyword box, type 3scale operator to find the 3scale operator.
4. Click the 3scale operator. Information about the Operator is displayed.
5. Read the information about the operator and click Install. The Create Operator Subscription page opens.

6. On the Create Operator Subscription page, accept all of the default selections and click Subscribe.

   Note

   The operator will only be available in the specific single namespace on the cluster that you have selected.

   The 3scale-operator details page is displayed, where you can see the Subscription Overview.

7. After the subscription upgrade status is shown as Up to date, click Catalog > Installed Operators to verify that the 3scale operator ClusterServiceVersion (CSV) is displayed and its Status ultimately resolves to InstallSucceeded in the operator-test project.

   1. Successful installation will register the APIManager CRD and the CRDs related to the Capabilities functionality of the operator in the OpenShift API server.

8. After successful installation, query the resource types defined by the CRDs via oc get.

   1. For example, to verify that the APIManager CRD has been correctly registered, execute the following command:

      oc get apimanagers

9. You should see the following output:

   No resources found.

   For troubleshooting information, see the OpenShift Container Platform documentation.

Procedure

1. Login to the OpenShift node where your 3scale On-premises instance is hosted and change to its project:

   oc login -u <user> <url>
   oc project <3scale-project>

   Replace <user>, <url>, and <3scale-project> with your own credentials and the project name.

2. Follow the steps below in the order shown to scale down all the pods. This will avoid loss of data.

   Stop 3scale On-premises

   From the OpenShift web console or from the command line interface (CLI), scale down all the deployment configurations to zero replicas in the following order:

   • apicast-wildcard-router and zync for versions before 3scale 2.6 or zync-que and zync for 3scale 2.6 and above.
   • apicast-staging and apicast-production.

   • system-sidekiq, backend-cron, and system-sphinx.

     • 3scale 2.3 includes system-resque.
   • system-app.
   • backend-listener and backend-worker.

   • backend-redis, system-memcache, system-mysql, system-redis, and zync-database.

     The following example shows how to perform this in the CLI for apicast-wildcard-router and zync:

     oc scale dc/apicast-wildcard-router --replicas=0
     oc scale dc/zync --replicas=0

     Note

     The deployment configuration for each step can be scaled down at the same time. For example, you could scale down apicast-wildcard-router and zync together. However, it is better to wait for the pods from each step to terminate before scaling down the ones that follow. The 3scale instance will be completely inaccessible until it is fully started again.

3. To confirm that no pods are running on the 3scale project use the following command:

   oc get pod

   The command should return No resources found.

4. Scale up the database level pods again using the following command:

   oc scale dc/{backend-redis,system-memcache,system-mysql,system-redis,zync-database} --replicas=1

5. Ensure that you are able to login to the external MySQL database through the system-mysql pod before proceeding with the next steps:

   oc rsh system-mysql-<system_mysql_pod_id>
   mysql -u root -p -h <host>

   • <system_mysql_pod_id>: The identifier of the system-mysql pod.

   • The user should always be root. For more information see Section 9.1, “External MySQL database limitations”.

     1. The CLI will now display mysql>. Type exit, then press return. Type exit again at the next prompt to go back to the OpenShift node console.

6. Perform a full MySQL dump using the following command:

   oc rsh system-mysql-<system_mysql_pod_id> /bin/bash -c "mysqldump -u root --single-transaction --routines --triggers --all-databases" > system-mysql-dump.sql

   • Replace <system_mysql_pod_id> with your unique system-mysql pod ID .

   • Validate that the file system-mysql-dump.sql contains a valid MySQL level dump as in the following example:

     $ head -n 10 system-mysql-dump.sql
     -- MySQL dump 10.13  Distrib 5.7.24, for Linux (x86_64)
     --
     -- Host: localhost    Database:
     -- ------------------------------------------------------
     -- Server version   5.7.24
     
     /*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
     /*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
     /*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
     /*!40101 SET NAMES utf8 */;

7. Scale down the system-mysql pod and leave it with 0 (zero) replicas:

   oc scale dc/system-mysql --replicas=0

8. Find the base64 equivalent of the URL mysql2://root:<password>@<host>/system, replacing <password> and <host> accordingly:

   echo "mysql2://root:<password>@<host>/system" | base64

9. Create a default 'user'@'%' on the remote MySQL database. It only needs to have SELECT privileges. Also find its base64 equivalents:

   echo "user" | base64
   echo "<password>" | base64

   • Replace <password> with the password for 'user'@'%'.

10. Perform a backup and edit the OpenShift secret system-database:

    oc get secret system-database -o yaml > system-database-orig.bkp.yml
    oc edit secret system-database

    • URL: Replace it with the value from [step-8].
    • DB_USER and DB_PASSWORD: Use the values from the previous step for both.

11. Use the command below to send system-mysql-dump.sql to the remote database server and import the dump into the server:

    mysql -u root -p < system-mysql-dump.sql

12. Ensure that a new database called system was created:

    mysql -u root -p -se "SHOW DATABASES"

13. Use the following instructions to Start 3scale On-premises, which scales up all the pods in the correct order.

    Start 3scale On-premises

    • backend-redis, system-memcache, system-mysql, system-redis, and zync-database.
    • backend-listener and backend-worker.
    • system-app.

    • system-sidekiq, backend-cron, and system-sphinx

      • 3scale 2.3 includes system-resque.
    • apicast-staging and apicast-production.

    • apicast-wildcard-router and zync for versions before 3scale 2.6 or zync-que and zync for 3scale 2.6 and above.

      The following example shows how to perform this in the CLI for backend-redis, system-memcache, system-mysql, system-redis, and zync-database:

      oc scale dc/backend-redis --replicas=1
      oc scale dc/system-memcache --replicas=1
      oc scale dc/system-mysql --replicas=1
      oc scale dc/system-redis --replicas=1
      oc scale dc/zync-database --replicas=1

      The system-app pod should now be up and running without any issues.

14. After validation, scale back up the other pods in the order shown.
15. Backup the system-mysql DeploymentConfig object. You may delete after a few days once you are sure everything is running properly. Deleting system-mysql DeploymentConfig avoids any future confusion if this procedure is done again in the future.

1. Edit the secret system-database using the original values from system-database-orig.bkp.yml. See [step-10]:

   oc edit secret system-database

   Replace URL, DB_USER, and DB_PASSWORD with their original values.

2. Scale down all the pods and then scale them back up again, including system-mysql. The system-app pod and the other pods to be started after it should be up and running again. Run the following command to confirm all pods are back up and running:

   oc get pods -n <3scale-project>