nmasse-itix.threescale-cicd

Überblick Versionen Einblicke

ansible-cicd

Build Status MIT lizenziert Galaxy Role

Ermöglicht die kontinuierliche Lieferung mit der Red Hat 3scale API Management Plattform (3scale AMP).

Anforderungen

Dieses Rollenspiel erfordert:

  • Eine Instanz der 3scale API Management Plattform (gehostet oder lokal)
  • Eine Instanz von Red Hat SSO, wenn Sie die OpenID Connect-Authentifizierung verwenden möchten
  • Zwei APIcast-Gateways (Staging und Produktion), entweder gehostet oder selbst verwaltet
  • Eine Swagger 2.0-Datei, die die API beschreibt, die Sie veröffentlichen möchten

Alle Komponenten werden über APIs gesteuert, sodass keine SSH-Verbindung erforderlich ist!

Auf dem Steuerungsknoten wird die Bibliothek jmespath benötigt. Wenn sie nicht bereits vorhanden ist, können Sie sie mit folgendem Befehl installieren:

pip install jmespath

Eine aktuelle Version von Jinja (2.8) wird ebenfalls benötigt. Sie können Ihre Jinja-Version mit folgendem Befehl aktualisieren:

pip install -U Jinja2

Wenn Ihr Steuerungsknoten auf RHEL7 läuft, können Sie dieses Playbook ausführen, um die fehlenden Abhängigkeiten zu installieren.

Beispiel: Bereitstellung einer API auf 3scale SaaS mit gehosteten APIcast-Gateways

Wenn Sie die klassische "Echo API" auf einer SaaS 3scale-Instanz unter Verwendung von API-Schlüsseln bereitstellen möchten, können Sie dies in drei Schritten tun:

  1. Erstellen Sie eine Swagger-Datei für Ihre Echo API
  2. Erstellen Sie Ihre Inventardatei
  3. Schreiben Sie das Playbook
  4. Führen Sie das Playbook aus!

Zuerst stellen Sie sicher, dass Ihre Swagger-Datei (api-swagger.yaml) die erforderlichen Informationen enthält:

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: 'Einen Echo abrufen'
      description: 'Einen Echo vom Server abrufen'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Ein Echo vom Server'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

In dieser Swagger-Datei werden folgende Felder verwendet:

  • x-threescale-system-name wird als Basis für den system_name der Konfigurationsobjekte in 3scale verwendet.
  • title wird als Name der Dienstdefinition verwendet.
  • version wird für eine ordnungsgemäße Versionierung verwendet und folgt dem semver-Schema.
  • host ist der DNS-Name des bestehenden API-Backends, das exponiert werden soll.
  • Die operationId-Felder werden als system_name für die Methoden/Metriken verwendet.
  • Die summary- und description-Felder werden als Name und Beschreibung für die Methoden/Metriken verwendet.
  • x-threescale-smoketests-operation wird verwendet, um eine Operation als verwendbar für Smoke-Tests zu kennzeichnen. Die Methode muss idempotent, schreibgeschützt und ohne Parameter sein. Wenn keine Methode als Smoke-Test markiert ist, werden die Smoke-Tests einfach übersprungen.
  • Die security- und securityDefinitions-Felder werden verwendet, um das Sicherheitschema der exponierten API zu bestimmen. In diesem Beispiel verwenden wir das API-Key-Schema.

Dann schreiben Sie die inventory-Datei:

[all:vars]
ansible_connection=local

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

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

Die wichtigen Punkte der Inventardatei sind:

  • Das 3scale-Admin-Portal muss in einer Gruppe mit dem Namen threescale deklariert werden.
  • Das 3scale-Zugriffstoken muss in der Variable threescale_cicd_access_token festgelegt werden.
  • Da keine SSH-Verbindung benötigt wird (wir verwenden nur die 3scale-Admin-APIs), wird ansible_connection=local für das gesamte Inventar festgelegt.

Jetzt können Sie das Playbook (deploy-api.yaml) schreiben:

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

Die Hauptbestandteile sind:

  • threescale_cicd_openapi_file ist der Pfad zur Swagger-Datei, die in Schritt 1 definiert wurde.
  • Die Rolle nmasse-itix.threescale-cicd wird verwendet.
  • gather_facts: no muss verwendet werden, da keine SSH-Verbindung zu den Zielsystemen besteht.

