Ncloud Kubernetes Service 문제 해결

VPC 환경에서 이용 가능합니다.

Ncloud Kubernetes Service를 이용하면서 사용자가 만날 수 있는 문제 상황과 원인 및 해결 방법을 안내합니다. 하지만 일부 문제 상황은 다음 안내를 숙지하여도 사용자가 직접 해결하기 어려운 과제일 수 있습니다. 이러한 사용자의 어려움을 효율적으로 해결하고자 네이버 클라우드 플랫폼은 다양한 문제 해결 창구도 함께 제공하고 있습니다. 문제 해결 가이드를 통해 해결하지 못한 경우 고객 센터를 통해 확인할 수 있습니다.

Ncloud Kubernetes Service 설정 및 관리

Q. Ncloud Kubernetes Service의 클러스터가 오랜 시간 동안 작업 중을 유지합니다.

A. 신규 클러스터 생성 및 삭제, 노드풀 스케일 인아웃, 클러스터 업그레이드 중 오랜 시간 동안 작업 중 상태를 유지하는 경우 네이버클라우드플랫폼 포털의 고객 문의를 통해 문제 상황을 확인하고 해결할 수 있습니다.

Q. Ncloud Kubernetes Service의 클러스터 생성 이후 Cilium-Operator 파드가 Pending 상태입니다.

A. Ncloud Kubernetes Service는 CNI인 Cilium의 안정적인 동작을 위하여 Operator의 개수가 2개로 설정되어 있습니다. 따라서 워커노드가 1개인 클러스터의 경우 한 개의 Cilium Operator가 Pending 상태를 가지게 됩니다. 이는 의도된 바이며 실제 Cilium의 동작에 영향을 끼치지 않습니다. Cilium-Operator의 Scale을 조정하시거나 워커노드의 개수를 증가시켜 해소할 수 있습니다.

Q. Ncloud Kubernetes Service의 워커노드가 Not Ready 상태를 보이고 있습니다.

A. 워커노드가 Not Ready 인 경우 다양한 원인을 가지고 있습니다. 그 중 대부분은 워커노드의 높은 리소스 사용량으로 인해 발생합니다. 워커 노드의 리소스 사용량 확인 이후 워커 노드에 위치한 파드를 다른 워커노드로 스케줄링하거나 스케일을 줄여 리소스 사용량을 감소시킵니다. 이후 워커노드를 재기동하여 상태가 Ready로 변경되는지 확인합니다.
높은 리소스 사용량으로 인해 워커노드에 문제가 생기는 것을 방지하기 위하여 아래 Kubernetes 기능 사용을 권장합니다.

• Resource Request&Limit
• Horizontal Pod Autoscaling
• Cluster AutoScaling

Q. Evict 상태를 가진 파드가 생성되었거나 생성되고 있습니다.

A. Kubernetes의 컴포넌트인 kubelet은 노드의 자원을 모니터링 합니다. 모니터링 대상 노드 자원이 임계치에 도달하는 경우 kubelet은 파드를 능동적으로 중단시켜 자원을 회수합니다. Evict 상태의 경우 kubelet이 파드를 중단시킨 상태를 뜻합니다. 파드가 Evict 상태인 경우 노드의 자원을 모니터링하여 임계치 아래로 떨어뜨려야 합니다. Ncloud Kubernetes Service의 임계값은 Kubernetes의 기본 설정을 따릅니다. 기타 자세한 내용은 아래의 공식 문서를 참고해 주십시오.

• Node-pressure Eviction

Q. 클러스터 업그레이드 시 컨트롤플레인과 워커노드의 버전 차이 정책이 궁금합니다.

Ncloud Kubernetes Service는 Kubernetes의 버전 차이 정책을 따릅니다. Kubernetes는 컨트롤플레인과 워커노드 간의 일정한 버전 차이를 허용하고 있습니다. 자세한 정책은 공식 문서를 통해 확인할 수 있습니다.

Ncloud Kubernetes Service 배포

