nmasse-itix.threescale-cicd

Aperçu Versions Perspectives

ansible-cicd

Statut de construction Licence MIT Rôle Galaxy

Permet la livraison continue avec la plateforme de gestion d'API Red Hat 3scale (3scale AMP).

Exigences

Ce rôle nécessite :

  • une instance de la plateforme de gestion d'API 3scale (hébergée ou sur site)
  • une instance de Red Hat SSO si vous prévoyez d'utiliser l'authentification OpenID Connect
  • deux passerelles APIcast (staging et production), soit hébergées, soit auto-gérées
  • un fichier Swagger 2.0 décrivant l'API que vous souhaitez publier

Tous les composants sont gérés via des API, il n'est donc pas nécessaire d'avoir une connexion SSH !

Sur le nœud de contrôle, la bibliothèque jmespath est requise. Si elle n'est pas déjà présente, vous pouvez l'installer avec :

pip install jmespath

Une version récente de Jinja (2.8) est également requise. Vous pouvez mettre à jour votre version de Jinja avec :

pip install -U Jinja2

Si votre nœud de contrôle fonctionne sur RHEL7, vous pouvez exécuter ce playbook pour installer les dépendances manquantes.

Exemple : Déployer une API sur 3scale SaaS avec des passerelles APIcast hébergées

Si vous souhaitez déployer l'API classique "Echo API" sur une instance SaaS 3scale utilisant des clés API, vous pouvez le faire en trois étapes :

  1. Créer un fichier Swagger pour votre Echo API
  2. Construire votre fichier d'inventaire
  3. Écrire le playbook
  4. Exécuter le playbook !

Tout d'abord, assurez-vous que votre fichier swagger (api-swagger.yaml) contient les informations requises :

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: 'Obtenir un écho'
      description: 'Obtenir un écho du serveur'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Un écho du serveur'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

Dans ce fichier Swagger, les champs suivants sont utilisés :

  • x-threescale-system-name est utilisé comme base pour le system_name pour les objets de configuration dans 3scale.
  • title est utilisé comme nom de la définition de service.
  • version est utilisé pour un versionnement correct et suit le schéma semver.
  • host est le nom DNS de l'API backend que vous souhaitez exposer.
  • les champs operationId sont utilisés comme system_name pour les méthodes/métriques.
  • les champs summary et description sont utilisés comme nom et description pour les méthodes/métriques.
  • x-threescale-smoketests-operation est utilisé pour marquer une opération comme utilisable pour les tests de validation. La méthode doit être idempotente, en lecture seule et sans paramètres. Si aucune méthode n'est marquée pour les tests de validation, les tests sont simplement ignorés.
  • les security et securityDefinitions sont utilisés pour déterminer le schéma de sécurité de l'API exposée. Dans cet exemple, nous utilisons le schéma des clés API.

Ensuite, écrivez le fichier inventory :

[all:vars]
ansible_connection=local

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

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

Les éléments importants du fichier d'inventaire sont :

  • le portail d'administration 3scale doit être déclaré dans un groupe nommé threescale.
  • le jeton d'accès 3scale doit être défini dans la variable threescale_cicd_access_token.
  • comme aucune connexion SSH n'est nécessaire (nous n'utilisons que les API Admin de 3scale), ansible_connection=local est défini pour l'ensemble de l'inventaire.

Vous pouvez maintenant écrire le playbook (deploy-api.yaml) :

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

Les parties principales sont :

  • threescale_cicd_openapi_file est le chemin du fichier swagger défini à l'étape 1.
  • le rôle nmasse-itix.threescale-cicd est utilisé.
  • gather_facts: no doit être utilisé car il n'y a pas de connexion SSH aux systèmes cibles.

Enfin, vous pouvez exécuter le playbook :

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

Inventaire

Le portail d'administration 3scale qui sera provisionné est celui qui est référencé dans le playbook incluant ce rôle. Par exemple, dans l'exemple précédent, le portail d'administration 3scale provisionné sera <TENANT>-admin.3scale.net car le playbook principal spécifie hosts: threescale et le groupe threescale contient uniquement un hôte : <TENANT>-admin.3scale.net.

Si vous spécifiez plusieurs hôtes pour le portail d'administration 3scale, tous seront provisionnés avec exactement la même configuration (utile pour des déploiements multi-sites).

Pour vous connecter au portail d'administration 3scale, vous devez fournir un jeton d'accès ayant des privilèges de lecture/écriture sur l'API de gestion des comptes. Vous pouvez fournir ce jeton au niveau de l'hôte, au niveau du groupe ou globalement avec la variable threescale_cicd_access_token.

