Apigee Adapter for Istio 1.1.0 以降をインストールする

このトピックでは、Apigee Adapter for Istio 1.1.0 以降のリリースを設定、構成、テストする方法について説明します。

リリースノート

リリースノートについては、https://github.com/apigee/istio-mixer-adapter/releases をご覧ください。Istio 1.1.0 以降のバージョンと一緒に、最新バージョンの Apigee Adapter for Istio をインストールすることをおすすめします。

対象

Apigee Adapter for Istio のドキュメント全体を通して、Kubernetes と Istio 両方の基本事項を理解していることを前提としています。また、API プロキシ、プロダクト、デベロッパー アプリ、API キーなどの Apigee の基本的なコンセプトを理解している Apigee Edge ユーザーであることを前提としています。

前提条件

Istio とともに Apigee アダプタをインストールするには、次の前提条件を満たしている必要があります。

Apigee アカウントが必要

Apigee アダプタを構成して使用するには Apigee アカウントが必要であり、組織名、ユーザー名（通常は Apigee アカウントのメールアドレス）、アカウントのパスワードを知っている必要があります。

Kubernetes クラスタの要件

Kubernetes の推奨バージョンについては、Istio のドキュメントをご覧ください。最新バージョンの Istio のドキュメントは、https://istio.io/docs にあります。以前のバージョンの Istio のドキュメントは、https://archive.istio.io/ にあります。

Kubernetes クラスタを作成する方法については、Kubernetes ドキュメント サイトの Setup をご覧ください。

Istio のインストール

Istio 1.1.0 以降では、カスタム Mixer イメージが不要になりました。代わりに、Apigee アダプタはスタンドアロン サービスとして動作でき、それを呼び出す方法を構成で Mixer に指示できます。

  1. 正式な Istio インストール手順に従って Istio をクラスタにインストールします。

  2. ポリシー制御が明示的に有効になっていることを確認します。詳細については、Enabling Policy Enforcement をご覧ください。

Edge Public Cloud 上のコンポーネントをプロビジョニングする

Edge Public Cloud を使用している場合、次の手順に従って、アダプタが Apigee Edge と通信するために必要なコンポーネントをプロビジョニングします。プロビジョニングでは、Apigee Edge 組織にプロキシをインストールして、証明書を設定し、後でアダプタを構成するときに必要となる認証情報を生成します。

  1. 使用しているオペレーティング システム用の Apigee Adapter for Istio リリース パッケージをダウンロードします。Istio 1.1.0 以降のバージョンと一緒に、最新バージョンの Apigee Adapter for Istio をインストールすることをおすすめします。
  2. リリース ファイルを解凍します。
  3. ルートフォルダの名前を apigee-istio-adapter に変更します。
  4. cd を実行してルートフォルダに移動します。

  5. PATH に apigee-istio コマンド実行可能ファイルを追加して、簡単にアクセスできるようにします。

  6. 次のコマンドを実行して Apigee Edge をプロビジョニングし、出力をファイルにリダイレクトします。このファイルは後でアダプタを構成するときに使用します。このコマンドには認証が必要です。Basic 認証では Apigee のユーザー名 / パスワードを使用できます。また、OAuth または SAML トークンを使用して認証することもできます。

    Basic 認証を使用する場合:

    apigee-istio provision -u username -p password -o organization \
-e environment > samples/apigee/handler.yaml

    トークンを使用する場合:

    apigee-istio provision -t token -o organization \
-e environment > samples/apigee/handler.yaml

    ここで、パラメータ organization、environment、username、password は Apigee アカウントの値です。ユーザー名は通常、Apigee アカウントのメールアドレスです。使用する場合、token パラメータはユーザーが生成する必要がある値です。トークンを生成する方法については、get_token の使用および SAML を使用して Management API にアクセスするをご覧ください。

    ホーム ディレクトリに .netrc ファイルがある場合、apigee-istio はユーザー名とパスワード、またはトークンを自動的に取得します。詳細については、.netrc に認証情報を指定するをご覧ください。

    例

    apigee-istio provision -o docs -e test -u jdoe@example.com \
-p abc123 > samples/apigee/handler.yaml

    出力例

    出力は samples/apigee/handler.yaml で確認できます。出力の最後にある「spec」ブロックが重要です。このブロックに Apigee アダプタを構成するために必要なキーとシークレットが含まれています。実際の出力ファイルの値は、以下に示す値とは異なります。

    # Istio handler configuration for Apigee gRPC adapter for Mixer
