Google Cloud Apigee サポートケースに関するベスト プラクティス

Apigee X のドキュメントを表示中。
Apigee Edge のドキュメントを表示する。

サポートケースに必須情報を詳細を記載していただければ、Google Cloud Apigee サポートチームが迅速かつ効率的に対応できるようになります。サポートケースに重要な詳細が欠落していると、追加の情報をリクエストする必要性が生じます。こうなると、複数回のやり取りが発生する可能性があります。このやり取りは時間を要するため、問題解決が遅れてしまう可能性があります。このベスト プラクティス ガイドでは、テクニカル サポートケースを迅速に解決するために必要な情報について説明します。

問題の説明

問題には、何が発生したか(および何が発生すると想定されていたか)、いつ、どのように発生したかに関する詳細を説明する情報を含める必要があります。適切な Apigee サポートケースには、Apigee の各プロダクトに関する以下の主要な情報が記載される必要があります。

鍵情報 説明 Apigee Cloud(Apigee on Google Cloud / Apigee Edge for Public Cloud) Apigee Edge for Private Cloud Apigee ハイブリッド
プロダクト 問題が発生している具体的な Apigee プロダクト(可能な場合はバージョン情報も記載)
  • バージョン
  • ハイブリッド バージョン
問題の詳細 問題を概説する明確で詳細な説明(ある場合はエラーメッセージの全文も記載)。
  • エラー メッセージ
  • デバッグツールの出力
  • 問題を再現する手順
  • 完全な API リクエスト / コマンド
  • エラー メッセージ
  • デバッグツールの出力
  • 問題を再現する手順
  • 完全な API リクエスト / コマンド
  • コンポーネント診断ログ
  • エラー メッセージ
  • デバッグツールの出力
  • 問題を再現する手順
  • 完全な API リクエスト / コマンド
  • コンポーネント診断ログ
  • Cloud Monitoring の指標
時間 問題が発生した具体的なタイムスタンプと問題の持続時間
  • 問題が発生した日時とタイムゾーン
  • 問題が発生した期間
  • 問題が発生した日時とタイムゾーン
  • 問題が発生した期間
  • 問題が発生した日時とタイムゾーン
  • 問題が発生した期間
設定 問題の発生場所に関する詳細情報
  • 組織名
  • 環境名
  • API プロキシの名前
  • リビジョン
  • ネットワーク トポロジ
  • 失敗した Edge コンポーネント

次のセクションで、これらのコンセプトについて詳しく説明します。

プロダクト

Apigee Cloud(Apigee on Google Cloud / Apigee Edge on Public Cloud)、Apigee Edge on Private CloudApigee ハイブリッドといった、さまざまな Apigee プロダクトがあるので、問題が発生している特定のプロダクトに関する固有の情報をお知らせください。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts
Public Cloud 組織で API プロキシ OAuth2 をデプロイできませんでした...

API プロキシをデプロイできませんでした

(問題が発生している Apigee プロダクトをお知らせください。)

Edge Private Cloud バージョン 4.50.00 で次のエラーが発生し、インストールが失敗しました...

Private Cloud のセットアップでインストールに失敗しました。

(バージョン情報が欠落しています)

Apigee ハイブリッド バージョン 1.3cqlsh を使用して Cassandra にアクセスすると、以下のエラーが発生します...

cqlsh を使用して Cassandra にアクセスできません。

(ハイブリッド バージョンの情報が欠落しています)

問題の詳細

エラー メッセージ(ある場合)、想定されていた挙動、実際に確認された挙動など、確認される問題に関する情報を正確に提供します。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts

新しい edgemicro プロキシ edgemicro_auth が次のエラーで失敗します。

{"error":"missing_authorization","error_description":"Missing Authorization header"}

今日作成された新しい edgemicro プロキシが機能しません

(プロキシ名が不明です。また、プロキシがエラーを返しているか、予期しないレスポンスを返しているか不明瞭です。)

クライアントが、API プロキシへのリクエスト中に次のエラー メッセージで 500 エラーを受け取ります。

