:scrollbar: :data-uri: :toc2: :linkattrs:

= 3scale_multitenant

:numbered:

== Overview

This workload provisions a single centralized 3scale API Manager in a single OCP namespace.

This workload only needs to be executed once per OCP cluster.

It also allows for management (ie: creation / deletion) of a configurable number of API tenants in the 3scale API Manager installation.

This role might be valuable in the following circumstances:

. Instructor Led Training (ILTs), Hackathons and workshops: + Given X number of students in an ILT requiring 3scale, provision a single central multi-tenant Red Hat 3scale API Manager where each student is assigned their own tenant. + The student is provided with administrative credentials to their assigned tenant. + This approach might be more desirable than the alternative where each student provisions their own 3scale API Manager.

. Red Hat 3scale enablement + A few learning objectives might be:

.. Demonstrate the provisioning of 3scale on OCP. .. Integration with an external smtp provider to send out emails and facilitate a user self-registration workflow. .. Invocation of the REST Admin API of 3scale using OAuth2 access and refresh tokens.

=== Prerequisites

. The version of 3scale provisioned in this lab (v2.4) is known to run on OpenShift Container Platform 4.8. + This version of OpenShift should already be pre-installed before executing this ansible role.

. Using a version of oc utility that corresponds to your target OCP cluster, ensure oc utility is already authenticated as the cluster-admin.

. This ansible role requires installation of the lxml and openshift python modules on target host executing this ansible. ie: +

---

dnf install python3-lxml

dnf install python3-openshift

---

== API Manager

The ansible describe in this section can provision a 3scale API Manager using OpenShift templates.

=== Known Problems

. link:https://issues.redhat.com/browse/THREESCALE-5725[API Manager on FIPS compliant OpenShift] . Target fix: 3scale 2.12

=== Resource requirements

This ansible role allows for provisioning of 3scale of different sizes based on the value of the following ansible variable: is_production

. Resource utilization: is_production = true .. The cluster quota for both CPU and RAM is set fairly high by default: ... CPU limit: 30 cores ... RAM limit: 30 Gi .. The cpu and RAM limits defined in the 3scale API Manager template are also set fairly high. .. These default settings are set intentionally high to allow for high throughput

. Resource utilization: is_production = false + This is the default. The resources needed to provision 3scale drops down to about 12 Gi RAM and 6 CPU

=== SMTP Providers You'll want to have registered with an smtp provider to enable the 3scale API Manager with the ability to send emails.

In 3scale, smtp settings are configured globally and is leveraged by all API tenants.

A few SMTP providers with Free Plans that this ansible role has been tested with are listed below:

. SocketLabs: Currently offering a free plan that allows for link:https://www.socketlabs.com/signup/[2000 emails per month] . SendGrid: Currently offering a free plan that allows for link:https://sendgrid.com/pricing/[100 emails per day]

=== Environment Variables All environment variables are optional.

If no environment variables are specified, then a 3scale API Manager control plane will be provisioned that expects at least one RWX PVC and does not integrate with an SMTP provider.

The API Manager will be provisioned in the following namespace: 3scale-mt-api0 .

. amp_master_passwd + Optional. Default value = master .

. master_access_token + Optional. Default value = wtqhhsly

. default_tenant_access_token + Optional. Default value = 3832cnj371woiduh

. is_production + Optional. Default value = false.

. use_rwo_for_cms + Optional. Default value is false + 3scale control plane consists of a Content Management System (CMS) that typically is scaled out for improved performance in a production environment. This CMS subsequently requires a ReadWriteMany access mode for its corresponding "system-storage" PVC. In a deployment of the API Manager to OCP 4.* where AWS EBS is used for storage, a ReadWriteMany access mode link:https://docs.openshift.com/container-platform/4.2/storage/understanding-persistent-storage.html#pv-access-modes_understanding-persistent-storage[is not available]. In that scenario, set this environment variable to: true. Doing so hacks the 3scale control plane template to specify ReadWriteOnce (and not ReadWriteMany). If you set this to true, then do not attempt to create more than one replica of the system-app pod.

. SMTP Configurations to enable API Manager to send emails + Emails are used extensively to support the various sign-up flows to the 3scale Developer Portal. + Integration between a SMTP Provider and 3scale is done globally for the entire API Manager.

.. smtp_userid + Optional. Default is null. If null, integration between 3scale API Manager and smtp provider will not be configured.

.. smtp_host .. smtp_port .. smtp_authentication .. smtp_passwd .. smtp_domain

