Amazon EKS용 Amazon VPC CNI 애드온 관련 문제를 해결하려면 어떻게 해야 합니까?

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

Amazon VPC CNI 애드온이 초기화되지 않아 워커 노드가 준비되지 않은 경우 다음 예와 유사한 오류 메시지를 받습니다.

"container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not initialized"

이 문제를 확인하려면 다음 명령을 실행합니다.

kubectl describe node node_name

참고: node_name을 노드 이름으로 바꾸십시오. 출력에서 cni plugin no initialized 오류 메시지를 찾을 수 있습니다.

다음 작업을 수행하여 문제를 해결하십시오.

Amazon VPC CNI 애드온을 설치했는지 확인

클러스터에 aws-node 포드가 없는 경우 컨테이너 로그에 다음 예와 유사한 오류 메시지가 표시됩니다.

"cni config load failed: no network config found in /etc/cni/net.d: cni plugin not initialized: failed to load cni config"

이 문제를 해결하려면 Amazon VCP CNI 애드온을 설치하십시오.

IAM 권한 문제 확인

Amazon VPC CNI 애드온을 사용하려면 AmazonEKS_CNI_Policy AWS Identity and Access Management(IAM) 관리형 정책을 사용하십시오. 또는 사용자 지정 정책을 사용하는 경우 다음 권한이 포함되어 있는지 확인하십시오.

 "ec2:AssignPrivateIpAddresses",
 "ec2:AttachNetworkInterface",
 "ec2:CreateNetworkInterface",
 "ec2:DeleteNetworkInterface",
 "ec2:DescribeInstances",
 "ec2:DescribeTags",
 "ec2:DescribeNetworkInterfaces",
 "ec2:DescribeInstanceTypes",
 "ec2:DescribeSubnets",
 "ec2:DetachNetworkInterface",
 "ec2:ModifyNetworkInterfaceAttribute",
 "ec2:UnassignPrivateIpAddresses"
 "ec2:CreateTags"

누락된 IAM 권한을 식별하려면 /var/log/aws-routed-eni/ipamd.log 호스트 디렉터리에서 L-IPAM 대몬(IPAMD) 로그를 확인하십시오. Amazon VPC CNI 애드온에 필수 IAM 권한이 없는 경우 다음 예와 유사한 오류 메시지가 표시됩니다.

{"level":"error","ts":"2023-11-18T01:08:34.083Z","caller":"aws-k8s-agent/main.go:28","msg":"Initialization failure: ipamd init: failed to retrieve attached ENIs info: UnauthorizedOperation: You are not authorized to perform this operation. User: arn:aws:sts::XXXXXXXXXXXXXXXXXXXX:assumed-role/rolename is not authorized to perform: ec2:DescribeNetworkInterfaces because no identity-based policy allows the ec2:DescribeNetworkInterfaces action\n\tstatus code: 403, request id: request id"}

위의 오류 메시지 예는 애드온을 사용하려면 ec2:DescribeNetworkInterfaces 권한이 필요하다는 것을 보여줍니다.

워커 노드에 직접 액세스할 수 없는 경우 워커 노드에서 aws-node 포드를 확인하십시오. 워커 노드에서 aws-node 포드를 식별하려면 다음 명령을 실행합니다.

kubectl describe node node_name

참고: node_name을 노드 이름으로 바꾸십시오. 출력의 종료되지 않은 포드 섹션에서 aws-node 포드 이름을 확인합니다.

그 후 다음 명령을 실행하여 aws-node 포드에 대한 세부 정보를 확인합니다.

kubectl describe pod pod-name -n kube-system

참고: pod-name을 aws-node 포드 이름으로 바꾸십시오.

출력에서 누락된 권한에 대한 정보를 보려면 이벤트를 확인하십시오.

출력 예시:

Type Reason Age From Message
---- ------ ---- ---- -------
Warning MissingIAMPermissions 105s (x2 over 105s) aws-node Unauthorized operation: failed to call ec2:DescribeNetworkInterfaces due to missing permissions. Please refer https://github.com/aws/amazon-vpc-cni-k8s/blob/master/docs/iam-policy.md to attach relevant policy to IAM role in the event section you can able to see the error message also you can check the AWS cloud trail event for the particular instance by filtering the cloudtrail with username and provide the instanceID there.

또는 AWS CloudTrail을 사용하여 특정 이벤트를 확인하십시오. 예를 들어, DescribeNetworkInterfaces API 직접 호출의 사용자 이름과 인스턴스 ID를 확인하여 실행 여부를 확인하십시오.

네트워크 문제 확인

Amazon VPC CNI 애드온은 실행 시 API 서버 엔드포인트와 Amazon Elastic Compute Cloud(Amazon EC2) 엔드포인트에 연결해야 합니다. 두 연결 중 하나라도 실패하면 애드온을 초기화할 수 없으며 노드는 NotReady 상태로 전환됩니다.

특정 오류 메시지를 확인하려면 /var/log/aws-routed-eni/ipamd.log 호스트 디렉터리에서 IPAMD 로그를 검토하십시오. kube-proxy 및 coreDNS 포드가 오류 없이 실행될 수 있는지 확인하십시오.

애드온 구성 요소 버전 확인

핵심 구성 요소를 최신 버전으로 업데이트하는 것이 가장 좋습니다. 애드온 버전이 Kubernetes 클러스터 버전과 일치하지 않으면 애드온을 초기화할 수 없습니다. 애드온 버전이 Kubernetes 클러스터 버전과 호환되는지 확인하십시오.

