Creating an EKS Cluster
Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this documentation.
Prerequisites in Amazon Web Services
Note Deploying to Amazon AWS will incur charges. For more information, refer to the EKS pricing page.
To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate permissions. For details, refer to the official guide on Amazon EKS Prerequisites.
Amazon VPC
You need to set up an Amazon VPC to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. For more information, refer to the Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster.
IAM Policies
Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access.
Create a user with programmatic access by following the steps here.
Next, create an IAM policy that defines what this user has access to in your AWS account. It's important to only grant this user minimal access within your account. The minimum permissions required for an EKS cluster are listed here. Follow the steps here to create an IAM policy and attach it to your user.
Finally, follow the steps here to create an access key and secret key for this user.
Note: It's important to regularly rotate your access and secret keys. See this documentation for more information.
For more detailed information on IAM policies for EKS, refer to the official documentation on Amazon EKS IAM Policies, Roles, and Permissions.
Architecture
The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS.
Create the EKS Cluster
Use Rancher to set up and configure your Kubernetes cluster.
From the Clusters page, click Add Cluster.
Choose Amazon EKS.
Enter a Cluster Name.
Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
Fill out the rest of the form. For help, refer to the configuration reference.
Click Create.
Result:
Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.
You can access your cluster after its state is updated to Active.
Active clusters are assigned two Projects:
Default, containing thedefaultnamespaceSystem, containing thecattle-system,ingress-nginx,kube-public, andkube-systemnamespaces
EKS Cluster Configuration Reference
Account Access
Complete each drop-down and field using the information obtained for your IAM policy.
| Setting | Description |
|---|---|
| Region | From the drop-down choose the geographical region in which to build your cluster. |
| Access Key | Enter the access key that you created for your IAM policy. |
| Secret Key | Enter the secret key that you created for your IAM policy. |
Service Role
Choose a service role.
| Service Role | Description |
|---|---|
| Standard: Rancher generated service role | If you choose this role, Rancher automatically adds a service role for use with the cluster. |
| Custom: Choose from your existing service roles | If you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the Amazon documentation. |
Public IP for Worker Nodes
Your selection for this option determines what options are available for VPC & Subnet.
| Option | Description |
|---|---|
| Yes | When your cluster nodes are provisioned, they're assigned a both a private and public IP address. |
| No: Private IPs only | When your cluster nodes are provisioned, they're assigned only a private IP address. If you choose this option, you must also choose a VPC & Subnet that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane. |
VPC & Subnet
The available options depend on the public IP for worker nodes.
| Option | Description |
|---|---|
| Standard: Rancher generated VPC and Subnet | While provisioning your cluster, Rancher generates a new VPC and Subnet. |
| Custom: Choose from your existing VPC and Subnets | While provisioning your cluster, Rancher configures your nodes to use a VPC and Subnet that you've already created in AWS. If you choose this option, complete the remaining steps below. |
For more information, refer to the AWS documentation for Cluster VPC Considerations. Follow one of the sets of instructions below based on your selection from the previous step.
If you choose to assign a public IP address to your cluster's worker nodes, you have the option of choosing between a VPC that's automatically generated by Rancher (i.e., Standard: Rancher generated VPC and Subnet), or a VPC that you've already created with AWS (i.e., Custom: Choose from your existing VPC and Subnets). Choose the option that best fits your use case.
Click to expand
If you're using Custom: Choose from your existing VPC and Subnets:
(If you're using Standard, skip to the instance options.)
Make sure Custom: Choose from your existing VPC and Subnets is selected.
From the drop-down that displays, choose a VPC.
Click Next: Select Subnets. Then choose one of the Subnets that displays.
Click Next: Select Security Group.
If your worker nodes have Private IPs only, you must also choose a VPC & Subnet that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane.
Click to expand
Follow the steps below.
Tip: When using only private IP addresses, you can provide your nodes internet access by creating a VPC constructed with two subnets, a private set and a public set. The private set should have its route tables configured to point toward a NAT in the public set. For more information on routing traffic from private subnets, please see the official AWS documentation.
From the drop-down that displays, choose a VPC.
Click Next: Select Subnets. Then choose one of the Subnets that displays.
Security Group
Amazon Documentation:
Instance Options
Instance type and size of your worker nodes affects how many IP addresses each worker node will have available. See this documentation for more information.
| Option | Description |
|---|---|
| Instance Type | Choose the hardware specs for the instance you're provisioning. |
| Custom AMI Override | If you want to use a custom Amazon Machine Image (AMI), specify it here. By default, Rancher will use the EKS-optimized AMI for the EKS version that you chose. |
| Desired ASG Size | The number of instances that your cluster will provision. |
| User Data | Custom commands can to be passed to perform automated configuration tasks WARNING: Modifying this may cause your nodes to be unable to join the cluster. Note: Available as of v2.2.0 |
Troubleshooting
If an unauthorized error is returned while attempting to modify or import the cluster and the cluster was not created with the role or user that your credentials belong to, refer to Security and Compliance.
For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this documentation.
AWS Service Events
To find information on any AWS Service events, please see this page.
Security and Compliance
By default only the IAM user or role that created a cluster has access to it. Attempting to access the cluster with any other user or role without additional configuration will lead to an error. In Rancher, this means using a credential that maps to a user or role that was not used to create the cluster will cause an unauthorized error. For example, an EKSCtl cluster will not be imported in Rancher unless the credentials used to import the cluster match the role or user used by EKSCtl. Additional users and roles can be authorized to access a cluster by being added to the aws-auth configmap in the kube-system namespace. For a more in-depth explanation and detailed instructions, please see this documentation.
For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this documentation.
Tutorial
This tutorial on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB.
Minimum EKS Permissions
Documented here is a minimum set of permissions necessary to use all functionality of the EKS driver in Rancher. Additional permissions are required for Rancher to provision the Service Role and VPC resources. Optionally these resources can be created before the cluster creation and will be selectable when defining the cluster configuration.
| Resource | Description |
|---|---|
| Service Role | The service role provides Kubernetes the permissions it requires to manage resources on your behalf. Rancher can create the service role with the following Service Role Permissions. |
| VPC | Provides isolated network resources utilised by EKS and worker nodes. Rancher can create the VPC resources with the following VPC Permissions. |
Resource targeting uses * as the ARN of many of the resources created cannot be known before creating the EKS cluster in Rancher.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EC2Permissions",
"Effect": "Allow",
"Action": [
"ec2:RunInstances",
"ec2:RevokeSecurityGroupIngress",
"ec2:RevokeSecurityGroupEgress",
"ec2:DescribeVpcs",
"ec2:DescribeTags",
"ec2:DescribeSubnets",
"ec2:DescribeSecurityGroups",
"ec2:DescribeRouteTables",
"ec2:DescribeLaunchTemplateVersions",
"ec2:DescribeLaunchTemplates",
"ec2:DescribeKeyPairs",
"ec2:DescribeInternetGateways",
"ec2:DescribeImages",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeAccountAttributes",
"ec2:DeleteTags",
"ec2:DeleteLaunchTemplate",
"ec2:DeleteSecurityGroup",
"ec2:DeleteKeyPair",
"ec2:CreateTags",
"ec2:CreateSecurityGroup",
"ec2:CreateLaunchTemplateVersion",
"ec2:CreateLaunchTemplate",
"ec2:CreateKeyPair",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress"
],
"Resource": "*"
},
{
"Sid": "CloudFormationPermissions",
"Effect": "Allow",
"Action": [
"cloudformation:ListStacks",
"cloudformation:ListStackResources",
"cloudformation:DescribeStacks",
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackResource",
"cloudformation:DeleteStack",
"cloudformation:CreateStackSet",
"cloudformation:CreateStack"
],
"Resource": "*"
},
{
"Sid": "IAMPermissions",
"Effect": "Allow",
"Action": [
"iam:PassRole",
"iam:ListRoles",
"iam:ListRoleTags",
"iam:ListInstanceProfilesForRole",
"iam:ListInstanceProfiles",
"iam:ListAttachedRolePolicies",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:DetachRolePolicy",
"iam:DeleteRole",
"iam:CreateRole",
"iam:AttachRolePolicy"
],
"Resource": "*"
},
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": "kms:ListKeys",
"Resource": "*"
},
{
"Sid": "EKSPermissions",
"Effect": "Allow",
"Action": [
"eks:UpdateNodegroupVersion",
"eks:UpdateNodegroupConfig",
"eks:UpdateClusterVersion",
"eks:UpdateClusterConfig",
"eks:UntagResource",
"eks:TagResource",
"eks:ListUpdates",
"eks:ListTagsForResource",
"eks:ListNodegroups",
"eks:ListFargateProfiles",
"eks:ListClusters",
"eks:DescribeUpdate",
"eks:DescribeNodegroup",
"eks:DescribeFargateProfile",
"eks:DescribeCluster",
"eks:DeleteNodegroup",
"eks:DeleteFargateProfile",
"eks:DeleteCluster",
"eks:CreateNodegroup",
"eks:CreateFargateProfile",
"eks:CreateCluster"
],
"Resource": "*"
}
]
}
Service Role Permissions
Rancher will create a service role with the following trust policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Principal": {
"Service": "eks.amazonaws.com"
},
"Effect": "Allow",
"Sid": ""
}
]
}
This role will also have two role policy attachments with the following policies ARNs:
arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
arn:aws:iam::aws:policy/AmazonEKSServicePolicy
Permissions required for Rancher to create service role on users behalf during the EKS cluster creation process.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "IAMPermissions",
"Effect": "Allow",
"Action": [
"iam:AddRoleToInstanceProfile",
"iam:AttachRolePolicy",
"iam:CreateInstanceProfile",
"iam:CreateRole",
"iam:CreateServiceLinkedRole",
"iam:DeleteInstanceProfile",
"iam:DeleteRole",
"iam:DetachRolePolicy",
"iam:GetInstanceProfile",
"iam:GetRole",
"iam:ListAttachedRolePolicies",
"iam:ListInstanceProfiles",
"iam:ListInstanceProfilesForRole",
"iam:ListRoles",
"iam:ListRoleTags",
"iam:PassRole",
"iam:RemoveRoleFromInstanceProfile"
],
"Resource": "*"
}
]
}
VPC Permissions
Permissions required for Rancher to create VPC and associated resources.
{
"Sid": "VPCPermissions",
"Effect": "Allow",
"Action": [
"ec2:ReplaceRoute",
"ec2:ModifyVpcAttribute",
"ec2:ModifySubnetAttribute",
"ec2:DisassociateRouteTable",
"ec2:DetachInternetGateway",
"ec2:DescribeVpcs",
"ec2:DeleteVpc",
"ec2:DeleteTags",
"ec2:DeleteSubnet",
"ec2:DeleteRouteTable",
"ec2:DeleteRoute",
"ec2:DeleteInternetGateway",
"ec2:CreateVpc",
"ec2:CreateSubnet",
"ec2:CreateSecurityGroup",
"ec2:CreateRouteTable",
"ec2:CreateRoute",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:AssociateRouteTable"
],
"Resource": "*"
}