> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# トラブルシューティング

まず、次の点を確認してください。

```bash theme={null}
kubectl -n fineparser get pods,pvc
kubectl -n fineparser get events --sort-by=.lastTimestamp | tail -30
```

## ヘルスチェック

すべてのコンポーネントは、レディネスプローブとしてポート 8080 で `GET /healthz` を提供します。準備が完了した pod は `{"status":"ok"}` を返します。準備が完了していない pod は `503` を返し、`status` とともに `error` に理由を含めます。この場合、pod は再起動されず、そのまま実行され続けます。

```bash theme={null}
kubectl -n fineparser port-forward deploy/fineparser-ingest 8081:8080
curl -s localhost:8081/healthz
```

| コンポーネント | 未準備 (Unready) となる条件 |
| - | - |
| Orchestrator | Kubernetes API 経由でワーカーの Deployment をまだ読み取っていない場合。 |
| Ingest | ボリュームを使用できない場合、またはまだ Orchestrator に接続できていない場合。 |
| Worker | エンジンの起動中、課金がまだ確認されていない場合、またはデフォルトのプロファイルが拒否された場合。 |

## インストール

### クレームが Pending のままになる

```bash theme={null}
kubectl -n fineparser describe pvc <claim>
```

インプロセスのクレームの場合：EFS CSI ドライバーがインストールされていない、そのコントローラーに `AmazonEFSCSIDriverPolicy` が付与されていない、または `fileSystemId` が正しくないことが考えられます。`mnesia-fineparser-orchestrator-0` の場合：クラスターにデフォルトの StorageClass が設定されていない、またはそのドライバーがインストールされていないことが考えられます。

### pod が ContainerCreating のまま進まない

原因は `kubectl describe pod` で確認できます。

* EFS のマウントがタイムアウトする: ノードのアベイラビリティーゾーンにマウントターゲットが存在しないか、TCP 2049 がブロックされています。
* S3 のマウントが失敗する: バケットまたはリージョンの指定が誤っているか、Mountpoint ドライバーのロールにバケットへのアクセス権がありません。`No signing credentials available` と表示される場合は、ロールの信頼ポリシーがクラスターの OIDC プロバイダーと一致していません。

### pod が exec format error で失敗する

pod が `arm64` ノード上で実行されています。[amd64 で実行する](https://docs.abbyy.com/ja/fine-parser/enterprise/best-practices/scheduling.md#run-on-amd64)を参照してください。

## ワーカー

### ワーカーが起動しない

```bash theme={null}
kubectl -n fineparser get deploy fineparser-worker
kubectl -n fineparser logs statefulset/fineparser-orchestrator | grep 'scaling workers'
```

Deployment がワーカーを要求しているのにワーカーが Pending のままの場合は、クラスターのリソースが不足しています。ノードオートスケーラーが、`worker.nodeSelector` および `worker.tolerations` に一致する `amd64` ノードを追加できるかどうかを確認してください。`worker.prepull` を有効にしている場合は、事前プル用の DaemonSet が新しいノード上で実行されているかどうかも確認してください。

### 起動時にワーカーが終了する

```bash theme={null}
kubectl -n fineparser logs deploy/fineparser-worker --previous | grep billing
```

`billing refused this worker, exiting:` という行に理由が示されます。

| 理由 | 対処法 |
| - | - |
| `AWS_ROLE_ARN is unset` または `AWS_REGION is unset` | サービスアカウントに `eks.amazonaws.com/role-arn` アノテーションが設定されていません。[IAM と課金](https://docs.abbyy.com/ja/fine-parser/enterprise/aws/iam-and-billing.md)を参照してください。 |
| `AccessDenied` | ロールに `AWSMarketplaceMeteringRegisterUsage` をアタッチしてください。 |
| STS エラー | ロールの信頼ポリシーが、クラスター、名前空間、またはサービスアカウントと一致していません。 |
| `CustomerNotEntitled` | アカウントに有効なサブスクリプションがありません。 |
| 証明書エラー | プロキシが `*.amazonaws.com` への TLS 通信を検査しています。このドメインを検査対象から除外してください。 |

`billing: RegisterUsage failed, retrying` は一時的なエラーで、ワーカーが自動的に再試行します。

### ワーカーが準備完了にならない

FineReader Engine がデフォルトのプロファイルを受け付けませんでした。理由はワーカーのログと `/healthz` で確認できます。`worker.predefinedProfile` または `worker.userProfile` を修正し、アップグレードを実行してからワーカーを再起動してください。

### ワーカーが終了コード 2 で再起動する

ワーカーは、5 つのユニットで連続して処理に失敗すると再起動します。失敗したジョブの `failure.message` を確認してください。すべてのドキュメントで処理が失敗する場合は、ボリュームまたはプロファイルを確認してください。

## ジョブ

| 症状 | 対処法 |
| - | - |
| ジョブが `timed-out` で失敗する | `orchestrator.workLeaseSeconds` の値を大きくするか、`ingest.pageSplitThreshold` の値を小さくしてください。詳しくは[ユニットサイズとリース](https://docs.abbyy.com/ja/fine-parser/enterprise/concepts/scaling.md#unit-size-and-leases)を参照してください。 |
| ジョブが `finalize-failed` で失敗する | ワーカーが出力ボリュームに書き込めることを確認してください。 |
| リクエストが `413` で失敗する | `ingest.maxUploadSize` の値を大きくし、`ingest.scratchSize` をその約 2 倍に設定してください。 |
| アップロード中に Ingest pod が退避 (evict) される | `ingest.scratchSize` の値を大きくするか、`ingest.maxUploadSize` の値を小さくしてください。 |
| 既知のジョブに対して `GET /jobs/{jobId}` が `404` を返す | `orchestrator.jobRetentionSeconds` が経過したため、ジョブのステータスの保持期限が切れています。結果は出力ボリューム上に残っています。 |

## アップグレード

| 症状 | 対処法 |
| - | - |
| `.spec.replicas` で競合が発生する | 同じ `helm upgrade` をもう一度実行します。 |
| StorageClass、PersistentVolume、または クレーム でアップグレードが失敗する | この変更には再インストールが必要です。[再インストールが必要な変更](https://docs.abbyy.com/ja/fine-parser/enterprise/best-practices/upgrades.md#changes-that-need-a-reinstall)を参照してください。 |