Au niveau de l'hôte, il est défini comme suit :

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

Au niveau du groupe, vous pouvez le définir comme suit :

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

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

Et vous pouvez également le définir globalement, par exemple comme variable de playbook :

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

L'instance Red Hat SSO (actuellement il ne peut y en avoir qu'une) est définie par la variable threescale_cicd_sso_issuer_endpoint du groupe threescale.

Sa syntaxe est https://<client_id>:<client_secret>@hostname/auth/realms/<realm>. Les client_id et client_secret sont utilisés par Zync pour synchroniser les applications 3scale avec Red Hat SSO.

Exemple :

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

Les instances APIcast sont définies à partir des variables supplémentaires suivantes :

  • threescale_cicd_apicast_sandbox_endpoint
  • threescale_cicd_apicast_production_endpoint

Exemple :

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

Champs de la spécification OpenAPI

Ce rôle prend en charge uniquement les spécifications OpenAPI v2.0 (alias Swagger 2.0).

Les champs étendus suivants des spécifications OpenAPI peuvent être utilisés :

  • x-threescale-system-name, dans la structure info, est utilisé comme base pour construire le system_name pour les objets de configuration dans 3scale.
  • x-threescale-smoketests-operation, dans une définition de méthode, est utilisé pour marquer cette opération comme utilisable pour les tests de validation. La méthode doit être idempotente, en lecture seule et sans paramètres. Si aucune méthode n'est marquée pour les tests de validation, les tests sont simplement ignorés.

Si les champs étendus ne peuvent pas être utilisés (si, par exemple, vous ne souhaitez pas modifier votre contrat API), vous pouvez utiliser les variables supplémentaires correspondantes :

  • threescale_cicd_api_base_system_name
  • threescale_cicd_openapi_smoketest_operation

Voici un exemple d'une spécification OpenAPI utilisant ces champs étendus :

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: 'Obtenir un écho'
      description: 'Obtenir un écho du serveur'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Un écho du serveur'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

Ainsi, echo-api serait utilisé comme base pour construire le system_name de la définition de service 3scale et un GET sur / serait utilisé pour les tests de validation.

Pour obtenir le même effet sans les champs étendus OpenAPI, vous devriez passer les variables supplémentaires suivantes :

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # L'opérationId de la méthode "GET /"

Les champs standards suivants des spécifications OpenAPI sont utilisés.

Dans la section info :

  • title est utilisé comme nom d'affichage de la définition de service 3scale.
  • version est utilisé pour un versionnement correct et suit le schéma semver.
  • host est le nom DNS de l'API backend existante à exposer.

Pour chaque méthode définie :

  • le champ operationId est utilisé comme system_name pour les méthodes/métriques correspondantes.
  • les champs summary et description sont utilisés comme nom et description pour les méthodes/métriques.
  • les security et securityDefinitions sont utilisés pour déterminer le schéma de sécurité de l'API exposée.

Pour avoir une correspondance exacte entre les spécifications OpenAPI et les fonctionnalités 3scale, certaines restrictions sont appliquées sur les structures security et securityDefinitions. Par exemple, il doit y avoir une et exactement une exigence de sécurité dans la structure security. L'exigence de sécurité doit être appliquée globalement (pas sur une base par méthode).

Les définitions de sécurité ont également des restrictions : vous pouvez choisir entre seulement deux schémas de sécurité :

  • OAuth / OpenID Connect
  • Clé API

Le schéma de clé d'application proposé par 3scale n'a pas de définition correspondante dans les spécifications OpenAPI et n'est actuellement pas pris en charge par ce rôle.

Pour être plus concret, pour sécuriser votre API avec une clé API, utilisez cet extrait dans votre fichier de spécification OpenAPI :

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

Vous pouvez bien sûr choisir le nom de l'en-tête HTTP qui sera utilisé pour envoyer la clé API en modifiant le champ name (dans cet exemple : api-key).

Et pour le sécuriser avec OpenID Connect, utilisez cet extrait dans votre fichier de spécification OpenAPI :

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

Vous pouvez bien sûr utiliser le flux OpenID Connect de votre choix :

  • implicit
  • password
  • application
  • accessCode

Variables de rôle

Cette section présente en détail toutes les variables utilisées par ce rôle. En préambule, ce rôle adopte un schéma de convention plutôt que de configuration. Cela signifie que des valeurs par défaut sensées et des schémas de nommage opinés sont fournis directement.

