Add an existing EKS cluster

After creating a credential to access your Amazon Web Services (AWS) Elastic Kubernetes Service (EKS) account, you can bring the existing clusters in your account under the management of Tanzu Platform for Kubernetes.

If you have an existing EKS cluster on which you want to deploy a Space, you can add the cluster to Tanzu Platform. The following procedure provides the steps to add an existing EKS cluster and specify the cluster group with which to associate the cluster. When you associate the cluster with a cluster group, all the resources associated with the cluster group are also deployed to the cluster.

Before you begin

You need the following to add an existing EKS cluster:

• A Tanzu Platform EKS credential role ARN. If you don’t have a role ARN, you can create the role when you go through the steps in Tanzu Platform hub to add the EKS cluster. The instructions to generate the role ARN are provided in Tanzu Platform hub.

• An EKS cluster ARN.

• In Tanzu Platform for Kubernetes:

  • An EKS credential for life cycle management. For more information, see Create an AWS account credential for EKS cluster lifecycle management.
  • A Project.
  • A cluster group.

• If you are using the Tanzu CLI:

  • Ensure that you have Tanzu CLI v1.4.0 or later.

  Note

  To make installing subsequent updates easier, use the package manager method to install the Tanzu CLI, rather than installing from a binary release.

  • Create a Tanzu CLI context. For how to create the Tanzu CLI context, see Create a Tanzu CLI Context.

Gain admin access

You need admin access for the Tanzu Platform EKS credential role ARN to EKS cluster. Depending on the EKS cluster authentication mode, there are two ways to do this.

Run the following AWS CLI command to identify the authentication mode.

aws eks describe-cluster --name foo | jq -r .cluster.accessConfig.authenticationMode

• If the output is API or API_AND_CONFIG_MAP, follow these steps:

  1. Create an access entry using the Tanzu Platform EKS credential role ARN as Principal ARN by running:

     aws eks create-access-entry --cluster-name foo --principal-arn tanzu-platform-eks-credential-role-ARN
     

  2. Associate the EKS Cluster Admin Policy with the access entry by running:

     aws eks associate-access-policy --cluster-name foo --principal-arn \
     tanzu-platform-eks-credential-role-ARN --policy-arn \
     arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
     --access-scope type=cluster
     

     This gives the Tanzu Platform EKS credential role admin access to the EKS cluster.

• If the output is CONFIG_MAP, follow these steps:

  1. Add a new kubeconfig context for the cluster you want to bring under Tanzu Platform management by running:

     aws eks update-kubeconfig --name foo --kubeconfig mykubeconfig-name --region myregion-name
     

  2. Get the aws-auth configmap by running:

     kubectl get configmap -n kube-system aws-auth -o yaml --kubeconfig=mykubeconfig-name
     

     The aws-auth configmap is not created until there is at least one node group associated with the cluster.

  3. Create a new group and cluster role binding by running:

     kubectl create clusterrolebinding my-cluster-rolebinding-name --clusterrole=cluster-admin \
     --group=mygroup-name --kubeconfig=mykubeconfig-name
     

  4. Edit the aws-auth configmap by running:

     kubectl edit configmaps -n kube-system aws-auth -o yaml --kubeconfig=mykubeconfig-name
     

  5. Add the following code block to the mapRoles section of the aws-auth configmap:

     - groups:
     - mygroup-name
     rolearn: tanzu-platform-eks-credential-role-ARN
     

  6. Validate the changes to, and formatting of, the aws-auth configmap by running:

     kubectl get configmap aws-auth -n kube-system -o yaml --kubeconfig=mykubeconfig-name
     

Fulfil these extra requirements:

• The EKS cluster must have managed Nodegroups.

• The EKS cluster must have kube-proxy, coreDNS, and vpc-cni add-ons. aws-ebs-csi-driver is optional. Tanzu Platform manages these add-ons.

  Note

  The EKS cluster can have aws-efs-csi-driver, aws-guardduty-agent, eks-pod-identity-agent, amazon-cloudwatch-observability, or snapshot-controller add-ons, but Tanzu Platform does not manage upgrades for these add-ons.

• The node pools cannot have ARM architecture-based nodes.
• The Tanzu Platform EKS credential role needs to have some permissions to access the EKS cluster. To add the permission, see the Tanzu Mission Control documentation.
• (Optional) To use Bitnami Services in your Space, the EKS cluster must have the Amazon EBS CSI driver installed.

Add an EKS cluster

You can add an existing EKS cluster by using Tanzu Platform hub or the Tanzu CLI.

Tanzu Platform hub

Perform the following steps in Tanzu Platform hub:

1. Select the Project in which you want to work.
2. In the left navigation pane, click to expand Infrastructure and then click Kubernetes Clusters.
3. On the Clusters tab of the Kubernetes Clusters page, click Add Cluster, and then click Manage existing EKS cluster.
4. Follow the instructions in the UI to add the EKS cluster.

Tanzu CLI

Run these commands:

1. Add an existing EKS cluster by running:

   tanzu operations pekscluster manage <name of the cluster> -c <credential name> -r <region> -g \
   <cluster group> -a <roleArn>
   

2. Remove the cluster from Tanzu Platform management by running:

   tanzu operations pekscluster unmanage <name of the cluster> -c <credential name> -r <region> \
   -g <cluster group>
   

After you add the cluster, it is listed on the Clusters tab of the Kubernetes Clusters page. You might need to wait up to five minutes before you can perform actions on the newly added EKS cluster.