nmasse-itix.threescale-cicd

Обзор Версии Аналитика

ansible-cicd

Статус сборки Лицензия MIT Роль Galaxy

Позволяет реализовать непрерывную поставку с помощью платформы управления API Red Hat 3scale (3scale AMP).

Требования

Эта роль требует:

  • экземпляр платформы управления API 3scale (в облаке или на локальной машине)
  • экземпляр Red Hat SSO, если вы планируете использовать аутентификацию OpenID Connect
  • два шлюза APIcast (для тестирования и продакшена), либо в облаке, либо управляемые самостоятельно
  • файл Swagger 2.0, описывающий API, который вы хотите опубликовать

Все компоненты управляются через API, поэтому подключение по SSH не требуется!

На управляющем узле требуется библиотека jmespath. Если она еще не установлена, вы можете установить ее с помощью:

pip install jmespath

Также требуется актуальная версия Jinja (2.8). Вы можете обновить свою версию Jinja с помощью:

pip install -U Jinja2

Если ваш управляющий узел работает на RHEL7, вы можете запустить этот плейбук для установки недостающих зависимостей.

Пример: Развертывание API на 3scale SaaS с использованием облачных шлюзов APIcast

Если вы хотите развернуть классический "Echo API" на экземпляре SaaS 3scale с использованием API ключей, вы можете сделать это в три простых шага:

  1. Создайте файл Swagger для вашего Echo API.
  2. Подготовьте файл инвентаризации.
  3. Напишите плейбук.
  4. Запустите плейбук!

Сначала убедитесь, что ваш swagger файл (api-swagger.yaml) содержит всю необходимую информацию:

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: 'Получить эхо'
      description: 'Получить эхо от сервера'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Эхо от сервера'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

В этом Swagger файле используются следующие поля:

  • x-threescale-system-name используется в качестве основы для system_name для объектов конфигурации в 3scale.
  • title используется как название определения службы.
  • version используется для правильного версионирования и соответствует схеме semver.
  • host — это DNS-имя существующего API бекенда, который нужно открыть.
  • поля operationId используются в качестве system_name для методов/метрик.
  • поля summary и description используются для названия и описания методов/метрик.
  • x-threescale-smoketests-operation используется, чтобы пометить одну операцию как доступную для дымовых тестов. Метод должен быть идемпотентным, только для чтения и без параметров. Если ни один метод не помечен как для дымовых тестов, то они просто пропускаются.
  • security и securityDefinitions используются для определения схемы безопасности открытого API. В этом примере используется схема API ключей.

После этого создайте файл inventory:

[all:vars]
ansible_connection=local

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

[threescale:vars]
threescale_cicd_access_token=<ACCESS_TOKEN>

Важные моменты файла инвентаризации:

  • Портал администратора 3scale должен быть объявлен в группе с именем threescale.
  • Токен доступа 3scale должен быть установлен в переменной threescale_cicd_access_token.
  • Так как подключение по SSH не требуется (мы используем только API администратора 3scale), для всего инвентаря устанавливается ansible_connection=local.

Теперь вы можете написать плейбук (deploy-api.yaml):

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

Основные части:

  • threescale_cicd_openapi_file — это путь к файлу swagger, определенному на шаге 1.
  • используется роль nmasse-itix.threescale-cicd.
  • gather_facts: no нужно использовать, так как нет подключения по SSH к целевым системам.

Наконец, вы можете запустить плейбук:

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

Инвентаризация

Портал администратора 3scale, который будет создан, — это тот, который указан в плейбуке, включающем эту роль. Например, в предыдущем примере созданный портал администратора 3scale будет <TENANT>-admin.3scale.net, потому что основной плейбук указывает hosts: threescale, а группа threescale содержит только один хост: <TENANT>-admin.3scale.net.

Если вы укажете несколько хостов для портала администратора 3scale, все они будут созданы с одной и той же конфигурацией (полезно для развертывания на нескольких сайтах).

Чтобы подключиться к порталу администратора 3scale, вам нужно будет предоставить токен доступа, имеющий права на чтение/запись в API управления аккаунтами. Вы можете указать этот токен на уровне хоста, группы или глобально с помощью переменной threescale_cicd_access_token.

На уровне хоста его можно определить так:

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