Schließlich können Sie das Playbook ausführen:

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

Inventar

Das 3scale-Admin-Portal, das bereitgestellt wird, ist das, das im Playbook, das diese Rolle enthält, referenziert wird. Zum Beispiel wird im vorherigen Beispiel das bereitgestellte 3scale-Admin-Portal <TENANT>-admin.3scale.net sein, weil das Hauptplaybook hosts: threescale angibt und die Gruppe threescale nur einen Host enthält: <TENANT>-admin.3scale.net.

Wenn Sie mehrere Hosts für das 3scale-Admin-Portal angeben, werden alle mit derselben Konfiguration bereitgestellt (nützlich für Multi-Site-Bereitstellungen).

Um sich mit dem 3scale-Admin-Portal zu verbinden, müssen Sie ein Zugriffstoken mit Lese-/Schreibberechtigungen für die Account Management API angeben. Sie können dieses Token auf Host-, Gruppen- oder globaler Ebene mit der Variable threescale_cicd_access_token bereitstellen.

Auf der Host-Ebene wird es wie folgt definiert:

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

Auf der Gruppenebene können Sie es wie folgt definieren:

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

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

Und Sie können es auch global definieren, zum Beispiel als Playbook-Variablen:

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

Die Red Hat SSO-Instanz (aktuell kann es nur eine geben) wird durch die Variable threescale_cicd_sso_issuer_endpoint der Gruppe threescale definiert.

Die Syntax lautet https://<client_id>:<client_secret>@hostname/auth/realms/<realm>. Die client_id/client_secret werden von Zync verwendet, um die 3scale-Anwendungen mit Red Hat SSO zu synchronisieren.

Beispiel:

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

Die APIcast-Instanzen werden aus den folgenden zusätzlichen Variablen definiert:

  • threescale_cicd_apicast_sandbox_endpoint
  • threescale_cicd_apicast_production_endpoint

Beispiel:

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

OpenAPI-Spezifikationsfelder

Dieses Rollenspiel unterstützt derzeit nur OpenAPI-Spezifikationen v2.0 (auch bekannt als Swagger 2.0).

Die folgenden erweiterten Felder der OpenAPI-Spezifikationen können verwendet werden:

  • x-threescale-system-name, in der Struktur info, wird als Grundlage verwendet, um den system_name für die Konfigurationsobjekte in 3scale zu erstellen.
  • x-threescale-smoketests-operation in einer Methodendefinition wird verwendet, um diese Operation als verwendbar für Smoke-Tests zu kennzeichnen. Die Methode muss idempotent, schreibgeschützt und ohne Parameter sein. Wenn keine Methode als Smoke-Test markiert ist, werden die Smoke-Tests einfach übersprungen.

Wenn die erweiterten Felder nicht verwendet werden können (wenn Sie beispielsweise Ihren API-Vertrag nicht ändern möchten), können Sie die entsprechenden zusätzlichen Variablen verwenden:

  • threescale_cicd_api_base_system_name
  • threescale_cicd_openapi_smoketest_operation

Hier ist ein Beispiel für eine OpenAPI-Spezifikation, die diese erweiterten Felder verwendet:

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: 'Einen Echo abrufen'
      description: 'Einen Echo vom Server abrufen'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Ein Echo vom Server'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

Genauer gesagt, echo-api würde als Grundlage verwendet, um den system_name der 3scale-Dienstdefinition zu erstellen, und ein GET auf / würde als Smoke-Test verwendet werden.

Um denselben Effekt ohne die erweiterten OpenAPI-Felder zu erzielen, müssten Sie die folgenden zusätzlichen Variablen übergeben:

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # Die operationId der "GET /"-Methode

Die folgenden Standardfelder der OpenAPI-Spezifikationen werden verwendet.

Im Abschnitt info:

  • title wird als Anzeigename der 3scale-Dienstdefinition verwendet.
  • version wird für eine ordnungsgemäße Versionierung verwendet und folgt dem semver-Schema.
  • host ist der DNS-Name des bestehenden API-Backends, das exponiert werden soll.

