Install Red Hat 3scale and configure tenants with 7 simple commands

A couple weeks ago I was faced with the challenge of installing Red Hat 3scale and configuring its tenants using solely the command line — no GUI allowed. This is a rather interesting use case, so I decided to write this article and show how to do it with just seven commands!

(By the way, I also decided to include Red Hat Single Sign-On (SSO) in the mix because I want my APIs to use OpenID Connect (OIDC) for authentication. But I'll leave those commands to a future article.)

Requirements

With the challenge at hand, I knew that if I were to succeed I would have to make good use of the 3scale Master API and some ingenuity. But before jumping into the solution, here are the basic requirements that need to be in place:

• Access via the oc CLI to an OpenShift cluster with rights to create projects (or have at least two projects created for you, one for the management and one for each tenant).
• 3scale OpenShift Templates to install 3scale components (amp.yml and apicast.yml).
• Images and ImageStreams for 3scale.

Disclaimer: I am using Red Hat OpenShift 3.11 with 3scale v2.5. Newer versions of 3scale (2.6+) on OpenShift 4.x introduce the option of using the 3scale Operator for installation, which is quite different from what is described here.

Commands

So, here we go. Let's install 3scale and the tenant!

Note: In the next sections, whenever you see ${A_PLACEHOLDER_NAME}, it means something that needs to be replaced by a value, either self-explanatory or defined in a previous step.

Command #0: Ensure you've got the basics

# the templates
git clone https://github.com/3scale/3scale-amp-openshift-templates
# the access with CLI
oc login ${YOUR_OCP_MASTER_CONSOLE_URL}
# the projects created
oc new-project 3scale-management-project
oc new-project 3scale-tenant-project

Command #1: Install 3scale (management)

The command below is a minimal command to install 3scale. Many other configuration parameters are available, and I highly recommend reading the installation guide. For the purposes of this use case, it is sufficient.

The MASTER_NAME (=3scale-master) parameter is used as a prefix to create the URL of the 3scale Master API. In this case, the final URL should look like 3scale-master.apps.ocp.example.com

oc new-app --file amp.yml \
  -p WILDCARD_DOMAIN=apps.ocp.example.com \
  -p MASTER_NAME=3scale-master \
  -n 3scale-management-project

IMPORTANT: The output of the command above will contain some generated tokens and secrets; take note of them. The remaining commands will use the MASTER_ACCESS_TOKEN but you may need the other values in the future.

Once the installation triggered by the previous command completes, you can start creating the tenant with the next commands.

Command #2: Create the tenant via the Master API

The parameters below will use the variable TENANT_NAME to represent the name of the tenant and other parameters will be derived from it. You should replace/define it with the name you want for the tenant, for example, devblog.

curl -X POST \
  https://3scale-master.apps.ocp.example.com/master/api/providers.xml \
  -d "access_token=${MASTER_ACCESS_TOKEN}" \
  -d "org_name=${TENANT_NAME}-tenant" \
  -d "username=${TENANT_NAME}-tenant-admin" \
  --data-urlencode "email=${TENANT_NAME}@example.com" \
  -d "password=${A_PASSWORD}"

The Master API should return a successful response containing the XML representation of the new tenant configuration. Look for the following data within the payload:

• TENANT_ACCESS_TOKEN from the value of the element /signup/access_token/value
• TENANT_ACCOUNT_ID from the value of the element /signup/account/id
• TENANT_USER_ID from the value of the element /signup/users/user[0]/id

Command #3: Activate the tenant

By default, new tenants are not created active. Run the command below to activate it.

curl -X PUT \
  "https://3scale-master.apps.ocp.example.com/admin/api/accounts/${TENANT_ACCOUNT_ID}/users/${TENANT_USER_ID}/activate.xml" \
  -d "access_token=${MASTER_ACCESS_TOKEN}"

Command #4: Create the tenant's Admin Portal route

This command creates the route to configure the gateway (apicast) so it can communicate to its API Manager.

oc create route edge ${TENANT_NAME}-admin \
  --service=system-provider \
  --hostname=${TENANT_NAME}-tenant-admin.apps.ocp.example.com \
  --insecure-policy=Allow \
  -n 3scale-management-project

You can access the tenant's Admin Portal through this new URL with the credentials (username/password) provided in Command #2.

Command #5: Create the secret with the AMP management URL

oc secret new-basicauth apicast-configuration-url-secret \
  --password=https://${TENANT_ACCESS_TOKEN}@${TENANT_NAME}-tenant-admin.apps.ocp.example.com \
  -n 3scale-tenant-project

Command #6: Install the tenant's API gateway (apicast)

The command below installs only the apicast gateway pods. As this tenant won't handle production workloads, it uses the minimal configuration parameters recommended for non-production deployments.

oc new-app -f apicast.yml \
  -p CONFIGURATION_LOADER=lazy \
  -p DEPLOYMENT_ENVIRONMENT=staging \
  -p CONFIGURATION_CACHE=0 \
  -n 3scale-tenant-project

Command #7: Expose your tenant's API gateway

Now you just need to create the route (URL) to expose your apicast service (the gateway) to its clients.

oc create route edge \
  --service=apicast \
  --hostname=${TENANT_NAME}-tenant.apps.ocp.example.com \
  --insecure-policy=Allow \
  -n 3scale-tenant-project

The APIs you create for this tenant will be exposed through this new URL.

To create more tenants, just repeat commands #2 to #7.

Conclusion

As we move toward automating all the things, it is important to challenge ourselves not to use GUIs and instead do things the harder but more repeatable way. Getting the set of commands is just the first step for automation. Next, we can compile them in the form of a script, or even better, an Ansible playbook. The automation that such capability provides means not only that new tenants can be easily created, but also that the whole environment can be rebuilt from code.

Although these commands show a simple configuration of 3scale, the gist was extracted from a real-life consulting engagement when each tenant represents one of the multiple environments of a software delivery lifecycle — like development, testing, integration, pre-production, and production. Ultimately, this is part of a bigger picture where our customers need to have the full API lifecycle as code so it can be automated.