. adminEmailUser + Optional. Default value = jdoe

. adminEmailDomain + Optional. Default value = redhat.com

. RESUME_CONTROL_PLANE_GWS + Optional. Default value = true + 3scale API Manager includes a staging and production gateway by default. These two GWs typically are not used for applying API policies to requests because the "data plane" (aka: gateways) tends to be deployed in a different environment. However, the staging gateway is needed by system-provider web application for API Gateway policies details. Subsquently, the default value is: true

. OCP_AMP_ADMIN_ID + Optional. Default = api0 + OCP user that owns OCP namespace where the API Manager resides A cluster quota is assigned to this user. NOTE: this OCP user doesn't necessarily need to exist

=== Execution

. Provision API Manager: +

---

$ $ ansible-playbook playbooks/apimanager.yml

. Notice all API Manager routes in the 3scale-mt-api0 namespace: +

---

$ oc get route -n 3scale-mt-api0

. Optional: Delete API Manager: +

---

$ ansible-playbook playbooks/apimanager.yml -e ACTION=uninstall

== API Tenant With the provisioning of 3scale API Manager, a default tenant is created.

If needed, the ansible described in this section can create additional tenants.

=== Environment Variables All environment variables are optional.

If no environment variables are specified, then a single tenant (called: ocp01 ) will be created in the API Manager with a tenant admin user of: api01 / admin . Corresponding gateways will also be created in a namespace called: ocp01.

. orgName + Optional: Default value = ocp01 + Specifies name of tenant as well as name of namespace where corresponding gateways will be provisioned. + Useful if the intent is to create a single tenant with a specific name.

. tenant_admin_user_name_base + Optional. Default value = api + Base name of API users that will be admins of their API tenants (and admins of thier own API gateways) ie; if desired API user names are: api01, api02, api03 ....... , then the value of this variable should be: "api"

. tenantAdminPasswd + Optional: Default value = admin

. create_gws_with_each_tenant + Optional: Default value = true
+ If true, then an OCP project with API gateways will be created for each corresponding tenant in the same OCP cluster where API Manager resides

. ocp_user_name_base + Optional. Default value = ocp
+ Determines base name of OCP users that will have access to their corresponding API Mgmt related projects. ie; if OCP user names are: user01, user02, user03 ....... , then the value of this variable should be: "user"

. START_TENANT + Optional. Default = 1

. END_TENANT + Optional. Default = 1

. use_padded_tenant_numbers + Optional. Default value = true + If creating sequential generic tenants, specify whether the tenant names should include a padded numer or not ie; ocp01, ocp02 ... ocp10 or ocp1, ocp2 ... ocp10 Default value is true Default value corresponds to the defualt use of padded numbers in: https://github.com/gpe-mw-ansible-org/rh-sso-multi-realm

=== Execution

. Provision: +

---

$ ansible-playbook playbooks/api_tenant.yml

. After the tenant provisioning completes, you will see messages similar to the following at the end of the ansible standard out: +

---

ok: [localhost] => { "msg": [ "tenant_output_dir: /home/jbride/provisioning_output/3295.openshift.opentlc.com/tenants_3scale-mt-api0", "tenant_provisioning_log_file = /home/jbride/provisioning_output/3295.openshift.opentlc.com/tenants_3scale-mt-api0/tenant_provisioning.log", "tenant_provisioning_results_file = /home/jbride/provisioning_output/3295.openshift.opentlc.com/tenants_3scale-mt-api0/tenant_info_file_1_2.txt", "start and end tenants = 1 2", "create API Gateways for each tenant = true" ] }

---

. The tenant_provisioning_results_file contains credential details and URLs of each provisioned tenant. + This is a tab delimited file that can be imported into Google Spreadsheets or LibreOffice Calc.

== API Gateways

If your API Manager and tenants are already provisioned and corresponding apicast gateways are desired specific to that tenant, then this ansible will be useful.

=== Environment Variables

. threescale_tenant_admin_accesstoken + Required + Value of the following variable when the 3scale tenant was created: ADMIN_ACCESS_TOKEN . Alternatively, a new access token can be created from the 3scale tenant admin UI: Gear Icon -> Personal Settings -> Tokens -> Access Tokens -> Add Access Token Alternatively, this can be the "Provider API key" of your 3scale tenant admin.

. threescale_tenant_admin_hostname + Required. + provider admin route URL of target 3scale tenant + ie: t1-admin.apps.cluster-4663.4663.sandbox758.opentlc.com