Q. 파드 생성 시 ImagePullBackOff 상태가 발생합니다.

A. ImagePullBackOff 상태는 파드가 사용할 이미지를 가져오지 못해 발생합니다. 아래 내용을 통해 원인을 파악한 이후 해결할 수 있습니다.

• 이미지 명 및 태그가 잘못된 경우 이미지를 가져올 수 없습니다.
• 프라이빗 레지스트리에서 이미지를 받아오는 경우 적합한 인증을 진행하지 못할 때 이미지를 가져올 수 없습니다. 알맞은 imagePullSecrets을 사용하였는지 확인이 필요합니다. Container Registry 상품을 사용하는 경우 사용 가이드를 통해 imagePullSecrets을 생성할 수 있습니다.
• Private Subnet을 사용하는 Kubernetes Cluster의 경우 외부 이미지를 사용하기 위해 아웃바운드 트래픽이 활성화 되어 있어야 합니다. 활성화되어 있지 않은 경우 아래 과정을 통해 진행할 수 있습니다.

  • NAT Gateway (Old) 의 경우

    • 콘솔 > VPC > NAT Gateway(Old) 메뉴로 이동 후 NAT Gateway를 생성
    • 콘솔 > Products & Services > Networking > VPC > Route Table 메뉴로 이동
    • 인터넷 통신이 필요한 Private Subnet의 라우트 테이블을 선택하고, [Routes 설정] 버튼을 클릭
    • 외부 통신을 위한 라우트 규칙을 추가
      • Destination : 목적지 공인 IP 주소를 CIDR 형태로 입력 (예를 들어 인터넷 전체가 통신 대상이라면 0.0.0.0/0으로 입력)
      • Target Type : 목적지와 통신하기 위한 다음 Hop 타입을 선택 (NAT Gateway)
      • Target Name : 생성한 NAT Gateway 이름을 선택
      • [생성] 버튼을 클릭하여 정상적으로 규칙 추가 및 반영

  • NAT Gateway (New)의 경우

    • 콘솔 > VPC > Nat Gateway (New) 메뉴로 이동 후 공인 NAT Gateway를 생성
    • 콘솔 > VPC > Route Table 메뉴로 이통 후 NAT Gateway 를 통해 통신할 네트워크 경로 설정
      • Route Table 설정 가이드를 참고하여 설정 진행
• DockerHub 이미지 다운로드 정책에 의해 제한되었을 경우 이미지를 정상적으로 이용할 수 없습니다. 대량 이용을 위한 지불 계정을 사용하시거나 프라이빗 레지스트리를 이용해야 합니다.

Q. 특정 파드에서 간헐적으로 DNS 조회가 실패하거나 오랜 시간이 소요됩니다.

A. DNS 조회에 실패하거나 쿼리 처리에 문제가 존재하는 경우 해당 파드가 사용하는 이미지의 확인이 필요합니다.

• Alpine Linux에 기반한 컨테이너 이미지
  • dnsConfig 를 적용하여 해결 가능

  spec:
  ...
    dnsConfig:
      options:
      - name: single-request-reopen
  

• BusyBox에 기반한 컨테이너 이미지
  • busybox 1.28 기반의 이미지 사용을 통해 해결 가능

위 두 이미지를 사용하는 경우 DNS 쿼리 처리에 문제가 발생할 수 있습니다. 이미지 내부 이슈의 경우 네이버 클라우드 플랫폼에서 해결 드리기 어려우므로 다른 컨테이너 이미지를 사용하거나 DNS 설정을 수정하여 문제 해결이 필요합니다.

Ncloud Kubernetes Service 네트워킹

Q. 생성하지 않은 Target Group이 존재합니다.

A. ALB와 매핑 된 Ingress Manifest 내의 spec.defaultBackend 가 지정되지 않은 경우 워커노드 그룹의 80 포트로 설정된 Target Group 이 생성됩니다. 해당 Target Group은 ALB의 동작에 영향을 주지 않으며 의도된 동작입니다.

