diff --git a/latest/ug/troubleshooting/troubleshooting.adoc b/latest/ug/troubleshooting/troubleshooting.adoc index 73beed7c..0e7aab24 100644 --- a/latest/ug/troubleshooting/troubleshooting.adoc +++ b/latest/ug/troubleshooting/troubleshooting.adoc @@ -16,6 +16,7 @@ :info_abstract: This chapter covers some common errors that you may see while using Amazon EKS and how \ to work around them. + include::../attributes.txt[] [abstract] @@ -27,6 +28,7 @@ This chapter covers some common errors that you may see while using Amazon EKS a For other troubleshooting information, see https://repost.aws/tags/knowledge-center/TA4IvCeWI1TE66q4jEj4Z9zg/amazon-elastic-kubernetes-service[Knowledge Center content about Amazon Elastic Kubernetes Service] on _{aws} re:Post_. + [[ice,ice.title]] == Insufficient capacity @@ -36,7 +38,8 @@ If you receive the following error while attempting to create an Amazon EKS clus Retry creating your cluster with subnets in your cluster VPC that are hosted in the Availability Zones returned by this error message. -There are Availability Zones that a cluster can't reside in. Compare the Availability Zones that your subnets are in with the list of Availability Zones in the <>. +There are Availability Zones that a cluster can't reside in. Compare the Availability Zones that your subnets are in with the list of Availability Zones in the link:eks/latest/userguide/network-reqs.html#network-requirements-subnets[Subnet requirements and considerations,type="documentation"]. + [[worker-node-fail,worker-node-fail.title]] == Nodes fail to join cluster @@ -45,9 +48,9 @@ There are a few common reasons that prevent nodes from joining the cluster: -* If the nodes are managed nodes, Amazon EKS adds entries to the `aws-auth` `ConfigMap` when you create the node group. If the entry was removed or modified, then you need to re-add it. For more information, enter `eksctl create iamidentitymapping --help` in your terminal. You can view your current `aws-auth` `ConfigMap` entries by replacing [.replaceable]`my-cluster` in the following command with the name of your cluster and then running the modified command: ``eksctl get iamidentitymapping --cluster [.replaceable]`my-cluster```. The ARN of the role that you specify can't include a link:IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names[path,type="documentation"] other than `/`. For example, if the name of your role is `development/apps/my-role`, you'd need to change it to `my-role` when specifying the ARN for the role. Make sure that you specify the node IAM role ARN (not the instance profile ARN). +* If the nodes are managed nodes, Amazon EKS adds entries to the `aws-auth` `ConfigMap` when you create the node group. If the entry was removed or modified, then you need to re-add it. For more information, enter `eksctl create iamidentitymapping --help` in your terminal. You can view your current `aws-auth` `ConfigMap` entries by replacing [.replaceable]`my-cluster` in the following command with the name of your cluster and then running the modified command: `eksctl get iamidentitymapping --cluster [.replaceable]``my-cluster```. The ARN of the role that you specify can't include a link:IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names[path,type="documentation"] other than `/`. For example, if the name of your role is `development/apps/my-role`, you'd need to change it to `my-role` when specifying the ARN for the role. Make sure that you specify the node IAM role ARN (not the instance profile ARN). + -If the nodes are self-managed, and you haven't created <> for the ARN of the node's IAM role, then run the same commands listed for managed nodes. If you have created an access entry for the ARN for your node IAM role, then it might not be configured properly in the access entry. Make sure that the node IAM role ARN (not the instance profile ARN) is specified as the principal ARN in your `aws-auth` `ConfigMap` entry or access entry. For more information about access entries, see <>. +If the nodes are self-managed, and you haven't created an link:eks/latest/userguide/access-entries.html[access entry,type="documentation"] for the ARN of the node's IAM role, then run the same commands listed for managed nodes. If you have created an access entry for the ARN for your node IAM role, then it might not be configured properly in the access entry. Make sure that the node IAM role ARN (not the instance profile ARN) is specified as the principal ARN in your `aws-auth` `ConfigMap` entry or access entry. For more information about access entries, see <>. * The *ClusterName* in your node {aws} CloudFormation template doesn't exactly match the name of the cluster you want your nodes to join. Passing an incorrect value to this field results in an incorrect configuration of the node's `/var/lib/kubelet/kubeconfig` file, and the nodes will not join the cluster. * The node is not tagged as being _owned_ by the cluster. Your nodes must have the following tag applied to them, where [.replaceable]`my-cluster` is replaced with the name of your cluster. + @@ -83,8 +86,8 @@ This could be due to one of the following reasons: * The cluster was created with credentials for one IAM principal and `kubectl` is configured to use credentials for a different IAM principal. To resolve this, update your `kube config` file to use the credentials that created the cluster. For more information, see <>. -* If your cluster meets the minimum platform requirements in the prerequisites section of <>, an access entry doesn't exist with your IAM principal. If it exists, it doesn't have the necessary [.noloc]`Kubernetes` group names defined for it, or doesn't have the proper access policy associated to it. For more information, see <>. -* If your cluster doesn't meet the minimum platform requirements in <>, an entry with your IAM principal doesn't exist in the `aws-auth` `ConfigMap`. If it exists, it's not mapped to [.noloc]`Kubernetes` group names that are bound to a [.noloc]`Kubernetes` `Role` or `ClusterRole` with the necessary permissions. For more information about [.noloc]`Kubernetes` role-based authorization (RBAC) objects, see https://kubernetes.io/docs/reference/access-authn-authz/rbac/[Using RBAC authorization] in the [.noloc]`Kubernetes` documentation. You can view your current `aws-auth` `ConfigMap` entries by replacing [.replaceable]`my-cluster` in the following command with the name of your cluster and then running the modified command: ``eksctl get iamidentitymapping --cluster [.replaceable]`my-cluster```. If an entry for with the ARN of your IAM principal isn't in the `ConfigMap`, enter `eksctl create iamidentitymapping --help` in your terminal to learn how to create one. +* If your cluster meets the minimum platform requirements in the prerequisites section of link:eks/latest/access-entries.html[access entries,type="documentation"], an access entry doesn't exist with your IAM principal. If it exists, it doesn't have the necessary [.noloc]`Kubernetes` group names defined for it, or doesn't have the proper access policy associated to it. For more information, see <>. +* If your cluster doesn't meet the minimum platform requirements in link:eks/latest/access-entries.html[access entries,type="documentation"], an entry with your IAM principal doesn't exist in the `aws-auth` `ConfigMap`. If it exists, it's not mapped to [.noloc]`Kubernetes` group names that are bound to a [.noloc]`Kubernetes` `Role` or `ClusterRole` with the necessary permissions. For more information about [.noloc]`Kubernetes` role-based authorization (RBAC) objects, see https://kubernetes.io/docs/reference/access-authn-authz/rbac/[Using RBAC authorization] in the [.noloc]`Kubernetes` documentation. You can view your current `aws-auth` `ConfigMap` entries by replacing [.replaceable]`my-cluster` in the following command with the name of your cluster and then running the modified command: `eksctl get iamidentitymapping --cluster [.replaceable]``my-cluster```. If an entry for with the ARN of your IAM principal isn't in the `ConfigMap`, enter `eksctl create iamidentitymapping --help` in your terminal to learn how to create one. If you install and configure the {aws} CLI, you can configure the IAM credentials that you use. For more information, see link:cli/latest/userguide/cli-chap-getting-started.html[Configuring the {aws} CLI,type="documentation"] in the _{aws} Command Line Interface User Guide_. You can also configure `kubectl` to use an IAM role, if you assume an IAM role to access [.noloc]`Kubernetes` objects on your cluster. For more information, see <>. @@ -720,4 +723,4 @@ The first two columns are what are needed for API response values. The third fie |=== -📝 https://github.com/search?q=repo:awsdocs/amazon-eks-user-guide+[[troubleshooting,&type=code[Edit this page on GitHub] \ No newline at end of file +📝 https://github.com/search?q=repo:awsdocs/amazon-eks-user-guide+[[troubleshooting,&type=code[Edit this page on GitHub]