Für jede definierte Methode:

  • Die operationId-Felder werden als system_name für die entsprechenden Methoden/Metriken verwendet.
  • Die summary- und description-Felder werden als Name und Beschreibung für die Methoden/Metriken verwendet.
  • Die security- und securityDefinitions-Felder werden verwendet, um das Sicherheitschema der exponierten API zu bestimmen.

Um eine eins-zu-eins-Zuordnung zwischen den OpenAPI-Spezifikationen und den 3scale-Funktionen zu erreichen, gelten einige Einschränkungen für die Strukturen security/securityDefinitions. Genauer gesagt muss es ein und genau ein Sicherheitsanforderung in der Struktur security geben. Die Sicherheitsanforderung muss global angewendet werden (nicht auf einer pro Methode-Basis).

Die Sicherheitsdefinitionen haben ebenfalls Einschränkungen: Sie können nur zwischen zwei Sicherheitsverfahren wählen:

  • OAuth / OpenID Connect
  • API-Key

Das von 3scale vorgeschlagene App-Key-Paar-Schema hat keine entsprechende Definition in den OpenAPI-Spezifikationen und wird derzeit von dieser Rolle nicht unterstützt.

Um konkreter zu sein, um Ihre API mit API-Schlüssel abzusichern, verwenden Sie diesen Auszug in Ihrer OpenAPI-Spezifikationsdatei:

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

Sie können natürlich den HTTP-Header-Namen wählen, der verwendet wird, um den API-Schlüssel zu senden, indem Sie das Feld name ändern (in diesem Beispiel: api-key).

Und um es mit OpenID Connect abzusichern, verwenden Sie diesen Auszug in Ihrer OpenAPI-Spezifikationsdatei:

securityDefinitions:
  oidc:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://dummy/placeholder
    tokenUrl: http://dummy/placeholder
    scopes:
      openid: Erhalte ein OpenID Connect-Token
security:
- oidc:
  - openid

Sie können natürlich den OpenID Connect-Flow Ihrer Wahl verwenden:

  • implicit
  • password
  • application
  • accessCode

Rollenvariablen

Dieser Abschnitt präsentiert ausführlich alle Variablen, die von dieser Rolle verwendet werden. Vorweg: Diese Rolle verfolgt ein Konzept von "Konvention vor Konfiguration". Dies bedeutet, dass sinnvolle Standardwerte und durchdachte Benennungsschemata out-of-the-box bereitgestellt werden.

threescale_cicd_openapi_file

Gibt die OpenAPI-Spezifikationsdatei an, die gelesen werden soll.

  • Syntax: Vollständiger Pfad zur OpenAPI-Spezifikation auf dem lokalen Dateisystem. Vermeiden Sie relative Pfade, bevorzugen Sie absolute. Wenn Sie eine Datei lesen müssen, die relativ zu Ihrem Playbook ist, verwenden Sie den Platzhalter {{ playbook_dir }}.
  • Erforderlich: ja
  • Beispiele: /tmp/openapi.yaml oder {{ playbook_dir }}/git/openapi.json

threescale_cicd_openapi_file_format

Gibt das Format (JSON oder YAML) der zu lesenden OpenAPI-Spezifikationsdatei an.

  • Syntax: JSON oder YAML
  • Erforderlich: nein
  • Standardwert: YAML
  • Beispiel: YAML

threescale_cicd_api_system_name

Definiert den system_name des 3scale-Dienstes, der bereitgestellt wird.

  • Syntax: Kleinbuchstaben, alphanumerisch + Unterstrich
  • Erforderlich: nein
  • Standardwert: Wenn nicht definiert, wird der system_name aus der Variable threescale_cicd_api_base_system_name übernommen. Dieser Basis-system_name wird dann mit der Hauptversionsnummer der API suffixiert und, falls threescale_cicd_api_environment_name definiert ist, mit dem Umgebungsnamen präfixiert.
  • Beispiel: dev_my_wonderful_service_1

threescale_cicd_api_base_system_name

