Cloud-native API Administration with Red Hat 3scale API Management
After completing this section, you should be able to install Red Hat 3scale API Management on OpenShift and install the 3scale Toolbox CLI.
Both the installation of the 3scale API Management and the 3scale Toolbox CLI require access to the Red Hat Registry (registry.redhat.io) to pull several container images.
You can use your Red Hat account to get a valid username and token.
The https://access.redhat.com/terms-based-registry/ web page displays your current Red Hat Registry Service Accounts, if you have any.
Red Hat recommends creating a new Registry Service Account for the 3scale installation.
Then, you can use those credentials during the installation process.
Before you install 3scale, you should consider your system requirements, and create a Service Account for the Red Hat Registry.
Depending on your OpenShift installation and your application's workload, your system requirements might vary. Review the recommended parameters in 3scale official documentation.
Most of the container images used by 3scale are stored in the Red Hat Registry. To download images from the Red Hat Registry, your OpenShift cluster must be authenticated.
You can authenticate your OpenShift cluster by creating an OpenShift docker-registry secret.
This secret contains the username and token that is used when pulling images from the Red Hat Registry.
Use the Red Hat Registry Service Account credentials.
[user@host ~]$oc create secret docker-registry \ threescale-registry-auth \ --docker-server=registry.redhat.io \ --docker-username=REDHAT_USERNAME\
--docker-password=REDHAT_TOKEN
| Your Red Hat Registry Service Account username |
| Your Red Hat Registry Service Account token |
Then, link the secret to your OpenShift service account for pulling container images.
You can link it to the default OpenShift service account.
[user@host ~]$ oc secrets link default \
threescale-registry-auth --for=pullLink the secret to the builder OpenShift service account for pushing and pulling build images.
[user@host ~]$ oc secrets link builder threescale-registry-authThe 3scale operator is available in the OperatorHub of OpenShift. The operator facilitates the installation of specific versions of 3scale and future updates.
The 3scale operator provides several custom resources used to deploy some of the product features.
After installing the operator, you must deploy a new APIManager custom resource.
The APIManager custom resource is used to deploy the 3scale API Management product itself.
The following snippet is an APIManager example:
apiVersion: apps.3scale.net/v1alpha1 kind: APIManager metadata: name: apimanager-sample namespace: 3scale
| The namespace where the |
| The domain that is used to generate all the 3scale routes. |
Note
Red Hat recommends to both install the operator and deploy the APIManager custom resource in a custom project.
For example, in the previous snippet, the 3scale project is used.
The wildcardDomain field must be a resolvable domain.
Usually, it is the domain where your OpenShift cluster is running.
For example, if your OpenShift cluster is running in yourdomain.com, then the deployment of the APIManager custom resource generates routes such as 3scale-admin.yourdomain.com.
The most frequent issues that you might face when installing 3scale are:
| Issue | How to identify it | Resolution |
|---|---|---|
| OpenShift cannot pull container images from the Red Hat Registry. | Some pods showing an error similar to ErrImagePull or ImagePullBackOff. | Review the Container registry authentication section of this document. Refer to the 3scale documentation. |
| Not enough memory and/or CPU to deploy 3scale | Some pods cannot get to the Running or Completed status after several minutes | Increase the memory and/or CPU of your OpenShift nodes. |
The 3scale installation provides several graphical interfaces to configure and manage most of the features of the product. If you want to use a command-line utility instead, then 3scale provides the 3cale Toolbox CLI.
You can use the Toolbox by running the official container image provided by 3scale, registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11.
Because the container image is stored in the Red Hat Registry, you must log in with your Red Hat Registry credentials.
[user@host ~]$podman login registry.redhat.ioUsername:redhat_registry_usernamePassword:redhat_registry_token
Then, you can pull the image.
[user@host ~]$ podman pull \
registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11
Trying to pull registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11...
...output omitted...You can use podman run to execute the Toolbox by using the following format:
podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale COMMANDFor example, if you want to execute the help command.
[user@host ~]$ podman run \
registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale help
NAME
3scale - 3scale toolbox
USAGE
3scale <sub-command> [options]
...output omitted...Because executing podman run is too long, you can create a bash alias.
[user@host ~]$ alias 3scale="podman run \
registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale"A single 3scale installation can have more than one tenant, which encapsulates separate configurations.
To use the Toolbox, you must configure one or more remotes. A Toolbox remote holds the credentials to interact with a 3scale tenant. The following is an example of a Toolbox remote.
https://ACCESS_TOKEN@TENANT_ADMIN_PORTAL_URL
The TENANT_ADMIN_PORTAL_URL variable is your tenant's Admin Portal URL.
The default tenant created when you install 3scale is 3scale, therefore, the URL of the default tenant's Admin Portal is 3scale-admin..
The YOUR_DOMAINACCESS_TOKEN variable is used to authenticate the remote against the tenant.
You can create a new access token by using the Admin Portal of the tenant.
Then, you can use the remote add command to add the remote to the Toolbox.
[user@host ~]$ 3scale remote add 3scale-tenant -k \
https://ACCESS_TOKEN@TENANT_ADMIN_PORTAL_URLNote
The -k option, provided in the previous command, allows connections to 3scale without an SSL certificate.
Because the container created by podman run does not hold a proper certificate, you must add the -k option.
Because the podman run command creates a new container on every execution, the remote data is not kept between executions.
You can solve this issue by creating a new container image that contains the remote information.
This way, podman run creates a new container on every execution with an image that holds the remote.
For example, you can use podman run to create a named container that contains the remote information.
[user@host ~]$ podman run --name=toolbox-original \
registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale remote \
add 3scale-tenant -k https://ACCESS_TOKEN@TENANT_ADMIN_PORTAL_URLThen, you can use podman commit to create a new image, toolbox, from the named container.
Because the previous created container holds the remote information, the new image contains it too.
[user@host ~]$ podman commit toolbox-original toolbox
Getting image source signatures
...output omitted...
Writing manifest to image destination
Storing signaturesNow, you can update the 3scale bash alias to use the toolbox image.
[user@host ~]$ alias 3scale="podman run toolbox 3scale -k"Note
To persist this alias across sessions, add it to your user's ~/.bashrc file.
