最近實在是遇到太多客戶使用 EKS Self-managed nodes 遇到無法加入 EKS Cluster 的問題，雖然在網路上的文章不少但要爬文並不容易，這篇來紀錄一下使用 Self-managed nodes 要注意的事項。

首先 AWS 官方文件在 Self-managed nodes 其實寫得蠻清楚的，但相信願意啃完且理解的人不多而且不容易，所以在這裡列了 6 點當你使用 Self-managed nodes 必須注意的問題。

Mandatory Tags for EC2 (worker nodes)

所有 Worker nodes (EC2) 都必須加上 Tags 用來辨識加入哪一個 EKS Cluster

Key: "kubernetes.io/cluster/<cluster-name>"
Value: "owned"

Mandatory Tags on subnets for 1.18 and earlier clusters

這條適用於 1.18 或更早的 EKS Cluster 中所有 Worker nodes (EC2) 的 subnets 都必須加上 Tags

Key: "kubernetes.io/cluster/<cluster-name>"
Value: "shared"

1.19 之後的版本就不需要這個 Tag 了，而當 1.18 升級上來的也不會預設刪掉 Tag。

Security Group inbound and outbound

Security Group 的話會有三者要考量：User, Control plane 和 Worker nodes 之間的溝通：

User <-- 443/tcp --> Control plane <-- Any --> Worker nodes

一個很簡單的示意圖，443 是用於 kubectl 等 command line 訪問 API endpoint 使用，而 Control plane <> Worker nodes 之間的溝通很吃 Application, daemonsets 的情境，如果沒什麼考量其實可以直接開放 Any 或者參考 Amazon EKS security group considerations

AMI version mapping Control plane

Worker node AMI 必須要考量 Control plane 的版本選擇，假設 Control plane v1.19 版則 Worker node AMI 就建議要以 v1.19 為主，這有關於 Kubernetes 版本相容性為主。而 EKS platform 版本比較與 Kubernetes AMI 沒有太大的差異。

bootstrap script in User data

AWS 有提供 Worker nodes 加入 Control plane 一個簡單的 bootstrap.sh 執行 Worker nodes 的安裝環境，基本上他做了幾項事情：

• 安裝並設定 Container Runtime (containerd or dockerd)
• 安裝並設定 Kubelet
• 安裝並設定 Nvidia for GPU (optional)

最簡單的方式是讓 bootstrap.sh 跑在 User data 讓開機時就跑一次

#!/bin/bash -xe

sudo /etc/eks/bootstrap.sh --apiserver-endpoint 'CLUSTER-ENDPOINT' --b64-cluster-ca 'CERTIFICATE_AUTHORITY_DATA' 'CLUSTER_NAME'

Update the aws-auth ConfigMap with the NodeInstanceRole

Control plane 預設情況只有建立 EKS 的 IAM 擁有權限，即便你是 IAM Administrator 也無法訪問，這是由於 Kubernetes 與 AWS IAM 權限並不是透通的，而是利用 RBAC 的方法作為訪問權限的依據，在 EKS 上即是 aws-auth ConfigMap：

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: <ARN of instance role (not instance profile)>
      username: system:node:{{EC2PrivateDNSName}}
      groups:
        - system:bootstrappers
        - system:nodes

mapRoles 即是開放 Worker nodes Role 的權限設定，相對的如果要開放 IAM User 訪問則是可以用 mapUsers：

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapUsers: |
    - userarn: <arn:aws:iam::111122223333:user/admin>
      username: <admin>
      groups:
        - <system:masters>

修改 aws-auth ConfigMap 後，最好也重啟 Worker nodes kubelet service 會更快生效，懶一點就直接 terminate 讓 Auto Scaling Group 重新長一套 instances 出來。

如果很不幸的過幾分鐘 kubectl get nodes 還是沒有加入成功，可以登入到 Worker node 檢查以下幾個 Logs 看看是否有一些蛛絲馬跡：

• Kubelet 服務與紀錄 systemctl status kubelet
• Container Runtime 服務與紀錄 systemctl status containerd
• bootstrap.sh 執行紀錄 /var/log/cloud-init-output.log

References

• How can I get my worker nodes to join my Amazon EKS cluster?
• 5 things you need to know to add worker nodes in the AWS EKS cluster

AWS eks Kuberntes