nmasse-itix.threescale-cicd

Descripción general Versiones Perspectivas

ansible-cicd

Estado de Construcción Licencia MIT Rol de Galaxy

Permite la Entrega Continua con la Plataforma de Gestión de API de Red Hat 3scale (3scale AMP).

Requisitos

Este rol requiere:

  • una instancia de la Plataforma de Gestión de API de 3scale (alojada o local)
  • una instancia de Red Hat SSO si planeas usar autenticación OpenID Connect
  • dos puertas de enlace de APIcast (una de pruebas y otra de producción), ya sea alojadas o autogestionadas
  • un archivo Swagger 2.0 que describa la API que deseas publicar

¡Todos los componentes se manejan a través de APIs, por lo que no se requiere conexión SSH!

En el nodo de control, se requiere la biblioteca jmespath. Si no está ya instalada, puedes instalarla con:

pip install jmespath

También se requiere una versión reciente de Jinja (2.8). Puedes actualizar tu versión de Jinja con:

pip install -U Jinja2

Si tu nodo de control funciona en RHEL7, puedes ejecutar este playbook para instalar las dependencias faltantes.

Ejemplo: Desplegar una API en 3scale SaaS con puertas de enlace APIcast alojadas

Si deseas desplegar la clásica "API de Echo" en una instancia SaaS de 3scale usando Claves de API, puedes hacerlo en tres pasos:

  1. Crear un archivo Swagger para tu API de Echo
  2. Construir tu archivo de inventario
  3. Escribir el playbook
  4. ¡Ejecutar el playbook!

Primero, asegúrate de que tu archivo swagger (api-swagger.yaml) tenga la información requerida:

swagger: '2.0'
info:
  x-threescale-system-name: 'echo-api'
  title: 'Echo API'
  version: '1.0'
host: 'echo-api.3scale.net'
paths:
  /:
    get:
      operationId: Echo
      summary: 'Obtener un eco'
      description: 'Obtener un eco del servidor'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Un eco del servidor'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

En este archivo Swagger, se utilizan los siguientes campos:

  • x-threescale-system-name se usa como base para el system_name de los objetos de configuración en 3scale.
  • title se usa como el nombre de la definición del servicio.
  • version se usa para el versionado adecuado y sigue el esquema semver.
  • host es el nombre DNS del backend de API existente a exponer.
  • los campos operationId se utilizan como el system_name para los métodos/métricas.
  • los campos summary y description se utilizan como nombre y descripción para los métodos/métricas.
  • x-threescale-smoketests-operation se utiliza para marcar una operación como usable para pruebas rápidas. El método debe ser idempotente, de solo lectura y sin parámetros. Si ningún método está marcado para pruebas rápidas, las pruebas se omiten.
  • security y securityDefinitions se utilizan para determinar el esquema de seguridad de la API expuesta. En este ejemplo, estamos utilizando el esquema de Claves de API.

Luego, escribe el archivo inventory:

[all:vars]
ansible_connection=local

[threescale]
<TENANT>-admin.3scale.net

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

Los aspectos importantes del archivo de inventario son:

  • el portal de administración de 3scale debe declararse en un grupo llamado threescale.
  • el token de acceso de 3scale debe establecerse en la variable threescale_cicd_access_token.
  • dado que no se necesita conexión SSH (solo usamos las APIs de administración de 3scale), se establece ansible_connection=local para todo el inventario.

Ahora puedes escribir el playbook (deploy-api.yaml):

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_openapi_file: 'api-swagger.yaml'
  roles:
  - nmasse-itix.threescale-cicd

Las partes principales son:

  • threescale_cicd_openapi_file es la ruta al archivo swagger definido en el paso 1.
  • se utiliza el rol nmasse-itix.threescale-cicd.
  • gather_facts: no debe usarse ya que no hay conexión SSH a los sistemas de destino.

Finalmente, puedes ejecutar el playbook:

ansible-galaxy install nmasse-itix.threescale-cicd
ansible-playbook -i inventory deploy-api.yaml

Inventario

El Portal de Administración de 3scale que se provisionará es el que se menciona en el playbook que incluye este rol. Por ejemplo, en el ejemplo anterior, el Portal de Administración de 3scale provisionado será <TENANT>-admin.3scale.net porque el playbook principal especifica hosts: threescale y el grupo threescale contiene solo un host: <TENANT>-admin.3scale.net.

Si especificas múltiples hosts para el Portal de Administración de 3scale, todos se provisionarán con la misma configuración (útil para implementaciones en múltiples sitios).

Para conectarte al Portal de Administración de 3scale, deberás proporcionar un Token de Acceso que tenga privilegios de lectura/escritura en la API de Gestión de Cuentas. Puedes proporcionar este token a nivel de host, a nivel de grupo o de manera global con la variable threescale_cicd_access_token.