Q. Ncloud Kubernetes Service 클러스터를 통해 생성된 로드밸런서의 삭제가 진행되지 않습니다.

A. Global DNS에 로드밸런서를 등록한 경우 로드밸런서의 삭제가 진행되지 않습니다. Global DNS에서 해당 로드밸런서의 등록 여부를 확인 후 설정 해제 시 해당 로드밸런서의 삭제가 진행됩니다.
해당 제약조건은 개선될 예정입니다.

Q. NetworkPolicy가 정상적으로 작동하지 않습니다.

A. Cilium CNI 를 사용하는 경우 NetworkPolicy 의 기능 중 아래와 같이 알려진 미지원 기능들이 있습니다.

• pod IP 를 이용한 ipBlock
• SCTP Protocol
• Port 범위 (endPort)

Q. Cilium 의 Connectivity Test 가 실패합니다.

A. Cilium 은 network 상태를 테스트하기 위한 Connectivity Test셋을 제공하고 있습니다. Ncloud Kubernetes Service 에서 해당 테스트 셋을 그대로 실행할 경우 아래 두 건의 테스트가 실패합니다.

이는 link-local ip 에 바인딩 된 node-local-dns 를 사용할 경우 발생하는 이미 알려진 이슈 입니다. 정상적인 DNS 리졸빙을 위해 아래와 같이 CiliumNetworkPolicy 에서 toCIDR 필드에 node-local-dns 가 사용하는 IP 대역을 추가해야 합니다.

# pod-to-a-allowed-cnp
  egress:
  - toPorts:
    - ports:
      - port: "53"
        protocol: ANY
    toEndpoints:
    - matchLabels:
        k8s:io.kubernetes.pod.namespace: kube-system
        k8s:k8s-app: kube-dns
    toCIDR:
    - 169.254.25.10/32

# pod-to-external-fqdn-allow-google-cnp
  egress:
  - toPorts:
    - ports:
      - port: "53"
        protocol: ANY
      rules:
        dns:
        - matchPattern: '*'
    toEndpoints:
    - matchLabels:
        k8s:io.kubernetes.pod.namespace: kube-system
        k8s:k8s-app: kube-dns
    toCIDR:
    - 169.254.25.10/32

Q. LoadBalancer 타입의 서비스 리소스 생성 이후 Pending 상태를 유지하고 있습니다.

A. 클러스터 생성 시 선택한 로드밸런서 서브넷을 삭제하거나 할당 가능한 아이피가 없는 경우 External-IP를 할당받지 못합니다. 아래 과정을 통해 기본 로드밸런서 서브넷을 변경하거나 다른 로드밸런서 서브넷을 선택할 수 있습니다.

