Chapter 2. Installation guide for 3scale on OpenShift

1. Log in to the OpenShift server as an administrator, as follows:

   oc login -u system:admin

2. Log in to the OpenShift project where you will be installing the image streams. Red Hat recommends that you use the openshift project for the 3scale OpenShift image streams.

   Note: It will have a prefix that is a fixed, random string.

   oc project your-openshift-project

3. Create a docker-registry secret using the credentials you created in Section 2.4.3, “Creating registry service accounts”.

   Note

   • Replace your-registry-service-account-username with the username created in the format, 12345678|username.
   • Replace your-registry-service-account-password with the password string below the username, under the Token Information tab.
   • Create a docker-registry secret for every new namespace where the image streams reside and which use registry.redhat.io.

   $ oc create secret docker-registry threescale-registry-auth \
     --docker-server=registry.redhat.io \
     --docker-username="your-registry-service-account-username" \
     --docker-password="your-registry-service-account-password"

1. Navigate to the Registry Service Accounts page and log in.
2. Click New Service Account.

3. Fill in the form on the Create a New Registry Service Account page.

   1. Add a name for the service account.

      Note: You will see a fixed-length, randomly generated number string before the form field.

4. Enter a Description.
5. Click Create.
6. Navigate back to your Service Accounts.
7. Click the Service Account you created.

8. Make a note of the username, including the prefix string, for example 12345678|username, and your password.

   1. This username and password will be used to log in to registry.redhat.io.

1. From a terminal session log in to OpenShift as the cluster administrator:

   oc login

2. Select your project, or create a new project:

   oc project <project_name>

   oc new-project <project_name>

3. Enter the oc new-app command:

   1. Specify the --file option with the path to the amp.yml file you downloaded as part of Section 2.3, “Configuring nodes and entitlements”.

   2. Specify the --param option with the WILDCARD_DOMAIN parameter set to the domain of your OpenShift cluster:

      oc new-app --file /opt/amp/templates/amp.yml --param WILDCARD_DOMAIN=<WILDCARD_DOMAIN>

      The terminal shows the master and tenant URLs and credentials for your newly created 3scale Admin Portal. This output should include the following information:

      • master admin username
      • master password
      • master token information
      • tenant username
      • tenant password
      • tenant token information

4. Log in to https://user-admin.3scale-project.example.com as admin/xXxXyz123.

   * With parameters:
   
    * ADMIN_PASSWORD=xXxXyz123 # generated
    * ADMIN_USERNAME=admin
    * TENANT_NAME=user
   
    * MASTER_NAME=master
    * MASTER_USER=master
    * MASTER_PASSWORD=xXxXyz123 # generated
   
   --> Success
   Access your application via route 'user-admin.3scale-project.example.com'
   Access your application via route 'master-admin.3scale-project.example.com'
   Access your application via route 'backend-user.3scale-project.example.com'
   Access your application via route 'user.3scale-project.example.com'
   Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
   Access your application via route 'api-user-apicast-production.3scale-project.example.com'

5. Make a note of these details for future reference.

   Note

   Wait for 3scale to fully deploy on OpenShift for your login and credentials to work.

1. If you are not already logged in, log in to OpenShift:

   oc login

   1. Configure variables for the SMTP config map. Use the oc patch command, specify the configmap and smtp objects, followed by the -p option and write the following new values in JSON for the following variables:

      Variable	Description
      address	Allows you to specify a remote mail server as a relay
      username	Specify your mail server username
      password	Specify your mail server password
      domain	Specify a HELO domain
      port	Specify the port on which the mail server is listening for new connections
      authentication	Specify the authentication type of your mail server. Allowed values: plain ( sends the password in the clear), login (send password Base64 encoded), or cram_md5 (exchange information and a cryptographic Message Digest 5 algorithm to hash important information)
      openssl.verify.mode	Specify how OpenSSL checks certificates when using TLS. Allowed values: none, peer, client_once, or fail_if_no_peer_cert.

      Example

      oc patch configmap smtp -p '{"data":{"address":"<your_address>"}}'
      oc patch configmap smtp -p '{"data":{"username":"<your_username>"}}'
      oc patch configmap smtp -p '{"data":{"password":"<your_password>"}}'

2. After you have set the configmap variables, redeploy the system-app and system-sidekiq pods:

   oc rollout latest dc/system-app
   oc rollout latest dc/system-sidekiq

1. Create an access token with the following configurations:

   • Scoped to Account Management API
   • Having read-only access

2. Log in to your APIcast cluster:

   oc login

