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

現在は、Apigee と Apigee ハイブリッドのドキュメントが表示されています。
Apigee Edge のドキュメントはこちらをご覧ください。

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

問題の説明

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

注: 個別の Apigee プロダクトの詳細については、Apigee プロダクトの比較をご覧ください。

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

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

プロダクト

さまざまな Apigee プロダクト（Apigee on Google Cloud と Apigee ハイブリッド）があるため、どのプロダクトで問題が発生しているかに関する具体的な情報が必要です。

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

DOs	DON'Ts
Apigee on Google Cloud 組織で API プロキシ OAuth2 をデプロイできませんでした。	API プロキシをデプロイできませんでした （問題が発生している Apigee プロダクトをお知らせください。）
Apigee ハイブリッド バージョン 1.3 で cqlsh を使用して 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 on Google Cloud を使用している場合は、複数の組織が存在する可能性があるため、問題が発生している組織やその他の詳細を具体的に把握する必要があります。
  • 組織名と環境名
  • API プロキシ名とリビジョン番号（API リクエストの失敗の場合）
• ハイブリッドを使用している場合、サポートされている数多くのハイブリッド プラットフォームおよびインストール トポロジのうちのいずれかを使用している可能性があります。そのため、データセンターとノードの数など、使用しているハイブリッド プラットフォームとトポロジについて知る必要があります。

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

DOs	DON'Ts
2020-11-06 09:30 CST 以降、Apigee on Google Cloud で 401 のエラーが増えています。 Apigee の設定の詳細: 失敗した 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 エラーの数が増えています。 （使用されているプロダクト、問題がいつから確認されるか、設定の詳細に関する情報が何もありません。）
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 でデバッグに失敗します。

有用な資料

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

注意: ケースの説明、更新、添付ファイルで、TLS 証明書に関連付けられているユーザー名、パスワード、API キー、OAuth トークン、秘密鍵などの機密情報を共有しないでください。

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

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

次のアーティファクトは、すべての Apigee プロダクト（Apigee on Google Cloud と Apigee ハイブリッド）で有用です。

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

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

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

アーティファクト	説明
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 クラスタ、Namespace、Pod を含むハイブリッド セットアップを説明する Apigee インストール トポロジ図。
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 ランタイム Pod のログ）: kubectl -n {namespace} get pods kubectl -n {namespace} logs {apigee-runtime-pod-name}
ログの説明	Pod に関する詳細情報。 これは、Pod が CrashLoopBackoff 状態で停止するなどの問題が発生している場合に特に有用です。 kubectl -n apigee describe pod {pod-name}
Cloud Monitoring	指標ダッシュボードへのリンク Cloud Monitoring の指標に関連するダッシュボードのスナップショット。

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

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

Apigee Cloud

テンプレート

このセクションでは、Apigee on Google Cloud のサンプル テンプレートを説明します。

問題:

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

エラー メッセージ:

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

問題の開始時刻（ISO 8601 形式）

問題の終了時刻（ISO 8601 形式）

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

再現手順:

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

診断情報:

<添付ファイルの一覧>

サンプルケース

このセクションでは、Apigee on Google Cloud のサンプルケースを説明します。

問題:

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

エラー メッセージ:

{"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 ハイブリッドの場合のサンプル テンプレートを示します。

問題:

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

エラー メッセージ:

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

問題の開始時刻（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 クラスタ、Namespace、Pod など、Apigee ハイブリッドのセットアップを説明するネットワーク トポロジを添付します。>
• 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
      commit: 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 を添付しました
• 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 のログ