apiVersion: config.istio.io/v1alpha2
kind: handler
metadata:
  name: apigee-handler
  namespace: istio-system
spec:
  adapter: apigee
  connection:
    address: apigee-adapter:5000
  params:
    apigee_base: https://istioservices.apigee.net/edgemicro
    customer_base: https://myorg-env.apigee.net/istio-auth
    org_name: myorg
    env_name: myenv
    key: 06a40b65005d03ea24c0d53de69ab795590b0c332526e97fed549471bdea00b9
    secret: 93550179f344150c6474956994e0943b3e93a3c90c64035f378dc05c98389633

  7. テストサービスをインストールするのセクションに進みます。

Edge Private Cloud 上のコンポーネントをプロビジョニングする

Edge Private Cloud を使用している場合、次の手順に従って、アダプタが Apigee Edge と通信するために必要なコンポーネントをプロビジョニングします。プロビジョニングでは、Apigee Edge 組織にプロキシをインストールして、証明書を設定し、後でアダプタを構成するときに必要となる認証情報を生成します。

  1. cd を実行して、Apigee アダプタがインストールされているディレクトリ apigee-istio-adapter. に移動します。

  2. PATH に apigee-istio コマンド実行可能ファイルを追加して、簡単にアクセスできるようにします。

  3. 次のコマンドを実行して Apigee Edge をプロビジョニングします。便宜上、出力をファイルにリダイレクトします。後でアダプタを構成するときに出力値を使用します。このコマンドには認証が必要です。Basic 認証では Apigee のユーザー名 / パスワードを使用できます。また、OAuth または SAML トークンを使用して認証することもできます。

    Basic 認証を使用する場合:

    apigee-istio provision -o organization -e environment -u username \
-p password --managementBase management server URL > samples/apigee/handler.yaml

    トークンを使用する場合:

    apigee-istio provision -o organization -e environment -u username \
-t token --managementBase management server URL > samples/apigee/handler.yaml

    ここで、パラメータ organization、environment、username、password は Apigee アカウントの値です。ユーザー名は通常、Apigee アカウントのメールアドレスです。使用する場合、token パラメータはユーザーが生成する必要がある値です。トークンを生成する方法については、get_token の使用および SAML を使用して Management API にアクセスするをご覧ください。

    ホーム ディレクトリに .netrc ファイルがある場合、apigee-istio はユーザー名とパスワードを自動的に取得します。詳細については、.netrc に認証情報を指定するをご覧ください。

    例

    apigee-istio provision -o docs -e test -u jdoe@example.com -p abc123 \
--managementBase http://192.162.55.100:8080 > samples/apigee/handler.yamlcode

    ここで、パラメータ organization、environment、username、password は Apigee アカウントの値です。ユーザー名は通常、Apigee アカウントのメールアドレスです。

    出力例

    出力は samples/apigee/handler.yaml で確認できます。出力の最後にある「spec」ブロックが重要です。このブロックに Apigee アダプタを構成するために必要なキーとシークレットが含まれています。実際の出力ファイルの値は、以下に示す値とは異なります。

    # istio handler configuration for apigee adapter
apiVersion: config.istio.io/v1alpha2
kind: apigee
metadata:
  name: apigee-handler
  namespace: istio-system
spec:
  apigee_base: https://edgemicroservices.apigee.net/edgemicro
  customer_base: https://myorg-myenv.apigee.net/istio-auth
  org_name: myorg
  env_name: myenv
  key: 06a40b65005d03ea24c0d53de69ab795590b0c332526e97fed549471bdea00b9
  secret: 93550179f344150c6474956994e0943b3e93a3c90c64035f378dc05c98389633

  4. テストサービスをインストールするのセクションに進みます。

テストサービスをインストールする

