本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 對閘道進行故障診斷
使用此主題來疑難排解 Amazon ECS Gateway 的問題，包括服務連線失敗、閘道路由佈建失敗、閘道組態更新和連線問題。
Amazon ECS 閘道、閘道路由和應用程式目標會獨立報告其狀態。即使閘道路由無法佈建`ACTIVE`，閘道也可以保留，`ACTIVE`即使其應用程式目標運作狀態不佳，閘道路由也可以保留。若要識別失敗的原因，請檢閱 API 操作傳回的錯誤，或檢查受影響閘道或閘道路由的狀態和失敗詳細資訊。
在進一步調查之前，請確認您使用的是正確的資源名稱或 ARN、 AWS 帳戶和區域。請確定您的 區域支援 Amazon ECS Gateway，而且您擁有必要的許可。對於服務連線問題，請確認服務的任務定義使用 `awsvpc` 網路模式。
如果問題仍然存在，請使用下列疑難排解程序來識別和解決故障。
## 服務連線和部署失敗
### 叢集沒有相關聯的閘道
當沒有閘道與服務叢集相關聯時，包含閘道連接器的 `CreateService`或 `UpdateService`請求會失敗。Amazon ECS 會報告`gatewayConnectors were specified but no gateways are associated with cluster`並拒絕請求，而不是部署無法給予 URL 的服務。檢查叢集的閘道關聯，確認至少有一個閘道與服務的叢集相關聯。
```
aws ecs list-gateway-cluster-associations \
--cluster my-cluster
```
如果沒有關聯，請聯絡您的平台團隊，在部署服務與連接器之前建立閘道關聯。已輸入關聯的閘道`DISASSOCIATING`不適用於新連線。在平台團隊刪除叢集上的最後一個閘道之後，您也會看到此錯誤。從服務中移除連接器，或等待替換閘道，然後再進行下一次更新。
### 沒有相容的閘道符合服務
Amazon ECS 會評估與叢集相關聯的閘道，並將服務連線至符合下列所有條件的每個閘道：
+ **存取類型。**閘道的存取類型符合服務閘道連接器中的`filters.accessTypes`設定。如果您省略此篩選條件，則 `PUBLIC`和 `PRIVATE`閘道都符合資格。
+ **VPC。**閘道和服務位於相同的 VPC 中。
+ **可用區域。**閘道涵蓋服務所設定子網路使用的所有可用區域。子網路 IDs 本身不需要相符，但閘道必須在服務使用的每個可用區域中具有子網路涵蓋範圍。
不符合這些條件的閘道會被排除。如果至少有一個相容的閘道可用，服務會連接到它。如果沒有可用的相容閘道，請求會失敗。`has associated gateways but none are in the service's VPC` 當服務 VPC 中沒有相關聯的閘道，以及存取類型篩選條件排除每個剩餘的閘道`none of the gateways associated with cluster match`時，Amazon ECS 會報告 。
**識別和解決相容性不相符的問題**
1. **檢查服務的存取類型篩選條件。**確認 `filters.accessTypes`符合您要連線之閘道的存取類型。
1. **擷取服務的已設定子網路。**使用 `list-service-deployments` 識別相關的服務修訂 ARN。
```
aws ecs list-service-deployments \
--cluster my-cluster \
--service my-service \
--query 'serviceDeployments[].targetServiceRevisionArn'
```
然後使用 `describe-service-revisions`擷取其設定的子網路。
```
aws ecs describe-service-revisions \
--service-revision-arns \
--query 'serviceRevisions[0].networkConfiguration.awsvpcConfiguration.subnets'
```
1. **擷取閘道設定的子網路。**使用 `describe-gateway` 來檢視閘道的聯網組態。
```
aws ecs describe-gateway \
--gateway my-gateway
```
1. **比較 VPCs和可用區域。**使用 `describe-subnets` 擷取服務和閘道子網路的 VPC ID 和可用區域。
```
aws ec2 describe-subnets \
--subnet-ids \
--query 'Subnets[].{SubnetId:SubnetId,VpcId:VpcId,AvailabilityZone:AvailabilityZone}'
```
確認服務和閘道位於相同的 VPC 中，且閘道涵蓋服務使用的所有可用區域。
1. **解決不相符的問題。**視需要更新服務的存取類型篩選條件或子網路組態。如果沒有可用的相容閘道，請聯絡您的平台團隊，以設定或關聯符合服務存取類型、VPC 和可用區域的閘道。
解決不相符項目後，請重試服務建立或更新。
**注意**
若要在連線 ECS 服務時獲得更大的彈性，請使用子網路設定閘道，涵蓋服務可能執行的所有可用區域。更廣泛的可用區域涵蓋範圍可讓閘道支援更多服務，並減少建立其他閘道的需求。閘道子網路無法在建立後變更。
### 閘道連接器參考無效的容器連接埠
閘道連接器的 `portName` 必須符合服務任務定義中連接埠映射的名稱。它是連接埠的名稱，而不是數值容器連接埠。當任務定義中沒有容器具有與該名稱對應的連接埠時，Amazon ECS 會報告 `InvalidConfiguration: "portName not found in task definition portMappings"`。若要檢查具名連接埠映射，請執行：
```
aws ecs describe-task-definition \
--task-definition my-task-definition:1 \
--query 'taskDefinition.containerDefinitions[].portMappings[].name'
```
更正連接器或任務定義，使名稱相符，然後重試服務操作。更新任務定義後再次檢查，因為先前有效的連接埠名稱可能不再存在。
### 使用 ROLLING 部署策略更新運作狀態檢查失敗
更新閘道連接器的運作狀態檢查設定會傳回錯誤，指出無法使用`ROLLING`部署策略變更目標群組屬性。變更這些設定需要替換目標群組，而使用`ROLLING`部署策略的服務在更新期間不支援該替換。
保留現有的運作狀態檢查設定，或使用藍/綠或金絲雀部署策略進行變更。如果您必須中斷連線並重新連接服務以取代目標群組，請規劃移除並重新建立其閘道路由和主機名稱。如需連接器組態，請參閱 [將 Amazon ECS 服務連線至閘道](gateway-connect-service.md)。
## 閘道路由佈建失敗
服務連線的閘道路由可能處於 `CREATE_FAILED`或 `UPDATE_FAILED` 狀態，或者服務部署可能無法完成佈建輸入。路由層級失敗不一定會變更閘道的整體狀態，或影響其他服務的現有路由。
1. 尋找失敗的閘道路由。
```
aws ecs list-gateway-routes \
--gateway my-gateway \
--status CREATE_FAILED UPDATE_FAILED
```
1. 識別每個失敗路由所屬的服務，以及閘道為其建立的資源。
```
aws ecs describe-gateway-route \
--gateway-route-arn arn:aws:ecs:us-west-2:123456789012:gateway-route/my-gateway/a1b2c3d4/9f8e7d6c
```
1. 檢查服務的部署狀態和服務事件是否有失敗原因。從原因判斷憑證發行、接聽程式規則、目標群組、安全群組或其他資源是否失敗。
1. 修正基礎問題，然後重試受影響的服務部署。閘道組態變更不一定會重新啟動已失敗的服務部署。
**注意**
閘道路由會報告失敗狀態，但不會報告原因。Amazon ECS 會在觸發佈建的服務部署，以及服務事件中記錄原因。
常見原因包括基礎設施角色許可不足、負載平衡器容量或服務配額不足、子網路 IP 耗盡，以及在 Amazon ECS 外部刪除或變更的資源。您可能會看到的兩個原因是 `InsufficientAvailabilityZones`，這表示閘道的子網路位於少於兩個可用區域、Application Load Balancer 的最小值，以及 `InvalidSubnet`，這表示設定的子網路不存在、屬於不同的 VPC，或沒有剩餘的可用 IP 地址。以下各節說明如何調查許可、容量和out-of-band條件。如需監控程序，請參閱 [監控閘道](gateway-monitoring.md)。
如需`hostSharedAlb`閘道類型所需的許可，請參閱《 *AWS 受管政策參考*》中的 [AmazonECSInfrastructureRoleForGatewayHostSharedALB](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonECSInfrastructureRoleForGatewayHostSharedALB.html)。
## 容量和配額問題
如需配額值，請參閱 [Gateway 服務限制](gateway-overview.md#gateway-service-quotas)。
### 叢集已達到其閘道關聯限制
叢集最多可與 5 個閘道建立關聯。當達到該限制時，Amazon ECS 會報告 `Cluster has reached the maximum number of gateway associations (5)`。取消叢集不再需要的閘道關聯，這需要先中斷服務使用。
### 閘道已達到其最大負載平衡器數量
當閘道的現有負載平衡器無法接受另一個服務連線時，Amazon ECS 會佈建另一個負載平衡器，直到達到閘道`maxAlbCount`的設定為止，預設為 10。負載平衡器最多可提供 25 個 ECS 服務。當每個負載平衡器都已滿且閘道位於 時`maxAlbCount`，新服務的部署會失敗。`currentAlbCount` 檢查 ，`maxAlbCount`並檢查受管資源：
```
aws ecs describe-gateway --gateway my-gateway
aws ecs describe-gateway-resources --gateway my-gateway
```
如果 `maxAlbCount`是限制因素，請在支援的限制內增加。例如：
```
aws ecs update-gateway \
--gateway my-gateway \
--configuration '{"hostSharedAlb":{"maxAlbCount":25}}'
```
等待閘道更新完成，然後重新部署受影響的服務。增加 `maxAlbCount` 不會自動重試失敗的服務部署。
### 已達到基礎 AWS 資源配額
ECS Gateway 佈建的資源受其擁有服務的配額限制，包括負載平衡器、目標群組、接聽程式規則、憑證和安全群組規則。如果設定的子網路沒有足夠的可用 IP 地址，佈建也會失敗。您可能會看到下列原因：
+ `LoadBalancerQuotaExceeded` 和 `TargetGroupQuotaExceeded`，適用於 區域中的帳戶限制。
+ `ResourceQuotaExceeded`，適用於每個負載平衡器限制，例如接聽程式規則或憑證。
+ `CertificateQuotaExceeded`，適用於帳戶的憑證限制。
+ `CertificateAnnualLimitExceeded`，適用於過去 365 天內請求的憑證。刪除憑證不會減少此計數，因此需要透過 AWS Support 提高配額。
+ `SecurityGroupCapacityExceeded` 和 `SecurityGroupRuleCapacityExceeded`，適用於每個 VPC 的安全群組和每個安全群組的規則。
+ `TestRuleLimitExceeded`，用於在一個服務上測試流量規則。
+ `TagLimitExceeded`，用於超過資源允許範圍的閘道標籤和服務標籤組合，或用於帳戶標籤政策拒絕的標籤。Amazon ECS 也會套用自己的`AmazonECSManaged`標籤，該標籤使用一個槽。
使用失敗原因來識別受限的資源，然後檢查適用的服務配額。請求增加配額、釋放未使用的容量，或使用支援的替代組態，然後重試服務部署。如需 Elastic Load Balancing 限制，請參閱 [Application Load Balancer 的配額](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-limits.html)。
## IAM 和許可問題
閘道操作涉及兩個不同的身分：發出 API 請求的 IAM 主體，以及 Amazon ECS 擔任以管理 AWS 資源的基礎設施 IAM 角色。變更一個許可問題並未修正另一個許可問題。
### 發起人無法傳遞基礎設施角色
`CreateGateway` 當發起人無法傳遞 中提供的角色`iam:PassRole`時， 和 會`UpdateGateway`失敗並出現許可錯誤`infrastructureRoleArn`。這是最常見的初次執行失敗，因為即使呼叫者被允許建立閘道，呼叫也會失敗。確認發起人具有 中確切角色 ARN 的`iam:PassRole`許可`infrastructureRoleArn`，並檢查許可界限、服務控制政策和明確拒絕。將許可新增至基礎設施角色並不會解決呼叫身分缺少的許可。如需 IAM 角色設定，請參閱 [Amazon ECS Gateway 的基礎設施 IAM 角色](gateway-managing.md#gateway-infrastructure-role)。
### Amazon ECS 無法擔任基礎設施角色
Amazon ECS 可以到達角色，但無法擔任該角色。確認 IAM 角色是否存在，且其信任政策允許`ecs.amazonaws.com`呼叫 `sts:AssumeRole`。
```
aws iam get-role --role-name ecsInfrastructureRoleForGateways
```
角色的信任政策必須符合下列項目。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAccessInfrastructureForECSGateways",
"Effect": "Allow",
"Principal": {
"Service": "ecs.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
如果角色剛建立或修改，請預留時間讓 IAM 變更傳播，然後再重試。`iam:PassRole` 單獨授予發起人不會修正遺失或不正確的信任關係。同時確認角色與閘道位於相同的帳戶和分割區中。相關失敗 `AWS STS is not activated for this account in a Region`表示 AWS Security Token Service 該區域未啟用 。啟用它，然後重試。
### 基礎設施角色無法管理資源
當基礎設施角色缺少許可時，閘道路由或閘道更新會報告 Elastic Load Balancing、Amazon EC2 或 AWS Certificate Manager 操作的存取遭拒錯誤。確認角色具有閘道組態所需的許可。對於`hostSharedAlb`閘道類型，請檢查連接的 AWS 受管政策。
```
aws iam list-attached-role-policies --role-name ecsInfrastructureRoleForGateways
```
連接`AmazonECSInfrastructureRoleForGatewayHostSharedALB`受管政策，或者，如果您將其取代為自己的政策，請將該政策與失敗中名為 的 IAM 動作進行比較。您可以在 [*AWS 受管政策參考*](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonECSInfrastructureRoleForGatewayHostSharedALB.html)中查看此政策授予的許可。同時檢查許可界限或其他帳戶限制是否阻止 動作。完全失敗的操作和資源 ARN 比未區分`AccessDenied`的訊息更有用。
## 服務連線和目標運作狀態
### 服務主機名稱未回應
當對閘道產生的 HTTPS 主機名稱的請求逾時或失敗時，請檢查從閘道路由到應用程式的連線。
1. **檢查閘道路由狀態。**尋找服務的路由，並確認其為 `ACTIVE`。中的路由`CREATE_IN_PROGRESS`尚未完成佈建，且處於 `*_FAILED` 狀態的路由發生佈建失敗。在對應用程式進行故障診斷之前，請檢查路由失敗：
```
aws ecs list-gateway-routes --cluster my-cluster --service my-service
```
1. **檢查閘道存取。**內部閘道需要網路連線至內部負載平衡器。確認您正從可以連線的網路進行測試。
1. **檢查目標運作狀態。**從傳回的服務閘道連線取得目標群組 ARN`describe-service-revisions`，然後檢查其已註冊的目標。
```
aws elbv2 describe-target-health \
--target-group-arn arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-service/0123456789abcdef
```
當應用程式傳回非預期的狀態碼、逾時、接聽不同的連接埠，或負載平衡器無法連線時，目標群組可以報告運作狀態不佳的目標。回應包含每個目標的運作狀態，以及相關的原因和描述。例如， 的原因`Target.ResponseCodeMismatch`表示回應不符合設定的成功碼範圍。在您修改任何閘道基礎設施之前，請檢查運作狀態檢查路徑、應用程式回應和目標連接埠。如需運作狀態檢查原因代碼，請參閱 [ Application Load Balancer 目標群組的運作狀態檢查](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-health-checks.html)。
`ACTIVE` 閘道路由表示輸入佈建成功。這並不表示應用程式目標運作狀態良好。
1. **檢查安全群組。**確認負載平衡器的傳入安全群組允許來自預期用戶端的流量，且任務安全群組允許來自容器連接埠上負載平衡器的流量。當平台團隊提供閘道的傳入安全群組時，Amazon ECS 不會管理其傳入規則。
1. **檢查應用程式和流量控制。**驗證容器的接聽連接埠和運作狀態端點。如果已設定 AWS WAF Web ACL，請檢查規則是否封鎖請求。使用負載平衡器存取日誌和 CloudWatch 指標，在應用程式回應之外指出負載平衡器錯誤。
## 閘道更新失敗
`DescribeGateway` 會在閘道組態更新`UPDATE_FAILED`後報告 Amazon ECS 無法套用至每個負載平衡器。Amazon ECS 會輪流將更新套用至每個受管負載平衡器，並盡最大努力更新所有負載平衡器，而不是在第一次故障時停止，因此有些負載平衡器可能會接受變更，而其他負載平衡器則會失敗。請勿假設更新已跨閘道轉返。擷取狀態和失敗資訊。
```
aws ecs describe-gateway --gateway my-gateway
```
檢查 `statusReason`和 `failures` 是否有無法更新的資源和操作。例如，無效安全群組識別符的錯誤會指向閘道設定的傳入安全群組，而拒絕存取的錯誤會指向基礎設施角色可用的許可。如需如何讀取`failures`清單，請參閱 [尋找失敗詳細資訊](gateway-monitoring.md#gateway-where-failures-recorded)。更正報告的原因，然後重試請求的更新。請等到閘道報告成功更新，再假設每個受管負載平衡器都有新的組態，並等待更新完成再重試。
**重要**
部分閘道更新可能會讓不同的負載平衡器具有不同的組態，進而變更其背後服務的流量或政策行為。將更新視為部分套用，直到閘道報告 `UPDATE_COMPLETE`，並在復原後驗證受影響的資源。
## 取消關聯和刪除問題
### 叢集關聯會保持取消關聯
閘道叢集關聯會保留在 中，`DISASSOCIATING`直到與該叢集相關聯的所有閘道路由都移除為止。當您取消閘道的關聯時，Amazon ECS 不會自動重新部署連線的服務或移除其現有的路由。
若要識別仍然連線的服務，請使用下列命令：
```
aws ecs list-gateway-routes --gateway my-gateway --cluster my-cluster
```
與應用程式團隊協調，以更新或重新部署受影響的服務，使其與閘道中斷連線。移除最後一個路由時，取消關聯即完成。
### 無法刪除閘道
啟用刪除保護或叢集關聯處於 `ACTIVE`或 `DISASSOCIATING` 狀態時，無法刪除閘道。檢查閘道的叢集關聯，並確保移除所有剩餘的閘道路由，以便取消關聯可以完成。移除所有關聯後，請確定已停用刪除保護，然後重試刪除閘道。如需完整程序，請參閱 [刪除閘道](gateway-managing.md#gateway-delete)。
```
aws ecs update-gateway --gateway my-gateway --no-deletion-protection
aws ecs delete-gateway --gateway my-gateway
```
## 在 Amazon ECS 外部所做的變更
Amazon ECS 不會自動修復或重新建立在 Amazon ECS 外部修改或刪除的閘道受管資源。修改或刪除 Amazon ECS 外部的受管資源，例如負載平衡器、接聽程式、接聽程式規則、目標群組、憑證或安全群組，可能會中斷流量或導致後續服務部署、閘道更新或清除操作失敗。
如果在 Amazon ECS 之外修改或刪除閘道受管資源，請執行下列步驟：
1. **識別受影響的資源**：使用 `describe-gateway-resources`或 `describe-gateway-route` 來識別受管資源。在對應的 AWS 服務中檢查其目前的組態，以識別遺失或修改的資源。在 Amazon ECS 外部所做的變更可能會顯示為下列其中一個失敗原因：
+ `ManagedResourceDeleted`，當在 Amazon ECS 外部刪除為服務建立的資源 Amazon ECS 時。
+ `ConflictingListener`，當閘道連接埠上的接聽程式存在於負載平衡器上，且 Amazon ECS 未建立它時。
+ `SecurityGroupNameInUse`，當名稱為 Amazon ECS 的安全群組存在且不受 Amazon ECS 管理時。Amazon ECS 不會重新設定或刪除它。
+ `InvalidSecurityGroup`，當閘道的傳入安全群組不再存在時。
1. **復原受影響的服務**：如果資源已修改，請還原其原始組態並重新部署服務。如果資源已刪除，請從服務移除閘道連接器並部署，然後新增連接器，然後再次部署。第二個部署會佈建新的資源和新的閘道路由。由於服務會收到新產生的主機名稱，因此請更新指向舊主機名稱的任何用戶端或 DNS 記錄。
1. **驗證連線**：確認服務的閘道路由是正常的，`ACTIVE`然後再將流量重新導向到該路由。
**重要**
請勿修改或移除閘道受管資源的`AmazonECSManaged`標籤。Amazon ECS 使用它來識別其管理的資源，如果沒有它，Amazon ECS 就無法再更新或清除該資源。透過 Amazon ECS Gateway 操作進行支援的組態變更，而不是直接修改基礎資源。