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

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

対象

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

前提条件

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

Apigee アカウントが必要

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

Kubernetes クラスタの要件

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

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

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

Istio のインストール

次に示す手順では、Apigee アダプタを含む Istio のバージョンをインストールする方法について説明します。Istio をすでにクラスタにインストールしていて、Apigee によって構築された Mixer で既存の Istio Mixer コンポーネントをアップグレードするだけの場合は、Apigee アダプタで既存の Istio をアップグレードするをご覧ください。

Helm パッケージ マネージャーを入手する

アダプタのインストールには、Kubernetes 用の Helm パッケージ マネージャーを使用します。Helm をインストールして構成するには、Helm の Quickstart Guide に記載されている手順に従ってください。Helm のドキュメントで説明されているように、Helm クライアントと Tiller サーバー コンポーネントがインストールされている必要があります。

アダプタ ソフトウェアをダウンロードする

ソフトウェアをシステムにダウンロードします。

  1. 使用しているオペレーティング システム用の Apigee Adapter for Istio リリース パッケージをダウンロードします。
  2. リリース ファイルを解凍します。
  3. ルートフォルダの名前を apigee-istio-adapter に変更します。

これで、Istio とともにアダプタをインストールする準備が整いました。

Helm を使用して Istio をインストールする

次に示す手順では、Apigee アダプタが含まれた新しい Istio インストールを作成する方法について説明します。この手順は、現在 Istio がインストールされていない場合に使用します。

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

    cd $PATH_TO_PARENT_DIR/istio-1.0.7

  2. apigee-istio-adapter ディレクトリへのパスを指定して、環境変数をエクスポートします。

    export APIGEE_ADAPTER=$PATH_TO_PARENT_DIR/apigee-istio-adapter

  3. Tiller が kube-system 名前空間で動作していることを確認します。

    kubectl get pods -n kube-system

    Tiller が動作していない場合は、Istio ドキュメントの Installation with Helm をご覧ください。

  4. 次のいずれかの Helm コマンド オプションを使用します。これらのオプションの詳細については、Istio ドキュメントの Installation with Helm をご覧ください。

    1. オプション 1:

      helm install install/kubernetes/helm/istio --name istio \
--namespace istio-system --values $APIGEE_ADAPTER/install/mixer/helm.yaml

    2. オプション 2:

      helm template install/kubernetes/helm/istio --name istio \
--namespace istio-system --values $APIGEE_ADAPTER/install/mixer/helm.yaml > istio.yaml

  5. クラスタにデプロイされている Istio サービスを表示します。

    kubectl get service -n istio-system

  6. Istio ポッドを表示し、すべてが動作していることを確認します。

    kubectl get pods -n istio-system

    Istio ドキュメント サイトの Verifying the installation もご覧ください。

次に、Apigee Edge 組織に必要なコンポーネントをプロビジョニングし、「hello world」アプリケーションをサービス メッシュにデプロイしてテストします。

Apigee Mixer で既存の Istio をアップグレードする

Istio がすでにインストールされている場合は、次の手順に従って、既存の istio-mixer コンポーネントを、Apigee アダプタが組み込まれた Mixer に置き換えます。

  1. Apigee Mixer がインストールされているかどうかを確認します。次のコマンドを実行すると、現在 Istio 環境にデプロイされている Istio Mixer コンテナ イメージに関する情報が表示されます。

    kubectl get deployment/istio-policy -n istio-system -o yaml | grep image.*istio-mixer
kubectl get deployment/istio-telemetry -n istio-system -o yaml | grep image.*istio-mixer

    次のような出力が表示された場合、Apigee Mixer がインストールされているため、残りの手順をスキップできます。

    image: gcr.io/apigee-api-management-istio/istio-mixer:1.0.7

  2. Apigee アダプタがインストールされていない場合は、次のコマンドを使用してインストールします。

    kubectl -n istio-system set image deployment/istio-telemetry mixer=gcr.io/apigee-api-management-istio/istio-mixer:istio_version
kubectl -n istio-system set image deployment/istio-policy mixer=gcr.io/apigee-api-management-istio/istio-mixer:istio_version

    ここで、istio_version は、実行している Istio のバージョンです。

    例:

    kubectl -n istio-system set image deployment/istio-telemetry mixer=gcr.io/apigee-api-management-istio/istio-mixer:1.0.7