Amazon VPC CNI 애드온 오류 해결

애드온 오류를 식별하려면 애드온이 IP 주소를 할당할 수 없는 워커 노드에 SSH를 사용하여 연결합니다. 그런 다음, /var/log/aws-routed-eni/ipamd.log 파일의 IPAMD 로그에서 오류 메시지를 검토하십시오.

Failed to assign ip 오류

Failed to assign ip 오류는 Amazon VPC CNI 애드온이 워커 노드에 예약된 포드에 IP 주소를 할당할 수 없을 때 발생합니다. 오류를 식별하기 위해 CloudTrail 이벤트 기록 페이지에서 AssignPrivateIpAddresses 이벤트를 확인할 수도 있습니다.

할당된 서브넷에 사용 가능한 IP 주소가 없는지 확인하려면 다음 describe-subnets AWS CLI 명령을 실행합니다.

aws ec2 describe-subnets --filters "Name=vpc-id,Values= VPCID" | jq '.Subnets[] | .SubnetId + "=" + "\(.AvailableIpAddressCount)"'

참고: VPCID를 VPC ID로 바꾸십시오.

WARM_ENI_TARGET, WARM_IP_TARGET 또는 MINIMUM_IP_TARGET 환경 변수의 값을 너무 낮게 설정한 경우에도 Failed to assign ip 오류가 발생할 수 있습니다. 서브넷 CIDR 범위가 충분히 넓고 사용 사례에 맞는 IP 주소 할당이 충분한지 확인하십시오. 자세한 내용은 GitHub 웹 사이트에서 WARM_ENI_TARGET, WARM_IP_TARGET 및 MINIMUM_IP_TARGET을 참조하십시오.

환경 변수 값을 확인하려면 다음 명령을 실행하여 포드 세부 정보를 확인하십시오.

kubectl describe pod pod-name -n kube-system

참고: pod-name을 aws-node 포드 이름으로 바꾸십시오.

aws-node DaemonSet에서 환경 변수를 업데이트할 수 있습니다.

env:
  - name: WARM_ENI_TARGET
    value: "1"
  - name: WARM_IP_TARGET
    value: "5"
  - name: MINIMUM_IP_TARGET
    value: "25"

또는 다음 명령을 실행하여 환경 변수를 업데이트합니다.

kubectl set env ds aws-node -n kube-system WARM_ENI_TARGET=1 WARM_IP_TARGET=5 MINIMUM_IP_TARGET=25

접두사 위임 모드를 사용하고 전용 포드 서브넷 범위를 사용하지 않는 경우 서브넷 조각화로 인해 애드온이 실패할 수 있습니다. 애드온은 IPv4의 경우 연속 /28을, IPv6 접두사 범위의 경우 /80을 네트워크 인터페이스에 할당해야 합니다. 접두사 위임에 대한 자세한 내용은 GitHub 웹 사이트에서 ENABLE_PREFIX_DELEGATION을 참조하십시오.

서브넷 조각화를 직접 확인할 수는 없습니다. 대신 서브넷 CIDR 범위에 사용 가능한 IP 주소가 16개 이상 있는지 확인하십시오. IP 주소가 충분한데도 Failed to assign ip 오류가 자주 발생하는 경우, 문제는 일반적으로 서브넷 조각화입니다. 이 문제를 해결하려면 접두사 위임이 포함된 사용자 지정 네트워킹을 사용하여 포드에 전용 서브넷을 설정하는 것이 가장 좋습니다. 자세한 내용은 GitHub 웹 사이트에서 AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG를 참조하십시오.

Failed to get pod ENI config 오류

AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG를 사용하여 사용자 지정 네트워킹을 활성화하지만 ENIConfig 리소스를 생성하지 않는 경우 다음 예와 유사한 오류 메시지가 표시됩니다.

"{"level":"error","ts":"","caller":"ipamd/ipamd.go:798","msg":"Failed to get pod ENI config"}"

ENIConfig 리소스가 클러스터에 있는지 확인하려면 다음 명령을 실행합니다.

kubectl get eniconfig -o yaml

ENIConfig 사용자 지정 리소스가 없으면 새로 생성하십시오. 사용자 지정 네트워킹에 대한 자세한 내용은 GitHub 웹 사이트에서 AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG를 참조하십시오.

Failed to watch 오류

YAML 파일을 올바른 형식으로 작성하지 않으면 다음 예와 유사한 오류 메시지가 표시될 수 있습니다.

"Failed to watch *v1alpha1.ENIConfig: failed to list *v1alpha1.ENIConfig:json: cannot unmarshal string into Go struct field ENIConfigSpec.items.spec.securityGroups of type []string"

이 문제는 일반적으로 JSON 데이터와 Go 데이터 유형 정의가 일치하지 않을 때 발생합니다. 위의 오류 메시지 예는 securityGroups 필드에 문제가 있음을 보여줍니다.

이 문제를 해결하려면 다음 명령을 실행하여 JSON 데이터를 확인하십시오.

kubectl describe ENIConfig

명령 출력에서 오류 메시지에 식별된 문제를 기반으로 구문을 확인합니다. 예를 들어, JSON의 securityGroups 필드는 단일 문자열이 아닌 문자열 배열이어야 합니다.

출력 예시:

cat >$az_1.yaml <<EOF
apiVersion: crd.k8s.amazonaws.com/v1alpha1
kind: ENIConfig
metadata:
  name: us-west-2a
spec:
  securityGroups:
    - sg-0123456789abcdef0
  subnet: subnet-0123456789abcdef0
EOF