A nivel de host, se define así:

[threescale]
tenant1-admin.3scale.net threescale_cicd_access_token=123...456
tenant2-admin.3scale.net threescale_cicd_access_token=789...012

A nivel de grupo, puedes definirlo así:

[threescale:vars]
threescale_cicd_access_token=123...456

[threescale]
tenant1-admin.3scale.net
tenant2-admin.3scale.net

Y también puedes definirlo globalmente, por ejemplo como variables de playbook:

- hosts: threescale
  vars:
    threescale_cicd_access_token: 123...456

La instancia de Red Hat SSO (actualmente solo puede haber una), se define por la variable threescale_cicd_sso_issuer_endpoint del grupo threescale.

Su sintaxis es https://<client_id>:<client_secret>@hostname/auth/realms/<realm>. El client_id/client_secret son usados por Zync para sincronizar las aplicaciones de 3scale con Red Hat SSO.

Ejemplo:

threescale_cicd_sso_issuer_endpoint=https://3scale:123@sso.acme.corp/auth/realms/acme

Las instancias de APIcast se definen con las siguientes variables adicionales:

  • threescale_cicd_apicast_sandbox_endpoint
  • threescale_cicd_apicast_production_endpoint

Ejemplo:

threescale_cicd_apicast_sandbox_endpoint=http://api-test.acme.corp
threescale_cicd_apicast_production_endpoint=https://api.acme.corp

Campos de la Especificación OpenAPI

Este rol actualmente solo soporta Especificaciones OpenAPI versión 2.0 (también conocida como Swagger 2.0).

Se pueden utilizar los siguientes campos extendidos de las Especificaciones OpenAPI:

  • x-threescale-system-name, en la estructura info, se usa como base para construir el system_name de los objetos de configuración en 3scale.
  • x-threescale-smoketests-operation en una definición de método se usa para marcar esta operación como utilizable para pruebas rápidas. El método debe ser idempotente, de solo lectura y sin parámetros. Si ningún método está marcado como pruebas rápidas, las pruebas se omiten.

Si los campos extendidos no pueden ser utilizados (si, por ejemplo, no deseas alterar tu Contrato API), puedes usar la correspondiente variable adicional:

  • threescale_cicd_api_base_system_name
  • threescale_cicd_openapi_smoketest_operation

Aquí hay un ejemplo de una Especificación OpenAPI usando esos campos extendidos:

swagger: '2.0'
info:
  x-threescale-system-name: 'echo-api'
  title: 'Echo API'
  version: '1.0'
host: 'echo-api.3scale.net'
paths:
  /:
    get:
      operationId: Echo
      summary: 'Obtener un eco'
      description: 'Obtener un eco del servidor'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Un eco del servidor'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

En resumen, echo-api se utilizaría como base para construir el system_name de la definición del servicio en 3scale y un GET en / se utilizaría como pruebas rápidas.

Para lograr el mismo efecto sin los campos extendidos de OpenAPI, tendrías que pasar las siguientes variables adicionales:

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # El operationId del método "GET /"

Los siguientes campos estándar de las Especificaciones OpenAPI son utilizados.

En la sección info:

  • title se utiliza como el nombre para mostrar de la definición del servicio de 3scale.
  • version se utiliza para el versionado adecuado y sigue el esquema semver.
  • host es el nombre DNS del backend de API existente a exponer.

Para cada método definido:

  • el campo operationId se usa como el system_name para los correspondientes métodos/métricas.
  • los campos summary y description se usan como nombre y descripción para los métodos/métricas.
  • security y securityDefinitions se utilizan para determinar el esquema de seguridad de la API expuesta.

Para tener un mapeo uno a uno entre las Especificaciones OpenAPI y las características de 3scale, se aplican algunas restricciones a las estructuras security/securityDefinitions. En concreto, debe haber exactamente un requisito de seguridad en la estructura de security. El requisito de seguridad debe aplicarse globalmente (no de manera individual por método).

Las definiciones de seguridad también tienen restricciones: puedes elegir entre solo dos esquemas de seguridad:

  • OAuth / OpenID Connect
  • Clave de API

El esquema de Par de Clave de Aplicación propuesto por 3scale no tiene una definición correspondiente en las Especificaciones OpenAPI y actualmente no es soportado por este rol.

Así que, para ser más concreto, para asegurar tu API con Clave de API, utiliza este fragmento en tu archivo de Especificación OpenAPI:

securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey
security:
- apikey: []

Por supuesto, puedes elegir el nombre del encabezado HTTP que se usará para enviar la Clave de API cambiando el campo name (en este ejemplo: api-key).

Y para asegurarla con OpenID Connect, usa este fragmento en tu archivo de Especificación OpenAPI:

