nmasse-itix.threescale-cicd

ansible-cicd

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:

Erstellen Sie eine Swagger-Datei für Ihre Echo API
Erstellen Sie Ihre Inventardatei
Schreiben Sie das Playbook
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.