Help improve this page
Want to contribute to this user guide? Scroll to the bottom of this page
and select Edit this page on GitHub. Your contributions will help make our
user guide better for everyone.
Connect an external Kubernetes cluster to the Amazon EKS Management Console
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.
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
Step 1: Registering the cluster
- AWS CLI
-
To register your cluster with 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.
- AWS Management Console
-
To register your Kubernetes cluster with the console.
Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
-
Choose Add cluster and select
Register to bring up the configuration
page.
-
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.
-
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.
-
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
-
To register your cluster with 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
Step 2: Installing the eks-connector
agent
- Helm chart
-
If you registered the cluster with eksctl
, use the YAML manifest
method instead of the Helm chart method.
-
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
.
- YAML manifest
-
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.
-
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
Ensure that your activation code is in the base64 format.
-
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.
Next steps
If you have any issues with these steps, see Troubleshoot Amazon EKS Connector issues.
To grant additional IAM principals 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.