nmasse-itix.threescale-cicd

概要 バージョン 洞察

ansible-cicd

ビルドステータス MITライセンス Galaxyロール

Red Hat 3scale API管理プラットフォーム（3scale AMP）を使用して継続的デリバリーを実現します。

要件

このロールには次のものが必要です：

  • 3scale API管理プラットフォームのインスタンス（ホスティングまたはオンプレミス）
  • OpenID Connect認証を使用する場合はRed Hat SSOのインスタンス
  • 2つのAPIcastゲートウェイ（ステージングと本番）、ホスティングまたは自己管理のいずれか
  • 公開したいAPIを説明するSwagger 2.0ファイル

すべてのコンポーネントはAPIを介して操作されるため、SSH接続は必要ありません！

コントロールノードにはjmespathライブラリが必要です。ない場合は、次のコマンドでインストールできます：

pip install jmespath

また、最新のJinja（2.8）が必要です。Jinjaのバージョンをアップグレードするには、次のコマンドを使用します：

pip install -U Jinja2

コントロールノードがRHEL7で動作している場合、次のプレイブックを実行して不足している依存関係をインストールできます。

例：ホストされたAPIcastゲートウェイを使用して3scale SaaSにAPIをデプロイする

APIキーを使用してSaaS 3scaleインスタンスにクラシックな「Echo API」をデプロイしたい場合、次の3つのステップで実行できます：

  1. Echo API用のSwaggerファイルを作成する
  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: 'Get an echo'
      description: 'Get an echo from the server'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'An Echo from the server'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

このSwaggerファイルでは、以下のフィールドが使用されています：

  • x-threescale-system-nameは、3scaleの設定オブジェクトのsystem_nameの基礎として使用されます。
  • titleは、サービス定義の名前として使用されます。
  • versionは、適切なバージョン管理のために使用され、semverスキームに従います。
  • hostは、公開する既存のAPIバックエンドのDNS名です。
  • 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接続が不要なため（3scale管理APIのみを使用するため）、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は、ステップ1で定義したSwaggerファイルへのパスです。
  • 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グループに1つのホスト<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インスタンス（現在は1つのみ）は、threescaleグループのthreescale_cicd_sso_issuer_endpoint変数によって定義されます。

その構文はhttps://<client_id>:<client_secret>@hostname/auth/realms/<realm>です。 client_id/client_secretは、3scaleアプリケーションをRed Hat SSOと同期するためにZyncによって使用されます。

例：

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構造内で3scaleの設定オブジェクトのsystem_nameを構成するための基礎として使用されます。
  • メソッド定義内の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: 'Get an echo'
      description: 'Get an echo from the server'
      x-threescale-smoketests-operation: true
      responses:
        200:
          description: 'An Echo from the server'
security:
- apikey: []
securityDefinitions:
  apikey:
    name: api-key
    in: header
    type: apiKey

具体的には、echo-apiは3scaleサービス定義のsystem_nameを構成するための基礎として使用され、GETメソッドがスモークテストとして使用されます。

OpenAPIの拡張フィールドなしで同様の効果を得るには、次の追加変数を渡す必要があります：

threescale_cicd_api_base_system_name=echo-api
threescale_cicd_openapi_smoketest_operation=Echo # "GET /"メソッドのoperationId

OpenAPI仕様で使用される次の標準フィールド：

infoセクションでは：

  • titleは、3scaleサービス定義の表示名として使用されます。
  • versionは、適切なバージョン管理のために使用され、semverスキームに従います。
  • hostは、公開する既存のAPIバックエンドのDNS名です。

各定義されたメソッドについて：

  • operationIdフィールドは、対応するメソッド/メトリクスのsystem_nameとして使用されます。
  • summaryおよびdescriptionフィールドは、メソッド/メトリクスの名前と説明として使用されます。
  • securityおよびsecurityDefinitionsは、公開APIのセキュリティスキームを決定するために使用されます。

OpenAPI仕様と3scale機能との間に1対1のマッピングを持つために、security/securityDefinitions構造に制限が適用されます。具体的には、security構造にセキュリティ要件が1つだけ存在する必要があります。このセキュリティ要件は、グローバルに適用される必要があります（メソッドごとではありません）。

セキュリティ定義にも制限があります。使用するセキュリティスキームは、次の2つのいずれかを選択できます：

  • OAuth / OpenID Connect
  • APIキー

3scaleで提案されているアプリケーションキーのペアスキームは、OpenAPI仕様に対応する定義がなく、現在このロールではサポートされていません。

具体的には、APIキーでAPIを保護するには、OpenAPI仕様ファイルに次の抜粋を使用します：

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

もちろん、APIキーを送信するために使用するHTTPヘッダ名を変更することで、nameフィールド（この例ではapi-key）を変更して選択することができます。

OpenID Connectで保護するには、OpenAPI仕様ファイルに次の抜粋を使用します：

securityDefinitions:
  oidc:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://dummy/placeholder
    tokenUrl: http://dummy/placeholder
    scopes:
      openid: Get an OpenID Connect token
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

読み取るOpenAPI仕様ファイルの形式（JSONまたはYAML）を指定します。

  • 構文: JSONまたはYAML
  • 必須: いいえ
  • デフォルト値: YAML
  • 例: YAML

threescale_cicd_api_system_name

