Connect an external Kubernetes cluster to the Amazon EKS Management Console

AWS CLI must be installed. To install or upgrade it, see Installing the AWS CLI.

For the Connector configuration, specify your Amazon EKS Connector agent IAM role. For more information, see Required IAM roles for Amazon EKS Connector.

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.

Open the Amazon EKS console.

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

On the Configure cluster section, fill in the following fields:

Select Register cluster.

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.

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.

eksctl version 0.68 or later must be installed. To install or upgrade it, see Get started with Amazon EKS – eksctl.

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.

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

kubectl apply -f eks-connector-binding.yaml

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.

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

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

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

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

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.

(Optional) Add tags to your cluster. For more information, see Organize Amazon EKS resources with tags.