このシンプルなサービスを後で使用してテストを行い、Apigee アダプタを含む Istio が正しく機能していることを確認します。後で、Apigee 固有のポリシールールを使用してアダプタを構成します。

  1. cd を実行して、システム上の Istio インストール ディレクトリに移動します。次に例を示します。

    cd $PATH_TO_PARENT_DIR/istio-1.4.0

  2. デフォルトの名前空間についての自動サイドカー インジェクションを有効にします。

    kubectl label namespace default istio-injection=enabled

    デフォルトでは、Istio サービスは default 名前空間にデプロイされます。ただし、別の名前空間にサービスをデプロイする場合は、サービスをデプロイする前に、その名前空間についてサイドカー インジェクションを有効にする必要があります。

  3. 次のコマンドを実行して、テストサービスとゲートウェイをデプロイします。

    kubectl apply -f samples/helloworld/helloworld.yaml

  4. ゲートウェイをデプロイします。

    kubectl apply -f samples/helloworld/helloworld-gateway.yaml

  5. しばらくしてから、サービスがデプロイされていることを確認します。次に例を示します。

    kubectl get pods

NAME                                          READY     STATUS            RESTARTS      AGE
helloworld-v1-55cd697cc8-tff7v   2/2            Running            0                       1m
helloworld-v2-5df5d6ff46-fkw9s   2/2            Running            0                       1m

    各ポッドに 2 つのサービス インスタンスが稼働中であることがわかります。1 つのインスタンスは helloworld サービスで、もう 1 つはサイドカー プロキシとも呼ばれる Istio プロキシです。

  6. 次のコマンドを使用して、ロードバランサの外部 IP アドレスを返します。これは、テストサービスを呼び出すために使用する IP です。

    kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

    出力は IP アドレスです。たとえば、104.154.82.135 のように出力されます。

  7. 外部 IP アドレスを使用して環境変数を設定します。

    export HELLOWORLD_URL=IP_ADDRESS

    例:

    export HELLOWORLD_URL=104.154.82.135

  8. helloworld サービスを次のようにして呼び出します。

    curl http://$HELLOWORLD_URL/hello

    サービスがデプロイされると（数分かかる場合があります）、その API を呼び出してステータスが 200 の正常な「hello」レスポンスを受け取ることができます。次に例を示します。

    Hello version: v2, instance: helloworld-v2-78f774ff78-zmlzt

404 エラーのトラブルシューティング

helloworld サービスを呼び出したときに 404 エラーが発生した場合は、問題のトラブルシューティングに次の情報が役立つ場合があります。

helloworld サンプル サービスは、hosts 値として「*」を使用する helloworld-gateway でデプロイされます。この設定は samples/helloworld/helloworld.yaml で確認できます。この同じゲートウェイ hosts 値を使用する別のサービス（Istio Bookinfo サービスなど）を以前にデプロイしていた場合、helloworld サービスへの API 呼び出しは 404 ステータスで失敗します。

他のサービス（Bookinfo など）の構成は、その構成ファイルを調べることによって確認できます。たとえば、Bookinfo サービスをメッシュにデプロイした場合は、ファイル samples/networking/bookinfo-gateway.yaml を確認できます。他のサービスが「*」host 設定でゲートウェイをデプロイしている場合、このことが問題の原因になります。問題を解決するために、他のサービスのゲートウェイを削除できます。次に例を示します。

kubectl delete gateway bookinfo-gateway

または、他のサービスを完全に削除することもできます。

Apigee アダプタを構成する

Istio がインストールされて実行されているため、Apigee アダプタに構成するルールを追加する必要があります。

  1. 現在のディレクトリが、Apigee アダプタがインストールされているディレクトリ（apigee-istio-adapter.）であることを確認します。

  2. 次の Apigee アダプタ構成を Istio に適用します。

    kubectl apply -f samples/apigee

  3. 構成をテストするために、helloworld サービスを呼び出します。PERMISSION_DENIED エラーを受け取るはずです。

    curl http://$HELLOWORLD_URL/hello

PERMISSION_DENIED:apigee-handler.apigee.istio-system:missing authentication

    このエラーは、API 呼び出しが Apigee によって検証され、アダプタが想定どおりに機能していることを示しています。API 呼び出しを正常に行うには、API キーを提供する必要があります。次のセクションでは、キーを取得し、キーを使用してサービスを呼び出す方法について説明します。

API キーを取得する

API キーを取得するには、Apigee Edge でデベロッパー、API プロダクト、デベロッパー アプリを作成する必要があります。

1. Apigee Edge にログインする

  1. 以下の手順を実行するために、Edge UI にログインします。https://login.apigee.com/login にアクセスし、Apigee 認証情報でログインします。
  2. UI で、Apigee Edge コンポーネントをプロビジョニングするで指定したのと同じ組織を選択します。

