Installing 3scale

1. Create an Identity and Access Management (IAM) policy with the following minimum permissions:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "s3:ListAllMyBuckets",
               "Resource": "arn:aws:s3:::*"
           },
           {
               "Effect": "Allow",
               "Action": "s3:*",
               "Resource": [
                   "arn:aws:s3:::targetBucketName",
                   "arn:aws:s3:::targetBucketName/*"
               ]
           }
       ]
   }

2. Create a CORS configuration with the following rules:

   <?xml version="1.0" encoding="UTF-8"?>
   <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <CORSRule>
       <AllowedOrigin>https://*</AllowedOrigin>
       <AllowedMethod>GET</AllowedMethod>
   </CORSRule>
   </CORSConfiguration>

Procedure

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.

Procedure

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 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.

6. The 3scale deployment on OpenShift has been successful when the following command returns:

   oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)

   Note

   When the 3scale deployment on OpenShift has been successful, your login credentials will work.

Procedure

1. Download amp-s3.yml.

2. Log in to OpenShift from a terminal session :

   oc login

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

   oc project <project_name>

   OR

1. Enter the oc new-app command:

   • Specify the --file option with the path to the amp-s3.yml file.
   • Specify the --param options with the following values:
   • WILDCARD_DOMAIN: the parameter set to the domain of your OpenShift cluster.
   • AWS_BUCKET: with your target bucket name.
   • AWS_ACCESS_KEY_ID: with your AWS credentials ID.
   • AWS_SECRET_ACCESS_KEY: with your AWS credentials KEY.
   • AWS_REGION: with the AWS: region of your bucket.
   • AWS_HOSTNAME: Default: Amazon endpoints - AWS S3 compatible provider endpoint hostname.
   • AWS_PROTOCOL: Default: HTTPS - AWS S3 compatible provider endpoint protocol.
   • AWS_PATH_STYLE: Default: false - When set to true, the bucket name is always left in the request URI and never moved to the host as a sub-domain.

   • Optionally, specify the --param option with the TENANT_NAME parameter to set a custom name for the Admin Portal. If omitted, this defaults to 3scale

     oc new-app --file /path/to/amp-s3.yml \
     	--param WILDCARD_DOMAIN=<a-domain-that-resolves-to-your-ocp-cluster.com> \
     	--param TENANT_NAME=3scale \
     	--param AWS_ACCESS_KEY_ID=<your-aws-access-key-id> \
     	--param AWS_SECRET_ACCESS_KEY=<your-aws-access-key-secret> \
     	--param AWS_BUCKET=<your-target-bucket-name> \
     	--param AWS_REGION=<your-aws-bucket-region> \
     	--param FILE_UPLOAD_STORAGE=s3

     The terminal shows the master and tenant URLs, as well as 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

2. 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'
   Access your application via route 'apicast-wildcard.3scale-project.example.com'
   
   ...

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

4. The 3scale deployment on OpenShift has been successful when the following command returns:

   oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)

   Note

   When the 3scale deployment on OpenShift has been successful, your login credentials will work.

Procedure

1. Download amp-postgresql.yml.

2. Log in to OpenShift from a terminal session :

   oc login

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

   oc project <project_name>

   OR

1. Enter the oc new-app command:

   • Specify the --file option with the path to the amp-postgresql.yml file.
   • Specify the --param options with the following values:
   • WILDCARD_DOMAIN: the parameter set to the domain of your OpenShift cluster.

   • Optionally, specify the --param option with the TENANT_NAME parameter to set a custom name for the Admin Portal. If omitted, this defaults to 3scale

     oc new-app --file /path/to/amp-postgresql.yml \
     	--param WILDCARD_DOMAIN=<a-domain-that-resolves-to-your-ocp-cluster.com> \
     	--param TENANT_NAME=3scale \

     The terminal shows the master and tenant URLs, as well as the 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

2. 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'
   Access your application via route 'apicast-wildcard.3scale-project.example.com'
   
   ...

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

4. The 3scale deployment on OpenShift has been successful when the following command returns:

   oc wait --for=condition=available --timeout=-1s $(oc get dc --output=name)

   Note

   When the 3scale deployment on OpenShift has been successful, your login and credentials will work.

Procedure

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

   oc login

   1. Using the oc patch command, specify the secret type where system-smtp is the name of the secret, followed by the -p option, and write the 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 or peer.

      Example

      oc patch secret system-smtp -p '{"stringData":{"address":"<your_address>"}}'
      oc patch secret system-smtp -p '{"stringData":{"username":"<your_username>"}}'
      oc patch secret system-smtp -p '{"stringData":{"password":"<your_password>"}}'

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

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

3. Check the status of the rollout to ensure it has finished:

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

Procedure

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 the create secret and apicast-configuration-url-secret parameters with the access token, tenant name, and wildcard domain of your 3scale deployment:

   oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<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 Configuring nodes and entitlements.

