**このページの改善にご協力ください** 

このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。

# AWS Outposts でローカル Amazon EKS クラスターをトラブルシューティングする
<a name="eks-outposts-troubleshooting"></a>

このトピックでは、ローカルクラスターの使用中に表示される可能性がある一般的なエラーとそのトラブルシューティング方法について説明します。ローカルクラスターはクラウド内の Amazon EKS クラスターと似ていますが、Amazon EKS による管理方法にはいくつかの違いがあります。

**重要**  
AWS サポートから明示的に指示されていない限り、Outpost で実行されているマネージド型 EKS ローカルクラスターの `Kubernetes` コントロールプレーンインスタンスを終了しないでください。これらのインスタンスを終了すると、複数のインスタンスが同時に終了した場合にローカルクラスターが失われるなど、ローカルクラスターサービスの可用性にリスクが伴います。EKS ローカルクラスターの `Kubernetes` コントロールプレーンインスタンスは、EC2 インスタンスコンソールでは `eks-local:controlplane-name` タグで識別します。

## API の動作
<a name="outposts-troubleshooting-api-behavior"></a>

ローカルクラスターは Amazon EKS API を通して作成されますが、非同期で実行されます。つまり、Amazon EKS API へのリクエストはローカルクラスターに対してすぐに返されます。ただし、これらのリクエストは成功し、入力検証エラーにより迅速に失敗するか、あるいは失敗して説明入りの検証エラーが発生する可能性があります。この動作は、Kubernetes API と同様です。

ローカルクラスターは `FAILED` ステータスに移行しません。Amazon EKS は、クラスターの状態をユーザーが要求した望ましい状態と一致させようと継続的に試みます。その結果、根本的な問題が解決されるまで、長期間にわたってローカルクラスターが `CREATING` 状態のままになる可能性があります。

## クラスターヘルスフィールドについて説明します
<a name="outposts-troubleshooting-describe-cluster-health-field"></a>

[describe-cluster](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-cluster.html) Amazon EKS AWS CLI コマンドを使用して、ローカルクラスターの問題を検出できます。ローカルクラスターの問題は、`describe-cluster` コマンドの応答の `cluster.health` フィールドによって明らかになります。このフィールドに含まれるメッセージには、エラーコード、説明メッセージ、および関連するリソース ID が含まれます。この情報は、Amazon EKS API および AWS CLI のみから利用可能です。次の例では、*my-cluster* をローカルクラスターの名前に置き換えます。

```
aws eks describe-cluster --name my-cluster --query 'cluster.health'
```

出力例は次のとおりです。

```
{
    "issues": [
        {
            "code": "ConfigurationConflict",
            "message": "The instance type 'm5.large' is not supported in Outpost 'my-outpost-arn'.",
            "resourceIds": [
                "my-cluster-arn"
            ]
        }
    ]
}
```

問題が修復できない場合は、ローカルクラスターを削除して新しいクラスターを作成する必要がある場合があります。たとえば、Outpost で利用できないインスタンスタイプでクラスターをプロビジョニングしようとしている場合などです。下表は、一般的なヘルス関連のエラーを示しています。