3. Create a secret that allows APIcast to communicate with 3scale. Specify new-basicauth, apicast-configuration-url-secret, and the --password parameter with the access token, tenant name, and wildcard domain of your 3scale deployment:

   oc secret new-basicauth apicast-configuration-url-secret --password=https://<APICAST_ACCESS_TOKEN>@<TENANT_NAME>-admin.<WILDCARD_DOMAIN>

   Note

   TENANT_NAME is the name under the root that the Admin Portal will be available with. The default value for TENANT_NAME is 3scale. If you used a custom value in your 3scale deployment, you must use that value here.

4. Import the APIcast template using the oc new-app command, specifying the --file option with the apicast.yml file:

   oc new-app --file /opt/amp/templates/apicast.yml

   Note

   First install the APIcast template as described in Section 2.3, “Configuring nodes and entitlements”.

1. Create an access token with the following configurations:

   • Scoped to Account Management API
   • Having read-only access

2. Log in to your APIcast cluster:

   oc login

3. Create a secret that allows APIcast to communicate with 3scale. Specify new-basicauth, apicast-configuration-url-secret, and the --password parameter with the access token, tenant name, and wildcard domain of your 3scale deployment:

   oc secret new-basicauth apicast-configuration-url-secret --password=https://<APICAST_ACCESS_TOKEN>@<TENANT_NAME>-admin.<WILDCARD_DOMAIN>

   Note

   TENANT_NAME is the name under the root that the Admin Portal will be available with. The default value for TENANT_NAME is 3scale. If you used a custom value in your 3scale deployment, you must use that value.

4. Deploy APIcast on a different OpenShift cluster using the oc new-app command. Specify the --file option and the to path to your apicast.yml file:

   oc new-app --file /path/to/file/apicast.yml

1. If not already logged in, log in to your OpenShift cluster:

   oc login

2. Enter the following command to display the backend-listener route URL:

   oc get route backend

3. Enter the oc new-app command with the path to apicast.yml:

   oc new-app -f apicast.yml

1. If not already logged in, log in to your OpenShift cluster:

   oc login

2. As admin, specify the oadm command with the pod-network and join-projects options to set up communication between both projects:

   oadm pod-network join-projects --to=<3SCALE_PROJECT> <APICAST_PROJECT>

3. Enter the following command to display the backend-listener route URL:

   oc get route backend

4. Enter the oc new-app command with the path to apicast.yml:

   oc new-app -f apicast.yml

Procedure

1. Click Catalog > Installed Operators.

   1. From the list of Installed Operators, click 3scale Operator.
2. Click the API Manager tab.
3. Click Create APIManager.

4. Clear the sample content and add the following YAML definitions to the editor, then click Create.

   Note

   The wildcardDomain parameter can be any desired name you wish to give that resolves to an IP address, which is a valid DNS domain. Be sure to remove the placeholder marks for your parameters: < >.

   apiVersion: apps.3scale.net/v1alpha1
   kind: APIManager
   metadata:
     name: example-apimanager
   spec:
     wildcardDomain: <wildcardDomain>
     resourceRequirementsEnabled: true

   Note

   For more information about the APIManager fields, refer to the Reference documentation.

1. Run these commands:

   oc get secret system-seed -o json | jq -r .data.ADMIN_USERNAME | base64 -d
   oc get secret system-seed -o json | jq -r .data.ADMIN_PASSWORD | base64 -d

2. Login as the APIManager administrator to verify these credentials are working.

1. Find the PVC containing the erroneous MySQL data with the oc get pvc command:

   # oc get pvc
   NAME                    STATUS    VOLUME    CAPACITY   ACCESSMODES   AGE
   backend-redis-storage   Bound     vol003    100Gi      RWO,RWX       4d
   mysql-storage           Bound     vol006    100Gi      RWO,RWX       4d
   system-redis-storage    Bound     vol008    100Gi      RWO,RWX       4d
   system-storage          Bound     vol004    100Gi      RWO,RWX       4d

2. Stop the deployment of the system-mysql pod by clicking cancel deployment in the OpenShift UI.
3. Delete everything under the MySQL path to clean the volume.
4. Start a new system-mysql deployment.

1. The directories used for the persistent volumes MUST have the write permissions for the root group. Having rw permissions for the root user is not enough as the MySQL service runs as a different user in the root group. Execute the following command as the root user:

   chmod -R g+w /path/for/pvs

2. Execute the following command to prevent SElinux from blocking access:

   chcon -Rt svirt_sandbox_file_t /path/for/pvs