. gw_namespace + Optional. Default = user1-gw

. threescale_version + Optional. Default = 3scale-2.10.0-GA-jbride + Other tags are listed link:https://github.com/3scale/3scale-amp-openshift-templates/tags[here]

=== Execution:

. Deploy apicast gateways +

---

$ $ ansible-playbook playbooks/api_gw.yml
-e threescale_tenant_admin_accesstoken=$threescale_tenant_admin_accesstoken
-e threescale_tenant_admin_hostname=$threescale_tenant_admin_hostname

---

== Old

=== Ansible Set-up

. Install this role locally +

---

$ ansible-galaxy install gpe_mw_ansible.3scale_multitenant --force -p $HOME/.ansible/roles

. Create Playbook: +

---

$ echo "

• hosts: all become: false gather_facts: False vars_files: roles:
  • gpe_mw_ansible.3scale_multitenant " > /tmp/3scale_multitenant.yml

---

=== Provision 3scale API manager

The OCP namespace for 3scale multi-tenant app will be owned by the following user: {{OCP_AMP_ADMIN_ID}}.

{{OCP_AMP_ADMIN_ID}} will be assigned a clusterquota so as to manage limits and requests assigned to 3scale

. Execute: +

---

API manager provision

$ ansible-playbook playbooks/apimanager.yml \ -e"use_rwo_for_cms=$use_rwo_for_cms"
-e"smtp_port=$smtp_port"
-e"smtp_authentication=$smtp_authentication"
-e"smtp_host=$smtp_host"
-e"smtp_userid=$smtp_userid"
-e"smtp_passwd=$smtp_passwd"

---

. After about 5 minutes, provisioning of the API Manager should complete. . Being that the API Manager is a large application with many different components, the components are broought up in an ordered manner. + Subsequently, the ansible places itself in a wait loop at each stage of the provisioning process.

=== Named tenants

Alternative to the ability to create a sequence of generica tenant, a named tenant can be created on an individual basis.

---

orgName=openbanking-prod

ocpAdminId=ocp01 # name of OCP user that will have access to their corresponding API Mgmt related projects.

tenantAdminId=api01 # name of API user that will be the admin of their API tenants (and admins of thier own API gateways)

create_gws_with_each_tenant=true # if true, then an OCP project with API gateways will be created for each corresponding tenant in the same OCP cluster where API Manager resides

gw_project_name=$orgName-gw

$ ansible-playbook -i localhost, -c local /tmp/3scale_multitenant.yml
-e"ACTION=tenant_mgmt"
-e"API_MANAGER_NS=$API_MANAGER_NS"
-e"adminEmailUser=$adminEmailUser"
-e"adminEmailDomain=$adminEmailDomain"
-e"create_gws_with_each_tenant=$create_gws_with_each_tenant"
-e"orgName=$orgName"
-e"ocpAdminId=$ocpAdminId"
-e"tenantAdminId=$tenantAdminId"
-e"gw_project_name=$gw_project_name"
-e"rht_service_token_user=$rht_service_token_user"
-e"rht_service_token_password=$rht_service_token_password"

---

==== Tenant User credentials

Each tenant is provisioned with a user that has admin privleges to that tenant.

The useId and password are generated using the following ansible variables found in defaults/main.yml:

. Tenant admin userId: {{ tenant_admin_user_name_base }} (ie: api01, api02, api03 ...., api10 ) . Tenant admin password: {{ tenantAdminPasswd }}

=== Stale WILDCARD_DOMAIN State in API Manager There may be scenarios where the DNS of your originally provisioned API Manager changes. Specifically, the value of the WILDCARD_DOMAIN parameter utilized in the original provisioning of your API Manager is no longer valid.

An example of a scenario where this might occur is in Ravello where the original provisioning of the 3scale API Manager would be captured as a Ravello Blueprint. At runtime, a Ravello application is instantiated from this Ravello blueprint and the actual runtime DNS of the Ravello application is applied. This DNS applied to the runtime application will be different than the DNS originally utilized when creating the blueprint.

To correct issues pertaining to this stale state, the following needs to occur :

. Update all routes in the namespace of your API Manager . Update the stale URLs found in the system.accounts table in the system-mysql database of the API Manager. . Change the value of the THREESCALE_SUPERDOMAIN variable in the configmap: system-environment:

Examples of how to change the above are found link:https://gist.github.com/jbride/be32113707418cb43d73c9ef28a09b9d[here]