| エラーシナリオ | コード | メッセージ | ResourceIds | 
| --- | --- | --- | --- | 
|  指定されたサブネットが見つかりませんでした。  |   `ResourceNotFound`   |   `The subnet ID subnet-id does not exist`   |  指定されたすべてのサブネット ID  | 
|  指定されたサブネットが同じ VPC に属していません。  |   `ConfigurationConflict`   |   `Subnets specified must belong to the same VPC`   |  指定されたすべてのサブネット ID  | 
|  指定されたサブネットの一部が、指定された Outpost に属していません。  |   `ConfigurationConflict`   |   `Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn `   |  問題のあるサブネット ID  | 
|  指定されたサブネットの中には、どの Outpost にも属していないものがあります。  |   `ConfigurationConflict`   |   `Subnet subnet-id is not part of any Outpost`   |  問題のあるサブネット ID  | 
|  指定されたサブネットの中には、コントロールプレーンインスタンス用のエラスティックネットワークインターフェイスを作成するだけの十分な空きアドレスがないものがあります。  |   `ResourceLimitExceeded`   |   `The specified subnet does not have enough free addresses to satisfy the request.`   |  問題のあるサブネット ID  | 
|  指定されたコントロールプレーンインスタンスタイプは、お使いの Outpost でサポートされていません。  |   `ConfigurationConflict`   |   `The instance type type is not supported in Outpost outpost-arn `   |  クラスター ARN  | 
|  コントロールプレーン Amazon EC2 インスタンスを終了したか、`run-instance` が成功し、観察された状態が `Terminated` に変わりました。これは、Outpost が再接続され、Amazon EBS の内部エラーが原因で Amazon EC2 内部ワークフローが失敗した後、一定期間発生する可能性があります。  |   `InternalFailure`   |   `EC2 instance state "Terminated" is unexpected`   |  クラスター ARN  | 
|  Outpost の容量が不足しています。これは、クラスターの作成中に Outpost が AWS リージョンから切断された場合にも発生する可能性があります。  |   `ResourceLimitExceeded`   |   `There is not enough capacity on the Outpost to launch or start the instance.`   |  クラスター ARN  | 
|  アカウントがセキュリティグループの制限を超えています。  |   `ResourceLimitExceeded`   |  Amazon EC2 API から返されたエラーメッセージ  |  ターゲット VPC ID  | 
|  アカウントがエラスティックネットワークインターフェイスの制限を超えています。  |   `ResourceLimitExceeded`   |  Amazon EC2 API から返されたエラーメッセージ  |  ターゲットサブネット ID  | 
|  AWS Systems Manager を介してコントロールプレーンインスタンスにアクセスできません。解決策については、「[AWS Systems Manager を介してコントロールプレーンインスタンスにアクセスできません。](#outposts-troubleshooting-control-plane-instances-ssm)」を参照してください。  |   `ClusterUnreachable`   |  Amazon EKS コントロールプレーンインスタンスには SSM 経由ではアクセスできません。SSM とネットワーク設定を確認し、EKS on Outposts のトラブルシューティングドキュメントを参照してください。  |  Amazon EC2 インスタンス ID  | 
|  マネージドセキュリティグループまたはエラスティックネットワークインターフェイスの詳細を取得中に、エラーが発生しました。  |  Amazon EC2 クライアントエラーコードに基づきます。  |  Amazon EC2 API から返されたエラーメッセージ  |  すべてのマネージドセキュリティグループ ID  | 
|  セキュリティグループのイングレスルールを承認または取り消す際にエラーが発生しました。これは、クラスターとコントロールプレーンの両方のセキュリティグループに適用されます。  |  Amazon EC2 クライアントエラーコードに基づきます。  |  Amazon EC2 API から返されたエラーメッセージ  |  問題のあるセキュリティグループの ID  | 
|  コントロールプレーンインスタンスのエラスティックネットワークインターフェイスの削除中にエラーが発生しました。  |  Amazon EC2 クライアントエラーコードに基づきます。  |  Amazon EC2 API から返されたエラーメッセージ  |  問題のあるエラスティックネットワークインターフェイス ID  | 

次の表は、`describe-cluster` 応答のヘルスフィールドに表示される他の AWS サービスからのエラーを示しています。


| Amazon EC2 エラーコード | クラスターヘルス問題コード | 説明 | 
| --- | --- | --- | 
|   `AuthFailure`   |   `AccessDenied`   |  このエラーは、さまざまな理由で発生する可能性があります。最も一般的な理由は、サービスにリンクされたロールポリシーの範囲を狭めるためにサービスが使用するタグが、コントロールプレーンインスタンスから誤って削除された場合に発生するのです。この場合、Amazon EKS はこれらの AWS リソースを管理および監視できなくなります。  | 
|   `UnauthorizedOperation`   |   `AccessDenied`   |  このエラーは、さまざまな理由で発生する可能性があります。最も一般的な理由は、サービスにリンクされたロールポリシーの範囲を狭めるためにサービスが使用するタグが、コントロールプレーンインスタンスから誤って削除された場合に発生するのです。この場合、Amazon EKS はこれらの AWS リソースを管理および監視できなくなります。  | 
|   `InvalidSubnetID.NotFound`   |   `ResourceNotFound`   |  このエラーは、セキュリティグループのイングレスルールのサブネット ID が見つからない場合に発生します。  | 
|   `InvalidPermission.NotFound`   |   `ResourceNotFound`   |  このエラーは、セキュリティグループのイングレスルールの権限が正しくない場合に発生します。  | 
|   `InvalidGroup.NotFound`   |   `ResourceNotFound`   |  このエラーは、セキュリティグループのイングレスルールのグループが見つからない場合に発生します。  | 
|   `InvalidNetworkInterfaceID.NotFound`   |   `ResourceNotFound`   |  このエラーは、セキュリティグループのイングレスルールのネットワークインターフェイス ID が見つからない場合に発生します。  | 
|   `InsufficientFreeAddressesInSubnet`   |   `ResourceLimitExceeded`   |  このエラーは、サブネットリソースのクォータを超えたときに発生します。  | 
|   `InsufficientCapacityOnOutpost`   |   `ResourceLimitExceeded`   |  このエラーは、outpost のクォータを超えたときに発生します。  | 
|   `NetworkInterfaceLimitExceeded`   |   `ResourceLimitExceeded`   |  このエラーは、エラスティックネットワークインターフェイスのクォータを超えた場合に発生します。  | 
|   `SecurityGroupLimitExceeded`   |   `ResourceLimitExceeded`   |  このエラーは、セキュリティグループのクォータを超えたときに発生します。  | 
|   `VcpuLimitExceeded`   |   `ResourceLimitExceeded`   |  Amazon EC2 インスタンスを新規アカウントで作成するときに発生します。エラーは次のようなものになります: 「`You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to. Please visit http://aws.amazon.com/contact-us/ec2-request to request an adjustment to this limit."`   | 
|   `InvalidParameterValue`   |   `ConfigurationConflict`   |  Amazon EC2 は、指定されたインスタンスタイプが Outpost でサポートされていない場合、このエラーコードを返します。  | 
|  その他のすべての障害  |   `InternalFailure`   |  なし  | 

## クラスターを作成または変更できません
<a name="outposts-troubleshooting-unable-to-create-or-modify-clusters"></a>

ローカルクラスターには、クラウド内にホストされている Amazon EKS クラスターとは異なるアクセス権限とポリシーが必要です。クラスターの作成に失敗し `InvalidPermissions` エラーが表示される場合は、使用しているクラスターロールに [AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) マネージドポリシーがアタッチされているかどうかをもう一度確認します。その他すべての API 呼び出しには、クラウド内の Amazon EKS クラスターと同じ権限セットが必要です。

## クラスターが `CREATING` の状態でスタックしています
<a name="outposts-troubleshooting-cluster-stuck-in-creating-state"></a>

ローカルクラスターの作成にかかる時間は、いくつかの要因によって異なります。ネットワーク設定、Outpost の設定、およびクラスターの設定などが要因として考えられます。通常、ローカルクラスターは 15 ～ 20 分以内に作成され、`ACTIVE` ステータスに変わります。ローカルクラスターが `CREATING` 状態を維持する場合は、`describe-cluster` を呼び出すと `cluster.health` 出力フィールドに原因に関する情報が表示されます。

次は、最も一般的な問題を示しています。
+ クラスターが Systems Manager のある AWS リージョンからコントロールプレーンインスタンスに接続できません。地域内の踏み台ホストから `aws ssm start-session --target instance-id ` を呼び出すことでこれを検証できます。このコマンドがうまくいかない場合は、Systems Manager がコントロールプレーンインスタンスで実行されているかどうかを確認します。または、別の回避策として、クラスターを削除して再度作成することもできます。
+ EBS ボリュームの KMS キーのアクセス許可が原因で、コントロールプレーンインスタンスの作成に失敗します。暗号化された EBS ボリュームのユーザーマネージド KMS キーでは、キーにアクセスできない場合、コントロールプレーンインスタンスは終了します。インスタンスが終了した場合、AWS マネージド KMS キーに切り替えるか、ユーザーマネージドキーポリシーがクラスターロールに必要なアクセス許可を付与していることを確認します。
+ Systems Manager のコントロールプレーンインスタンスが、インターネットにアクセスできない可能性があります。クラスターの作成時に指定したサブネットに NAT ゲートウェイとインターネットゲートウェイを備えた VPC があるかどうかを確認します。VPC 到達可能性アナライザーを使用して、コントロールプレーンインスタンスがインターネットゲートウェイに到達できることを確認します。詳細については、「[VPC Reachability Analyzer の開始方法](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html)」を参照してください。
+ 指定したロール ARN にポリシーがありません。[AWS マネージドポリシー: AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) がロールから削除されたかどうかを確認します。これは、AWS CloudFormation スタックの設定が間違っている場合にも発生する可能性があります。
+ 指定されているすべてのサブネットが同じ Outpost に関連付けられており、相互に到達できる必要があります。クラスターの作成時に複数のサブネットを指定すると、Amazon EKS はコントロールプレーンインスタンスを複数のサブネットに分散させようとします。
+ Amazon EKS マネージド セキュリティグループは、エラスティックネットワークインターフェイスに適用されます。しかしながら、NACL ファイアウォールルールなどの他の設定要素が、エラスティックネットワークインターフェイスのルールと競合する可能性があります。

**VPC とサブネット DNS の設定が誤っているか、欠落しています**  
「[AWS Outposts で Amazon EKS クラスターの VPC とサブネットを作成する](eks-outposts-vpc-subnet-requirements.md)」を確認します。

## クラスターが `UPDATING` の状態でスタックしています
<a name="outposts-troubleshooting-cluster-stuck-in-updating-state"></a>

Amazon EKS は既存のすべてのローカルクラスターを、対応する Kubernetes マイナーバージョン用の最新のプラットフォームバージョンに自動的にアップデートします。プラットフォームバージョンの詳細については、「[AWS Outposts の Kubernetes および Amazon EKS プラットフォームバージョンについて説明します。](eks-outposts-platform-versions.md)」を参照してください。

プラットフォームバージョンの自動ロールアウト中に、クラスターのステータスが `UPDATING` に変わります。更新プロセスでは、すべての Kubernetes コントロールプレーンインスタンスを、それぞれの Kubernetes マイナーバージョン用にリリースされた最新のセキュリティパッチとバグ修正を含む新しいインスタンスに置き換えます。一般的に、ローカルクラスタープラットフォームの更新プロセスは 30 分以内に完了し、クラスターは `ACTIVE` ステータスに戻ります。ローカルクラスターが長時間 `UPDATING` 状態になる場合は、`describe-cluster` を呼び出すと `cluster.health` 出力フィールドで原因に関する情報を確認できます。

Amazon EKS は、ローカルクラスターの可用性を維持し、サービスの中断を防ぐために、3 つの Kubernetes コントロールプレーンインスタンスのうち少なくとも 2 つが正常で運用可能なクラスターノードであるようにします。ローカルクラスターが `UPDATING` 状態で停止している場合、通常は、プロセスが続行された場合に 2 つのインスタンスの最小可用性が保証されないインフラストラクチャまたは設定の問題が原因です。したがって、ローカルクラスターサービスの中断を防ぐために、更新プロセスの進行が停止します。

更新プロセスを完了し、3 つの Kubernetes コントロールプレーンインスタンスの高可用性でローカルクラスターを `ACTIVE` に戻すことができるように、`UPDATING` 状態で停止しているローカルクラスターをトラブルシューティングし、根本原因に対処することが重要です。

AWS サポートから明示的に指示されていない限り、Outposts でマネージド型 EKS ローカルクラスターの `Kubernetes` インスタンスを終了しないでください。これは、別のコントロールプレーンノードが完全には正常ではなく、間違ったインスタンスを終了すると、サービスの中断やローカルクラスターのデータ損失のリスクが生じる可能性が高いため、ローカルクラスターが `UPDATING` 状態で停止した場合、特に重要です。

次は、最も一般的な問題を示しています。
+ ローカルクラスターが最初に作成された以降のネットワーク設定の変更により、1 つまたは複数のコントロールプレーンインスタンスが System Manager に接続できません。地域内の踏み台ホストから `aws ssm start-session --target instance-id ` を呼び出すことでこれを検証できます。このコマンドがうまくいかない場合は、Systems Manager がコントロールプレーンインスタンスで実行されているかどうかを確認します。
+ EBS ボリュームの KMS キーのアクセス許可が原因で、新しいコントロールプレーンインスタンスを作成できません。暗号化された EBS ボリュームのユーザーマネージド KMS キーでは、キーにアクセスできない場合、コントロールプレーンインスタンスは終了します。インスタンスが終了した場合、AWS マネージド KMS キーに切り替えるか、ユーザーマネージドキーポリシーがクラスターロールに必要なアクセス許可を付与していることを確認します。
+ Systems Manager のコントロールプレーンインスタンスが、インターネットにアクセスできない可能性があります。クラスターの作成時に指定したサブネットに NAT ゲートウェイとインターネットゲートウェイを備えた VPC があるかどうかを確認します。VPC 到達可能性アナライザーを使用して、コントロールプレーンインスタンスがインターネットゲートウェイに到達できることを確認します。詳細については、「[VPC Reachability Analyzer の開始方法](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html)」を参照してください。プライベートネットワークにアウトバウンドインターネット接続がない場合は、必要なすべての VPC エンドポイントとゲートウェイエンドポイントがクラスターのリージョンサブネットにまだ存在することを確認してください (「[AWS サービスへのサブネットアクセス](eks-outposts-vpc-subnet-requirements.md#subnet-access-to-services)」を参照)。
+ 指定したロール ARN にポリシーがありません。[AWS managed policy: AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) がロールから削除されたかどうかを確認します。
+ 新しい Kubernetes コントロールプレーンインスタンスのいずれかで、予期しないブートストラップ障害が発生した可能性があります。この例外的なケースのトラブルシューティングとログ収集に関する詳細なガイダンスについては、[AWS サポートセンター](https://console.aws.amazon.com/support/home)にチケットを提出してください。

## ノードをクラスターに結合できない
<a name="outposts-troubleshooting-unable-to-join-nodes-to-a-cluster"></a>
+ AMI に関する問題:
  + 互換性のない AMI を使用しています。Amazon EKS 最適化 Amazon Linux 2 AMI のみがサポートされています (`amazon-linux-2`、`amazon-linux-2-gpu`、`amazon-linux-2-arm64`)。AL2023 ノードを AWS Outposts で EKS Local Clusters に結合しようとしても、ノードをクラスターに結合できません。詳細については、「[AWS Outposts で Amazon Linux ノードを作成する](eks-outposts-self-managed-nodes.md)」を参照してください。
  + AWS CloudFormation テンプレートを使用してノードを作成した場合、サポートされていない AMI を使用していないことを確認します。
+ AWS IAM Authenticator `ConfigMap` が見つからない - 見つからない場合は、作成する必要があります。詳細については、「[`aws-auth`   `ConfigMap` をクラスターに適用する](auth-configmap.md#aws-auth-configmap)」を参照してください。
+ 間違ったセキュリティグループが使用されている - ワーカーノードのセキュリティグループには、必ず `eks-cluster-sg-cluster-name-uniqueid ` を使用してください。スタックが使用されるたびに、選択したセキュリティグループは AWS CloudFormation によって変更され、新しいセキュリティグループを使用できるようになります。
+ 予期しないプライベートリンクの VPC 手順に従う - CA データが間違っている (`--b64-cluster-ca`) または API エンドポイント (`--apiserver-endpoint`) が渡されました。

## ログの収集
<a name="outposts-troubleshooting-collecting-logs"></a>

Outpost が関連付けられている AWS リージョンから切断された場合でも、Kubernetes クラスターは依然として正常に動作し続けるはずです。ただし、クラスターが正常に機能しない場合は、「[AWS Outposts でローカル Amazon EKS クラスターを準備して、ネットワークの切断に備える](eks-outposts-network-disconnects.md)」にあるトラブルシューティング手順に従ってください。他の問題が発生した場合は、AWS サポートにお問い合わせください。AWSサポートからログ収集ツールをダウンロードして実行する方法を説明します。この方法により、Kubernetes クラスターコントロールプレーンインスタンスからログを収集し、詳細な調査のために AWS サポートに送信できます。

## AWS Systems Manager を介してコントロールプレーンインスタンスにアクセスできません。
<a name="outposts-troubleshooting-control-plane-instances-ssm"></a>

Amazon EKS コントロールプレーンインスタンスが AWS Systems Manager (Systems Manager) を通してアクセスでない場合、Amazon EKS はクラスターに対して次のエラーを表示します。

```
Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation.
```

この問題を解決するには、VPC とサブネットが「[AWS Outposts で Amazon EKS クラスターの VPC とサブネットを作成する](eks-outposts-vpc-subnet-requirements.md)」の要件を満たしており、AWS Systems Manager ユーザーガイドの「[Session Manager の設定](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html)」にある手順が完了していることを確認してください。