{"fault":{"faultstring":"Execution of JSReadResponse failed with error: Javascript runtime error: \"TypeError: Cannot read property \"content\" from undefined. (JSReadResponse.js:23)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

クライアントが、API プロキシへのリクエスト中に 500 エラーを受け取ります。

500 エラーを伝えるだけでは、問題を調査するために必要な情報として不十分です。実際に確認されるエラー メッセージとエラーコードを伝える必要があります。)

時間

時間は非常に重要な情報です。この問題に最初に気付いたのはいつか、問題がどの程度継続したか、まだ問題が継続中かをサポート エンジニアに知らせることが重要です。

問題を解決するサポート エンジニアがお客様と同じタイムゾーンにいない場合もあります。そのため、時間を相対的に説明してしまうと、問題の診断が難しくなります。そのため、ISO 8601 形式で日時を指定し、問題がいつ発生したかに関する情報を正確に伝えることをおすすめします。

次の表で例をいくつか示します。DOs 列は問題が発生した正確な時刻と期間を、DON'Ts 列には問題が発生した時間に関するあいまいで不正確な情報を示しています。

DOs DON'Ts
昨日の 2020-11-06 17:30 PDT から 2020-11-06 17:35 PDT の間に、多数の 503s が確認されました。

昨日午後 5 時 30 分に多数の 503s が 5 分間確認されました。

(暗示的に指定されたこの日付形式を使用せざるを得なくなります。また、この問題が確認された時刻のタイムゾーンが不明瞭です。)

2020-11-09 15:30 IST から 2020-11-09 18:10 IST までの間に、以下の API プロキシで高いレイテンシが確認されました。

先週、一部の API プロキシで高いレイテンシが確認されました。

(この問題が先週のどの日付で確認されたか、どの程度持続したかが不明瞭です。)

設定

問題が発生している場所に関する詳細をお知らせください。使用しているプロダクトに応じて、次の情報が必要です。

  • Apigee Cloud を使用している場合は、複数の組織が存在する可能性があるため、問題が発生している組織やその他の詳細を具体的に把握する必要があります。
    • 組織名と環境名
    • API プロキシ名とリビジョン番号(API リクエストの失敗の場合)
  • Private Cloud を使用している場合、サポートされている数多くのインストール トポロジのうちのいずれかを使用している可能性があります。そのため、データセンターとノードの数など、使用しているトポロジについて説明する必要があります。
  • ハイブリッドを使用している場合、サポートされている数多くのハイブリッド プラットフォームおよびインストール トポロジのうちのいずれかを使用している可能性があります。そのため、データセンターとノードの数など、使用しているハイブリッド プラットフォームとトポロジについて説明する必要があります。

次の表はいくつかの例を示しています。DOs 列は完全な情報を、DON'Ts 列は不完全な情報を示しています。

DOs DON'Ts

2020-11-06 09:30 CST 以降、Edge Public Cloud での 401 エラーの数が増えています。

Edge の設定に関する詳細:

失敗した API の詳細は以下のとおりです。
  組織名: myorg
  環境名: test
  API プロキシ名: myproxy
  リビジョン番号: 3

エラー:

{"fault":{"faultstring":"Failed to resolve API Key variable request.header.X-APP-API_KEY","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

401 エラーの数が増えています。

(使用されているプロダクト、問題がいつから確認されるか、設定の詳細に関する情報が何もありません。)

ゲートウェイ ノードの追加後、Edge Private Cloud バージョン 4.19.06 で Message Processor を起動できません。

診断ログ:
Message Processor のログを添付しました。

ネットワーク トポロジ:
追加のノードを含むファイル network-topology.png を添付しました。

ゲートウェイ ノードの追加後、Edge Private Cloud バージョン 4.19.06 で Message Processor を起動できません。

(Message Processor のログとネットワーク トポロジがありません。)

Apigee ハイブリッド バージョン 1.3 でデバッグが次のエラーで失敗します。

エラー:

Error while Creating trace session for corp-apigwy-discovery, revision 3, environment dev.

Failed to create DebugSession {apigee-hybrid-123456 dev corp-apigwy-discovery 3 ca37384e-d3f4-4971-9adb-dcc36c392bb1}

Apigee ハイブリッドの設定の詳細:

  • Apigee ハイブリッド プラットフォーム:
      Anthos GKE On-Prem バージョン 1.4.0
  • Google Cloud プロジェクト、ハイブリッド組織、ハイブリッド環境
      Google Cloud プロジェクト ID: apigee-hybrid-123456
      Apigee ハイブリッド組織: apigee-hybrid-123456
      Apigee ハイブリッド環境: dev
  • Kubernetes クラスタ名の詳細
      k8sCluster:
      名前: user-cluster-1
      リージョン: us-east1
  • ネットワーク トポロジ
    ファイル network-topology.png を添付しました。
Apigee Hybrid でデバッグに失敗します。

有用な資料

問題に関連するアーティファクトを提供していただければ、確認される挙動をより正確に把握して、分析情報をより多く引き出せるため、問題の解決をスピードアップできます。

このセクションでは、すべての Apigee プロダクトの場合で役立つ有用なアーティファクトについて説明します。

すべての Apigee プロダクトに共通のアーティファクト

次のアーティファクトは、Apigee Cloud(Apigee on Google Cloud / Apigee Edge on Public Cloud)、Apigee Edge on Private Cloud、および Apigee ハイブリッドといったすべての Apigee プロダクトに有用です。

アーティファクト 説明
デバッグツールの出力 デバッグツールの出力には、Apigee プロダクトを通過する API リクエストに関する詳細情報が含まれます。これは、4XX5XX、レイテンシの問題などのランタイム エラーに対して有用です。
スクリーンショット スクリーンショットは、確認される実際の挙動やエラーのコンテキストを伝達するために活用できます。UI やアナリティクスなどで確認されるエラーや問題に対して有用です。
HAR(Http ARchive) HAR は、UI 関連の問題をデバッグするために HTTP セッション ツールによってキャプチャされるファイルです。Chrome、Firefox、Internet Explorer などのブラウザを使用してキャプチャできます。
tcpdumps tcpdump ツールは、ネットワーク経由で送受信された TCP/IP パケットをキャプチャします。これは、TLS handshake エラー、502 エラー、レイテンシの問題など、ネットワーク関連のあらゆる問題に対して有用です。

Apigee Edge for Private Cloud の追加アーティファクト

Apigee Edge for Private Cloud では、問題の診断を迅速に行うために、追加のアーティファクトが必要になる場合があります。

アーティファクト 説明
ネットワーク トポロジ すべてのデータセンター、ノード、各ノードにインストールされているコンポーネントを含む、Private Cloud のセットアップを説明する Edge インストール トポロジ図。
Edge のコンポーネント診断ログ Message Processor、Router、Cassandra など、特定の Apigee Edge コンポーネントに関連する診断ログ。
インストール構成ファイル Apigee Edge のインストールやアップグレード時に使用するサイレント構成ファイル。

このファイルは、インストールや移行の問題が発生したときに、すべての設定が正しいことを検証する際に有用です。

ヒープダンプ ヒープダンプは、Java メモリプロセスのスナップショットです。これは、特定の Edge コンポーネントで高いメモリ使用率や OutOfMemory エラーが発生した場合に有用です。
スレッドダンプ スレッドダンプは、実行中の Java プロセスのすべてのスレッドのスナップショットです。

これは、特定の Edge コンポーネントで高い CPU 使用率や高負荷が発生した場合に有用です。

ハイブリッドの追加アーティファクト

ハイブリッドの場合、問題の診断を迅速に行うために追加のアーティファクトが必要になる場合があります。

アーティファクト 説明
Apigee ハイブリッド プラットフォーム 以下のサポートされているハイブリッド プラットフォームから、使用しているものを指定します。
  • GKE
  • GKE On-Prem
  • AKS(Azure Kubernetes Service)
  • Amazon EKS
  • GKE on AWS
Apigee ハイブリッドと従属コンポーネントのバージョン
  • Apigee ハイブリッド CLI のバージョン:
    apigeectl バージョン
  • Apigee Connect エージェントのバージョン:
    kubectl -n=apigee get pods -l app=apigee-connect-agent -o=json | jq '.items[].spec.containers[].image'
  • Apigee MART のバージョン:
    kubectl -n=apigee get pods -l app=apigee-mart -o=json | jq '.items[].spec.containers[].image'
  • Apigee Synchronizer のバージョン:
    kubectl -n=apigee get pods -l app=apigee-synchronizer -o=json | jq '.items[].spec.containers[].image'
  • Apigee Cassandra のバージョン:
    kubectl -n=apigee get pods -l app=apigee-cassandra -o=json | jq '.items[].spec.containers[].image'
  • Apigee ランタイムのバージョン:
    kubectl -n=apigee get pods -l app=apigee-runtime -o=json | jq '.items[].spec.containers[].image'
  • Kubernetes CLI とサーバーのバージョン:
    kubectl バージョン
  • Istio CLI とサーバーのバージョン:
    istioctl バージョン
ネットワーク トポロジ すべてのデータセンター、Kubernetes クラスタ、名前空間、ポッドを含むハイブリッド セットアップを説明する Apigee インストール トポロジ図。
overrides.yaml ファイル Apigee ハイブリッド ランタイム プレーンをインストールするために各データセンターで使用される overrides.yaml ファイル。
Apigee ハイブリッド デプロイのステータス

各データセンター / Kubernetes クラスタでの次のコマンドの出力。

kubectl get pods -A
kubectl get services -A

Apigee ハイブリッド コンポーネント ログ

ハイブリッド コンポーネント用の Stackdriver ログへのリンクを提供します。または

各データセンター / Kubernetes クラスタで次のコマンドを使用して Apigee ハイブリッド コンポーネント ログを取得し、共有できます。

kubectl -n {namespace} get pods
kubectl -n {namespace} logs {pod-name}

  • Apigee Connect エージェントのログ:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-connect-agent-pod-name}
  • MART のログ:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-mart-pod-name}
  • Synchronizer のログ:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {synchronizer-pod-name}
  • Apigee Cassandra のログ:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-cassandra-pod-name}
  • MP/Apigee ランタイムログ(すべての Apigee ランタイム ポッドのログ):
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-runtime-pod-name}
ログの説明