kubectl -n istio-system set image deployment/istio-policy mixer=gcr.io/apigee-api-management-istio/istio-mixer:1.0.7

  3. ここで、ステップ 1 を繰り返して、Apigee アダプタがインストールされていることを確認します。

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

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

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

  2. apigee-istio コマンド実行可能ファイルを PATH に追加します。このステップにより、アダプタ用の apigee-istio コマンドライン インターフェースを実行できます。次に例を示します。

    export PATH=$PATH:$PWD/apigee-istio

  3. 次のステップでは、ファイル samples/apigee/handler.yaml を上書きします。したがって、操作を行う前に元のファイルの名前を変更します。

    cp samples/apigee/handler.yaml samples/apigee/handler.sav

  4. Apigee Edge をプロビジョニングするための以下のスクリプトを実行し、出力をファイルにリダイレクトします。このファイルは後でアダプタを構成するときに使用します。

    provision コマンドには認証が必要です。Basic 認証では Apigee のユーザー名 / パスワードを使用できます。また、OAuth または SAML トークンを使用して認証することもできます。

    Basic 認証を使用する場合:

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

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

    apigee-istio provision -o [organization] -e [environment] -t [token] > 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 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

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

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

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

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

  2. apigee-istio コマンド実行可能ファイルを PATH に追加します。このステップにより、アダプタ用の apigee-istio コマンドライン インターフェースを実行できます。次に例を示します。

    export PATH=$PATH:$PWD/apigee-istio

  3. 次のステップでは、ファイル samples/apigee/handler.yaml を上書きします。したがって、操作を行う前に元のファイルの名前を変更します。

    cp samples/apigee/handler.yaml samples/apigee/handler.sav

  4. 次のスクリプトを実行して Apigee Edge をプロビジョニングします。便宜上、出力をファイルにリダイレクトします。後でアダプタを構成するときに出力値を使用します。

    provision コマンドには認証が必要です。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</code> <code>> samples/apigee/handler.yaml

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

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

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

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

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

    cd $PATH_TO_PARENT_DIR/istio-1.0.7

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

    kubectl label namespace default istio-injection=enabled

    デフォルトでは、Istio サービスは default 名前空間にデプロイされます。しかし、異なる名前空間にサービスをデプロイする場合は、サービスをデプロイする前に、その名前空間に対するサイドカー インジェクションを有効にする必要があります。たとえば、サービスを test 名前空間にデプロイする場合は、次のようにします。

    kubectl label namespace test istio-injection=enabled

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

    kubectl apply -f samples/helloworld/helloworld.yaml

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

    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 プロキシです。

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

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

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

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

    export HELLOWORLD_URL=IP_ADDRESS<104.154.82.135>

    例:

    export HELLOWORLD_URL=104.154.82.135

  7. 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. ファイル samples/apigee/handler.yaml を開き、以前に実行した apigee-istio provision コマンドで返された情報が含まれていることを確認します。ファイルを変更する必要はありません。次に例を示します。実際の値は以下に示す値とは異なります。

    apiVersion: config.istio.io/v1alpha2
kind: apigee
metadata:
  name: apigee-handler
  namespace: istio-system
spec:
  apigee_base: https://istioservices.apigee.net/edgemicro
  customer_base: https://myorg-test.apigee.net/istio-auth
  org_name: myorg
  env_name: test
  key: 3acfcf6ec5e2014d9cfabee4f7cb4d438ab309ed6de1ebb9cb8f9fb46e45db3f
  secret: 52cf0c44d20c513c4fe6a41f7bb9a489806f3e5af9ddde9ae9d67776a0a3b779

  3. ファイルを閉じます。

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

    kubectl apply -f samples/apigee/definitions.yaml
kubectl apply -f samples/apigee/handler.yaml
kubectl apply -f samples/apigee/rule.yaml

  5. 構成をテストするために、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. ページの下半分で、[+ Add Custom Resource] をクリックします。

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

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

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

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

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

    ダイアログの設定は次のようになります。

    alt_text

  11. [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] セクションで [+ Product] をクリックし、作成したプロダクト（hello-istio-product.）を選択します。

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

  6. すべてのデベロッパー アプリを一覧表示するページに戻ります。

  7. 作成したアプリ（hello-istio-app）を選択します。

  8. [Consumer Key] の横にある [Show] をクリックします。

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