**Help improve this page** 

To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page.

# Connect an external Kubernetes cluster to the Amazon EKS Management Console
Connect a cluster

You can connect an external Kubernetes cluster to Amazon EKS by using multiple methods in the following process. This process involves two steps: Registering the cluster with Amazon EKS and installing the `eks-connector` agent in the cluster.

**Important**  
You must complete the second step within 3 days of completing the first step, before the registration expires.

## Considerations


You can use YAML manifests when installing the agent. Alternatively, you can use Helm if you register the cluster with the AWS Management Console or AWS Command Line Interface. However, you cannot use Helm to install the agent if you register the cluster with `eksctl`.

## Prerequisites

+ Ensure the Amazon EKS Connector agent role was created. Follow the steps in [Creating the Amazon EKS connector agent role](connector-iam-role.md#create-connector-role).
+ You must have the following permissions to register a cluster:
  +  `eks:RegisterCluster` 
  +  `ssm:CreateActivation` 
  +  `ssm:DeleteActivation` 
  +  `iam:PassRole` 

## Step 1: Registering the cluster


To register a cluster to Amazon EKS connector, you can use one of these tools:
+  [AWS CLI](#awscli_register_cluster_connect) 
+  [AWS Management Console](#console_register_cluster_connect) 
+  [`eksctl`](#eksctl_register_cluster_connect) 

### AWS CLI


1.  AWS CLI must be installed. To install or upgrade it, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).

1. For the Connector configuration, specify your Amazon EKS Connector agent IAM role. For more information, see [Required IAM roles for Amazon EKS Connector](eks-connector.md#connector-iam-permissions).

   ```
   aws eks register-cluster \
        --name my-first-registered-cluster \
        --connector-config roleArn=arn:aws:iam::111122223333:role/AmazonEKSConnectorAgentRole,provider="OTHER" \
        --region aws-region
   ```

   An example output is as follows.

   ```
   {
       "cluster": {
           "name": "my-first-registered-cluster",
           "arn": "arn:aws:eks:region:111122223333:cluster/my-first-registered-cluster",
           "createdAt": 1627669203.531,
           "ConnectorConfig": {
               "activationId": "xxxxxxxxACTIVATION_IDxxxxxxxx",
               "activationCode": "xxxxxxxxACTIVATION_CODExxxxxxxx",
               "activationExpiry": 1627672543.0,
               "provider": "OTHER",
               "roleArn": "arn:aws:iam::111122223333:role/AmazonEKSConnectorAgentRole"
           },
           "status": "CREATING"
       }
   }
   ```

   You use the `aws-region`, `activationId`, and `activationCode` values in the next step.

### AWS Management Console


1. Open the [Amazon EKS console](https://console.aws.amazon.com/eks/home#/clusters).

1. Choose **Add cluster** and select **Register** to bring up the configuration page.

1. On the **Configure cluster** section, fill in the following fields:
   +  **Name** – A unique name for your cluster.
   +  **Provider** – Choose to display the dropdown list of Kubernetes cluster providers. If you don’t know the specific provider, select **Other**.
   +  **EKS Connector role** – Select the role to use for connecting the cluster.

1. Select **Register cluster**.

1. The Cluster overview page displays. If you want to use the Helm chart, copy the `helm install` command and continue to the next step. If you want to use the YAML manifest, choose **Download YAML file** to download the manifest file to your local drive.
**Important**  
This is your only opportunity to copy the `helm install` command or download this file. Don’t navigate away from this page, as the link will not be accessible and you must deregister the cluster and start the steps from the beginning.

   The command or manifest file can be used only once for the registered cluster. If you delete resources from the Kubernetes cluster, you must re-register the cluster and obtain a new manifest file.

Continue to the next step to apply the manifest file to your Kubernetes cluster.

### `eksctl`


1.  `eksctl` version `0.68` or later must be installed. To install or upgrade it, see [Get started with Amazon EKS – `eksctl`](getting-started-eksctl.md).

1. Register the cluster by providing a name, provider, and region.

   ```
   eksctl register cluster --name my-cluster --provider my-provider --region region-code
   ```

   Example output:

   ```
   2021-08-19 13:47:26 [ℹ]  creating IAM role "eksctl-20210819194112186040"
   2021-08-19 13:47:26 [ℹ]  registered cluster "<name>" successfully
   2021-08-19 13:47:26 [ℹ]  wrote file eks-connector.yaml to <current directory>
   2021-08-19 13:47:26 [ℹ]  wrote file eks-connector-clusterrole.yaml to <current directory>
   2021-08-19 13:47:26 [ℹ]  wrote file eks-connector-console-dashboard-full-access-group.yaml to <current directory>
   2021-08-19 13:47:26 [!]  note: "eks-connector-clusterrole.yaml" and "eks-connector-console-dashboard-full-access-group.yaml" give full EKS Console access to IAM identity "<aws-arn>", edit if required; read https://eksctl.io/usage/eks-connector for more info
   2021-08-19 13:47:26 [ℹ]  run `kubectl apply -f eks-connector.yaml,eks-connector-clusterrole.yaml,eks-connector-console-dashboard-full-access-group.yaml` before expiry> to connect the cluster
   ```

   This creates files on your local computer. These files must be applied to the external cluster within 3 days, or the registration expires.

1. In a terminal that can access the cluster, apply the `eks-connector-binding.yaml` file:

   ```
   kubectl apply -f eks-connector-binding.yaml
   ```

## Step 2: Installing the `eks-connector` agent


To install the `eks-connector` agent, use one of the following tools:
+  [Helm](#helm_agent_cluster_connect) 
+  [yaml](#yaml_agent_cluster_connect) 

### Helm


**Note**  
If you registered the cluster with `eksctl`, use the YAML manifest method instead of the Helm chart method.

1. If you used the AWS CLI in the previous step, replace the `ACTIVATION_CODE` and `ACTIVATION_ID` in the following command with the `activationId`, and `activationCode` values respectively. Replace the `aws-region` with the AWS Region that you used in the previous step. Then run the command to install the `eks-connector` agent on the registering cluster:

   ```
   $ helm install eks-connector \
     --namespace eks-connector \
     oci://public.ecr.aws/eks-connector/eks-connector-chart \
     --set eks.activationCode=ACTIVATION_CODE \
     --set eks.activationId=ACTIVATION_ID \
     --set eks.agentRegion=aws-region
   ```

   If you used the AWS Management Console in the previous step, use the command that you copied from the previous step that has these values filled in.

1. Check the healthiness of the installed `eks-connector` deployment and wait for the status of the registered cluster in Amazon EKS to be `ACTIVE`.

### yaml


Complete the connection by applying the Amazon EKS Connector manifest file to your Kubernetes cluster. To do this, you must use the methods described previously. If the manifest isn’t applied within three days, the Amazon EKS Connector registration expires. If the cluster connection expires, the cluster must be deregistered before connecting the cluster again.

1. Download the Amazon EKS Connector YAML file.

   ```
   curl -O https://amazon-eks.s3.us-west-2.amazonaws.com/eks-connector/manifests/eks-connector/latest/eks-connector.yaml
   ```

1. Edit the Amazon EKS Connector YAML file to replace all references of `%AWS_REGION%`, `%EKS_ACTIVATION_ID%`, `%EKS_ACTIVATION_CODE%` with the `aws-region`, `activationId`, and `activationCode` from the output of the previous step.

   The following example command can replace these values.

   ```
   sed -i "s~%AWS_REGION%~$aws-region~g; s~%EKS_ACTIVATION_ID%~$EKS_ACTIVATION_ID~g; s~%EKS_ACTIVATION_CODE%~$(echo -n $EKS_ACTIVATION_CODE | base64)~g" eks-connector.yaml
   ```
**Important**  
Ensure that your activation code is in the base64 format.

1. In a terminal that can access the cluster, you can apply the updated manifest file by running the following command:

   ```
   kubectl apply -f eks-connector.yaml
   ```

1. After the Amazon EKS Connector manifest and role binding YAML files are applied to your Kubernetes cluster, confirm that the cluster is now connected.

   ```
   aws eks describe-cluster \
        --name "my-first-registered-cluster" \
        --region AWS_REGION
   ```

   The output should include `status=ACTIVE`.

1. (Optional) Add tags to your cluster. For more information, see [Organize Amazon EKS resources with tags](eks-using-tags.md).

## Next steps


If you have any issues with these steps, see [Troubleshoot Amazon EKS Connector issues](troubleshooting-connector.md).

To grant additional [IAM principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-principal) access to the Amazon EKS console to view Kubernetes resources in a connected cluster, see [Grant access to view Kubernetes cluster resources on an Amazon EKS console](connector-grant-access.md).