• 기본 로드밸런서 서브넷을 변경할 수 있습니다.
  • 아래 명령어를 실행하여 kube-system Namespace에서 ncloud-config 이름을 가지는 configmap을 확인해 주십시오.

  $ kubectl --kubeconfig $KUBE_CONFIG get configmap ncloud-config -n kube-system
  $ kubectl --kubeconfig $KUBE_CONFIG get configmap ncloud-config -n kube-system -o yaml
  

  • 아래를 참고하여 kube-system Namespace에서 ncloud-config 이름을 가지는 configmap을 확인한 후 수정해 주십시오.

  $ kubectl --kubeconfig $KUBE_CONFIG get configmap ncloud-config -n kube-system
    NAME            DATA   AGE
    ncloud-config   9      131m
  
  $ kubectl --kubeconfig $KUBE_CONFIG get configmap ncloud-config -n kube-system -o yaml
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: ncloud-config
      namespace: kube-system
    data:
      acgNo: "12345"
      apiUrl: https://nks.apigw.ntruss.com
      basePath: /ncloud-api/v1
      lbPublicSubnetNo: "98765"
      lbSubnetNo: "12345"
      regionCode: KR
      regionNo: "11"
      vpcNo: "12345"
      zoneNo: "110"
  

  • data.acgNo: 워커 노드의 eth0 인터페이스에 할당된 acg의 instanceID를 입력하십시오.
  • data.apiUrl: https://nks.apigw.ntruss.com 를 입력하십시오.
  • data.basePath: /ncloud-api/v1를 입력하십시오.
  • data.lbPublicSubnetNo: 워커 노드가 할당된 VPC 내 Load Balancer 전용 Public 서브넷의 SubnetID를 입력하십시오.
  • data.lbSubnetNo: 워커 노드가 할당된 VPC 내 Load Balancer 전용 Private 서브넷의 SubnetID를 입력하십시오.
  • data.regionCode: 워커 노드가 위치한 리전 코드를 입력하십시오. (예: "FKR")
  • data.regionNo: 워커 노드의 리전 번호를 입력하십시오. (예: "11")
  • data.vpcNo: 워커 노드가 할당된 VPC의 VPC ID를 입력하십시오.
  • data.zoneNo: 워커 노드가 위치한 존 번호를 입력하십시오. (예: "110")
  • 아래 명령어를 실행하여 Load Balancer 전용 서브넷을 변경해 주십시오.

  $ kubectl --kubeconfig $KUBE_CONFIG -n kube-system patch configmap ncloud-config --type='json' -p='[{"op":"replace", "path":"/data/lbSubnetNo", "value": "94465"}]'
  

  • 예제용 서브넷 ID로 94465를 사용한 명령어입니다.
  • Kubernetes 워커 노드가 생성된 VPC 내 Load Balancer 전용 서브넷의 SubnetID를 사용하십시오. 올바르지 않은 SubnetID를 사용할 경우 서브넷 변경 후에 Load Balancer가 정상적으로 생성되지 않습니다.
  • 변경 완료 후 아래 명령어를 실행하여 configmap에 변경 사항이 적용되었는지 확인해 주십시오.

  $ kubectl --kubeconfig $KUBE_CONFIG get configmap ncloud-config -n kube-system -o yaml
  

Q. Ingress와 연결된 ALB(ApplicationLoadBalancer)가 정상적으로 생성되지 않거나, 동작하지 않습니다.

A. ALB Ingress Controller를 통해 생성된 ALB의 경우 해당됩니다. 아래 명령어를 실행하여 관련 리소스와 로그를 조회할 수 있습니다.

$ kubectl --kubeconfig $KUBE_CONFIG logs -n kube-system -l app.kubernetes.io/name=alb-ingress-controller
$ kubectl --kubeconfig $KUBE_CONFIG describe ingress [ingress-name]

• ALB Ingress Controller가 존재하지 않는 경우 ALB가 생성되지 않습니다. ALB Ingress Controller 설정 가이드의 참고를 통해 ALB Ingress Controller를 클러스터에 설치할 수 있습니다.
• Ingress Manifest에 에러가 있는 경우 ALB가 생성되지 않거나 관련 룰이 생성되지 않습니다. ALB Ingress Controller의 파드 로그 조회를 통해 원인을 확인할 수 있습니다.
  • Manifest 내의 룰과 생성된 ALB의 룰이 일치하지 않는 경우
  • 올바른 어노테이션을 사용하지 않는 경우
  • Manifest 룰에 기재된 서비스의 이름과 포트가 잘못 기재된 경우
  • 룰 순서가 올바르지 않은 경우 (최상단의 룰이 가장 먼저 적용)
• 생성된 ALB를 콘솔 혹은 API를 통해 변경하는 경우 문제가 발생할 수 있습니다. ALB Ingress Controller를 통해 생성된 ALB의 경우 Kubernetes 클러스터 내에 등록된 Ingress의 Manifest와 주기적으로 동기화를 진행합니다. 가급적 콘솔 및 API를 통한 변경을 지양하여야 하며 변경 시 Manifest의 재적용을 통해 상태 동기화를 진행하여야 합니다.

