nmasse-itix.threescale-cicd

Przegląd Wersje Wgląd

ansible-cicd

Status budowy Licencja MIT Rola Galaxy

Umożliwia ciągłą dostawę z wykorzystaniem platformy zarządzania API Red Hat 3scale (3scale AMP).

Wymagania

Ta rola wymaga:

  • instancji platformy zarządzania API 3scale (hostowanej lub lokalnej)
  • instancji Red Hat SSO, jeśli planujesz używać uwierzytelniania OpenID Connect
  • dwóch bramek APIcast (staging i produkcja), hostowanych lub zarządzanych samodzielnie
  • pliku Swagger 2.0 opisującego API, które chcesz opublikować

Wszystkie komponenty są obsługiwane przez API, więc nie jest wymagane połączenie SSH!

Na węźle kontrolnym wymagana jest biblioteka jmespath. Jeśli nie jest jeszcze zainstalowana, możesz ją zainstalować za pomocą:

pip install jmespath

Wymagana jest również świeża wersja Jinja (2.8). Możesz zaktualizować swoją wersję Jinja poleceniem:

pip install -U Jinja2

Jeśli twój węzeł kontrolny działa na RHEL7, możesz uruchomić ten playbook w celu zainstalowania brakujących zależności.

Przykład: Wdrożenie API na 3scale SaaS z hostowanymi bramkami APIcast

Jeśli chcesz wdrożyć klasyczne "Echo API" na instancji SaaS 3scale, używając kluczy API, możesz to zrobić w trzech krokach:

  1. Przygotuj plik Swagger dla swojego Echo API
  2. Zbuduj swój plik inwentaryzacyjny
  3. Napisz playbook
  4. Uruchom playbook!

Najpierw upewnij się, że twój plik swagger (api-swagger.yaml) zawiera wymagane informacje:

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: 'Uzyskaj echo'
      description: 'Uzyskaj echo z serwera'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Echo z serwera'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

W tym pliku Swagger używane są następujące pola:

  • x-threescale-system-name jest używane jako podstawa dla system_name dla obiektów konfiguracyjnych w 3scale.
  • title jest używane jako nazwa definicji usługi.
  • version jest używane do odpowiedniego wersjonowania i przestrzega schematu semver.
  • host to nazwa DNS istniejącego backendu API, który ma być udostępniony.
  • pola operationId są używane jako system_name dla metod/mierników.
  • pola summary i description są używane jako nazwa i opis dla metod/mierników.
  • x-threescale-smoketests-operation jest używane do oznaczenia jednej operacji jako przydatnej do testów dymnych. Metoda musi być idempotentna, tylko do odczytu i bez parametrów. Jeśli żadna metoda nie zostanie oznaczona jako test dymny, testy dymne po prostu zostaną pominięte.
  • security i securityDefinitions są używane do określenia schematu zabezpieczeń wystawianego API. W tym przykładzie używamy schematu kluczy API.

Następnie napisz plik inventory:

[all:vars]
ansible_connection=local

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

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

Najważniejsze elementy pliku inwentaryzacyjnego to:

  • portal administracyjny 3scale musi być zadeklarowany w grupie o nazwie threescale.
  • token dostępu 3scale musi być ustawiony w zmiennej threescale_cicd_access_token.
  • ponieważ nie jest wymagane połączenie SSH (używamy tylko API Administracji 3scale), ansible_connection=local jest ustawione dla całej inwentaryzacji.

Teraz możesz napisać playbook (deploy-api.yaml):

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

Główne części to:

  • threescale_cicd_openapi_file to ścieżka do pliku swagger zdefiniowanego w kroku 1.
  • używana jest rola nmasse-itix.threescale-cicd.
  • gather_facts: no musi być używane, ponieważ nie ma połączenia SSH z systemami docelowymi.

Na koniec możesz uruchomić playbook:

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

Inwentaryzacja

Portal administracyjny 3scale, który zostanie utworzony, to ten, który jest cytowany w playbooku, który zawiera tę rolę. Na przykład, w poprzednim przykładzie portal administracyjny 3scale będzie <TENANT>-admin.3scale.net, ponieważ główny playbook określa hosts: threescale, a grupa threescale zawiera tylko jednego hosta: <TENANT>-admin.3scale.net.

Jeśli określisz wiele hostów dla portalu administracyjnego 3scale, wszystkie zostaną skonfigurowane z dokładnie tą samą konfiguracją (przydatne w przypadku wdrożeń wielostanowiskowych).

Aby połączyć się z portalem administracyjnym 3scale, musisz dostarczyć token dostępu z uprawnieniami do odczytu/zapisu na API zarządzania kontem. Możesz podać ten token na poziomie hosta, na poziomie grupy lub globalnie za pomocą zmiennej threescale_cicd_access_token.