securityDefinitions:
  oidc:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://dummy/placeholder
    tokenUrl: http://dummy/placeholder
    scopes:
      openid: Obtener un token de OpenID Connect
security:
- oidc:
  - openid

Por supuesto, puedes usar el flujo de OpenID Connect de tu elección:

  • implicit
  • password
  • application
  • accessCode

Variables del Rol

Esta sección presenta extensamente todas las variables utilizadas por este rol. Como introducción, este rol adopta un esquema de convención sobre configuración. Esto significa que se proporcionan valores predeterminados sensatos y esquemas de nombres opinados de manera inmediata.

threescale_cicd_openapi_file

Especifica el archivo de Especificación OpenAPI a leer.

  • Sintaxis: Ruta completa al archivo de Especificación OpenAPI, en el sistema de archivos local. Evitar rutas relativas, preferir absolutas. Si necesitas leer un archivo que es relativo a tu playbook, usa el marcador de posición {{ playbook_dir }}.
  • Requerido: sí
  • Ejemplos: /tmp/openapi.yaml o {{ playbook_dir }}/git/openapi.json

threescale_cicd_openapi_file_format

Especifica el formato (JSON o YAML) del archivo de Especificación OpenAPI a leer.

  • Sintaxis: JSON o YAML
  • Requerido: no
  • Valor predeterminado: YAML
  • Ejemplo: YAML

threescale_cicd_api_system_name

Define el system_name del Servicio de 3scale que será provisionado.

  • Sintaxis: caracteres alfanuméricos en minúsculas + guion bajo
  • Requerido: no
  • Valor predeterminado: si no se define, el system_name se toma de la variable threescale_cicd_api_base_system_name. Este base system_name se completa con el número de versión mayor de la API y se precede del nombre del entorno (solo si se define threescale_cicd_api_environment_name).
  • Ejemplo: dev_mi_servicio_maravilloso_1

threescale_cicd_api_base_system_name

Se usa como base para computar el threescale_cicd_api_system_name.

  • Sintaxis: caracteres alfanuméricos en minúsculas + guion bajo
  • Requerido: no
  • Valor predeterminado: si no se define, el campo extendido x-threescale-system-name de la Especificación OpenAPI o, como último recurso, el campo title se sanitiza y se utiliza. Si no se puede encontrar título, se utiliza el valor por defecto API. Si no se puede encontrar número de versión, se usa 0.
  • Ejemplo: mi_servicio_maravilloso

Nota: Si tanto threescale_cicd_api_base_system_name como threescale_cicd_api_system_name están establecidos, el último tiene prioridad.

threescale_cicd_wildcard_domain

Define automáticamente las URL públicas de APIcast según un esquema.

  • Sintaxis: sufijo de dominio DNS

  • Requerido: no

  • Valor predeterminado: si está definido, computa el threescale_cicd_apicast_sandbox_endpoint y threescale_cicd_apicast_production_endpoint a partir del system_name de la API. El APIcast sandbox será <system_name>-staging.<wildcard_domain> y el APIcast de producción será <system_name>.<wildcard_domain>. Los sufijos para staging (-staging) y producción (vacío) pueden personalizarse con las variables threescale_cicd_default_staging_suffix y threescale_cicd_default_production_suffix.

  • Ejemplo: las siguientes dos variables

    threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=mi_servicio_maravilloso

    son equivalentes a:

    threescale_cicd_apicast_sandbox_endpoint=https://mi-servicio-maravilloso-staging.acme.corp/
threescale_cicd_apicast_production_endpoint=https://mi-servicio-maravilloso.acme.corp/

threescale_cicd_api_basepath

Define una basePath en la que se despliega la API backend, sobrescribiendo el campo basePath de la Especificación OpenAPI. El valor resultante se usa para definir las reglas de mapeo de la Puerta de Enlace API de 3scale, anteponiendo esta base a los caminos de diferentes métodos/operaciones.

  • Sintaxis: parte de URI comenzando con /
  • Requerido: no
  • Valor predeterminado: el campo basePath de la Especificación OpenAPI.
  • Ejemplos: /api o /contexto

threescale_cicd_api_backend_hostname

Define el nombre del host del backend, sobrescribiendo el campo host de la Especificación OpenAPI. El valor resultante se usa para definir la variable threescale_cicd_private_base_url si falta.

  • Sintaxis: FQDN con un puerto opcional
  • Requerido: no
  • Valor predeterminado: el campo host de la Especificación OpenAPI.
  • Ejemplos: mibackend.acme.corp o mibackend.acme.corp:8080

threescale_cicd_api_backend_scheme