Q. Client IP 를 확인하고 싶습니다.

A. Ncloud Kubernetes Service를 통해 생성할 수 있는 로드밸런서는 NetworkLoadBalancer(NLB), NetworkProxyLoadBalancer(NPLB), ApplicationLoadBalancer(ALB) 입니다. 로드밸런서의 종류에 따라 Client IP 확인 방법이 달라집니다.

• ALB : HTTP/HTTPS 프로토콜을 사용하기 때문에 어플리케이션에서 X-Forwarded-For 헤더를 통해 클라이언트 IP를 확인할 수 있습니다.
• NPLB : proxy-protocol을 활성화 하여 Client IP를 확인할 수 있습니다. 서비스의 명세 내부에 관련 어노테이션의 기재가 필요하며 어플리케이션에서도 proxy-protocol 관련 설정이 활성화 되어있어야 합니다. 예를 들어 nginx-ingress-controller 를 사용하는 경우 nginx-ingress-controller의 proxy-protocol 설정이 활성화 되어있어야 합니다.
• NLB : NLB의 경우 로드밸런서에서 Client IP가 노출되나 클러스터 내부 설정이 필요합니다. 서비스의 명세 내부에서 "externalTrafficPolicy" 를 "Local" 로 변경하여 Client IP 를 확인할 수 있습니다. "externalTrafficPolicy" 설정 내용은 공식 문서에서 확인할 수 있습니다.

Q. 커널 파라미터 변경 이후 클러스터에서 패킷 드랍이 발생합니다.

A. Ncloud Kubernetes Service의 CNI 인 Cilium 기동 시 동적으로 "rp_filter"를 비활성화 합니다. sysctl.conf 파일 설정은 변경하지 않으므로 워커노드의 특정 커널 파라미터 변경을 위하여 sysctl.conf 파일을 적용하는 경우 주의가 필요합니다. 만일 Cilium 설정과 일치시키지 않는 경우 패킷 드랍이 발생할 수 있습니다. syctl.conf 파일 변경 및 적용 시 rp_filter 관련 설정인 "net.ipv4.conf.all.rp_filter"를 "0"으로 수정 한 이후 적용이 필요합니다. 이 외에도 커널 파라미터 변경 시 주의가 필요하며 판단이 어려운 경우 네이버클라우드플랫폼 포털의 고객 문의를 통해 확인 할 수 있습니다.

Q. ALB 생성 시 타겟 그룹의 설정을 변경하고 싶습니다.

A. Ingress의 백엔드로 지정되는 Service의 명세를 변경하여 설정할 수 있습니다. 어노테이션을 사용하면 Service를 통해 생성되는 타겟 그룹의 로드밸런싱 알고리즘, Health Check 설정이 가능합니다.
예를 들어 아래 내용처럼 지정하면 "naver" Service를 통해 생성된 타겟 그룹은 least-connection 알고리즘을 통해 로드밸런싱이 진행됩니다.

apiVersion: v1
kind: Service
metadata:
  annotations: 
    alb.ingress.kubernetes.io/algorithm-type: "least-connection"
  name: naver

Service, Ingress에서 사용 가능한 어노테이션의 경우 ALB Ingress Controller 설정에서 확인할 수 있습니다.

Ncloud Kubernetes Service 보안

Q. ncp-iam-authenticator를 통해 Kubernetes Cluster에 접근 할 수 없습니다.

A. ncp-iam-authenticator의 이용 도중 발생하는 에러 메시지를 통해 원인 분석이 가능합니다.