Na poziomie hosta definiuje się go w ten sposób:

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

Na poziomie grupy można go zdefiniować w ten sposób:

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

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

Możesz też zdefiniować go globalnie, na przykład jako zmienne playbooka:

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

Instancja Red Hat SSO (aktualnie może być tylko jedna) jest definiowana przez zmienną threescale_cicd_sso_issuer_endpoint grupy threescale.

Jej składnia to https://<client_id>:<client_secret>@hostname/auth/realms/<realm>. client_id/client_secret są używane przez Zync do synchronizacji aplikacji 3scale z Red Hat SSO.

Przykład:

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

Instancje APIcast są definiowane za pomocą następujących dodatkowych zmiennych:

  • threescale_cicd_apicast_sandbox_endpoint
  • threescale_cicd_apicast_production_endpoint

Przykład:

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

Pola specyfikacji OpenAPI

Ta rola obecnie obsługuje tylko specyfikacje OpenAPI v2.0 (znanej również jako Swagger 2.0).

Można używać następujących rozszerzonych pól specyfikacji OpenAPI:

  • x-threescale-system-name, w strukturze info jest używane jako podstawa do skonstruowania system_name dla obiektów konfiguracyjnych w 3scale.
  • x-threescale-smoketests-operation w definicji metody jest używane do oznaczenia tej operacji jako przydatnej do testów dymnych. Metoda musi być idempotentna, tylko do odczytu i bez parametrów. Jeśli żadna metoda nie jest oznaczona jako test dymny, testy dymne są po prostu pomijane.

Jeżeli rozszerzone pola nie mogą być używane (np. jeśli nie chcesz zmieniać swojej umowy API), możesz użyć odpowiadającej im dodatkowej zmiennej:

  • threescale_cicd_api_base_system_name
  • threescale_cicd_openapi_smoketest_operation

Oto przykład specyfikacji OpenAPI wykorzystującej te rozszerzone pola:

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: 'Uzyskaj echo'
      description: 'Uzyskaj echo z serwera'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Echo z serwera'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

Namely, echo-api zostanie użyte jako podstawa do stworzenia system_name definicji usługi 3scale, a GET na / zostanie wykorzystane jako test dymny.

Aby osiągnąć ten sam efekt bez rozszerzonych pól OpenAPI, musiałbyś przekazać następujące dodatkowe zmienne:

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # operationId metody "GET /"

Poniższe standardowe pola specyfikacji OpenAPI są używane.

W sekcji info:

  • title jest używane jako nazwa wyświetlana definicji usługi 3scale.
  • version jest używana do odpowiedniego wersjonowania i przestrzega schematu semver.
  • host to nazwa DNS istniejącego backendu API, który ma być eksponowany.

Dla każdej zdefiniowanej metody:

  • pole operationId jest używane jako system_name dla odpowiednich metod/mierników.
  • pola summary i description są używane jako nazwa i opis dla metod/mierników.
  • security i securityDefinitions są używane do określenia schematu zabezpieczeń eksponowanego API.

Aby mieć odwzorowanie jeden-do-jednego między specyfikacjami OpenAPI a funkcjami 3scale, zastosowano pewne ograniczenia na struktury security/securityDefinitions. Namely, musi istnieć jeden i dokładnie jeden wymóg bezpieczeństwa w strukturze security. Wymóg bezpieczeństwa musi być stosowany globalnie (nie na zasadzie per metoda).

Definicje zabezpieczeń mają też ograniczenia: można wybrać tylko dwa schematy zabezpieczeń:

  • OAuth / OpenID Connect
  • Klucz API

Schemat App Key Pair proponowany przez 3scale nie ma odpowiadającej definicji w specyfikacjach OpenAPI i obecnie nie jest obsługiwany przez tę rolę.

Aby być bardziej konkretnym, aby zabezpieczyć swoje API przy użyciu klucza API, użyj tego fragmentu w pliku specyfikacji OpenAPI:

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

Możesz oczywiście wybrać nazwę nagłówka HTTP, która będzie używana do wysyłania klucza API, zmieniając pole name (w tym przykładzie: api-key).

Aby zabezpieczyć go za pomocą OpenID Connect, użyj tego fragmentu w pliku specyfikacji OpenAPI:

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

Możesz oczywiście użyć dowolnego przepływu OpenID Connect według własnego wyboru:

  • implicit
  • password
  • application
  • accessCode

Zmienne roli

Ta sekcja szczegółowo opisuje wszystkie zmienne używane przez tę rolę. Jako wstęp, ta rola przyjmuje konwencję nad konfiguracją. Oznacza to, że rozsądne domyślne wartości i założone schematy nazewnictwa są dostarczane od razu.

