AWS eks documentation change

Service: eks · 2026-06-07 · Documentation low

File: eks/latest/userguide/capabilities-troubleshooting.md

Summary

Added documentation for using controller logs in troubleshooting workflows. Introduced new CloudWatch Logs Insights query examples for filtering controller logs by error level, controller group, application, and reconcile ID. Added common log patterns indicating issues.

Security assessment

The changes focus on operational troubleshooting through log analysis. While logs may contain security-related information, there's no evidence this change addresses a specific vulnerability or weakness. The added log queries help identify misconfigurations and permission issues, but don't introduce new security features.

Diff

diff --git a/eks/latest/userguide/capabilities-troubleshooting.md b/eks/latest/userguide/capabilities-troubleshooting.md
index 02e2349d6..953ddac65 100644
--- a//eks/latest/userguide/capabilities-troubleshooting.md
+++ b//eks/latest/userguide/capabilities-troubleshooting.md
@@ -7 +7 @@
-General troubleshooting approachCheck capability healthCommon capability statusesVerify Kubernetes resource statusReview IAM permissions and cluster accessCapability-specific troubleshootingCommon issues across all capabilitiesNext steps
+General troubleshooting approachUse controller logs for troubleshootingCheck capability healthCommon capability statusesVerify Kubernetes resource statusReview IAM permissions and cluster accessCapability-specific troubleshootingCommon issues across all capabilitiesNext steps
@@ -17 +17 @@ To contribute to this user guide, choose the **Edit this page on GitHub** link t
-EKS Capabilities are fully managed and run outside your cluster. You do not have access to controller logs or controller namespaces. Troubleshooting focuses on capability health, resource status, and configuration.
+EKS Capabilities are fully managed and run outside your cluster. You do not have direct access to controller namespaces. Troubleshooting focuses on capability health, resource status, configuration, and controller logs. You can configure controller log delivery to gain visibility into controller behavior. See [Access EKS Capabilities controller logs](./capabilities-controller-logs.html).
@@ -27 +27 @@ When troubleshooting EKS Capabilities, follow this general approach:
-  3. **Review IAM permissions** : Ensure the Capability Role has the necessary permissions
+  3. **Review controller logs** : If log delivery is configured, query controller logs for errors and reconciliation details
@@ -29 +29,64 @@ When troubleshooting EKS Capabilities, follow this general approach:
-  4. **Check configuration** : Verify capability-specific configuration is correct
+  4. **Review IAM permissions** : Ensure the Capability Role has the necessary permissions
+
+  5. **Check configuration** : Verify capability-specific configuration is correct
+
+
+
+
+## Use controller logs for troubleshooting
+
+If you have configured controller log delivery (see [Access EKS Capabilities controller logs](./capabilities-controller-logs.html)), you can query logs to identify reconciliation errors, resource conflicts, and configuration issues.
+
+### Query errors across all controllers
+    
+    
+    fields @timestamp, controller, message, error
+    | filter level = "error"
+    | sort @timestamp desc
+    | limit 50
+
+### Filter logs for a specific ACK service controller
+
+Use the `controllerGroup` field to isolate logs from a specific ACK service controller:
+    
+    
+    fields @timestamp, message, error
+    | filter controllerGroup = "s3.services.k8s.aws"
+    | filter level = "error"
+    | sort @timestamp desc
+
+To filter further by resource kind (for example, only `SecurityGroup` logs from the EC2 controller):
+    
+    
+    fields @timestamp, message, error
+    | filter controllerGroup = "ec2.services.k8s.aws"
+    | filter controllerKind = "SecurityGroup"
+    | sort @timestamp desc
+    | limit 100
+
+### Filter logs for a specific Argo CD application
+
+Use the `application` field to isolate logs for a particular Argo CD application:
+    
+    
+    fields @timestamp, message, error
+    | filter application = "my-application"
+    | sort @timestamp desc
+    | limit 100
+
+### Track reconciliation for a specific resource
+
+Use the `reconcileID` field to follow a single reconciliation cycle:
+    
+    
+    fields @timestamp, level, message, error
+    | filter reconcileID = "your-reconcile-id"
+    | sort @timestamp asc
+
+### Common log patterns indicating issues
+
+  * **Repeated reconciliation errors** — The controller is unable to reach the desired state for a resource. Check the `error` field for details such as IAM permission failures or invalid resource configurations.
+
+  * **"Reconciler error" with AWS API errors** — The Capability Role may be missing permissions for the specific AWS service operation. Review the error message and update IAM policies accordingly.
+
+  * **No log entries for a resource** — If you don’t see logs for a resource you expect the controller to reconcile, verify the capability is `ACTIVE` and that the resource exists in a namespace the capability can access.