Procedure

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 the create secret and apicast-configuration-url-secret parameters with the access token, tenant name, and wildcard domain of your 3scale deployment:

   oc create secret generic apicast-configuration-url-secret --from-literal=password=https://<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

Procedure

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

Procedure

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

   oc login

2. As administrator, 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.

   • Before 3scale 2.8, you could configure the automatic addition of replicas by setting the highAvailability field to true. From 3scale 2.8, the addition of replicas is controlled through the replicas field in the APIManager CR as shown in the following example.

     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.

   • APIManager CR with minimum requirements:

     apiVersion: apps.3scale.net/v1alpha1
     kind: APIManager
     metadata:
       name: apimanager-sample
     spec:
       wildcardDomain: example.com

   • APIManager CR with replicas configured:

     apiVersion: apps.3scale.net/v1alpha1
     kind: APIManager
     metadata:
       name: apimanager-sample
     spec:
       wildcardDomain: apimanager-sample
       system:
         appSpec:
           replicas: 1
         sidekiqSpec:
           replicas: 1
       zync:
         appSpec:
           replicas: 1
         queSpec:
           replicas: 1
       backend:
         cronSpec:
           replicas: 1
         listenerSpec:
           replicas: 1
         workerSpec:
           replicas: 1
       apicast:
         productionSpec:
           replicas: 1
         stagingSpec:
           replicas: 1
       wildcardDomain: example.com

1. Run the following commands to get the Admin Portal credentials:

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

   1. Log in as the Admin Portal administrator to verify these credentials are working.

2. Run the following commands to get the Master Admin Portal credentials:

   oc get secret system-seed -o json | jq -r .data.MASTER_USER | base64 -d
   oc get secret system-seed -o json | jq -r .data.MASTER_PASSWORD | base64 -d

   1. Log in as the Master Admin Portal administrator to verify these credentials are working.

Procedure

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.

Procedure

1. Type the following command to verify the configuration of your container registry authentication:

   $ oc get secret

   • If your secret exists, you will see the following output in the terminal:

     threescale-registry-auth          kubernetes.io/dockerconfigjson        1         4m9s

   • However, if you do not see the output, you must do the following:
2. Use the credentials you previously set up while Creating a registry service account to create your secret.
3. Use the steps in Configuring registry authentication in OpenShift, replacing <your-registry-service-account-username> and <your-registry-service-account-password> in the oc create secret command provided.

4. Generate the threescale-registry-auth secret in the same namespace as the APIManager resource. You must run the following inside the <project-name>:

   oc project <project-name>
   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>"
     --docker-email="<email-address>"

5. Delete and recreate the APIManager resource:

   $ oc delete -f apimanager.yaml
   apimanager.apps.3scale.net "example-apimanager" deleted
   
   $ oc create -f apimanager.yaml
   apimanager.apps.3scale.net/example-apimanager created

Verification

1. Type the following command to confirm that deployments have a status of Starting or Ready. The pods then begin to spawn:

   $ oc describe apimanager
   (...)
   Status:
     Deployments:
       Ready:
         apicast-staging
         system-memcache
         system-mysql
         system-redis
         zync
         zync-database
         zync-que
       Starting:
         apicast-production
         backend-cron
         backend-worker
         system-sidekiq
         system-sphinx
       Stopped:
         backend-listener
         backend-redis
         system-app

2. Type the following command to see the status of each pod:

   $ oc get pods
   NAME                               READY   STATUS             RESTARTS   AGE
   3scale-operator-66cc6d857b-sxhgm   1/1     Running            0          17h
   apicast-production-1-deploy        1/1     Running            0          17m
   apicast-production-1-pxkqm         0/1     Pending            0          17m
   apicast-staging-1-dbwcw            1/1     Running            0          17m
   apicast-staging-1-deploy           0/1     Completed          0          17m
   backend-cron-1-deploy              1/1     Running            0          17m

Procedure

1. The directories used for the persistent volumes MUST have the write permissions for the root group. Having read-write 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

Procedure

1. Configure the test call for the hosted staging environment.
2. Enter a path existing in your API in the API test GET request field (for example, /v1/word/good.json).

3. Save the settings by clicking on the Update Product button in the bottom right part of the page.

   1. This will deploy the APIcast configuration to the 3scale Hosted staging environment. If everything is configured correctly, the vertical line on the left should turn green.

      Note

      If you are using one of the Self-managed deployment options, save the configuration from the GUI and make sure it is pointing to your deployed API gateway by adding the correct host in the staging or production public base URL field. Before making any calls to your production gateway, do not forget to click on the Promote v.x to Production button.

4. Find the sample curl at the bottom of the staging section and run it from the console:

   curl "https://XXX.staging.apicast.io:443/v1/word/good.json?user_key=YOUR_USER_KEY"

   Note

   You should get the same response as above, however, this time the request will go through the 3scale hosted APIcast instance. Note: You should make sure you have an application with valid credentials for the service. If you are using the default API service created on sign up to 3scale, you should already have an application. Otherwise, if you see USER_KEY or APP_ID and APP_KEY values in the test curl, you need to create an application for this service first.

   Now you have your API integrated with 3scale.