Wird als Grundlage verwendet, um den threescale_cicd_api_system_name zu berechnen.

  • Syntax: Kleinbuchstaben, alphanumerisch + Unterstrich
  • Erforderlich: nein
  • Standardwert: Wenn nicht definiert, wird das erweiterte Feld x-threescale-system-name der OpenAPI-Spezifikation oder als letzter Ausweg das title-Feld gesäubert und dann verwendet. Wenn kein Titel gefunden werden kann, wird der Standardwert API verwendet. Wenn keine Versionsnummer gefunden werden kann, wird 0 verwendet.
  • Beispiel: my_wonderful_service

Hinweis: Wenn sowohl threescale_cicd_api_base_system_name als auch threescale_cicd_api_system_name festgelegt sind, hat letzteres Vorrang.

threescale_cicd_wildcard_domain

Definiert automatisch die öffentlichen APIcast-URLs basierend auf einem Schema.

  • Syntax: DNS-Domain-Suffix

  • Erforderlich: nein

  • Standardwert: Wenn definiert, berechnet es die threescale_cicd_apicast_sandbox_endpoint und threescale_cicd_apicast_production_endpoint aus dem API-system_name. Der Sandbox-APIcast wird <system_name>-staging.<wildcard_domain> sein und der Produktions-APIcast wird <system_name>.<wildcard_domain> sein. Die Endung für die Staging (-staging) und die Produktion (leer) kann mit den Variablen threescale_cicd_default_staging_suffix und threescale_cicd_default_production_suffix angepasst werden.

  • Beispiel: Die folgenden zwei Variablen

    threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=my_wonderful_service

    entsprechen:

    threescale_cicd_apicast_sandbox_endpoint=https://my-wonderful-service-staging.acme.corp/
threescale_cicd_apicast_production_endpoint=https://my-wonderful-service.acme.corp/

threescale_cicd_api_basepath

Definiert einen basePath, auf dem die Backend-API bereitgestellt wird, wobei das basePath-Feld der OpenAPI-Spezifikation überschrieben wird. Der resultierende Wert wird verwendet, um die Zuordnungsregeln des 3scale API-Gateways zu definieren, indem dieser Basis-Pfad den Pfaden verschiedener Methoden/Operationen vorangestellt wird.

  • Syntax: URI-Teil mit / am Anfang
  • Erforderlich: nein
  • Standardwert: Das basePath-Feld der OpenAPI-Spezifikation.
  • Beispiele: /api oder /context

threescale_cicd_api_backend_hostname

Definiert den Backend-Hostnamen, wobei das host-Feld der OpenAPI-Spezifikation überschrieben wird. Der resultierende Wert wird verwendet, um die Variable threescale_cicd_private_base_url zu definieren, falls diese fehlt.

  • Syntax: FQDN mit optionalem Port
  • Erforderlich: nein
  • Standardwert: Das host-Feld der OpenAPI-Spezifikation.
  • Beispiele: mybackend.acme.corp oder mybackend.acme.corp:8080

threescale_cicd_api_backend_scheme

Definiert das Schema, das verwendet wird, um eine Verbindung zum Backend herzustellen, und überschreibt das schemes-Feld der OpenAPI-Spezifikation. Der resultierende Wert wird verwendet, um die Variable threescale_cicd_private_base_url zu definieren, falls diese fehlt.

  • Syntax: http oder https
  • Erforderlich: nein
  • Standardwert: Das erste Element des scheme-Felds der OpenAPI-Spezifikation, standardmäßig http, wenn nicht vorhanden.
  • Beispiel: https

threescale_cicd_private_base_url

Definiert die 3scale Private Base URL.

  • Syntax: <schem>://<host>:<port>
  • Erforderlich: nein
  • Standardwert: <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • Beispiel: http://mybackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

Ermöglicht die Aktivierung der CORS-Richtlinie auf dem APICast-Gateway. Falls Ihre API die Unterstützung für cross-origin und browserbasierte Aufrufe benötigt und Sie das OPTIONS-Verb nicht auf dem richtigen Pfad in Ihrer OpenAPI-Spezifikationsdatei eingeschlossen haben...

  • Syntax: boolean ja oder nein
  • Erforderlich: nein
  • Standardwert: nein
  • Beispiel: ja, wenn Sie die CORS-Richtlinie auf APICast aktivieren möchten

threescale_cicd_openapi_smoketest_operation