• Cluster is undefined (400) : 올바르지 않은 클러스터 UUID가 입력되는 경우 발생합니다.
• Authentication Failed (200) : 올바르지 않은 인증키 값을 사용할 때 발생합니다. ncp-iam-authenticator은 ~/.ncloud/configure 이하의 인증키 값을 사용하며 만료된 인증키, 삭제된 인증키, 사용 중지 된 인증키, 잘못 기재된 인증키 아닌지 확인이 필요합니다.
• Not Found Exception (404) : ncloud_api_url 과 region 값의 확인이 필요합니다.
• You must be logged in to the server (Unauthorized) : 계정(서브어카운트)이 클러스터에 관련 권한을 가지고 있지 않을 때 발생합니다. 클러스터 생성 시 메인 계정, 클러스터 생성 계정은 system:masters 그룹으로 자동설정되나 이외 계정은 별도 권한 설정이 필요합니다. IAM 인증 사용자 관리를 통해 접근 계정에 대해 권한 설정을 진행하십시오.

Ncloud Kubernetes Service 확장성 및 성능

Q. Cluster AutoScaler를 설정하였지만 Scale Up/Down이 발생하지 않습니다.

A. Ncloud Kubernetes Service에서 제공하는 Cluster Autoscaler 클러스터 내에 리소스 부족으로 인해 스케줄링되지 못한 파드가 존재할 때 노드를 증가시키며, 일정 시간 동안 특정 노드의 사용률이 저조한 경우 노드를 감소합니다. Cluster Autoscaler는 다양한 원인으로 동작하지 않을 수 있습니다.

• 사용하고 있는 파드에 Resource Request, Limit 설정이 존재하지 않는 경우 동작하지 않습니다. 반드시 Resource Request&Limit 설정이 필요합니다.
• HPA(Horizontal Pod Autoscaling)의 설정이 없는 경우 동작하지 않습니다. HPA를 통해 파드가 증가하며 생성된 파드의 리소스 요청량을 통해 Cluster Autoscaler가 동작합니다. HPA 설정을 통해 Cluster Autoscaler를 동작할 수 있습니다.
• 노드 감소 예외 사항이 존재하는 경우 노드의 감소가 이루어지지 않을 수 있습니다. 아래와 같은 예외 사항이 존재합니다.
  • Controller(예: Deployment, StatefulSet .. )에 의해 제어되지 않는 경우
  • Local Storage가 설정되어 있는 경우
  • 다른 노드로 파드가 이동할 수 없는 경우
  • Annotation "cluster-autoscaler.kubernetes.io/safe-to-evict": "false"이 설정되어 있는 경우
  • 기타 예외 사항에 대해서는 공식 문서를 참고하십시오.

Q. 수동으로 노드풀 축소 시 특정 노드를 제거하고 싶습니다.

A. 노드풀 수동 축소 시 아래 우선순위를 통해 순서가 정해집니다.

• 정지 상태인 노드
• 생성일이 오래된 노드

특정 노드를 제거하고 싶은 경우 Kubernetes Service > Node pools > Node Pool 상세 > 노드 삭제 버튼 클릭을 통해 진행하거나, 해당 노드를 정지한 이후 노드 수를 수정하여 진행할 수 있습니다.

Q. Cluster AutoScaler 사용 시 파라미터를 변경하거나 확인하고 싶습니다.

A. Cluster AutoScaler 설정시 기본 파라미터를 사용하며, 변경은 제공하고 있지 않습니다. Cluster AutoScaler에서 사용되는 파라미터 및 기본 값은 아래 문서에서 확인할 수 있습니다.

• What are the parameters to CA?

Ncloud Kubernetes Service 모니터링 및 로깅

Q. Kubernetes Dashboard 에 접근 시 리소스가 조회되지 않습니다.

A. Ncloud Kubernetes Service에서 제공하는 Dashboard(Kubernetes Dashboard)의 접근 권한은 클러스터 내부 권한과 동일합니다. 네이버 클라우드 플랫폼의 메인 계정 및 클러스터 생성 계정(서브어카운트)는 어드민 권한을 가지고 있어 별도 작업 없이 Dashboard에 접근할 수 있습니다. 하지만 이 외 서브어카운트 계정은 클러스터 사용 권한을 가지고 있어야 합니다.

클러스터 권한 부여 방법은 가이드 문서를 통해 확인할 수 있습니다.

• IAM 인증 사용자 관리