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

= 3scale_multitenant

:numbered:

== Descripción General

Esta carga de trabajo provisiona un único gestor de API 3scale centralizado en un solo espacio de nombres de OCP.

Esta carga de trabajo solo necesita ejecutarse una vez por clúster de OCP.

También permite la gestión (es decir, creación/eliminación) de un número configurable de "inquilinos" API en la instalación del gestor de API 3scale.

Este rol puede ser valioso en las siguientes circunstancias:

. Capacitación guiada (ILTs), Hackathons y talleres: + Dado un número X de estudiantes en un ILT que requieren 3scale, provisionar un único gestor de API Red Hat 3scale centralizado donde cada estudiante tenga su propio inquilino. + Al estudiante se le proporcionan credenciales administrativas para su inquilino asignado. + Este enfoque puede ser más deseable que la alternativa en la que cada estudiante provisiona su propio gestor de API 3scale.

. Habilitación de Red Hat 3scale + Algunos objetivos de aprendizaje pueden ser:

.. Demostrar el aprovisionamiento de 3scale en OCP. .. Integración con un proveedor SMTP externo para enviar correos electrónicos y facilitar un flujo de registro de usuario. .. Invocación de la API REST de administración de 3scale usando tokens de acceso y refresco de OAuth2.

=== Requisitos Previos

. La versión de 3scale provisionada en este laboratorio (v2.4) se sabe que funciona en OpenShift Container Platform 4.8. + Esta versión de OpenShift debería estar preinstalada antes de ejecutar este rol de Ansible.

. Usando una versión de la utilidad oc que corresponde a tu clúster OCP objetivo, asegúrate de que la utilidad oc ya esté autenticada como el administrador del clúster.

. Este rol de Ansible requiere la instalación de los módulos Python lxml y openshift en el host de destino que ejecuta este Ansible. es decir: +

---

dnf install python3-lxml

dnf install python3-openshift

---

== Gestor de API

El Ansible descrito en esta sección puede aprovisionar un gestor de API 3scale usando templates de OpenShift.

=== Problemas Conocidos

. link:https://issues.redhat.com/browse/THREESCALE-5725[Gestor de API en OpenShift compatible con FIPS]. Solución objetivo: 3scale 2.12

=== Requisitos de Recursos

Este rol de Ansible permite el aprovisionamiento de 3scale de diferentes tamaños según el valor de la variable de Ansible: is_production

. Utilización de recursos: is_production = true .. La cuota del clúster para CPU y RAM se establece bastante alta por defecto: ... Límite de CPU: 30 núcleos ... Límite de RAM: 30 Gi .. Los límites de CPU y RAM definidos en el template del gestor de API 3scale también están establecidos bastante altos. .. Estas configuraciones predeterminadas se establecen intencionalmente altas para permitir un alto rendimiento.

. Utilización de recursos: is_production = false + Este es el valor predeterminado. Los recursos necesarios para aprovisionar 3scale se reducen a aproximadamente 12 Gi de RAM y 6 CPU.

=== Proveedores SMTP Querrás tener registrado un proveedor SMTP para habilitar al gestor de API 3scale con la capacidad de enviar correos electrónicos.

En 3scale, la configuración SMTP se configura globalmente y es utilizada por todos los inquilinos API.

A continuación se enumeran algunos proveedores SMTP con Planes Gratuitos con los que se ha probado este rol de Ansible:

. SocketLabs: Ofrece actualmente un plan gratuito que permite link:https://www.socketlabs.com/signup/[2000 correos por mes]. . SendGrid: Ofrece actualmente un plan gratuito que permite link:https://sendgrid.com/pricing/[100 correos por día].

=== Variables de Entorno Todas las variables de entorno son opcionales.

Si no se especifican variables de entorno, se aprovisionará un plano de control del gestor de API 3scale que espera al menos un PVC RWX y no se integra con un proveedor SMTP.

El gestor de API se aprovisionará en el siguiente espacio de nombres: 3scale-mt-api0.

. amp_master_passwd + Opcional. Valor predeterminado = master.

. master_access_token + Opcional. Valor predeterminado = wtqhhsly.

. default_tenant_access_token + Opcional. Valor predeterminado = 3832cnj371woiduh.

. is_production + Opcional. Valor predeterminado = false.

. use_rwo_for_cms + Opcional. Valor predeterminado = false. + El plano de control de 3scale consiste en un Sistema de Gestión de Contenidos (CMS) que normalmente se escala para mejorar el rendimiento en un entorno de producción. Este CMS requiere posteriormente un modo de acceso ReadWriteMany para su correspondiente PVC "system-storage". En un despliegue del gestor de API en OCP 4.* donde se utiliza AWS EBS para almacenamiento, un modo de acceso ReadWriteMany link:https://docs.openshift.com/container-platform/4.2/storage/understanding-persistent-storage.html#pv-access-modes_understanding-persistent-storage[no está disponible]. En ese escenario, establece esta variable de entorno en: true. Hacer esto modifica el template del plano de control de 3scale para especificar ReadWriteOnce (y no ReadWriteMany). Si configuras esto como verdadero, no intentes crear más de una réplica del pod system-app.

