Apigee Adapter for Istio 1.1.x をインストールする

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

対象

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

前提条件

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

Apigee アカウントが必要

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

Kubernetes クラスタの要件

Kubernetes クラスタの最小要件は次のとおりです。

  • Kubernetes バージョン 1.11 以降
  • kubectl バージョン 1.9 以降

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

Istio のインストール

Istio 1.1.x では、カスタム 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 リリース パッケージをダウンロードします。
  2. リリース ファイルを解凍します。
  3. ルートフォルダの名前を apigee-istio-adapter に変更します。
  4. cd を実行してルートフォルダに移動します。
  5. apigee-istio コマンド実行可能ファイルを PATH に追加して、簡単にアクセスできるようにします。

  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

    ここで、パラメータ organizationenvironmentusernamepassword は 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. apigee-istio コマンド実行可能ファイルを PATH に追加して、簡単にアクセスできるようにします。

  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

    ここで、パラメータ organizationenvironmentusernamepassword は 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

    ここで、パラメータ organizationenvironmentusernamepassword は 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.1.2
  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 というファイルを確認できます。他のサービスが「*」という hosts 設定でゲートウェイをデプロイした場合、それが問題の原因になります。問題を解決するために、他のサービスのゲートウェイを削除できます。次に例を示します。

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 ダッシュボードで表示できます。分析ロギングについてもご覧ください。