Definiert die OpenAPI-Spezifikationsmethode, die für Smoke-Tests verwendet werden soll.

  • Syntax: die operationId der OpenAPI-Spezifikationsmethode
  • Erforderlich: nein
  • Standardwert: keine. Wenn diese Variable nicht definiert ist und wenn keine Operation mit x-threescale-smoketests-operation in der OpenAPI-Spezifikation gekennzeichnet ist, werden die Smoke-Tests übersprungen.
  • Beispiel: GetName

threescale_cicd_api_environment_name

Fügt allen Diensten einen Umgebungsnamen voran, um Namenskonflikte zu vermeiden, wenn dieselbe API mehrfach auf derselben 3scale-Instanz bereitgestellt wird.

  • Syntax: Kleinbuchstaben, alphanumerisch + Unterstrich
  • Erforderlich: nein
  • Standardwert: keine, es erfolgt keine Voranstellung.
  • Beispiele: dev, test oder prod

threescale_cicd_validate_openapi

Validiert die OpenAPI-Spezifikationsdatei gegen das offizielle Schema. Dazu wird das Tool go-swagger verwendet.

Sie können dieses Tool irgendwo in Ihrem PATH vorinstallieren. Alternativ können Sie auch den vollständigen Pfad zum swagger-Befehl mit der zusätzlichen Variable threescale_cicd_goswagger_command angeben.

Wenn das Tool fehlt, wird es automatisch von GitHub heruntergeladen und in {{ threescale_cicd_local_bin_path }} installiert.

  • Syntax: boolean (ja, nein, wahr, falsch)
  • Erforderlich: nein
  • Standardwert: ja
  • Beispiele:
    • threescale_cicd_validate_openapi=nein
    • threescale_cicd_goswagger_command=/usr/local/bin/swagger
    • threescale_cicd_local_bin_path=/tmp

threescale_cicd_oicd_flows

Überschreiben oder aktualisieren Sie die Liste der unterstützten OAuth-Flows für diese API.

  • Syntax: Array von Zeichenfolgen ([ 'application', 'accessCode' ])
  • Erforderlich: nein
  • Standardwert: das flow-Feld des securityScheme-Objekts in Ihrer OpenAPI-Spezifikationsdatei.
  • Beispiele:
    • threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}" (Überschreiben der Flussliste)
    • threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}" (Hinzufügen eines Flusses)

threescale_cicd_create_default_application

Ermöglicht die Erstellung einer Testanwendung mit dem Standardanwendungsplan, unabhängig davon, ob Smoke-Tests aktiviert sind oder nicht.

  • Syntax: boolean (ja, nein, wahr, falsch)
  • Erforderlich: nein
  • Standardwert: nein
  • Beispiel: ja, wenn Sie eine Standardanwendung erstellen möchten

Verschiedene Variablen

Verschiedene Variablen, die in defaults/main.yml definiert sind, bieten sinnvolle Standardwerte. Werfen Sie einen Blick darauf.

Abhängigkeiten

Diese Rolle hat keine Abhängigkeiten von anderen Rollen, hat aber Abhängigkeiten von:

  • Ansible (mindestens Version 2.4)
  • JMESPath
  • Jinja (mindestens Version 2.8)
  • 3scale API Management 2.3

Integration mit anderen Technologien

Unterstützung für wichtige Technologien ist im Support-Ordner verfügbar. Es gibt Unterstützung für Jenkins, Kubernetes, Docker, OpenShift, einschließlich eines vorgefertigten Docker-Images.

Lizenz

MIT

Autor Informationen

  • Nicolas Massé, Red Hat
  • Laurent Broudoux, Red Hat
  • Daria Mayorova, Red Hat
Über das Projekt

Enables Continuous Deployment with 3scale API Management Platform

role 3scale api automation cd ci deploy deployment management redhat threescale
Installieren
ansible-galaxy install nmasse-itix.threescale-cicd
GitHub Repository
16 Sterne
13 Forks
23 Offene Issues
Lizenz
mit
Downloads
3.4k
Besitzer
Nicolas Massé
👪 Father, 🎮 Tech Enthusiast, 🛠 Craftsman of Code, 🗣 Wizard of Conferences, 🧩 World Builder, 🌍 Digital Explorer.