ポッドに関する詳細情報。

これは、ポッドが CrashLoopBackoff 状態で停止するなどの問題が発生している場合に特に有用です。

kubectl -n apigee describe pod {pod-name}

Cloud Monitoring
  • 指標ダッシュボードへのリンク
  • Cloud Monitoring の指標に関連するダッシュボードのスナップショット。

ケース テンプレートとサンプルケース

このセクションでは、このドキュメントで説明されるベスト プラクティスに基づいた、さまざまなプロダクトのケース テンプレートとサンプルケースを示します。

Apigee Cloud

テンプレート

このセクションでは、Apigee Cloud(Apigee on Google Cloud / Apigee Edge on Public Cloud)のサンプル テンプレートを示します。

問題:

<問題の詳細な説明や、お客様側で確認される挙動の説明を記載します。可能な場合は、プロダクト名とバージョンを記載します。>

エラー メッセージ:

<表示されたエラー メッセージ全体を記載します(ある場合)>

問題の開始時刻(ISO 8601 形式)

問題の終了時刻(ISO 8601 形式)

Apigee の設定の詳細:
  組織名:
  環境名:
  API プロキシ名:
  リビジョン番号:

再現するための手順:

<問題を再現するための手順を記載します(可能な場合)>

診断情報:

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee Cloud(Apigee on Google Cloud / Apigee Edge on Public Cloud)のサンプルケースを示します。