Procedure

1. List all repositories:

   sudo yum repolist all

2. Find and enable the *-extras repository:

   sudo yum-config-manager --enable rhui-REGION-rhel-server-extras

3. Install Docker-formatted container images:

   sudo yum install docker docker-registry

4. Add an insecure registry of 172.30.0.0/16 by adding or uncommenting the following line in /etc/sysconfig/docker file:

   INSECURE_REGISTRY='--insecure-registry 172.30.0.0/16'

5. Start the Docker service:

   sudo systemctl start docker

6. Verify that the container service is running with the following command:

   sudo systemctl status docker

Procedure

1. Download the latest stable release of the client tools (openshift-origin-client-tools-VERSION-linux-64bit.tar.gz) from OpenShift releases page, and place the Linux oc binary extracted from the archive in your PATH.

   Note

   The docker command runs as the root user, so you will need to run any oc or docker commands with root privileges.

2. Open a terminal with a user that has permission to run docker commands and run:

   oc cluster up

   At the bottom of the output you will find information about the deployed cluster:

       -- Server Information ...
         OpenShift server started.
         The server is accessible via web console at:
         https://172.30.0.112:8443
   
         You are logged in as:
           User:     developer
           Password: developer
   
         To login as administrator:
           oc login -u system:admin

3. Note the IP address that is assigned to your OpenShift server. You will refer to it in the tutorial as OPENSHIFT-SERVER-IP.

1. Create the backend-redis and system-redis secrets with the fields below:

   backend-redis

   REDIS_QUEUES_SENTINEL_HOSTS
   REDIS_QUEUES_SENTINEL_ROLE
   REDIS_QUEUES_URL
   REDIS_STORAGE_SENTINEL_HOSTS
   REDIS_STORAGE_SENTINEL_ROLE
   REDIS_STORAGE_URL

   system-redis

   MESSAGE_BUS_NAMESPACE
   MESSAGE_BUS_SENTINEL_HOSTS
   MESSAGE_BUS_SENTINEL_ROLE
   MESSAGE_BUS_URL
   NAMESPACE
   SENTINEL_HOSTS
   SENTINEL_ROLE
   URL

   • When configuring for Redis with sentinels, the corresponding URL fields in backend-redis and system-redis refer to the Redis group in the format redis://[:redis-password@]redis-group[/db]`, where [x] denotes optional element x and redis-password, redis-group, and db are variables to be replaced accordingly:

     Example

     redis://:redispwd@mymaster/5

   • The SENTINEL_HOSTS fields are comma-separated lists of sentinel connection strings in the following format:

     redis://:sentinel-password@sentinel-hostname-or-ip:port

     • For each element of the list, [x] denotes optional element x and sentinel-password, sentinel-hostname-or-ip, and port are variables to be replaced accordingly:

       Example

       :sentinelpwd@123.45.67.009:2711,:sentinelpwd@other-sentinel:2722

   • The SENTINEL_ROLE fields are either master or slave.

2. Deploy 3scale as indicated in Deploying 3scale on OpenShift using a template, using the latest version of the templates.

   1. Ignore the errors due to backend-redis and system-redis already present.

1. Edit the backend-redis and system-redis secrets with all fields as shown in Deploying a fresh installation of 3scale for HA.

2. Make sure the following backend-redis environment variables are defined for the back-end pods.

   name: BACKEND_REDIS_SENTINEL_HOSTS
     valueFrom:
       secretKeyRef:
         key: REDIS_STORAGE_SENTINEL_HOSTS
         name: backend-redis
   name: BACKEND_REDIS_SENTINEL_ROLE
     valueFrom:
       secretKeyRef:
         key: REDIS_STORAGE_SENTINEL_ROLE
         name: backend-redis

3. Make sure the following system-redis environment variables are defined for the system-(app|sidekiq|sphinx) pods.

   name: REDIS_SENTINEL_HOSTS
     valueFrom:
       secretKeyRef:
         key: SENTINEL_HOSTS
         name: system-redis
   name: REDIS_SENTINEL_ROLE
     valueFrom:
       secretKeyRef:
         key: SENTINEL_ROLE
         name: system-redis
   name: MESSAGE_BUS_REDIS_SENTINEL_HOSTS
     valueFrom:
       secretKeyRef:
         key: MESSAGE_BUS_SENTINEL_HOSTS
         name: system-redis
   name: MESSAGE_BUS_REDIS_SENTINEL_ROLE
     valueFrom:
       secretKeyRef:
         key: MESSAGE_BUS_SENTINEL_ROLE
         name: system-redis

4. Proceed with instructions to continue Upgrading 3scale 2.7 to 2.8 using templates.