10.3. ログおよびデバッグツール
本セクションでは、トラブルシューティングに使用できるログおよびデバッグツールについて説明します。
10.3.1. 移行計画リソースの表示
移行計画リソースを表示して、実行中の移行を監視するか、MTC の Web コンソールおよびコマンドラインインターフェイス (CLI) を使用して失敗した移行のトラブルシューティングを行うことができます。
手順
- MTC Web コンソールで、Migration plans をクリックします。
- 移行計画の横にある Migrations 番号をクリックし、Migrations ページを表示します。
- 移行をクリックして、移行の詳細を表示します。
Migration resources を展開して、移行リソースおよびそれらのステータスをツリービューで表示します。
注記移行の失敗をトラブルシューティングするには、失敗した高レベルのリソースで開始し、リソースツリーでより低い位置にあるリソースまで堀り下げます。
リソースの横にある Options メニュー
をクリックし、以下のオプションのいずれかを選択します。
copy
oc describe
コマンド は、コマンドをクリップボードにコピーします。関連するクラスターにログインしてから、コマンドを実行します。
リソースの条件およびイベントは YAML 形式で表示されます。
Copy
oc logs
コマンド は、コマンドをクリップボードにコピーします。関連するクラスターにログインしてから、コマンドを実行します。
リソースがログフィルターに対応していると、フィルターされたログが表示されます。
JSON ビューは、Web ブラウザーで JSON 形式でリソースデータを表示します。
データは
oc get <resource>
コマンドの出力と同じです。
10.3.2. 移行計画ログの表示
移行計画の集計ログを表示できます。MTC の Web コンソールを使用して、コマンドをクリップボードにコピーしてから、コマンドラインインターフェイス (CLI) からコマンドを実行します。
このコマンドは、以下の Pod に関するフィルターされたログを表示します。
-
Migration Controller
-
Velero
-
Restic
-
Rsync
-
Stunnel
-
Registry
手順
- MTC Web コンソールで、Migration plans をクリックします。
- 移行計画の横にある Migrations 番号をクリックします。
- View logs をクリックします。
-
コピーアイコンをクリックして、
oc logs
コマンドをクリップボードにコピーします。 関連するクラスターにログインし、CLI でコマンドを実行します。
移行契約の集約ログが表示されます。
10.3.3. 移行ログリーダーの使用
移行ログリーダーを使用して、すべての移行ログの単一のフィルタービューを表示できます。
手順
mig-log-reader
Pod を取得します。$ oc -n openshift-migration get pods | grep log
以下のコマンドを実行して、単一の移行ログを表示します。
$ oc -n openshift-migration logs -f <mig-log-reader-pod> -c color 1
- 1
-c plain
オプションは、色なしでログを表示します。
10.3.4. パフォーマンスメトリックへのアクセス
MigrationController
カスタムリソース (CR) はメトリクスを記録し、それらをクラスター上のモニターリングストレージにプルします。Prometheus Query Language (PromQL) を使用してメトリクスをクエリーし、移行のパフォーマンス問題を診断できます。すべてのメトリクスは、Migration コントローラー Pod の再起動時にリセットされます。
パフォーマンスメトリックにアクセスし、OpenShift Container Platform Web コンソールを使用してクエリーを実行できます。
手順
-
OpenShift Container Platform Web コンソールで、Observe
Metrics をクリックします。 PromQL クエリーを入力し、表示する期間を選択し、Run Queries をクリックします。
Web ブラウザーにすべての結果が表示されない場合は、Prometheus コンソールを使用します。
10.3.4.1. 提供されるメトリクス
MigrationController
カスタムリソース (CR) は、MigMigration
CR 数およびその API 要求のメトリクスを提供します。
10.3.4.1.1. cam_app_workload_migrations
このメトリクスは、一定期間の MigMigration
CR の数です。mtc_client_request_count
および mtc_client_request_elapsed
メトリックと一緒に表示して、API リクエスト情報を移行ステータスの変更と照合するのに役立ちます。このメトリクスは Telemetry に含まれます。
クエリー可能なラベル名 | サンプルラベル値 | ラベルの説明 |
---|---|---|
status |
|
|
type | stage、final |
|
10.3.4.1.2. mtc_client_request_count
このメトリクスは、MigrationController
が発行する Kubernetes API 要求の累積数です。これは Telemetry に含まれていません。
クエリー可能なラベル名 | サンプルラベル値 | ラベルの説明 |
---|---|---|
cluster |
| 要求が発行されたクラスター |
component |
| 要求を発行したサブコントローラー API |
function |
| 要求が発行された関数 |
kind |
| 要求が発行された Kubernetes の種類 |
10.3.4.1.3. mtc_client_request_elapsed
このメトリクスは、MigrationController
が発行する Kubernetes API 要求の累積レイテンシー (ミリ秒単位) です。これは Telemetry に含まれていません。
クエリー可能なラベル名 | サンプルラベル値 | ラベルの説明 |
---|---|---|
cluster |
| 要求が発行されたクラスター |
component |
| 要求を発行したサブコントローラー API |
function |
| 要求が発行された関数 |
kind |
| 要求が発行された Kubernetes リソース |
10.3.4.1.4. 有用なクエリー
この表には、パフォーマンスの監視に使用できる便利なクエリーが記載されています。
クエリー | 説明 |
---|---|
| 発行した API 要求の数。要求タイプ別でソート |
| 発行された API 要求の合計数 |
| 要求タイプ別にソートされた API 要求のレイテンシー |
| API 要求の合計レイテンシー |
| API 要求の平均レイテンシー |
| 要求タイプ別にソートされた API 要求の平均レイテンシー |
| 実行中の移行の数。要求数とともに簡単に表示できるように 100 で乗算されます。 |
10.3.5. must-gather ツールの使用
must-gather
ツールを使用して、MTC カスタムリソースのログ、メトリクス、および情報を収集できます。
must-gather
データはすべてのカスタマーケースに割り当てられる必要があります。
1 時間または 24 時間のデータを収集し、Prometheus コンソールでデータを表示できます。
前提条件
-
cluster-admin
ロールを持つユーザーとして OpenShift Container Platform クラスターにログインする必要があります。 -
OpenShift CLI (
oc
) がインストールされている必要があります。
手順
-
must-gather
データを保存するディレクトリーに移動します。 次のデータ収集オプションのいずれかに対して、
oc adm must-gather
コマンドを実行します。過去 1 時間のデータを収集するには、以下を実行します。
$ oc adm must-gather --image=registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8:v1.7
データは
must-gather/must-gather.tar.gz
として保存されます。このファイルを Red Hat カスタマーポータル で作成したサポートケースにアップロードすることができます。過去 24 時間のデータを収集するには、以下を実行します。
$ oc adm must-gather --image=registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8:v1.7 \ -- /usr/bin/gather_metrics_dump
この操作には長時間かかる場合があります。データは
must-gather/metrics/prom_data.tar.gz
として保存されます。
Prometheus コンソールを使用したメトリクスデータの表示
Prometheus コンソールでメトリックデータを表示できます。
手順
prom_data.tar.gz
ファイルを解凍します。$ tar -xvzf must-gather/metrics/prom_data.tar.gz
ローカルの Prometheus インスタンスを作成します。
$ make prometheus-run
このコマンドでは、Prometheus URL が出力されます。
出力
Started Prometheus on http://localhost:9090
- Web ブラウザーを起動して URL に移動し、Prometheus Web コンソールを使用してデータを表示します。
データを確認した後に、Prometheus インスタンスおよびデータを削除します。
$ make prometheus-cleanup
10.3.6. Velero CLI ツールを使用した Velero リソースのデバッグ
Velero CLI ツールを使用して、Backup
および Restore
カスタムリソース (CR) をデバッグし、ログを取得できます。
Velero CLI ツールは、OpenShift CLI ツールよりも詳細な情報を提供します。
構文
oc exec
コマンドを使用して、Velero CLI コマンドを実行します。
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ <backup_restore_cr> <command> <cr_name>
例
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ backup describe 0e44ae00-5dc3-11eb-9ca8-df7e5254778b-2d8ql
ヘルプオプション
velero --help
オプションを使用して、すべての Velero CLI コマンドを一覧表示します。
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ --help
describe コマンド
velero describe
コマンドを使用して、Backup
または Restore
CR に関連する警告とエラーの要約を取得します。
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ <backup_restore_cr> describe <cr_name>
例
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ backup describe 0e44ae00-5dc3-11eb-9ca8-df7e5254778b-2d8ql
logs コマンド
velero logs
コマンドを使用して、Backup
または Restore
CR のログを取得します。
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ <backup_restore_cr> logs <cr_name>
例
$ oc -n openshift-migration exec deployment/velero -c velero -- ./velero \ restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf
10.3.7. 部分的な移行の失敗のデバッグ
Velero CLI を使用して Restore
カスタムリソース (CR) ログを確認し、部分的な移行の失敗についての警告メッセージをデバッグできます。
部分的な障害は、Velero で移行の失敗を生じさせない問題が発生する際に見られます。たとえば、カスタムリソース定義 (CRD) がない場合や、ソースクラスターおよびターゲットクラスターの CRD バージョン間で不一致がある場合、移行は完了しますが、CR はターゲットクラスターで作成されません。
Velero は問題を部分的な障害としてログに記録し、Backup
CR の残りのオブジェクトを処理します。
手順
MigMigration
CR のステータスを確認します。$ oc get migmigration <migmigration> -o yaml
出力例
status: conditions: - category: Warn durable: true lastTransitionTime: "2021-01-26T20:48:40Z" message: 'Final Restore openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf: partially failed on destination cluster' status: "True" type: VeleroFinalRestorePartiallyFailed - category: Advisory durable: true lastTransitionTime: "2021-01-26T20:48:42Z" message: The migration has completed with warnings, please look at `Warn` conditions. reason: Completed status: "True" type: SucceededWithWarnings
Velero
describe
コマンドを使用してRestore
CR のステータスを確認します。$ oc -n {namespace} exec deployment/velero -c velero -- ./velero \ restore describe <restore>
出力例
Phase: PartiallyFailed (run 'velero restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf' for more information) Errors: Velero: <none> Cluster: <none> Namespaces: migration-example: error restoring example.com/migration-example/migration-example: the server could not find the requested resource
Velero
logs
コマンドを使用してRestore
CR ログを確認します。$ oc -n {namespace} exec deployment/velero -c velero -- ./velero \ restore logs <restore>
出力例
time="2021-01-26T20:48:37Z" level=info msg="Attempting to restore migration-example: migration-example" logSource="pkg/restore/restore.go:1107" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf time="2021-01-26T20:48:37Z" level=info msg="error restoring migration-example: the server could not find the requested resource" logSource="pkg/restore/restore.go:1170" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf
Restore
CR のログエラーメッセージのthe server could not find the requested resource
は、部分的に失敗した移行の原因を示します。
10.3.8. トラブルシューティング向けの MTC カスタムリソースの使用
以下の MTC (Migration Toolkit for Containers) カスタムリソース (CR) を確認し、失敗した移行のトラブルシューティングを行うことができます。
-
MigCluster
-
MigStorage
-
MigPlan
BackupStorageLocation
BackupStorageLocation
CR には、CR を作成した MTC インスタンスを識別するためのmigrationcontroller
ラベルが含まれます。labels: migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
VolumeSnapshotLocation
VolumeSnapshotLocation
CR には、CR を作成した MTC インスタンスを特定するためのmigrationcontroller
ラベルが含まれます。labels: migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
-
MigMigration
Backup
MTC は、移行された永続ボリューム (PV) の回収ポリシーをターゲットクラスターで
Retain
に変更します。Backup
CR には、元の回収ポリシーを示すopenshift.io/orig-reclaim-policy
アノテーションが含まれます。移行した PV の回収ポリシーを手動で復元できます。-
Restore
手順
openshift-migration
namespace のMigMigration
CR を一覧表示します。$ oc get migmigration -n openshift-migration
出力例
NAME AGE 88435fe0-c9f8-11e9-85e6-5d593ce65e10 6m42s
MigMigration
CR を検査します。$ oc describe migmigration 88435fe0-c9f8-11e9-85e6-5d593ce65e10 -n openshift-migration
出力は以下の例のようになります。
MigMigration
の出力例
name: 88435fe0-c9f8-11e9-85e6-5d593ce65e10 namespace: openshift-migration labels: <none> annotations: touch: 3b48b543-b53e-4e44-9d34-33563f0f8147 apiVersion: migration.openshift.io/v1alpha1 kind: MigMigration metadata: creationTimestamp: 2019-08-29T01:01:29Z generation: 20 resourceVersion: 88179 selfLink: /apis/migration.openshift.io/v1alpha1/namespaces/openshift-migration/migmigrations/88435fe0-c9f8-11e9-85e6-5d593ce65e10 uid: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 spec: migPlanRef: name: socks-shop-mig-plan namespace: openshift-migration quiescePods: true stage: false status: conditions: category: Advisory durable: True lastTransitionTime: 2019-08-29T01:03:40Z message: The migration has completed successfully. reason: Completed status: True type: Succeeded phase: Completed startTimestamp: 2019-08-29T01:01:29Z events: <none>
PV データを記述する Velero
バックアップ CR #2 の出力例
apiVersion: velero.io/v1 kind: Backup metadata: annotations: openshift.io/migrate-copy-phase: final openshift.io/migrate-quiesce-pods: "true" openshift.io/migration-registry: 172.30.105.179:5000 openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-44dd3bd5-c9f8-11e9-95ad-0205fe66cbb6 openshift.io/orig-reclaim-policy: delete creationTimestamp: "2019-08-29T01:03:15Z" generateName: 88435fe0-c9f8-11e9-85e6-5d593ce65e10- generation: 1 labels: app.kubernetes.io/part-of: migration migmigration: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 migration-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 velero.io/storage-location: myrepo-vpzq9 name: 88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7 namespace: openshift-migration resourceVersion: "87313" selfLink: /apis/velero.io/v1/namespaces/openshift-migration/backups/88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7 uid: c80dbbc0-c9f8-11e9-95ad-0205fe66cbb6 spec: excludedNamespaces: [] excludedResources: [] hooks: resources: [] includeClusterResources: null includedNamespaces: - sock-shop includedResources: - persistentvolumes - persistentvolumeclaims - namespaces - imagestreams - imagestreamtags - secrets - configmaps - pods labelSelector: matchLabels: migration-included-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 storageLocation: myrepo-vpzq9 ttl: 720h0m0s volumeSnapshotLocations: - myrepo-wv6fx status: completionTimestamp: "2019-08-29T01:02:36Z" errors: 0 expiration: "2019-09-28T01:02:35Z" phase: Completed startTimestamp: "2019-08-29T01:02:35Z" validationErrors: null version: 1 volumeSnapshotsAttempted: 0 volumeSnapshotsCompleted: 0 warnings: 0
Kubernetes リソースを記述する Velero
CR #2 の出力例
apiVersion: velero.io/v1 kind: Restore metadata: annotations: openshift.io/migrate-copy-phase: final openshift.io/migrate-quiesce-pods: "true" openshift.io/migration-registry: 172.30.90.187:5000 openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-36f54ca7-c925-11e9-825a-06fa9fb68c88 creationTimestamp: "2019-08-28T00:09:49Z" generateName: e13a1b60-c927-11e9-9555-d129df7f3b96- generation: 3 labels: app.kubernetes.io/part-of: migration migmigration: e18252c9-c927-11e9-825a-06fa9fb68c88 migration-final-restore: e18252c9-c927-11e9-825a-06fa9fb68c88 name: e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx namespace: openshift-migration resourceVersion: "82329" selfLink: /apis/velero.io/v1/namespaces/openshift-migration/restores/e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx uid: 26983ec0-c928-11e9-825a-06fa9fb68c88 spec: backupName: e13a1b60-c927-11e9-9555-d129df7f3b96-sz24f excludedNamespaces: null excludedResources: - nodes - events - events.events.k8s.io - backups.velero.io - restores.velero.io - resticrepositories.velero.io includedNamespaces: null includedResources: null namespaceMapping: null restorePVs: true status: errors: 0 failureReason: "" phase: Completed validationErrors: null warnings: 15