. Configuraciones SMTP para habilitar al gestor de API para enviar correos electrónicos. + Los correos electrónicos se utilizan extensamente para apoyar los varios flujos de registro en el Portal del Desarrollador de 3scale. + La integración entre un Proveedor SMTP y 3scale se realiza globalmente para todo el gestor de API.

.. smtp_userid + Opcional. Valor predeterminado es nulo. Si es nulo, la integración entre el gestor de API 3scale y el proveedor SMTP no se configurará.

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

. adminEmailUser + Opcional. Valor predeterminado = jdoe.

. adminEmailDomain + Opcional. Valor predeterminado = redhat.com.

. RESUME_CONTROL_PLANE_GWS + Opcional. Valor predeterminado = true. + El gestor de API 3scale incluye un gateway de staging y de producción por defecto. Estos dos GWs normalmente no se utilizan para aplicar políticas de API a solicitudes porque el "plano de datos" (es decir, los gateways) tiende a desplegarse en un entorno diferente. Sin embargo, el gateway de staging es necesario por la aplicación web del proveedor de sistema para detalles sobre las políticas del API Gateway. Por lo tanto, el valor predeterminado es: true.

. OCP_AMP_ADMIN_ID + Opcional. Valor predeterminado = api0. + Usuario OCP que posee el espacio de nombres OCP donde reside el gestor de API. Se asigna una cuota de clúster a este usuario. NOTA: este usuario OCP no necesita necesariamente existir.

=== Ejecución

. Provisionar Gestor de API: +

---

$ ansible-playbook playbooks/apimanager.yml

. Notar todas las rutas del Gestor de API en el espacio de nombres 3scale-mt-api0: +

---

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

. Opcional: Eliminar el Gestor de API: +

---

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

== Inquilino API Con el aprovisionamiento del gestor de API 3scale, se crea un inquilino predeterminado.

Si es necesario, el Ansible descrito en esta sección puede crear inquilinos adicionales.

=== Variables de Entorno Todas las variables de entorno son opcionales.

Si no se especifican variables de entorno, se creará un solo inquilino (llamado: ocp01) en el gestor de API con un usuario administrador del inquilino de: api01/admin. También se crearán gateways correspondientes en un espacio llamado: ocp01.

. orgName + Opcional: Valor predeterminado = ocp01. + Especifica el nombre del inquilino así como el nombre del espacio donde se provisionarán los gateways correspondientes. + Útil si la intención es crear un solo inquilino con un nombre específico.

. tenant_admin_user_name_base + Opcional. Valor predeterminado = api. + Nombre base de los usuarios API que serán administradores de sus inquilinos API (y administradores de sus propios gateways API). Es decir, si los nombres deseados de los usuarios API son: api01, api02, api03 ......., entonces el valor de esta variable debe ser: "api".

. tenantAdminPasswd + Opcional: Valor predeterminado = admin.

. create_gws_with_each_tenant + Opcional: Valor predeterminado = true.
+ Si es verdadero, entonces se creará un proyecto OCP con gateways API para cada inquilino correspondiente en el mismo clúster OCP donde reside el gestor de API.

. ocp_user_name_base + Opcional. Valor predeterminado = ocp.
+ Determina el nombre base de los usuarios OCP que tendrán acceso a sus proyectos relacionados con la gestión de API correspondientes. Es decir, si los nombres de los usuarios OCP son: user01, user02, user03 ......., el valor de esta variable debe ser: "user".

. START_TENANT + Opcional. Valor predeterminado = 1.

. END_TENANT + Opcional. Valor predeterminado = 1.

. use_padded_tenant_numbers + Opcional. Valor predeterminado = true. + Si se crean inquilinos genéricos secuenciales, especifica si los nombres de los inquilinos deben incluir un número con relleno o no. Es decir, ocp01, ocp02 ... ocp10 o ocp1, ocp2 ... ocp10. El valor predeterminado es verdadero. El valor predeterminado corresponde al uso de números con relleno en: https://github.com/gpe-mw-ansible-org/rh-sso-multi-realm.

=== Ejecución

. Provisionar: +

---

$ ansible-playbook playbooks/api_tenant.yml

. Después de que se complete el aprovisionamiento del inquilino, verás mensajes similares a los siguientes al final de la salida estándar de Ansible: +

---

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" ] }

---

. El tenant_provisioning_results_file contiene detalles de credenciales y URLs de cada inquilino provisionado. + Este es un archivo delimitado por tabulaciones que puede ser importado en Google Spreadsheets o LibreOffice Calc.