На уровне группы вы можете определить его так:

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

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

Вы также можете определить его глобально, например, как переменные плейбука:

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

Экземпляр Red Hat SSO (в настоящее время только один) определяется переменной threescale_cicd_sso_issuer_endpoint группы threescale.

Его синтаксис: https://<client_id>:<client_secret>@hostname/auth/realms/<realm>. client_id/client_secret используются Zync для синхронизации приложений 3scale с Red Hat SSO.

Пример:

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

Экземпляры APIcast определяются по следующим дополнительным переменным:

  • threescale_cicd_apicast_sandbox_endpoint
  • threescale_cicd_apicast_production_endpoint

Пример:

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

Поля спецификации OpenAPI

В этой роли поддерживаются только спецификации OpenAPI v2.0 (также известная как Swagger 2.0).

Можно использовать следующие расширенные поля спецификаций OpenAPI:

  • x-threescale-system-name, в структуре info используется как основа для построения system_name для объектов конфигурации в 3scale.
  • x-threescale-smoketests-operation в определении метода используется для пометки этой операции как доступной для дымовых тестов. Метод должен быть идемпотентным, только для чтения и без параметров. Если ни один метод не помечен как для дымовых тестов, дымовые тесты просто пропускаются.

Если расширенные поля не могут быть использованы (например, вы не хотите изменять свой API-контракт), вы можете использовать соответствующую дополнительную переменную:

  • threescale_cicd_api_base_system_name
  • threescale_cicd_openapi_smoketest_operation

Вот пример спецификации OpenAPI с использованием этих расширенных полей:

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: 'Получить эхо'
      description: 'Получить эхо от сервера'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'Эхо от сервера'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

Таким образом, echo-api будет использован как основа для построения system_name определения службы 3scale, а GET по / будет использоваться для дымовых тестов.

Чтобы добиться того же эффекта без расширенных полей OpenAPI, вам нужно будет передать следующие дополнительные переменные:

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # operationId метода "GET /"

Следующие стандартные поля спецификаций OpenAPI используются.

В разделе info:

  • title используется как отображаемое имя определения службы 3scale.
  • version используется для правильного версионирования и соответствует схеме semver.
  • host — это DNS-имя существующего API бекенда для открытия.

Для каждого определенного метода:

  • поле operationId используется как system_name для соответствующих методов/метрик.
  • поля summary и description используются как название и описание для методов/метрик.
  • security и securityDefinitions используются для определения схемы безопасности открытого API.

Чтобы достичь однозначного соответствия между спецификациями OpenAPI и функциями 3scale, некоторые ограничения применяются к структурам security/securityDefinitions. А именно, в структуре security должно быть одно и только одно требование безопасности. Требование безопасности должно применяться глобально (не применительно к каждому методу).

Также есть ограничения для определений безопасности: вы можете выбрать только две схемы безопасности:

  • OAuth / OpenID Connect
  • API Key

Схема App Key Pair, предложенная 3scale, не имеет соответствующего определения в спецификациях OpenAPI и в настоящее время не поддерживается этой ролью.

Чтобы быть более конкретным, чтобы защитить ваш API с помощью API Key, используйте следующий фрагмент в вашем файле спецификации OpenAPI:

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

Вы, конечно, можете выбрать имя HTTP-заголовка, который будет использоваться для отправки API Key, изменив поле name (в этом примере: api-key).

И чтобы защитить его с помощью OpenID Connect, используйте этот фрагмент в вашем файле спецификации OpenAPI:

securityDefinitions:
  oidc:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://dummy/placeholder
    tokenUrl: http://dummy/placeholder
    scopes:
      openid: Получить токен OpenID Connect
security:
- oidc:
  - openid

Вы, конечно, можете использовать любой поток OpenID Connect по вашему выбору:

  • implicit
  • password
  • application
  • accessCode

Переменные роли

Этот раздел подробно описывает все переменные, используемые этой ролью. В качестве предисловия, эта роль принимает схему "соглашение над конфигурацией". Это означает, что разумные значения по умолчанию и установленные схемы именования предоставляются из коробки.

threescale_cicd_openapi_file