threescale_cicd_openapi_file

Spécifie le fichier de spécification OpenAPI à lire.

  • Syntaxe : Chemin complet vers la spécification OpenAPI, sur le système de fichiers local. Évitez les chemins relatifs, préférez les absolus. Si vous avez besoin de lire un fichier qui est relatif à votre playbook, utilisez le placeholder {{ playbook_dir }}.
  • Requis : oui
  • Exemples : /tmp/openapi.yaml ou {{ playbook_dir }}/git/openapi.json

threescale_cicd_openapi_file_format

Spécifie le format (JSON ou YAML) du fichier de spécification OpenAPI à lire.

  • Syntaxe : JSON ou YAML
  • Requis : non
  • Valeur par défaut : YAML
  • Exemple : YAML

threescale_cicd_api_system_name

Définit le system_name du service 3scale qui sera provisionné.

  • Syntaxe : alphanumérique en minuscules + underscore
  • Requis : non
  • Valeur par défaut : s'il n'est pas défini, le system_name est pris de la variable threescale_cicd_api_base_system_name. Ce system_name de base est ensuite suffixé par le numéro de version majeure de l'API et préfixé par le nom de l'environnement (uniquement si threescale_cicd_api_environment_name est défini).
  • Exemple : dev_mon_service_formidable_1

threescale_cicd_api_base_system_name

Est utilisé comme base pour calculer le threescale_cicd_api_system_name.

  • Syntaxe : alphanumérique en minuscules + underscore
  • Requis : non
  • Valeur par défaut : s'il n'est pas défini, le champ étendu x-threescale-system-name de la spécification OpenAPI ou en dernier recours, le champ title est nettoyé et utilisé. S'il n'y a pas de titre trouvé, la valeur par défaut API est utilisée. Si aucun numéro de version n'est trouvé, 0 est utilisé.
  • Exemple : mon_service_formidable

Remarque : Si threescale_cicd_api_base_system_name et threescale_cicd_api_system_name sont tous deux définis, le second a la priorité.

threescale_cicd_wildcard_domain

Définit automatiquement les URL publiques de l'APIcast selon un schéma.

  • Syntaxe : suffixe de domaine DNS

  • Requis : non

  • Valeur par défaut : s'il est défini, cela calcule le threescale_cicd_apicast_sandbox_endpoint et le threescale_cicd_apicast_production_endpoint à partir du system_name de l'API. L'APIcast sandbox aura la forme <system_name>-staging.<wildcard_domain> et l'APIcast de production aura la forme <system_name>.<wildcard_domain>. Les suffixes pour le staging (-staging) et la production (vide) peuvent être personnalisés avec les variables threescale_cicd_default_staging_suffix et threescale_cicd_default_production_suffix.

  • Exemple : les deux variables suivantes

    threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=mon_service_formidable

    sont équivalentes à :

    threescale_cicd_apicast_sandbox_endpoint=https://mon-service-formidable-staging.acme.corp/
threescale_cicd_apicast_production_endpoint=https://mon-service-formidable.acme.corp/

threescale_cicd_api_basepath

Définit un basePath sur lequel est déployé l'API backend, remplaçant le champ basePath de la spécification OpenAPI. La valeur résultante est utilisée pour définir les règles de mappage de la passerelle API 3scale, ajoutant ce chemin de base aux chemins des différentes méthodes/opérations.

  • Syntaxe : partie URI avec un /
  • Requis : non
  • Valeur par défaut : le champ basePath de la spécification OpenAPI.
  • Exemples : /api ou /context

threescale_cicd_api_backend_hostname

Définit le nom d'hôte backend, remplaçant le champ host de la spécification OpenAPI. La valeur résultante est utilisée pour définir la variable threescale_cicd_private_base_url si elle est manquante.

  • Syntaxe : FQDN avec un port optionnel
  • Requis : non
  • Valeur par défaut : le champ host de la spécification OpenAPI.
  • Exemples : monbackend.acme.corp ou monbackend.acme.corp:8080

threescale_cicd_api_backend_scheme

Définit le schéma à utiliser pour se connecter au backend, remplaçant le champ schemes de la spécification OpenAPI. La valeur résultante est utilisée pour définir la variable threescale_cicd_private_base_url si elle est manquante.

  • Syntaxe : http ou https
  • Requis : non
  • Valeur par défaut : le premier élément du champ scheme de la spécification OpenAPI, par défaut à http s'il est manquant.
  • Exemple : https