== Gateways API

Si tu gestor de API y los inquilinos ya están provisionados y deseas gateways apicast específicos para ese inquilino, entonces este Ansible será útil.

=== Variables de Entorno

. threescale_tenant_admin_accesstoken + Requerido. + Valor de la siguiente variable al crear el inquilino 3scale: ADMIN_ACCESS_TOKEN. Alternativamente, se puede crear un nuevo token de acceso desde la interfaz de usuario de administración del inquilino 3scale: Icono de engranaje -> Configuración personal -> Tokens -> Tokens de acceso -> Agregar token de acceso. Alternativamente, este puede ser la "clave de API del proveedor" de tu administrador de inquilinos 3scale.

. threescale_tenant_admin_hostname + Requerido. + URL de la ruta administrador del proveedor del inquilino 3scale objetivo. + es decir: t1-admin.apps.cluster-4663.4663.sandbox758.opentlc.com.

. gw_namespace + Opcional. Valor predeterminado = user1-gw.

. threescale_version + Opcional. Valor predeterminado = 3scale-2.10.0-GA-jbride. + Otros tags se enumeran link:https://github.com/3scale/3scale-amp-openshift-templates/tags[aquí].

=== Ejecución:

. Desplegar gateways apicast +

---

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

---

== Antiguo

=== Configuración de Ansible

. Instalar este rol localmente +

---

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

. Crear Playbook: +

---

$ echo "

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

---

=== Aprovisionar el gestor de API 3scale

El espacio de nombres de OCP para la aplicación multi-inquilino 3scale será propiedad del siguiente usuario: {{OCP_AMP_ADMIN_ID}}.

{{OCP_AMP_ADMIN_ID}} se asignará una cuota de clúster para gestionar límites y solicitudes asignadas a 3scale.

. Ejecutar: +

---

Aprovisionar el gestor de API

$ 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"

---

. Después de unos 5 minutos, el aprovisionamiento del gestor de API debería completarse. . Dado que el gestor de API es una aplicación grande con muchos componentes diferentes, los componentes se inician de manera ordenada. + Posteriormente, el Ansible se coloca en un ciclo de espera en cada etapa del proceso de aprovisionamiento.

=== Inquilinos Nombrados

Alternativa a la capacidad de crear una secuencia de inquilinos genéricos, se puede crear un inquilino nombrado de manera individual.

---

orgName=openbanking-prod

ocpAdminId=ocp01 # nombre del usuario OCP que tendrá acceso a sus proyectos relacionados con la gestión de API correspondientes

tenantAdminId=api01 # nombre del usuario API que será el administrador de sus inquilinos API (y administradores de sus propios gateways API)

create_gws_with_each_tenant=true # si es verdadero, se creará un proyecto OCP con gateways API para cada inquilino correspondiente en el mismo clúster OCP donde reside el gestor de API

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"

---

==== Credenciales del Usuario del Inquilino

Cada inquilino se aprovisiona con un usuario que tiene privilegios de administrador para ese inquilino.

El useId y la contraseña se generan utilizando las siguientes variables de Ansible que se encuentran en defaults/main.yml:

. Usuario administrador del inquilino: {{ tenant_admin_user_name_base }} (es decir, api01, api02, api03 ...., api10). . Contraseña del administrador del inquilino: {{ tenantAdminPasswd }}.

=== Estado Obsoleto de WILDCARD_DOMAIN en el Gestor de API Puede haber situaciones en las que el DNS de tu gestor de API originalmente provisionado cambie. Específicamente, el valor del parámetro WILDCARD_DOMAIN utilizado en el aprovisionamiento original de tu gestor de API ya no es válido.

Un ejemplo de un escenario donde esto podría ocurrir es en Ravello, donde el aprovisionamiento original del gestor de API 3scale se capturaría como un Blueprint de Ravello. En tiempo de ejecución, se instancia una aplicación de Ravello a partir de este blueprint de Ravello y se aplica el DNS real en tiempo de ejecución de la aplicación de Ravello. Este DNS aplicado a la aplicación en tiempo de ejecución será diferente al DNS utilizado originalmente al crear el blueprint.

Para corregir problemas relacionados con este estado obsoleto, se deben llevar a cabo las siguientes acciones:

. Actualizar todas las rutas en el espacio de nombres de tu gestor de API. . Actualizar las URLs obsoletas encontradas en la tabla system.accounts en la base de datos system-mysql del gestor de API. . Cambiar el valor de la variable THREESCALE_SUPERDOMAIN en el configmap: system-environment:

Ejemplos de cómo cambiar lo anterior se pueden encontrar link:https://gist.github.com/jbride/be32113707418cb43d73c9ef28a09b9d[aquí].