Указывает файл спецификации OpenAPI для чтения.

  • Синтаксис: Полный путь к спецификации OpenAPI на локальной файловой системе. Избегайте относительных путей, предпочитайте абсолютные. Если вам нужно прочитать файл, который относителен к вашему плейбуку, используйте плейсхолдер {{ playbook_dir }}.
  • Обязательный: да
  • Примеры: /tmp/openapi.yaml или {{ playbook_dir }}/git/openapi.json

threescale_cicd_openapi_file_format

Указывает формат (JSON или YAML) файла спецификации OpenAPI для чтения.

  • Синтаксис: JSON или YAML
  • Обязательный: нет
  • Значение по умолчанию: YAML
  • Пример: YAML

threescale_cicd_api_system_name

Определяет system_name службы 3scale, которая будет создана.

  • Синтаксис: строчные алфавитно-цифровые символы + нижнее подчеркивание
  • Обязательный: нет
  • Значение по умолчанию: если не определено, system_name берется из переменной threescale_cicd_api_base_system_name. Эта базовая system_name затем дополняется номером основной версии API и префиксируется названием окружения (только если указано threescale_cicd_api_environment_name).
  • Пример: dev_my_wonderful_service_1

threescale_cicd_api_base_system_name

Используется как основа для вычисления threescale_cicd_api_system_name.

  • Синтаксис: строчные алфавитно-цифровые символы + нижнее подчеркивание
  • Обязательный: нет
  • Значение по умолчанию: если не определено, расширенное поле x-threescale-system-name спецификации OpenAPI или, в последнюю очередь, поле title обрабатывается и затем используется. Если не найдено ни одно название, используется значение по умолчанию API. Если не найден номер версии, используется 0.
  • Пример: my_wonderful_service

Примечание: если установлены как threescale_cicd_api_base_system_name, так и threescale_cicd_api_system_name, последний имеет приоритет.

threescale_cicd_wildcard_domain

Автоматически определяет публичные URL APIcast на основе схемы.

  • Синтаксис: суффикс DNS домена

  • Обязательный: нет

  • Значение по умолчанию: если определено, вычисляет threescale_cicd_apicast_sandbox_endpoint и threescale_cicd_apicast_production_endpoint из system_name API. Sandbox APIcast будет <system_name>-staging.<wildcard_domain>, а Production APIcast будет <system_name>.<wildcard_domain>. Суффиксы для тестирования (-staging) и продакшена (пустой) могут быть настроены с помощью переменных threescale_cicd_default_staging_suffix и threescale_cicd_default_production_suffix.

  • Пример: следующие две переменные

    threescale_cicd_wildcard_domain=acme.corp
threescale_cicd_api_base_system_name=my_wonderful_service

    эквивалентны:

    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

Определяет basePath, на котором развернут бекенд API, переопределяя поле basePath спецификации OpenAPI. Результирующее значение используется для определения правил сопоставления API Gateway 3scale, добавляя этот базовый путь к путям различных методов/операций.

  • Синтаксис: часть URI с начальным /
  • Обязательный: нет
  • Значение по умолчанию: поле basePath спецификации OpenAPI.
  • Примеры: /api или /context

threescale_cicd_api_backend_hostname

Определяет имя хоста бекенда, переопределяя поле host спецификации OpenAPI. Результирующее значение используется для определения переменной threescale_cicd_private_base_url, если она отсутствует.

  • Синтаксис: FQDN с необязательным портом
  • Обязательный: нет
  • Значение по умолчанию: поле host спецификации OpenAPI.
  • Примеры: mybackend.acme.corp или mybackend.acme.corp:8080

threescale_cicd_api_backend_scheme

Определяет схему, используемую для подключения к бекенду, переопределяя поле schemes спецификации OpenAPI. Результирующее значение используется для определения переменной threescale_cicd_private_base_url, если она отсутствует.

  • Синтаксис: http или https
  • Обязательный: нет
  • Значение по умолчанию: первый элемент поля scheme спецификации OpenAPI, по умолчанию http, если он отсутствует.
  • Пример: https

threescale_cicd_private_base_url

Определяет закрытый базовый URL 3scale.

  • Синтаксис: <schem>://<host>:<port>
  • Обязательный: нет
  • Значение по умолчанию: <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • Пример: http://mybackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