threescale_cicd_private_base_url

Définit l'URL de base privée pour 3scale.

  • Syntaxe : <schem>://<host>:<port>
  • Requis : non
  • Valeur par défaut : <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • Exemple : http://monbackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

Permet d'activer la politique CORS sur la passerelle APICast. Si votre API doit supporter les appels cross-origin et basé sur le navigateur et que vous n'avez pas inclus la méthode OPTIONS au bon chemin dans votre fichier de spécification OpenAPI...

  • Syntaxe : booléen yes ou no
  • Requis : non
  • Valeur par défaut : no
  • Exemple : yes si vous souhaitez activer la politique CORS sur APICast

threescale_cicd_openapi_smoketest_operation

Définit la méthode de spécification OpenAPI à utiliser pour les tests de validation.

  • Syntaxe : l'operationId de la méthode de spécification OpenAPI
  • Requis : non
  • Valeur par défaut : aucune. Si cette variable n'est pas définie et qu'aucune opération n'est marquée avec x-threescale-smoketests-operation dans la spécification OpenAPI, les tests de validation seront ignorés.
  • Exemple : GetName

threescale_cicd_api_environment_name

Ajoute un préfixe à tous les services avec un nom d'environnement pour éviter toute collision de noms lors du déploiement de la même API plusieurs fois sur la même instance 3scale.

  • Syntaxe : en minuscules, alphanumérique + underscore
  • Requis : non
  • Valeur par défaut : aucun, aucun préfixe n'est appliqué.
  • Exemples : dev, test ou prod

threescale_cicd_validate_openapi

Valide le fichier de spécification OpenAPI par rapport au schéma officiel. Pour ce faire, l'outil go-swagger est utilisé.

Vous pouvez pré-installer cet outil quelque part dans votre PATH. Alternativement, vous pouvez également pointer le chemin complet vers la commande swagger avec la variable supplémentaire threescale_cicd_goswagger_command.

Si l'outil est manquant, il sera automatiquement téléchargé depuis GitHub et installé dans {{ threescale_cicd_local_bin_path }}.

  • Syntaxe : booléen (yes, no, true, false)
  • Requis : non
  • Valeur par défaut : yes
  • Exemples :
    • threescale_cicd_validate_openapi=no
    • threescale_cicd_goswagger_command=/usr/local/bin/swagger
    • threescale_cicd_local_bin_path=/tmp

threescale_cicd_oicd_flows

Remplace ou met à jour la liste des flux OAuth pris en charge pour cette API.

  • Syntaxe : tableau de chaînes ([ 'application', 'accessCode' ])
  • Requis : non
  • Valeur par défaut : le champ flow de l'objet securityScheme dans votre fichier de spécification OpenAPI.
  • Exemples :
    • threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}" (remplacer la liste des flux)
    • threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}" (ajouter un flux)

threescale_cicd_create_default_application

Permet de créer une application de test avec le plan d'application par défaut, que les tests de validation soient activés ou non.

  • Syntaxe : booléen (yes, no, true, false)
  • Requis : non
  • Valeur par défaut : no
  • Exemple : yes si vous souhaitez qu'une application par défaut soit créée

Variables diverses

Des variables diverses définies dans defaults/main.yml fournissent des valeurs par défaut raisonnables. Jetez-y un œil.

Dépendances

Ce rôle n'a pas de dépendances sur d'autres rôles, mais il a des dépendances sur :

  • Ansible (au moins version 2.4)
  • JMESPath
  • Jinja (au moins version 2.8)
  • 3scale API Management 2.3

Intégration avec d'autres technologies

Le support pour les principales technologies est disponible dans le dossier de support. Il existe un support pour Jenkins, Kubernetes, Docker, OpenShift, y compris une image Docker pré-construite.

Licence

MIT

Informations sur l'auteur

  • Nicolas Massé, Red Hat
  • Laurent Broudoux, Red Hat
  • Daria Mayorova, Red Hat
À propos du projet

Enables Continuous Deployment with 3scale API Management Platform

role 3scale api automation cd ci deploy deployment management redhat threescale
Installer
ansible-galaxy install nmasse-itix.threescale-cicd
GitHub référentiel
16 étoiles
13 forks
23 problèmes ouverts
Licence
mit
Téléchargements
3.4k
Propriétaire
Nicolas Massé
👪 Father, 🎮 Tech Enthusiast, 🛠 Craftsman of Code, 🗣 Wizard of Conferences, 🧩 World Builder, 🌍 Digital Explorer.