プロビジョニングされる3scaleサービスのsystem_nameを定義します。

  • 構文: 小文字の英数字 + アンダースコア
  • 必須: いいえ
  • デフォルト値: 定義されていない場合、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を計算するための基盤として使用されます。

  • 構文: 小文字の英数字 + アンダースコア
  • 必須: いいえ
  • デフォルト値: 定義されていない場合、OpenAPI仕様のx-threescale-system-name拡張フィールド、または最後の手段としてtitleフィールドがサニタイズされて使用されます。 タイトルが見つからない場合、デフォルト値APIが使用されます。バージョン番号が見つからない場合は、0が使用されます。
  • 例: my_wonderful_service

注: 両方のthreescale_cicd_api_base_system_nameとthreescale_cicd_api_system_nameが設定されている場合、後者が優先されます。

threescale_cicd_wildcard_domain

APIcastのパブリックURLをスキームに基づいて自動的に定義します。

  • 構文: DNSドメインサフィックス

  • 必須: いいえ

  • デフォルト値: 定義されている場合、threescale_cicd_apicast_sandbox_endpointとthreescale_cicd_apicast_production_endpointがAPIのsystem_nameから計算されます。 サンドボックスAPIcastは<system_name>-staging.<wildcard_domain>、本番APIcastは<system_name>.<wildcard_domain>となります。ステージング（-staging）と本番（空）のサフィックスは、threescale_cicd_default_staging_suffixおよびthreescale_cicd_default_production_suffix変数でカスタマイズできます。

  • 例: 次の2つの変数

    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

バックエンドAPIがデプロイされるbasePathを定義し、OpenAPI仕様のbasePathフィールドをオーバーライドします。 resulting 値は3scale APIゲートウェイのマッピングルール定義に使用され、このベースパスがさまざまなメソッド/オペレーションのパスに追加されます。

  • 構文: 開始/のURI部分
  • 必須: いいえ
  • デフォルト値: OpenAPI仕様のbasePathフィールド。
  • 例: /api または /context

threescale_cicd_api_backend_hostname

OpenAPI仕様のhostフィールドをオーバーライドし、バックエンドホスト名を定義します。 resulting 値が欠けている場合、threescale_cicd_private_base_url変数を定義するために使用されます。

  • 構文: オプションのポートを持つFQDN
  • 必須: いいえ
  • デフォルト値: OpenAPI仕様のhostフィールド。
  • 例: mybackend.acme.corp または mybackend.acme.corp:8080

threescale_cicd_api_backend_scheme

OpenAPI仕様のschemesフィールドをオーバーライドし、バックエンドに接続するために使用するスキームを定義します。 resulting 値が欠けている場合、threescale_cicd_private_base_url変数を定義するために使用されます。

  • 構文: httpまたはhttps
  • 必須: いいえ
  • デフォルト値: OpenAPI仕様のschemeフィールドの最初の項目で、欠けている場合はhttpにデフォルト設定されます。
  • 例: https

threescale_cicd_private_base_url

3scaleプライベートベースURLを定義します。

  • 構文: <scheme>://<host>:<port>
  • 必須: いいえ
  • デフォルト値: <threescale_cicd_api_backend_scheme>://<threescale_cicd_api_backend_hostname>
  • 例: http://mybackend.acme.corp:8080

threescale_cicd_apicast_policies_cors

APICastゲートウェイにCORSポリシーを有効にします。APIがクロスオリジンおよびブラウザベースの呼び出しをサポートする必要がある場合、一部のパスに対するOPTIONS動詞をOpenAPI仕様ファイルに含めていなかった場合...

  • 構文: ブール値 yesまたはno
  • 必須: いいえ
  • デフォルト値: no
  • 例: APICastでCORSポリシーを有効にする場合はyes。

threescale_cicd_openapi_smoketest_operation

スモークテストに使用するOpenAPI仕様メソッドを定義します。

  • 構文: OpenAPI仕様メソッドのoperationId
  • 必須: いいえ
  • デフォルト値: なし。この変数が未定義で、OpenAPI仕様にx-threescale-smoketests-operationでフラグ付けされた操作がない場合、スモークテストはスキップされます。
  • 例: GetName

threescale_cicd_api_environment_name

同じAPIを同じ3scaleインスタンス上に複数回デプロイして名前の衝突を防ぐために、すべてのサービスに環境名をプレフィックスとして付けます。

  • 構文: 小文字の英数字 + アンダースコア
  • 必須: いいえ
  • デフォルト値: なし、プレフィックスが付けられません。
  • 例: dev、test または prod

threescale_cicd_validate_openapi

公式スキーマに対してOpenAPI仕様ファイルを検証します。そのために、go-swaggerツールが使用されます。

このツールを、PATHのどこかに事前にインストールできます。あるいは、threescale_cicd_goswagger_command追加変数でswaggerコマンドへの完全なパスを指定することもできます。

ツールが不足している場合、自動的に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

このAPIのためにサポートされるOAuthフローのリストをオーバーライドまたは更新します。

  • 構文: 文字列の配列（[ 'application', 'accessCode' ]）
  • 必須: いいえ
  • デフォルト値: OpenAPI仕様ファイル内のsecuritySchemeオブジェクトのflowフィールド。
  • 例:
    • 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管理 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.