Позволяет включить политику CORS на шлюзе APICast. В случае, если ваш API должен поддерживать взаимодействие между источниками и браузеров, и вы не включили метод OPTIONS на правильном пути в вашем файле спецификации OpenAPI...

  • Синтаксис: логическое значение yes или no
  • Обязательный: нет
  • Значение по умолчанию: no
  • Пример: yes, если вы хотите активировать политику CORS на APICast

threescale_cicd_openapi_smoketest_operation

Определяет метод спецификации OpenAPI, который будет использоваться для дымовых тестов.

  • Синтаксис: operationId метода спецификации OpenAPI
  • Обязательный: нет
  • Значение по умолчанию: нет. Если эта переменная не определена и если нет операции, помеченной x-threescale-smoketests-operation в спецификации OpenAPI, дымовые тесты будут пропущены.
  • Пример: GetName

threescale_cicd_api_environment_name

Добавляет префикс ко всем службам с именем окружения, чтобы предотвратить любые коллизии имен при развертывании одного и того же API несколько раз на одном экземпляре 3scale.

  • Синтаксис: строчные буквы, алфавитно-цифровые + нижнее подчеркивание
  • Обязательный: нет
  • Значение по умолчанию: нет, префикса не добавляется.
  • Примеры: dev, test или prod

threescale_cicd_validate_openapi

Проверяет файл спецификации OpenAPI на соответствие официальной схеме. Для этого используется инструмент go-swagger.

Вы можете заранее установить этот инструмент в вашу PATH. В качестве альтернативы, вы также можете указать полный путь к команде swagger с помощью дополнительной переменной threescale_cicd_goswagger_command.

Если инструмент отсутствует, он будет автоматически загружен с GitHub и установлен в {{ threescale_cicd_local_bin_path }}.

  • Синтаксис: булево значение (yes, no, true, false)
  • Обязательный: нет
  • Значение по умолчанию: yes
  • Примеры:
    • threescale_cicd_validate_openapi=no
    • threescale_cicd_goswagger_command=/usr/local/bin/swagger
    • threescale_cicd_local_bin_path=/tmp

threescale_cicd_oicd_flows

Переопределяет или обновляет список поддерживаемых OAuth-потоков для этого API.

  • Синтаксис: массив строк ([ 'application', 'accessCode' ])
  • Обязательный: нет
  • Значение по умолчанию: поле flow объекта securityScheme в вашем файле спецификации OpenAPI.
  • Примеры:
    • threescale_cicd_oicd_flows="{{ [ 'application', 'accessCode' ] }}" (переопределить список потоков)
    • threescale_cicd_oicd_flows="{{ [ 'application', threescale_cicd_api_security_scheme.flow ] }}" (добавить поток)

threescale_cicd_create_default_application

Позволяет создать тестовое приложение с планом по умолчанию, независимо от того, включены ли дымовые тесты или нет.

  • Синтаксис: булевое значение (yes, no, true, false)
  • Обязательный: нет
  • Значение по умолчанию: no
  • Пример: yes, если вы хотите создать приложение по умолчанию

Разное

Разные переменные, определенные в defaults/main.yml, предоставляют разумные значения по умолчанию. Ознакомьтесь с ними.

Зависимости

Эта роль не имеет зависимостей от других ролей, но имеет зависимости от:

  • Ansible (как минимум версия 2.4)
  • JMESPath
  • Jinja (минимум версия 2.8)
  • 3scale API Management 2.3

Интеграция с другими технологиями

Поддержка основных технологий доступна в папке поддержки. Есть поддержка для Jenkins, Kubernetes, Docker, OpenShift, включая предварительно собранный образ docker.

Лицензия

MIT

Информация об авторе

  • Николя Массé, Red Hat
  • Лорент Брудо, Red Hat
  • Дарья Майорова, Red Hat
О проекте

Enables Continuous Deployment with 3scale API Management Platform

role 3scale api automation cd ci deploy deployment management redhat threescale
Установить
ansible-galaxy install nmasse-itix.threescale-cicd
GitHub репозиторий
16 звезд(ы)
13 форк(ов)
23 открытых задач
Лицензия
mit
Загрузки
3.4k
Владелец
Nicolas Massé
👪 Father, 🎮 Tech Enthusiast, 🛠 Craftsman of Code, 🗣 Wizard of Conferences, 🧩 World Builder, 🌍 Digital Explorer.