Define el esquema para conectar al backend, sobrescribiendo el campo schemes de la Especificación OpenAPI. El valor resultante se usa para definir la variable threescale_cicd_private_base_url si falta.

  • Sintaxis: http o https
  • Requerido: no
  • Valor predeterminado: el primer elemento del campo scheme de la Especificación OpenAPI, por defecto http si falta.
  • Ejemplo: https

threescale_cicd_private_base_url

Define la URL Base Privada de 3scale.

  • Sintaxis: <esquema>://<host>:<puerto>
  • Requerido: no
  • Valor predeterminado: <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • Ejemplo: http://mibackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

Permite activar la política de CORS en la puerta de enlace APICast. En caso de que tu API deba soportar invocaciones de origen cruzado y basadas en navegador y no hayas incluido el verbo OPTIONS en el camino correcto dentro de tu archivo de Especificación OpenAPI...

  • Sintaxis: booleano sí o no
  • Requerido: no
  • Valor predeterminado: no
  • Ejemplo: sí si deseas activar la política de CORS en APICast

threescale_cicd_openapi_smoketest_operation

Define el método de la Especificación OpenAPI que se utilizará para las pruebas rápidas.

  • Sintaxis: el operationId del método de la Especificación OpenAPI
  • Requerido: no
  • Valor predeterminado: ninguno. Si esta variable no está definida y si no hay ninguna operación marcada con x-threescale-smoketests-operation en la Especificación OpenAPI, las pruebas rápidas se omiten.
  • Ejemplo: GetName

threescale_cicd_api_environment_name

Agrega un prefijo a todos los servicios con un nombre de entorno para evitar colisiones de nombre cuando se despliega la misma API múltiples veces en la misma instancia de 3scale.

  • Sintaxis: minúsculas, alfanumérico + guion bajo
  • Requerido: no
  • Valor predeterminado: ninguno, no se realiza prefijado.
  • Ejemplos: dev, prueba o prod

threescale_cicd_validate_openapi

Valida el archivo de Especificación OpenAPI contra el esquema oficial. Para ello, se utiliza la herramienta go-swagger.

Puedes preinstalar esta herramienta en algún lugar dentro de tu PATH. Alternativamente, también puedes señalar la ruta completa al comando swagger con la variable adicional threescale_cicd_goswagger_command.

Si falta la herramienta, se descargará automáticamente de GitHub y se instalará en {{ threescale_cicd_local_bin_path }}.

  • Sintaxis: booleano (sí, no, verdadero, falso)
  • Requerido: no
  • Valor predeterminado: sí
  • Ejemplos:
    • threescale_cicd_validate_openapi=no
    • threescale_cicd_goswagger_command=/usr/local/bin/swagger
    • threescale_cicd_local_bin_path=/tmp

threescale_cicd_oicd_flows

Sobrescribe o actualiza la lista de flujos OAuth soportados para esta API.

  • Sintaxis: array de cadenas ([ 'application', 'accessCode' ])
  • Requerido: no
  • Valor predeterminado: el campo flow del objeto securityScheme en tu archivo de Especificación OpenAPI.
  • Ejemplos:
    • threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}" (sobrescribe la lista de flujos)
    • threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}" (agrega un flujo)

threescale_cicd_create_default_application

Permite crear una aplicación de prueba con el plan de aplicación predeterminado, ya sea que se activen o no las pruebas rápidas.

  • Sintaxis: booleano (sí, no, verdadero, falso)
  • Requerido: no
  • Valor predeterminado: no
  • Ejemplo: sí si deseas que se cree una aplicación predeterminada

Variables Misceláneas

Las variables misceláneas definidas en defaults/main.yml brindan valores predeterminados sensatos. Échales un vistazo.

Dependencias

Este rol no tiene dependencias con otros roles, pero tiene dependencias en:

  • Ansible (versión 2.4 o superior)
  • JMESPath
  • Jinja (versión 2.8 o superior)
  • Gestión de API de 3scale 2.3

Integración con otras tecnologías

Soporte para las principales tecnologías está disponible en la carpeta de soporte. Hay soporte para Jenkins, Kubernetes, Docker, OpenShift, incluyendo una imagen docker preconstruida.

Licencia

MIT

Información del Autor

  • Nicolas Massé, Red Hat
  • Laurent Broudoux, Red Hat
  • Daria Mayorova, Red Hat
Acerca del proyecto

Enables Continuous Deployment with 3scale API Management Platform

role 3scale api automation cd ci deploy deployment management redhat threescale
Instalar
ansible-galaxy install nmasse-itix.threescale-cicd
GitHub repositorio
16 estrellas
13 bifurcaciones
23 problemas abiertos
Licencia
mit
Descargas
3.4k
Propietario
Nicolas Massé
👪 Father, 🎮 Tech Enthusiast, 🛠 Craftsman of Code, 🗣 Wizard of Conferences, 🧩 World Builder, 🌍 Digital Explorer.