threescale_cicd_openapi_file

Określa plik specyfikacji OpenAPI do odczytu.

  • Składnia: Pełna ścieżka do specyfikacji OpenAPI, na lokalnym systemie plików. Unikaj ścieżek względnych, preferuj absolutne. Jeśli musisz odczytać plik, który jest względny do twojego playbooka, użyj zastępnika {{ playbook_dir }}.
  • Wymagane: tak
  • Przykłady: /tmp/openapi.yaml lub {{ playbook_dir }}/git/openapi.json

threescale_cicd_openapi_file_format

Określa format (JSON lub YAML) pliku specyfikacji OpenAPI do odczytu.

  • Składnia: JSON lub YAML
  • Wymagane: nie
  • Domyślna wartość: YAML
  • Przykład: YAML

threescale_cicd_api_system_name

Definiuje system_name usługi 3scale, która zostanie utworzona.

  • Składnia: małe litery alfanumeryczne + podkreślnik
  • Wymagane: nie
  • Domyślna wartość: jeśli nie zdefiniowane, system_name jest pobierane z zmiennej threescale_cicd_api_base_system_name. Ten podstawowy system_name jest następnie dopełniane przez numer główny wersji API i poprzedzane przez nazwę środowiska (tylko jeśli threescale_cicd_api_environment_name jest zdefiniowane).
  • Przykład: dev_my_wonderful_service_1

threescale_cicd_api_base_system_name

Służy jako podstawa do obliczenia threescale_cicd_api_system_name.

  • Składnia: małe litery alfanumeryczne + podkreślnik
  • Wymagane: nie
  • Domyślna wartość: jeśli nie zdefiniowane, rozszerzone pole specyfikacji OpenAPI x-threescale-system-name lub jeśli nie ma, pole title jest oczyszczane i następnie używane. Jeśli nie można znaleźć tytułu, używana jest domyślna wartość API. Jeśli nie można znaleźć numeru wersji, używane jest 0.
  • Przykład: my_wonderful_service

Uwaga: Jeśli zarówno threescale_cicd_api_base_system_name, jak i threescale_cicd_api_system_name są ustawione, ten drugi ma pierwszeństwo.

threescale_cicd_wildcard_domain

Automatycznie definiuje publiczne URL-e APIcast na podstawie schematu.

  • Składnia: sufiks domeny DNS

  • Wymagane: nie

  • Domyślna wartość: jeśli zdefiniowane, oblicza threescale_cicd_apicast_sandbox_endpoint i threescale_cicd_apicast_production_endpoint na podstawie system_name API. Sandbox APIcast będzie <system_name>-staging.<wildcard_domain> a produkcyjny APIcast będzie <system_name>.<wildcard_domain>. Sufiksy dla staging (-staging) i dla produkcji (pusty) mogą być dostosowane za pomocą zmiennych threescale_cicd_default_staging_suffix i threescale_cicd_default_production_suffix.

  • Przykład: poniższe dwie zmienne

    threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=my_wonderful_service

    są równoważne:

    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

Definiuje basePath, na którym będzie wdrażane API backendowe, nadpisując pole basePath specyfikacji OpenAPI. Ostateczna wartość jest używana do definiowania reguł mapowania bramy API 3scale, poprzedzając tę bazową ścieżkę ścieżkami różnych metod/operacji.

  • Składnia: część URI z rozpoczynającym /
  • Wymagane: nie
  • Domyślna wartość: pole basePath specyfikacji OpenAPI.
  • Przykłady: /api lub /context

threescale_cicd_api_backend_hostname

Definiuje nazwę hosta backend, nadpisując pole host specyfikacji OpenAPI. Ostateczna wartość jest używana do definiowania zmiennej threescale_cicd_private_base_url, jeśli jest brakująca.

  • Składnia: FQDN z opcjonalnym portem
  • Wymagane: nie
  • Domyślna wartość: pole host specyfikacji OpenAPI.
  • Przykłady: mybackend.acme.corp lub mybackend.acme.corp:8080

threescale_cicd_api_backend_scheme

Definiuje schemat do użycia do połączenia z backendem, nadpisując pole schemes specyfikacji OpenAPI. Ostateczna wartość jest używana do definiowania zmiennej threescale_cicd_private_base_url, jeśli jest brakująca.

  • Składnia: http lub https
  • Wymagane: nie
  • Domyślna wartość: pierwszy element pola scheme specyfikacji OpenAPI, domyślnie http, jeśli nie jest dostępny.
  • Przykład: https

threescale_cicd_private_base_url