問題:

Public Cloud 組織で 503 Service Unavailable エラーが多数発生しています。問題を確認して解決いただくか、その解決方法を教えていただけますでしょうか。

エラー メッセージ:

{"fault":{"faultstring":"The Service is temporarily available", "detail":{"errorcode":"messaging.adaptors.http.flow.ServiceUnavailable"}}}

問題の開始時刻(ISO 8601 形式): 2020-10-04 06:30 IST

問題の終了時刻(ISO 8601 形式): 引き続き発生中。

Apigee Cloud の設定の詳細:
  組織名: myorg
  環境名: dev
  API プロキシ名: myproxy
  リビジョン番号: 3

再現するための手順:

次の curl コマンドを実行すると問題を再現できます。

curl -X GET 'https://myorg-dev.apigee.net/v1/myproxy'

診断情報:

デバッグツールの出力(trace-503.xml

Apigee Edge for Private Cloud

テンプレート

このセクションでは、Apigee Edge for Private Cloud のサンプル テンプレートを示します。

問題:

<問題の詳細な説明や、お客様側で確認される挙動の説明を記載します。可能な場合は、プロダクト名とバージョンを記載します。>

エラー メッセージ:

<表示されたエラー メッセージ全体を記載します(ある場合)>

問題の開始時刻(ISO 8601 形式)

問題の終了時刻(ISO 8601 形式)

Edge Private Cloud の設定の詳細:

<データセンターやノードなど、Private Cloud のセットアップを説明するネットワーク トポロジを添付します>

再現するための手順:

<問題を再現するための手順を記載します(可能な場合)>

診断情報

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee Edge for Private Cloud のサンプルケースを示します。

問題:

Linux RHEL 7.6Edge Private Cloud 4.19.06 の一部としてノード #10 に Apigee Management Server をインストールしているときに、以下のエラーが発生します。

エラー メッセージ:

<snipped as the output is too long>
Checking for management-server uuid ................................................
Unable to get uuid for management-server.
Error: setup.sh: /opt/apigee/apigee-service/bin/apigee-service exited with unexpected status 1

問題の開始時刻(ISO 8601 形式): インストールするたびに発生

問題の終了時刻(ISO 8601 形式): 該当なし

Edge Private Cloud の設定の詳細:

ファイル network-topology.png を添付しました

再現するための手順:

以下は、上記のエラーが発生したコマンドです。

/opt/apigee/apigee-setup/bin/setup.sh -p ms -f /app/NonProdConfig.txt

診断情報:

以下のファイルを添付しました。

  • エラー メッセージを含め、上記コマンドの完全な出力が記載された output.txt
  • 管理サーバーのログ
  • 構成ファイル NonProdConfig.txt

ハイブリッド

テンプレート

このセクションでは、Apigee ハイブリッドの場合のサンプル テンプレートを示します。

問題:

<問題の詳細な説明や、お客様側で確認される挙動の説明を記載します。可能な場合は、プロダクト名とバージョンを記載します。>

エラー メッセージ:

<表示されたエラー メッセージ全体を記載します(ある場合)>

問題の開始時刻(ISO 8601 形式)

問題の終了時刻(ISO 8601 形式)

Apigee ハイブリッドの設定の詳細:

  • Apigee ハイブリット プラットフォーム

    <ハイブリッドをインストールしたプラットフォームとそのバージョンに関する情報を記載します。>

  • Google Cloud プロジェクト、ハイブリッド組織、ハイブリッド環境:
      Google Cloud プロジェクト ID:
      <Google Kubernetes Engine(GKE)を使用している場合は、クラスタが配置されているプロジェクト ID を必ず指定してください。GKE On-Prem、Azure Kubernetes Service、Amazon EKS を使用している場合は、ログの送信先となるプロジェクト ID を指定します。>
      Apigee ハイブリッド組織:
      Apigee ハイブリッド環境:
  • Apigee ハイブリッドとその他 CLI のバージョン:
      Apigee ハイブリッド CLI(apigeectl)バージョン:
      Kubectl バージョン:
  • Kubernetes クラスタ名の詳細:
      k8sCluster:
      名前:
      リージョン:
  • ネットワーク トポロジ:
    <データセンター、Kubernetes クラスタ、名前空間、ポッドなど、Apigee ハイブリッドのセットアップを説明するネットワーク トポロジを添付します。>
  • overrides.yaml ファイル:
    <overrides.yaml ファイルを添付します>

再現するための手順

<問題を再現するための手順を記載します(可能な場合)>

診断情報:

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee ハイブリッドの場合のサンプル ケースを示します。

問題:

Apigee ハイブリッド バージョン 1.3 で管理 API を実行するとエラーが発生します。

エラー メッセージ:

[ERROR] 400 Bad Request
{
"error": {
"code": 400,
"message": "Error processing MART request: INTERNAL_ERROR",
"errors": [
{
"message": "Error processing MART request: INTERNAL_ERROR",
"domain": "global",
"reason": "failedPrecondition"
}
],
"status": "FAILED_PRECONDITION"
}
}

問題の開始時刻(ISO 8601 形式): 2020-10-24 10:30 PDT から

問題の終了時刻(ISO 8601 形式): 引き続き発生中。

Apigee ハイブリッドの設定の詳細:

  • Apigee ハイブリッド プラットフォーム
    GKE バージョン 1.15.1
  • Google Cloud プロジェクト、ハイブリッド組織、ハイブリッド環境
      Google Cloud プロジェクト ID: apigee-hybrid-123456
      注: これは、クラスタが配置されているプロジェクト ID です。
      Apigee ハイブリッド組織: apigee-hybrid-123456
      Apigee ハイブリッド環境: dev
  • Apigee ハイブリッドとその他 CLI のバージョン:
      Apigee ハイブリッド CLI(apigeectl)バージョン:
        バージョン: 1.2.0
        コミット: ac09109
        ビルド ID: 214
        ビルド時間: 2020-03-30T20:23:36Z
        Go バージョン: go1.12

      Kubectl バージョン:
        クライアント バージョン:
    version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0", GitCommit:"e8462b5b5dc2584fdcd18e6bcfe9f1e4d970a529", GitTreeState:"clean", BuildDate:"2019-06-19T16:40:16Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"darwin/amd64"}

        サーバーのバージョン:
    version.Info{Major:"1", Minor:"14+", GitVersion:"v1.14.10-gke.36", GitCommit:"34a615f32e9a0c9e97cdb9f749adb392758349a6", GitTreeState:"clean",
  • Kubernetes クラスタ名の詳細:
      k8sCluster:
      名前: user-cluster-1
      リージョン: us-east1
  • ネットワーク トポロジ
    ファイル network-topology.png を添付しました
  • overrides.yaml ファイル
    ファイル overrides.yaml を添付しました

再現するための手順:

次の管理 API を実行するとエラーを再現できます。

curl -X GET --header "Authorization: Bearer <TOKEN>" "https://apigee.googleapis.com/v1/organizations/apigee-hybrid-123456/environments/dev/keyvaluemaps"

診断情報:

以下のファイルを添付しました。

  • network-topology.png
  • overrides.yaml file
  • MART のログ
  • Synchronizer のログ