2. デベロッパーを作成する

テスト用の既存のデベロッパーを使用するか、次のようにしてデベロッパーを新しく作成できます。

  1. サイド ナビゲーション メニューで [Publish] > [Developers] を選択します。
  2. [+ Developer] をクリックします。
  3. 新しいデベロッパーを作成するためにダイアログに入力します。任意のデベロッパー名 / メールを使用できます。

3. API プロダクトを作成する

以下のプロダクト作成の例に従ってください。プロダクト構成オプションの詳細については、API のプロダクト構成についてをご覧ください。

  1. サイド ナビゲーション メニューで [Publish] > [API Products] を選択します。
  2. [+ API Product] をクリックします。[Product Details] ページが表示されます。

  3. 次のように、[Product Details] ページに入力します。指示があるまで [Save] をクリックしないでください。

    [Name] hello-istio-product
    [Display Name] Istio Apigee Test Product
    [Environment] test および prod
    [Access] Public
    [Key Approval Type] Automatic

  4. [Quota] フィールドで、[5 requests every 1 minute] を指定します。

    割り当てとは、1 時間、1 日、1 週間または 1 か月にアプリが API に送信できるリクエスト メッセージの数を指定したものです。アプリが割り当て上限に達すると、後続の API 呼び出しは拒否されます。割り当て構成は、後で Helloworld サービスを呼び出すときにテストします。割り当てについてもご覧ください。

    alt_text

  5. [API resources] セクションで、[Add a proxy] をクリックします。

  6. istio-auth という名前のプロキシを選択します。

  7. [Paths] に「/ 」（単一のスラッシュ）を入力します。

  8. ページの下半分で、[+ Add Custom Resource] をクリックします。

  9. リソースを / （単一のスラッシュ）に設定します。

  10. また、ページの下部で、[+ API Proxy] をクリックします。

  11. [Istio services] で、[Add an Istio service] をクリックします。

  12. [+ Istio Service] をクリックします。

  13. サービス名 helloworld.default.svc.cluster.local を追加します。また、apigee-istio binding コマンドを使用して、プロダクトを Istio サービスに関連付けることもできます。

  14. [Save] をクリックします。

4. デベロッパー アプリを作成する

  1. サイド ナビゲーション メニューで [Publish] > [Apps] を選択します。
  2. [+ App] をクリックします。[Developer App Details] ページが表示されます。

  3. 次のように、[Developer App] ページに入力します。指示があるまで保存しないでください。

    [Name] hello-istio-app
    [Display Name] Istio Apigee Test App
    [Developer] 作成したテスト デベロッパーを選択するか、どのようなデベロッパーでもかまいません。

  4. [Credentials] セクションで [+ Add product] をクリックし、作成したプロダクト（hello-istio-product.）を選択します。

  5. [Create] をクリックします。

  6. [Credentials] で、[Key] の横にある [Show] をクリックします。

  7. [Consumer Key] の値をコピーします。この値が、Istio メッシュの helloworld サービスに対して /hello API 呼び出しを行うために使用する API キーです。

API キーをテストする

これで、デベロッパー アプリからコピーした「コンシューマ キー」を使用して、helloworld サービスへの API 呼び出しを行うことができます。

curl http://$HELLOWORLD_URL/hello -H "x-api-key: Your consumer key"

次に例を示します。

curl http://$HELLOWORLD_URL/hello -H "x-api-key: XsU1R4zGXz2ERxa0ilYQ5szwuljr5bB"

正常に終了すると、次のような出力と HTTP ステータス 200 が返されます。

Hello version: v1, instance: helloworld-v1-8488567bb6-5cqnf

割り当て構成をテストする

上記で、API プロダクトの割り当てに 1 分あたり 5 回の呼び出しを構成したことを思い出してください。/hello API を短時間のうちに連続して複数回呼び出し、割り当て構成をテストします。API の呼び出しが 1 分間に 5 回を超えると、次のエラーが表示されます。

RESOURCE_EXHAUSTED:apigee-handler.apigee.istio-system:quota exceeded

Edge UI で分析データを表示する

Apigee アダプタは API トラフィックを処理するとき、Apigee Edge Analytics プラットフォームに分析データを非同期に送信します。このデータは、Edge UI の Apigee Analytics ダッシュボードで表示できます。分析ロギングについてもご覧ください。