Definiuje prywatny adres bazowy 3scale.

  • Składnia: <schem>://<host>:<port>
  • Wymagane: nie
  • Domyślna wartość: <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • Przykład: http://mybackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

Pozwala na włączenie polityki CORS w bramce APICast. W przypadku, gdy twoje API powinno wspierać cross-origin i wywołania z przeglądarki i nie masz włączonego werbu OPTIONS w odpowiedniej ścieżce w plik specyfikacji OpenAPI...

  • Składnia: boolean yes lub no
  • Wymagane: nie
  • Domyślna wartość: no
  • Przykład: yes, jeśli chcesz aktywować politykę CORS na APICast

threescale_cicd_openapi_smoketest_operation

Definiuje metodę specyfikacji OpenAPI do użycia w testach dymnych.

  • Składnia: operationId metody specyfikacji OpenAPI
  • Wymagane: nie
  • Domyślna wartość: brak. Jeśli ta zmienna jest niezdefiniowana i jeśli nie ma operacji oznaczonej jako x-threescale-smoketests-operation w specyfikacji OpenAPI, testy dymne zostaną pominięte.
  • Przykład: GetName

threescale_cicd_api_environment_name

Prefiksuje wszystkie usługi nazwą środowiska, aby uniknąć kolizji nazw przy wdrażaniu tego samego API wielokrotnie na tej samej instancji 3scale.

  • Składnia: małe litery, alfanumeryczne + podkreślnik
  • Wymagane: nie
  • Domyślna wartość: brak, nie przeprowadza się prefiksowania.
  • Przykłady: dev, test lub prod

threescale_cicd_validate_openapi

Waliduje plik specyfikacji OpenAPI według oficjalnego schematu. W tym celu wykorzystywane jest narzędzie go-swagger.

Możesz wstępnie zainstalować to narzędzie w dowolnym miejscu w swoim PATH. Alternatywnie możesz też podać pełną ścieżkę do polecenia swagger zmienną dodatkową threescale_cicd_goswagger_command.

Jeśli narzędzie jest niedostępne, zostanie automatycznie pobrane z GitHub i zainstalowane w {{ threescale_cicd_local_bin_path }}.

  • Składnia: boolean (yes, no, true, false)
  • Wymagane: nie
  • Domyślna wartość: yes
  • Przykłady:
    • threescale_cicd_validate_openapi=no
    • threescale_cicd_goswagger_command=/usr/local/bin/swagger
    • threescale_cicd_local_bin_path=/tmp

threescale_cicd_oicd_flows

Zastępuje lub aktualizuje listę obsługiwanych przepływów OAuth dla tego API.

  • Składnia: tablica łańcuchów ([ 'application', 'accessCode' ])
  • Wymagane: nie
  • Domyślna wartość: pole flow obiektu securityScheme w twoim pliku specyfikacji OpenAPI.
  • Przykłady:
    • threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}" (zastąp listę przepływów)
    • threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}" (dodaj nowy przepływ)

threescale_cicd_create_default_application

Pozwala na utworzenie aplikacji testowej z domyślnym planem aplikacji, niezależnie od tego, czy testy dymne są włączone, czy nie.

  • Składnia: boolean (yes, no, true, false)
  • Wymagane: nie
  • Domyślna wartość: no
  • Przykład: yes, jeśli chcesz utworzyć domyślną aplikację

Zróżnicowane zmienne

Zróżnicowane zmienne zdefiniowane w defaults/main.yml oferują rozsądne domyślne wartości. Sprawdź je.

Zależności

Ta rola nie ma zależności od innych ról, ale ma zależności od:

  • Ansible (przynajmniej wersja 2.4)
  • JMESPath
  • Jinja (przynajmniej wersja 2.8)
  • 3scale API Management 2.3

Integracja z innymi technologiami

Wsparcie dla głównych technologii jest dostępne w folderze wsparcia. Jest wsparcie dla Jenkins, Kubernetes, Docker, OpenShift, w tym gotowa obrazy dockerowe.

Licencja

MIT

Informacje o autorze

  • Nicolas Massé, Red Hat
  • Laurent Broudoux, Red Hat
  • Daria Mayorova, Red Hat
O projekcie

Enables Continuous Deployment with 3scale API Management Platform

role 3scale api automation cd ci deploy deployment management redhat threescale
Zainstaluj
ansible-galaxy install nmasse-itix.threescale-cicd
GitHub repozytorium
16 gwiazdki
13 forki
23 otwarte zgłoszenia
Licencja
mit
Pobrania
3.4k
Właściciel
Nicolas Massé
👪 Father, 🎮 Tech Enthusiast, 🛠 Craftsman of Code, 🗣 Wizard of Conferences, 🧩 World Builder, 🌍 Digital Explorer.