배포 도구로 쿠버네티스 설치하기

• 1: kubeadm으로 클러스터 구성하기
• 1.1: kubeadm 설치하기
• 1.2: kubeadm 문제 해결
• 1.3: kubeadm으로 클러스터 생성하기
• 1.4: kubeadm API로 컴포넌트 사용자 정의하기
• 1.5: 고가용성 토폴로지 선택

1 - kubeadm으로 클러스터 구성하기

1.1 - kubeadm 설치하기

이 페이지에서는 kubeadm 툴박스 설치 방법을 보여준다. 이 설치 프로세스를 수행한 후 kubeadm으로 클러스터를 만드는 방법에 대한 자세한 내용은 kubeadm으로 클러스터 생성하기 페이지를 참고한다.

시작하기 전에

• 호환되는 리눅스 호스트. 쿠버네티스 프로젝트는 데비안 및 레드햇 기반 리눅스 배포판과 패키지 매니저가 없는 배포판에 대한 일반적인 지침을 제공한다.
• 머신당 2GB 이상의 RAM (이보다 적으면 앱을 위한 공간이 거의 남지 않는다).
• 컨트롤 플레인 머신에는 2개 이상의 CPU.
• 클러스터의 모든 머신 간 완전한 네트워크 연결 (공용 또는 사설 네트워크 무관).
• 모든 노드에 대해 고유한 호스트네임, MAC 주소, 그리고 product_uuid. 자세한 내용은 여기를 참고한다.
• 머신에 특정 포트들이 열려있어야 한다. 자세한 내용은 여기를 참고한다.

OS 버전 확인

• Linux
• Windows

kubeadm으로 생성된 쿠버네티스 클러스터는 커널 기능을 사용하는 소프트웨어에 의존한다. 이 소프트웨어에는 컨테이너 런타임, kubelet, 그리고 컨테이너 네트워크 인터페이스 플러그인이 포함되지만 이에 국한되지 않는다.

지원되지 않는 커널 버전으로 인한 예기치 않은 오류를 방지하기 위해, kubeadm은 SystemVerification 사전 검사를 실행한다. 이 검사는 커널 버전이 지원되지 않으면 실패한다.

kubeadm이 커널 버전을 지원하지 않더라도, 커널이 필요한 기능을 제공한다는 것을 알고 있다면 검사를 건너뛰도록 선택할 수 있다.

모든 노드에서 MAC 주소와 product_uuid가 고유한지 확인

• ip link 또는 ifconfig -a 명령을 사용하여 네트워크 인터페이스의 MAC 주소를 확인할 수 있다
• sudo cat /sys/class/dmi/id/product_uuid 명령을 사용하여 product_uuid를 확인할 수 있다

하드웨어 장치는 고유한 주소를 가질 가능성이 매우 높지만, 일부 가상 머신은 동일한 값을 가질 수 있다. 쿠버네티스는 이러한 값을 사용하여 클러스터의 노드를 고유하게 식별한다. 이러한 값이 각 노드에서 고유하지 않으면 설치 과정이 실패할 수 있다.

네트워크 어댑터 확인

네트워크 어댑터가 두 개 이상이고, 쿠버네티스 컴포넌트가 디폴트 라우트(default route)에서 도달할 수 없는 경우, 쿠버네티스 클러스터 주소가 적절한 어댑터를 통해 이동하도록 IP 경로를 추가하는 것이 좋다.

필수 포트 확인

쿠버네티스 컴포넌트가 서로 통신하려면 이러한 필수 포트가 열려 있어야 한다. netcat과 같은 도구를 사용하여 포트가 열려 있는지 확인할 수 있다. 예를 들어

nc 127.0.0.1 6443 -zv -w 2

사용하는 파드 네트워크 플러그인도 특정 포트가 열려 있어야 할 수 있다. 각 파드 네트워크 플러그인마다 다르므로, 해당 플러그인이 필요로 하는 포트에 대해서는 플러그인 문서를 참고한다.

스왑 구성

노드에서 스왑 메모리가 감지되면 kubelet의 기본 동작은 시작에 실패하는 것이다. 이는 스왑이 비활성화되거나 kubelet에 의해 용인되어야 함을 의미한다.

• 스왑을 용인하려면, kubelet 구성에 failSwapOn: false를 추가하거나 커맨드라인 인수로 설정한다. 참고: failSwapOn: false가 제공되더라도 워크로드는 기본적으로 스왑에 접근할 수 없다. 이는 kubelet 구성 파일에서 다시 swapBehavior를 설정하여 변경할 수 있다. 스왑을 사용하려면, 기본 NoSwap 설정이 아닌 다른 swapBehavior를 설정한다. 자세한 내용은 스왑 메모리 관리를 참고한다.
• 스왑을 비활성화하려면, sudo swapoff -a를 사용하여 일시적으로 스와핑을 비활성화할 수 있다. 재부팅 후에도 이 변경사항을 유지하려면, 시스템 구성 방법에 따라 /etc/fstab, systemd.swap과 같은 구성 파일에서 스왑이 비활성화되어 있는지 확인한다.

컨테이너 런타임 설치

파드에서 컨테이너를 실행하기 위해, 쿠버네티스는 컨테이너 런타임을 사용한다.

기본적으로, 쿠버네티스는 컨테이너 런타임 인터페이스(CRI)를 사용하여 사용자가 선택한 컨테이너 런타임과 인터페이스한다.

런타임을 지정하지 않으면, kubeadm은 잘 알려진 엔드포인트를 스캐닝하여 설치된 컨테이너 런타임을 자동으로 감지하려고 한다.

컨테이너 런타임이 여러 개 감지되거나 하나도 감지되지 않은 경우, kubeadm은 에러를 반환하고 사용자가 어떤 것을 사용할지를 명시하도록 요청할 것이다.

자세한 정보는 컨테이너 런타임 을 참고한다.

아래 표는 지원 운영 체제에 대한 알려진 엔드포인트를 담고 있다.

• 리눅스
• 윈도우

kubeadm, kubelet 및 kubectl 설치

모든 머신에 다음 패키지들을 설치한다.

• kubeadm: 클러스터를 부트스트랩하는 명령이다.

• kubelet: 클러스터의 모든 머신에서 실행되는 파드와 컨테이너 시작과 같은 작업을 수행하는 컴포넌트이다.

• kubectl: 클러스터와 통신하기 위한 커맨드 라인 유틸리티이다.

kubeadm은 kubelet 또는 kubectl 을 설치하거나 관리하지 않으므로, kubeadm이 설치하려는 쿠버네티스 컨트롤 플레인의 버전과 일치하는지 확인해야 한다. 그렇지 않으면, 예상치 못한 버그 동작으로 이어질 수 있는 버전 차이(skew)가 발생할 위험이 있다. 그러나, kubelet과 컨트롤 플레인 사이에 하나의 마이너 버전 차이가 지원되지만, kubelet 버전은 API 서버 버전 보다 높을 수 없다. 예를 들어, 1.7.0 버전의 kubelet은 1.8.0 API 서버와 완전히 호환되어야 하지만, 그 반대의 경우는 아니다.

kubectl 설치에 대한 정보는 kubectl 설치 및 설정을 참고한다.

버전 차이에 대한 자세한 내용은 다음을 참고한다.

• 쿠버네티스 버전 및 버전-차이 정책
• Kubeadm 관련 버전 차이 정책

• 데비안 기반 배포판
• 레드햇 기반 배포판
• 패키지 매니저를 사용하지 않는 경우

CNI_PLUGINS_VERSION="v1.3.0"
ARCH="amd64"
DEST="/opt/cni/bin"
sudo mkdir -p "$DEST"
curl -L "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGINS_VERSION}/cni-plugins-linux-${ARCH}-${CNI_PLUGINS_VERSION}.tgz" | sudo tar -C "$DEST" -xz

DOWNLOAD_DIR="/usr/local/bin"
sudo mkdir -p "$DOWNLOAD_DIR"

CRICTL_VERSION="v1.31.0"
ARCH="amd64"
curl -L "https://github.com/kubernetes-sigs/cri-tools/releases/download/${CRICTL_VERSION}/crictl-${CRICTL_VERSION}-linux-${ARCH}.tar.gz" | sudo tar -C $DOWNLOAD_DIR -xz

RELEASE="$(curl -sSL https://dl.k8s.io/release/stable.txt)"
ARCH="amd64"
cd $DOWNLOAD_DIR
sudo curl -L --remote-name-all https://dl.k8s.io/release/${RELEASE}/bin/linux/${ARCH}/{kubeadm,kubelet}
sudo chmod +x {kubeadm,kubelet}

RELEASE_VERSION="v0.16.2"
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubelet/kubelet.service" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service
sudo mkdir -p /usr/lib/systemd/system/kubelet.service.d
curl -sSL "https://raw.githubusercontent.com/kubernetes/release/${RELEASE_VERSION}/cmd/krel/templates/latest/kubeadm/10-kubeadm.conf" | sed "s:/usr/bin:${DOWNLOAD_DIR}:g" | sudo tee /usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf

sudo systemctl enable --now kubelet

kubelet은 이제 kubeadm이 수행할 작업을 알려 줄 때까지 크래시루프(crashloop) 상태로 기다려야 하므로 몇 초마다 다시 시작된다.

cgroup 드라이버 구성

컨테이너 런타임과 kubelet은 "cgroup 드라이버"라는 속성을 갖고 있으며, cgroup 드라이버는 리눅스 머신의 cgroup 관리 측면에 있어서 중요하다.

문제 해결

kubeadm에 문제가 있는 경우, 문제 해결 문서를 참고한다.

다음 내용

• kubeadm을 사용하여 클러스터 생성

1.2 - kubeadm 문제 해결

다른 프로그램과 마찬가지로, kubeadm을 설치하거나 실행하는 중에 오류가 발생할 수 있다. 이 페이지에는 일반적인 실패 시나리오를 나열하고 문제를 이해하고 해결하는 데 도움을 줄 수 있는 단계를 제공한다.

아래에 문제가 언급되어 있지 않다면 다음 단계를 따르도록 한다.

• 문제가 kubeadm의 버그라고 생각되는 경우:

  • github.com/kubernetes/kubeadm으로 이동하여 기존 이슈를 검색한다.
  • 이슈가 없으면 새로운 이슈를 열고 이슈 템플릿을 따른다.

• kubeadm 작동 방식이 확실하지 않은 경우, 슬랙의 #kubeadm에서 질문하거나, 스택오버플로우에 질문을 올릴 수 있다. 사람들이 도움을 줄 수 있도록 #kubernetes 및 #kubeadm과 같은 관련 태그를 포함한다.

RBAC 누락으로 인해 v1.18 노드를 v1.17 클러스터에 참여할 수 없음

v1.18 kubeadm은 같은 이름의 노드가 이미 존재하는 경우 클러스터에 노드가 참여하는 것을 방지하는 기능을 추가했다. 이를 위해 bootstrap-token 사용자가 노드 객체를 GET할 수 있도록 RBAC를 추가해야 했다.

그러나 이로 인해 v1.18의 kubeadm join이 kubeadm 1.17로 생성된 클러스터에 참여할 수 없는 문제가 발생한다.

이 문제를 해결하기 위한 두 가지 옵션이 있다.

kubeadm v1.18을 사용하여 컨트롤 플레인 노드에서 kubeadm init phase bootstrap-token을 실행한다. 이렇게 하면 나머지 bootstrap-token 권한도 활성화된다는 점에 유의한다.

또는

kubectl apply -f ...를 사용하여 다음 RBAC를 수동으로 적용한다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubeadm:get-nodes
rules:
  - apiGroups:
      - ""
    resources:
      - nodes
    verbs:
      - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kubeadm:get-nodes
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubeadm:get-nodes
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: system:bootstrappers:kubeadm:default-node-token

설치 중 ebtables 또는 유사한 실행 파일을 찾을 수 없음

kubeadm init을 실행하는 동안 다음과 같은 경고 메시지가 출력된다면

[preflight] WARNING: ebtables not found in system path
[preflight] WARNING: ethtool not found in system path

노드에 ebtables, ethtool 또는 유사한 실행 파일이 누락되었을 수 있다. 다음 명령으로 설치할 수 있다.

• 우분투/데비안 사용자의 경우, apt install ebtables ethtool을 실행한다.
• CentOS/페도라 사용자의 경우, yum install ebtables ethtool을 실행한다.

설치 중 kubeadm이 컨트롤 플레인을 기다리다가 진행되지 않음 (block)

kubeadm init이 다음 줄을 출력한 후 중단되는 경우

[apiclient] Created API client, waiting for the control plane to become ready

이는 여러 문제로 인해 발생할 수 있다. 가장 일반적인 원인은

• 네트워크 연결 문제: 계속하기 전에 머신에 완전한 네트워크 연결이 있는지 확인한다.
• 컨테이너 런타임의 cgroup 드라이버가 kubelet과 다름. 올바르게 구성하는 방법은 cgroup 드라이버 구성을 참조한다.
• 컨트롤 플레인 컨테이너가 크래시 루프에 있거나 중단됨. docker ps를 실행하고 docker logs를 실행하여 각 컨테이너를 조사할 수 있다. 다른 컨테이너 런타임의 경우 crictl로 쿠버네티스 노드 디버깅하기를 참조한다.

관리되는 컨테이너를 제거할 때 kubeadm이 멈춤

컨테이너 런타임이 중단되고 쿠버네티스가 관리하는 컨테이너를 제거하지 않으면 다음과 같은 일이 발생할 수 있다.

sudo kubeadm reset

[preflight] Running pre-flight checks
[reset] Stopping the kubelet service
[reset] Unmounting mounted directories in "/var/lib/kubelet"
[reset] Removing kubernetes-managed containers
(block)

가능한 해결 방안은 컨테이너 런타임을 재시작한 뒤 kubeadm reset을 다시 실행하는 것이다. 또한 crictl을 사용하여 컨테이너 런타임의 상태를 디버그할 수도 있다. crictl로 쿠버네티스 노드 디버깅하기를 참조한다.

RunContainerError, CrashLoopBackOff 또는 Error 상태의 파드

kubeadm init 직후에는 이러한 상태의 파드가 없어야 한다.

• kubeadm init 직후 에 이러한 상태의 파드가 있다면 kubeadm 저장소에 이슈를 열자. coredns(또는 kube-dns)는 네트워크 애드온을 배포하기 전까지는 Pending 상태여야 한다.
• 네트워크 애드온을 배포한 이후에도 RunContainerError, CrashLoopBackOff 또는 Error 상태의 파드가 보이고 coredns(또는 kube-dns)에 아무 일도 일어나지 않는다면, 설치한 파드 네트워크 애드온이 어떤 식으로든 손상되었을 가능성이 높다. 더 많은 RBAC 권한을 부여하거나 최신 버전을 사용해야 할 수 있다. 파드 네트워크 공급자의 이슈 트래커에 이슈를 제출하고 분류를 받자.

coredns가 Pending 상태에 멈춤

이는 예상된 동작이며 설계의 일부다. kubeadm은 네트워크 공급자에 구애받지 않으므로 관리자가 선택한 파드 네트워크 애드온을 설치해야 한다. CoreDNS가 완전히 배포되기 전에 파드 네트워크를 설치해야 한다. 따라서 네트워크가 설정되기 전까지 Pending 상태가 된다.

HostPort 서비스가 동작하지 않음

HostPort와 HostIP 기능의 지원 여부는 파드 네트워크 공급자에 따라 달라진다. HostPort 및 HostIP 기능을 사용할 수 있는지 알아보려면 파드 네트워크 애드온 작성자에게 문의한다.

Calico, Canal 및 Flannel CNI 공급자는 HostPort를 지원하는 것으로 확인되었다.

자세한 내용은 CNI portmap 문서를 참조한다.

네트워크 공급자가 portmap CNI 플러그인을 지원하지 않는 경우, 서비스의 NodePort 기능을 사용하거나 HostNetwork=true를 사용해야 할 수 있다.

파드가 서비스 IP를 통해 액세스할 수 없음

• 많은 네트워크 애드온이 아직 파드가 서비스 IP를 통해 자신에 액세스할 수 있도록 하는 헤어핀 모드 를 활성화하지 않는다. 이는 CNI와 관련된 문제다. 헤어핀 모드 지원의 최신 상태를 확인하려면 네트워크 애드온 공급자에게 문의한다.

• VirtualBox를 사용하는 경우(직접 또는 Vagrant를 통해) hostname -i가 라우팅 가능한 IP 주소를 반환하는지 확인해야 한다. 기본적으로 첫 번째 인터페이스는 라우팅할 수 없는 호스트 전용 네트워크에 연결된다. 해결 방법은 /etc/hosts를 수정하는 것이다. 예시는 이 Vagrantfile을 참조한다.

TLS 인증서 오류

다음 오류는 인증서 불일치 가능성을 나타낸다.

# kubectl get pods
Unable to connect to the server: x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" while trying to verify candidate authority certificate "kubernetes")

• $HOME/.kube/config 파일에 유효한 인증서가 포함되어 있는지 확인하고 필요한 경우 인증서를 재생성한다. kubeconfig 파일의 인증서는 base64로 인코딩되어 있다. base64 --decode 명령을 사용하여 인증서를 디코딩하고 openssl x509 -text -noout을 사용하여 인증서 정보를 볼 수 있다.

• 다음을 사용하여 KUBECONFIG 환경 변수를 해제한다.

  unset KUBECONFIG
  

  또는 기본 KUBECONFIG 위치로 설정한다.

  export KUBECONFIG=/etc/kubernetes/admin.conf
  

• 또 다른 해결 방법은 "admin" 사용자의 기존 kubeconfig를 덮어쓰는 것이다.

  mv $HOME/.kube $HOME/.kube.bak
  mkdir $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config
  

Kubelet 클라이언트 인증서 갱신 실패

기본적으로 kubeadm은 /etc/kubernetes/kubelet.conf에 지정된 /var/lib/kubelet/pki/kubelet-client-current.pem 심볼릭 링크를 사용하여 kubelet 클라이언트 인증서가 자동 갱신되도록 구성한다. 이 갱신 프로세스가 실패하면 kube-apiserver 로그에 x509: certificate has expired or is not yet valid와 같은 오류가 표시될 수 있다. 이 문제를 해결하려면 다음 단계를 따라야 한다.

1. 실패한 노드에서 /etc/kubernetes/kubelet.conf 및 /var/lib/kubelet/pki/kubelet-client*를 백업하고 삭제한다.

2. /etc/kubernetes/pki/ca.key가 있는 클러스터의 작동 중인 컨트롤 플레인 노드에서 kubeadm kubeconfig user --org system:nodes --client-name system:node:$NODE > kubelet.conf를 실행한다. $NODE는 클러스터에서 기존에 실패한 노드 이름으로 설정해야 한다. 결과 kubelet.conf를 수동으로 수정하여 클러스터 이름과 서버 엔드포인트를 조정하거나 kubeconfig user --config를 전달한다(추가 사용자를 위한 kubeconfig 파일 생성 참조). 클러스터에 ca.key가 없으면 kubelet.conf에 포함된 인증서에 외부에서 서명해야 한다.

3. 결과 kubelet.conf를 실패한 노드의 /etc/kubernetes/kubelet.conf에 복사한다.

4. 실패한 노드에서 kubelet을 재시작(systemctl restart kubelet)하고 /var/lib/kubelet/pki/kubelet-client-current.pem이 재생성될 때까지 기다린다.

5. kubelet.conf를 수동으로 편집하여 갱신된 kubelet 클라이언트 인증서를 가리키도록 한다.
   client-certificate-data 및 client-key-data를 다음으로 교체한다.

   client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem
   client-key: /var/lib/kubelet/pki/kubelet-client-current.pem
   

6. kubelet을 재시작한다.

7. 노드가 Ready가 되었는지 확인한다.

Vagrant에서 flannel을 파드 네트워크로 사용할 때 기본 NIC

다음 오류는 파드 네트워크에 문제가 있음을 나타낼 수 있다.

Error from server (NotFound): the server could not find the requested resource

• Vagrant 내에서 파드 네트워크로 flannel을 사용하는 경우, flannel의 기본 인터페이스 이름을 지정해야 한다.

  Vagrant는 일반적으로 모든 VM에 두 개의 인터페이스를 할당한다. 첫 번째는 모든 호스트에 10.0.2.15 IP 주소가 할당되며, NAT 처리되는 외부 트래픽을 위한 것이다.

  이는 호스트의 첫 번째 인터페이스를 기본값으로 하는 flannel에 문제를 일으킬 수 있다. 이로 인해 모든 호스트가 동일한 공용 IP 주소를 가지고 있다고 생각하게 된다. 이를 방지하려면 flannel에 --iface eth1 플래그를 전달하여 두 번째 인터페이스가 선택하도록 한다.

컨테이너에 공용이 아닌 IP가 사용됨

정상적으로 작동하는 클러스터에서 kubectl logs 및 kubectl run 명령이 다음 오류와 함께 반환될 수 있다.

Error from server: Get https://10.19.0.41:10250/containerLogs/default/mysql-ddc65b868-glc5m/mysql: dial tcp 10.19.0.41:10250: getsockopt: no route to host

• 이는 쿠버네티스에서 머신 공급자의 정책에 따라, 겉보기에는 동일한 서브넷에 있는 다른 IP와 통신할 수 없는 IP를 사용하는 쿠버네티스 (환경) 때문일 수 있다.

• DigitalOcean은 eth0에 공용 IP와 플로팅 IP 기능의 앵커로 내부적으로 사용되는 프라이빗 IP를 할당하지만, kubelet은 공용 IP 대신 후자를 노드의 InternalIP로 선택한다.

  ifconfig는 문제가 되는 별칭 IP 주소를 표시하지 않으므로 이 시나리오를 확인하려면 ifconfig 대신 ip addr show를 사용한다. 또는 DigitalOcean에 특정한 API 엔드포인트를 사용하여 드롭릿(droplet)에서 앵커 IP를 쿼리할 수 있다.

  curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/address
  

  해결 방법은 --node-ip를 사용하여 kubelet에 사용할 IP를 알려주는 것이다. DigitalOcean을 사용하는 경우, 공용 IP(eth0에 할당됨) 또는 선택적 프라이빗 네트워크를 사용하려는 경우 프라이빗 IP(eth1에 할당됨)가 될 수 있다. kubeadm NodeRegistrationOptions 구조의 kubeletExtraArgs 섹션을 이에 사용할 수 있다.

  그런 다음 kubelet을 재시작한다.

  systemctl daemon-reload
  systemctl restart kubelet
  

coredns 파드가 CrashLoopBackOff 또는 Error 상태

이전 버전의 Docker와 함께 SELinux를 실행하는 노드가 있는 경우, coredns 파드가 시작되지 않는 시나리오가 발생할 수 있다. 이를 해결하려면 다음 옵션 중 하나를 시도할 수 있다.

• 최신 버전의 Docker로 업그레이드

• SELinux 비활성화.

• coredns 배포를 수정하여 allowPrivilegeEscalation을 true로 설정

kubectl -n kube-system get deployment coredns -o yaml | \
  sed 's/allowPrivilegeEscalation: false/allowPrivilegeEscalation: true/g' | \
  kubectl apply -f -

CoreDNS가 CrashLoopBackOff를 가지는 또 다른 원인은 쿠버네티스에 배포된 CoreDNS 파드가 루프를 감지하는 경우다. CoreDNS가 루프를 감지하고 종료할 때마다 쿠버네티스가 CoreDNS 파드를 재시작하지 않도록 여러 해결 방법을 사용할 수 있다.

etcd 파드가 지속적으로 재시작됨

다음 오류가 발생하는 경우

rpc error: code = 2 desc = oci runtime error: exec failed: container_linux.go:247: starting container process caused "process_linux.go:110: decoding init error from pipe caused \"read parent: connection reset by peer\""

이 문제는 Docker 1.13.1.84와 함께 CentOS 7을 실행하는 경우 나타난다. 이 버전의 Docker는 kubelet이 etcd 컨테이너로 실행되는 것을 방지할 수 있다.

이 문제를 해결하려면 다음 옵션 중 하나를 선택한다.

• 1.13.1-75와 같은 이전 버전의 Docker로 롤백

  yum downgrade docker-1.13.1-75.git8633870.el7.centos.x86_64 docker-client-1.13.1-75.git8633870.el7.centos.x86_64 docker-common-1.13.1-75.git8633870.el7.centos.x86_64
  

• 18.06과 같은 최신 권장 버전 중 하나를 설치

  sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  yum install docker-ce-18.06.1.ce-3.el7.x86_64
  

--component-extra-args 플래그 내부의 인수에 쉼표로 구분된 값 목록을 전달할 수 없음

--component-extra-args와 같은 kubeadm init 플래그를 사용하면 kube-apiserver와 같은 컨트롤 플레인 구성 요소에 사용자 정의 인수를 전달할 수 있다. 그러나 이 메커니즘은 값을 구문 분석하는 데 사용되는 기본 유형(mapStringString)으로 인해 제한된다.

--apiserver-extra-args "enable-admission-plugins=LimitRanger,NamespaceExists"와 같이 여러 쉼표로 구분된 값을 지원하는 인수를 전달하기로 결정한 경우, 이 플래그는 flag: malformed pair, expect string=string으로 실패한다. 이는 --apiserver-extra-args의 인수 목록이 key=value 쌍을 예상하고 이 경우 NamespacesExists가 값이 없는 키로 간주되기 때문이다.

대안으로 key=value 쌍을 다음과 같이 분리할 수 있다. --apiserver-extra-args "enable-admission-plugins=LimitRanger,enable-admission-plugins=NamespaceExists" 그러나 이는 enable-admission-plugins 키가 NamespaceExists 값만 가지게 된다.

알려진 해결 방법은 kubeadm 구성 파일을 사용하는 것이다.

cloud-controller-manager가 노드를 초기화하기 전에 kube-proxy가 스케줄됨

클라우드 공급자 시나리오에서 kube-proxy는 cloud-controller-manager가 노드 주소를 초기화하기 전에 새 워커 노드에 스케줄될 수 있다. 이로 인해 kube-proxy가 노드의 IP 주소를 제대로 가져오지 못하고 로드 밸런서를 관리하는 프록시 기능에 연쇄적인 영향을 미친다.

kube-proxy 파드에서 다음 오류를 볼 수 있다.

server.go:610] Failed to retrieve node IP: host IP unknown; known addresses: []
proxier.go:340] invalid nodeIP, initializing kube-proxy with 127.0.0.1 as nodeIP

알려진 해결 방법은 kube-proxy DaemonSet을 패치하여 조건에 관계없이 컨트롤 플레인 노드에 스케줄할 수 있도록 하고, 초기 보호 조건이 완화될 때까지 다른 노드에서 제외하는 것이다.

kubectl -n kube-system patch ds kube-proxy -p='{
  "spec": {
    "template": {
      "spec": {
        "tolerations": [
          {
            "key": "CriticalAddonsOnly",
            "operator": "Exists"
          },
          {
            "effect": "NoSchedule",
            "key": "node-role.kubernetes.io/control-plane"
          }
        ]
      }
    }
  }
}'

이 문제에 대한 추적 이슈는 여기에 있다.

노드에서 /usr이 읽기 전용으로 마운트됨

Fedora CoreOS 또는 Flatcar Container Linux와 같은 리눅스 배포판에서는 /usr 디렉터리가 읽기 전용 파일시스템으로 마운트된다. flex-volume 지원을 위해 kubelet 및 kube-controller-manager와 같은 쿠버네티스 구성 요소는 /usr/libexec/kubernetes/kubelet-plugins/volume/exec/의 기본 경로를 사용하지만, flex-volume 디렉터리는 기능이 작동하려면 쓰기 가능해야 한다.

이 문제를 해결하려면 kubeadm 구성 파일을
사용하여 flex-volume 디렉터리를 구성할 수 있다.

기본 컨트롤 플레인 노드(kubeadm init을 사용하여 생성)에서 --config를 사용하여 다음 파일을 전달한다.

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
nodeRegistration:
  kubeletExtraArgs:
  - name: "volume-plugin-dir"
    value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
controllerManager:
  extraArgs:
  - name: "flex-volume-plugin-dir"
    value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

참여하는 노드에서

apiVersion: kubeadm.k8s.io/v1beta4
kind: JoinConfiguration
nodeRegistration:
  kubeletExtraArgs:
  - name: "volume-plugin-dir"
    value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

또는 /etc/fstab를 수정하여 /usr 마운트를 쓰기 가능하게 만들 수 있지만, 이는 리눅스 배포판의 설계 원칙을 수정하는 것임을 유의한다.

kubeadm upgrade plan이 context deadline exceeded 오류 메시지 출력

이 오류 메시지는 외부 etcd를 실행하는 경우 kubeadm으로 쿠버네티스 클러스터를 업그레이드할 때 표시된다. 이는 중요한 버그가 아니며 이전 버전의 kubeadm이 외부 etcd 클러스터에서 버전 검사를 수행하기 때문에 발생한다. kubeadm upgrade apply ...를 계속 진행할 수 있다.

이 문제는 버전 1.19부터 수정되었다.

kubeadm reset이 /var/lib/kubelet을 언마운트함

/var/lib/kubelet이 마운트되어 있는 경우, kubeadm reset을 수행하면 효과적으로 언마운트된다.

이 문제를 해결하려면 kubeadm reset 작업을 수행한 후 /var/lib/kubelet 디렉터리를 다시 마운트한다.

이는 kubeadm 1.15에서 도입된 회귀 버그다. 이 문제는 1.20에서 수정되었다.

kubeadm 클러스터에서 metrics-server를 안전하게 사용할 수 없음

kubeadm 클러스터에서 metrics-server는 --kubelet-insecure-tls를 전달하여 안전하지 않게 사용할 수 있다. 이는 프로덕션 클러스터에는 권장되지 않는다.

metrics-server와 kubelet 간에 TLS를 사용하려는 경우 문제가 있다. kubeadm이 kubelet에 대해 자체 서명된 서빙 인증서를 배포하기 때문이다. 이로 인해 metrics-server 측에서 다음 오류가 발생할 수 있다.

x509: certificate signed by unknown authority
x509: certificate is valid for IP-foo not IP-bar

kubeadm 클러스터에서 kubelet이 올바르게 서명된 서빙 인증서를 갖도록 구성하는 방법을 이해하려면 서명된 kubelet 서빙 인증서 활성화를 참조한다.

또는 metrics-server를 안전하게 실행하는 방법을 참조한다.

etcd 해시가 변경되지 않아 업그레이드 실패

노드가 현재 kubeadm 버전 v1.28.0, v1.28.1 또는 v1.28.2로 관리되는 경우 kubeadm 바이너리 v1.28.3 이상으로 컨트롤 플레인 노드를 업그레이드하는 경우에만 해당된다.

발생할 수 있는 오류 메시지는 다음과 같다.

[upgrade/etcd] Failed to upgrade etcd: couldn't upgrade control plane. kubeadm has tried to recover everything into the earlier state. Errors faced: static Pod hash for component etcd on Node kinder-upgrade-control-plane-1 did not change after 5m0s: timed out waiting for the condition
[upgrade/etcd] Waiting for previous etcd to become available
I0907 10:10:09.109104    3704 etcd.go:588] [etcd] attempting to see if all cluster endpoints ([https://172.17.0.6:2379/ https://172.17.0.4:2379/ https://172.17.0.3:2379/]) are available 1/10
[upgrade/etcd] Etcd was rolled back and is now available
static Pod hash for component etcd on Node kinder-upgrade-control-plane-1 did not change after 5m0s: timed out waiting for the condition
couldn't upgrade control plane. kubeadm has tried to recover everything into the earlier state. Errors faced
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.rollbackOldManifests
	cmd/kubeadm/app/phases/upgrade/staticpods.go:525
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.upgradeComponent
	cmd/kubeadm/app/phases/upgrade/staticpods.go:254
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.performEtcdStaticPodUpgrade
	cmd/kubeadm/app/phases/upgrade/staticpods.go:338
...

이 실패의 이유는 영향을 받는 버전이 PodSpec에 원하지 않는 기본값을 사용하여 etcd 매니페스트 파일을 생성하기 때문이다. 이로 인해 매니페스트 비교에서 차이가 발생하고 kubeadm은 파드 해시의 변경을 기대하지만 kubelet은 해시를 업데이트하지 않는다.

클러스터에서 이 문제가 표시되는 경우 이를 해결하는 두 가지 방법이 있다.

• 영향을 받는 버전과 v1.28.3(또는 이후 버전) 사이에서 etcd 업그레이드를 건너뛸 수 있다.

  kubeadm upgrade {apply|node} [version] --etcd-upgrade=false
  

  이는 나중의 v1.28 패치 버전에서 새 etcd 버전이 도입된 경우 권장되지 않는다.

• 업그레이드하기 전에 etcd 정적 파드의 매니페스트를 패치하여 문제가 있는 기본 속성을 제거한다.

  diff --git a/etc/kubernetes/manifests/etcd_defaults.yaml b/etc/kubernetes/manifests/etcd_origin.yaml
  index d807ccbe0aa..46b35f00e15 100644
  --- a/etc/kubernetes/manifests/etcd_defaults.yaml
  +++ b/etc/kubernetes/manifests/etcd_origin.yaml
  @@ -43,7 +43,6 @@ spec:
          scheme: HTTP
        initialDelaySeconds: 10
        periodSeconds: 10
  -      successThreshold: 1
        timeoutSeconds: 15
      name: etcd
      resources:
  @@ -59,26 +58,18 @@ spec:
          scheme: HTTP
        initialDelaySeconds: 10
        periodSeconds: 10
  -      successThreshold: 1
        timeoutSeconds: 15
  -    terminationMessagePath: /dev/termination-log
  -    terminationMessagePolicy: File
      volumeMounts:
      - mountPath: /var/lib/etcd
        name: etcd-data
      - mountPath: /etc/kubernetes/pki/etcd
        name: etcd-certs
  -  dnsPolicy: ClusterFirst
  -  enableServiceLinks: true
    hostNetwork: true
    priority: 2000001000
    priorityClassName: system-node-critical
  -  restartPolicy: Always
  -  schedulerName: default-scheduler
    securityContext:
      seccompProfile:
        type: RuntimeDefault
  -  terminationGracePeriodSeconds: 30
    volumes:
    - hostPath:
        path: /etc/kubernetes/pki/etcd
  

이 버그에 대한 자세한 정보는 추적 이슈에서 찾을 수 있다.

1.3 - kubeadm으로 클러스터 생성하기

kubeadm을 사용하면, 모범 사례를 준수하는 최소 작동 가능한 쿠버네티스 클러스터를 생성할 수 있다. 실제로 kubeadm을 사용하여 쿠버네티스 적합성 테스트를 통과하는 클러스터를 구성할 수 있다. kubeadm은 부트스트랩 토큰 및 클러스터 업그레이드와 같은 다른 클러스터 수명 주기 기능도 지원한다.

kubeadm 도구는 다음과 같은 경우에 적합하다.

• 간단한 방법으로 쿠버네티스를 처음 시도해 보려는 경우
• 기존 사용자가 클러스터 설정을 자동화하고 애플리케이션을 테스트하려는 경우
• 더 큰 범위를 가진 다른 생태계 및/또는 설치 도구의 구성 요소로 사용하는 경우

노트북, 클라우드 서버 세트, 라즈베리 파이 등 다양한 머신에 kubeadm을 설치하여 사용할 수 있다. 클라우드 또는 온프레미스에 배포하든, kubeadm을 Ansible 또는 Terraform과 같은 프로비저닝 시스템에 통합할 수 있다.

시작하기 전에

이 가이드를 따르려면 다음이 필요하다.

• deb/rpm 호환 리눅스 OS를 실행하는 하나 이상의 머신(예: 우분투 또는 CentOS)
• 머신당 2GiB 이상의 RAM(이보다 적으면 앱을 위한 공간이 거의 남지 않음)
• 컨트롤 플레인 노드로 사용하는 머신에 최소 2개의 CPU
• 클러스터의 모든 머신 간 전체 네트워크 연결. 퍼블릭 또는 프라이빗 네트워크를 사용할 수 있다.

또한 새 클러스터에서 사용하려는 쿠버네티스 버전을 배포할 수 있는 kubeadm 버전을 사용해야 한다.

쿠버네티스 버전 및 버전 차이 지원 정책 이 쿠버네티스 전체와 마찬가지로 kubeadm에도 적용된다. 해당 정책을 확인하여 지원되는 쿠버네티스 및 kubeadm 버전을 알아보자. 이 페이지는 쿠버네티스 v1.34용으로 작성되었다.

kubeadm 도구의 전체 기능 상태는 일반 가용성(GA)이다. 일부 하위 기능은 아직 활발히 개발 중이다. 도구가 발전함에 따라 클러스터 생성 구현이 약간 변경될 수 있지만, 전체적인 구현은 꽤 안정적이어야 한다.

목표

• 단일 컨트롤 플레인 쿠버네티스 클러스터 설치
• 파드가 서로 통신할 수 있도록 클러스터에 파드 네트워크 설치

지침

호스트 준비

구성 요소 설치

모든 호스트에 컨테이너 런타임과 kubeadm을 설치한다. 자세한 지침과 기타 전제 조건은 kubeadm 설치하기를 참조한다.

네트워크 설정

kubeadm은 다른 쿠버네티스 구성 요소와 마찬가지로 호스트의 기본 게이트웨이와 연결된 네트워크 인터페이스에서 사용 가능한 IP를 찾으려고 시도한다. 그런 다음 이 IP는 구성 요소가 수행하는 광고 및/또는 수신에 사용된다.

리눅스 호스트에서 이 IP가 무엇인지 확인하려면 다음을 사용할 수 있다.

ip route show # "default via"로 시작하는 줄을 찾는다

쿠버네티스 구성 요소는 사용자 정의 네트워크 인터페이스를 옵션으로 허용하지 않으므로, 이러한 사용자 정의 구성이 필요한 모든 구성 요소 인스턴스에 사용자 정의 IP 주소를 플래그로 전달해야 한다.

init과 join 모두로 생성된 컨트롤 플레인 노드에 대한 API 서버 광고(advertise) 주소를 구성하려면 --apiserver-advertise-address 플래그를 사용할 수 있다. 선호하는 방법은 이 옵션을 kubeadm API에서 InitConfiguration.localAPIEndpoint 및 JoinConfiguration.controlPlane.localAPIEndpoint로 설정하는 것이다.

모든 노드의 kubelet의 경우, kubeadm 구성 파일(InitConfiguration 또는 JoinConfiguration)내의 .nodeRegistration.kubeletExtraArgs에서 --node-ip 옵션을 전달할 수 있다.

듀얼 스택의 경우 kubeadm을 사용한 듀얼 스택 지원을 참조한다.

컨트롤 플레인 구성 요소에 할당하는 IP 주소는 X.509 인증서의 주체 대체 이름 필드의 일부가 된다. 이러한 IP 주소를 변경하려면 새 인증서에 서명하고 영향을 받는 구성 요소를 재시작하여 인증서 파일의 변경 사항이 반영되도록 해야 한다. 이 주제에 대한 자세한 내용은 수동 인증서 갱신을 참조한다.

필요한 컨테이너 이미지 준비

이 단계는 선택 사항이며, 노드에서 인터넷 연결 없이 클러스터를 생성할 때 kubeadm init 및 kubeadm join이 registry.k8s.io에 호스팅된 기본 컨테이너 이미지를 다운로드하지 않도록 하려는 경우에만 적용된다.

kubeadm에는 인터넷 연결 없이 클러스터를 생성할 때 필요한 이미지를 미리 가져오는 데 도움이 되는 명령이 있다. 자세한 내용은 인터넷 연결 없이 kubeadm 실행을 참조한다.

kubeadm을 사용하면 필요한 이미지에 대해 사용자 정의 이미지 저장소를 사용할 수 있다. 자세한 내용은 사용자 정의 이미지 사용을 참조한다.

컨트롤 플레인 노드 초기화

컨트롤 플레인 노드는 etcd (클러스터 데이터베이스) 및 API 서버 (kubectl 명령줄 도구가 통신하는)를 포함한 컨트롤 플레인 구성 요소가 실행되는 머신이다.

1. (권장) 이 단일 컨트롤 플레인 kubeadm 클러스터를 고가용성으로 업그레이드할 계획이 있다면, 모든 컨트롤 플레인 노드에 대한 공유 엔드포인트를 설정하기 위해 --control-plane-endpoint를 지정해야 한다. 이러한 엔드포인트는 로드 밸런서의 DNS 이름 또는 IP 주소일 수 있다.
2. 파드 네트워크 애드온(add-on)을 선택하고, kubeadm init에 전달해야 하는 인수가 있는지 확인한다. 선택한 서드파티 공급자에 따라 --pod-network-cidr을 공급자별 값으로 설정해야 할 수 있다. 파드 네트워크 애드온 설치를 참조한다.
3. (선택 사항) kubeadm은 잘 알려진 엔드포인트 목록을 사용하여 컨테이너 런타임을 감지하려고 시도한다. 다른 컨테이너 런타임을 사용하거나 프로비저닝된 노드에 둘 이상이 설치된 경우 kubeadm에 --cri-socket 인수를 지정한다. 런타임 설치를 참조한다.

컨트롤 플레인 노드를 초기화하려면 다음을 실행한다.

kubeadm init <args>

apiserver-advertise-address 및 ControlPlaneEndpoint에 대한 고려 사항

--apiserver-advertise-address를 사용하여 이 특정 컨트롤 플레인 노드의 API 서버에 대한 광고 주소를 설정할 수 있지만, --control-plane-endpoint를 사용하여 모든 컨트롤 플레인 노드에 대한 공유 엔드포인트를 설정할 수 있다.

--control-plane-endpoint는 IP 주소와 IP 주소에 매핑할 수 있는 DNS 이름을 모두 허용한다. 이러한 매핑과 관련하여 가능한 솔루션을 평가하려면 네트워크 관리자에게 문의하는 것이 좋다.

다음은 매핑 예시이다.

192.168.0.102 cluster-endpoint

여기서 192.168.0.102는 이 노드의 IP 주소이고 cluster-endpoint는 이 IP에 매핑되는 사용자 정의 DNS 이름이다. 이를 통해 kubeadm init에 --control-plane-endpoint=cluster-endpoint를 전달하고 kubeadm join에 동일한 DNS 이름을 전달할 수 있다. 나중에 고가용성 시나리오에서 cluster-endpoint가 로드 밸런서 주소를 가리키도록 수정할 수 있다.

--control-plane-endpoint 없이 생성된 단일 컨트롤 플레인 클러스터를 고가용성 클러스터로 전환하는 것은 kubeadm에서 지원하지 않는다.

추가 정보

kubeadm init 인수에 대한 자세한 내용은 kubeadm 참조 가이드를 참조한다.

구성 파일로 kubeadm init을 구성하려면 구성 파일과 함께 kubeadm init 사용을 참조한다.

컨트롤 플레인 구성 요소 및 etcd 서버에 대한 활성(liveness) 프로브에 선택적 IPv6 할당을 포함하여 컨트롤 플레인 구성 요소를 사용자 정의하려면 사용자 정의 인수에 문서화된 대로 각 구성 요소에 추가 인수를 제공한다.

이미 생성된 클러스터를 재구성하려면 kubeadm 클러스터 재구성을 참조한다.

kubeadm init을 다시 실행하려면 먼저 클러스터를 해체해야 한다.

클러스터에 다른 아키텍처의 노드를 추가(join)하는 경우, 배포된 데몬셋이 이 아키텍처에 대한 컨테이너 이미지를 지원하는지 확인한다.

kubeadm init은 먼저 머신이 쿠버네티스를 실행할 준비가 되었는지 확인하기 위해 일련의 사전 검사를 실행한다. 이러한 사전 검사는 경고를 표시하고 오류가 발생하면 종료된다. 그런 다음 kubeadm init은 클러스터 컨트롤 플레인 구성 요소를 다운로드하고 설치한다. 이 작업은 몇 분 정도 걸릴 수 있다. 완료되면 다음이 표시된다.

Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a Pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  /docs/concepts/cluster-administration/addons/

You can now join any number of machines by running the following on each node
as root:

  kubeadm join <control-plane-host>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

루트(root)가 아닌 사용자가 kubectl을 사용할 수 있도록 하려면 kubeadm init 출력의 일부이기도 한 다음 명령을 실행한다.

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

또는 root 사용자인 경우 다음을 실행할 수 있다.

export KUBECONFIG=/etc/kubernetes/admin.conf

kubeadm init이 출력하는 kubeadm join 명령을 기록해 둔다. 클러스터에 노드를 추가하려면 이 명령이 필요하다.

토큰은 컨트롤 플레인 노드와 추가되는 노드 간의 상호 인증에 사용된다. 여기에 포함된 토큰은 비밀(secret)이다. 이 토큰을 안전하게 보관한다. 이 토큰을 가진 사람은 누구나 클러스터에 인증된 노드를 추가할 수 있기 때문이다. 이러한 토큰은 kubeadm token 명령으로 나열, 생성 및 삭제할 수 있다. kubeadm 참조 가이드를 참조한다.

파드 네트워크 애드온 설치

여러 외부 프로젝트가 CNI를 사용하여 쿠버네티스 파드 네트워크를 제공하며, 그 중 일부는 네트워크 정책도 지원한다.

쿠버네티스 네트워킹 모델을 구현하는 애드온 목록을 참조한다.

쿠버네티스에서 지원하는 네트워킹 애드온의 전체 목록은 아니지만 애드온 설치 페이지를 참조한다. 컨트롤 플레인 노드 또는 kubeconfig 자격 증명이 있는 노드에서 다음 명령으로 파드 네트워크 애드온을 설치할 수 있다.

kubectl apply -f <add-on.yaml>

클러스터당 하나의 파드 네트워크만 설치할 수 있다.

파드 네트워크가 설치되면 kubectl get pods --all-namespaces 출력에서 CoreDNS 파드가 Running 상태인지 확인하여 작동하는지 확인할 수 있다. CoreDNS 파드가 실행 중이면 노드 추가를 계속할 수 있다.

네트워크가 작동하지 않거나 CoreDNS가 Running 상태가 아닌 경우 kubeadm에 대한 문제 해결 가이드를 확인한다.

관리되는 노드 레이블

기본적으로 kubeadm은 노드 등록 시 kubelet이 자체 적용할 수 있는 레이블을 제한하는 NodeRestriction 어드미션 컨트롤러를 활성화한다. 어드미션 컨트롤러 문서에서는 kubelet --node-labels 옵션과 함께 사용할 수 있는 레이블을 다룬다. node-role.kubernetes.io/control-plane 레이블은 이러한 제한된 레이블이며 kubeadm은 노드가 생성된 후 권한 있는 클라이언트를 사용하여 수동으로 적용한다. 수동으로 수행하려면 kubectl label을 사용하고 kubeadm이 관리하는 /etc/kubernetes/admin.conf와 같은 권한 있는 kubeconfig를 사용하는지 확인한다.

컨트롤 플레인 노드 격리

기본적으로 클러스터는 보안상의 이유로 컨트롤 플레인 노드에 파드를 스케줄하지 않는다. 예를 들어 단일 머신 쿠버네티스 클러스터의 경우 컨트롤 플레인 노드에 파드를 스케줄할 수 있도록 하려면 다음을 실행한다.

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

출력은 다음과 같다.

node "test-01" untainted
...

이렇게 하면 컨트롤 플레인 노드를 포함하여 node-role.kubernetes.io/control-plane:NoSchedule 테인트(taint)가 있는 모든 노드에서 해당 테인트가 제거되어 스케줄러가 모든 곳에 파드를 스케줄할 수 있게 된다.

또한 다음 명령을 실행하여 컨트롤 플레인 노드에서 node.kubernetes.io/exclude-from-external-load-balancers 레이블을 제거할 수 있다. 이 레이블은 해당 노드를 백엔드 서버 목록에서 제외한다.

kubectl label nodes --all node.kubernetes.io/exclude-from-external-load-balancers-

더 많은 컨트롤 플레인 노드 추가

더 많은 컨트롤 플레인 노드를 추가하여 고가용성 kubeadm 클러스터를 생성하는 단계는 kubeadm으로 고가용성 클러스터 생성을 참조한다.

워커 노드 추가

워커 노드는 워크로드가 실행되는 곳이다.

다음 페이지에서는 kubeadm join 명령을 사용하여 클러스터에 리눅스 및 Windows 워커 노드를 추가하는 방법을 보여준다.

• 리눅스 워커 노드 추가
• Windows 워커 노드 추가

(선택 사항) 컨트롤 플레인 노드가 아닌 머신에서 클러스터 제어

다른 컴퓨터(예: 노트북)의 kubectl이 클러스터와 통신하도록 하려면 다음과 같이 컨트롤 플레인 노드에서 관리자 kubeconfig 파일을 워크스테이션으로 복사해야 한다.

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf get nodes

(선택 사항) API 서버를 localhost로 프록시

클러스터 외부에서 API 서버에 연결하려면 kubectl proxy를 사용할 수 있다.

scp root@<control-plane-host>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf proxy

이제 http://localhost:8001/api/v1에서 로컬로 API 서버에 액세스할 수 있다.

정리

테스트용으로 클러스터에 일회용 서버를 사용한 경우, 전원을 끄고 추가 정리를 수행하지 않을 수 있다. kubectl config delete-cluster를 사용하여 클러스터에 대한 로컬 참조를 삭제할 수 있다.

그러나 클러스터를 더 깔끔하게 프로비저닝 해제하려면 먼저 노드를 드레인(drain)하고 노드가 비어 있는지 확인한 다음 노드 구성을 해제해야 한다.

노드 제거

적절한 자격 증명으로 컨트롤 플레인 노드와 통신하여 다음을 실행한다.

kubectl drain <node name> --delete-emptydir-data --force --ignore-daemonsets

노드를 제거하기 전에 kubeadm이 설치한 상태를 재설정한다.

kubeadm reset

재설정 프로세스는 iptables 규칙이나 IPVS 테이블을 재설정하거나 정리하지 않는다. iptables를 재설정하려면 수동으로 수행해야 한다.

iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X

IPVS 테이블을 재설정하려면 다음 명령을 실행해야 한다.

ipvsadm -C

이제 노드를 제거한다.

kubectl delete node <node name>

다시 시작하려면 적절한 인수와 함께 kubeadm init 또는 kubeadm join을 실행한다.

컨트롤 플레인 정리

컨트롤 플레인 호스트에서 kubeadm reset을 사용하여 최선의 노력으로 정리를 트리거할 수 있다.

이 하위 명령 및 해당 옵션에 대한 자세한 내용은 kubeadm reset 참조 문서를 확인한다.

버전 차이 정책

kubeadm이 관리하는 일부 구성 요소에 대해 버전 차이를 허용하지만, kubeadm 버전을 컨트롤 플레인 구성 요소, kube-proxy 및 kubelet의 버전과 일치시키는 것이 좋다.

kubeadm과 쿠버네티스 버전 간의 차이

kubeadm은 kubeadm과 동일한 버전 또는 한 버전 이전의 쿠버네티스 구성 요소와 함께 사용할 수 있다. 쿠버네티스 버전은 kubeadm init의 --kubernetes-version 플래그 또는 --config 사용 시 ClusterConfiguration.kubernetesVersion 필드를 사용하여 kubeadm에 지정할 수 있다. 이 옵션은 kube-apiserver, kube-controller-manager, kube-scheduler 및 kube-proxy의 버전을 제어한다.

예시:

• kubeadm이 1.34인 경우
• kubernetesVersion은 1.34 또는 1.33이어야 한다

kubeadm과 kubelet 간의 차이

쿠버네티스 버전과 마찬가지로, kubeadm은 kubeadm과 동일한 버전 또는 세 버전 이전의 kubelet 버전과 함께 사용할 수 있다.

예시:

• kubeadm이 1.34인 경우
• 호스트의 kubelet은 1.34, 1.33, 1.32 또는 1.31이어야 한다

kubeadm 간의 차이

kubeadm 명령이 kubeadm이 관리하는 기존 노드 또는 전체 클러스터에서 작동할 수 있는 방법에는 특정 제한이 있다.

새 노드가 클러스터에 추가되는 경우, kubeadm join에 사용되는 kubeadm 바이너리는 kubeadm init으로 클러스터를 생성하거나 kubeadm upgrade로 동일한 노드를 업그레이드하는 데 사용된 kubeadm의 마지막 버전과 일치해야 한다. kubeadm upgrade를 제외한 나머지 kubeadm 명령에도 유사한 규칙이 적용된다.

kubeadm join 예시:

• kubeadm 버전 1.34을 사용하여 kubeadm init으로 클러스터를 생성한 경우
• 추가되는 노드는 1.34 버전의 kubeadm 바이너리를 사용해야 한다

업그레이드 중인 노드는 노드 관리에 사용된 kubeadm 버전과 동일한 MINOR 버전 또는 하나 높은 MINOR 버전의 kubeadm을 사용해야 한다.

kubeadm upgrade 예시:

• kubeadm 버전 1.33을 사용하여 노드를 생성하거나 업그레이드한 경우
• 노드 업그레이드에 사용되는 kubeadm 버전은 1.33 또는 1.34이어야 한다

다른 쿠버네티스 구성 요소 간의 버전 차이에 대해 자세히 알아보려면 버전 차이 정책을 참조한다.

제한사항

클러스터 복원력(resilience)

여기서 생성된 클러스터에는 단일 etcd 데이터베이스가 실행되는 단일 컨트롤 플레인 노드가 있다. 즉, 컨트롤 플레인 노드가 실패하면 클러스터가 데이터를 잃을 수 있으며 처음부터 다시 생성해야 할 수 있다.

해결 방법:

• 정기적으로 etcd를 백업한다. kubeadm이 구성한 etcd 데이터 디렉터리는 컨트롤 플레인 노드의 /var/lib/etcd에 있다.

• 여러 컨트롤 플레인 노드를 사용한다. 고가용성을 제공하는 클러스터 토폴로지를 선택하려면 고가용성 토폴로지 옵션을 읽을 수 있다.

플랫폼 호환성

kubeadm deb/rpm 패키지와 바이너리는 멀티 플랫폼 제안에 따라 amd64, arm(32비트), arm64, ppc64le 및 s390x용으로 빌드된다.

컨트롤 플레인 및 애드온용 멀티 플랫폼 컨테이너 이미지도 v1.12부터 지원된다.

일부 네트워크 공급자만 모든 플랫폼에 대한 솔루션을 제공한다. 공급자가 선택한 플랫폼을 지원하는지 확인하려면 위의 네트워크 공급자 목록이나 각 공급자의 문서를 참조한다.

문제 해결

kubeadm에 문제가 발생하면 문제 해결 문서를 참조한다.

다음 내용

• Sonobuoy로 클러스터가 제대로 실행되고 있는지 확인
• kubeadm을 사용한 클러스터 업그레이드에 대한 자세한 내용은 kubeadm 클러스터 업그레이드를 참조한다.
• kubeadm 참조 문서에서 고급 kubeadm 사용법에 대해 알아보기
• 쿠버네티스 개념 및 kubectl에 대해 자세히 알아보기
• 파드 네트워크 애드온의 더 큰 목록은 클러스터 네트워킹 페이지를 참조한다.
• 로깅, 모니터링, 네트워크 정책, 시각화 및 쿠버네티스 클러스터 제어를 위한 도구를 포함한 다른 애드온을 탐색하려면 애드온 목록을 참조한다.
• 클러스터 이벤트 및 파드에서 실행되는 애플리케이션의 로그를 클러스터가 처리하는 방법을 구성한다. 관련 사항에 대한 개요는 로깅 아키텍처를 참조한다.

피드백

• 버그의 경우, kubeadm GitHub 이슈 트래커를 방문한다
• 지원을 받으려면 #kubeadm 슬랙 채널을 방문한다
• 일반 SIG 클러스터 수명 주기 개발 슬랙 채널: #sig-cluster-lifecycle
• SIG 클러스터 수명 주기 SIG 정보
• SIG 클러스터 수명 주기 메일링 리스트: kubernetes-sig-cluster-lifecycle

1.4 - kubeadm API로 컴포넌트 사용자 정의하기

이 페이지는 kubeadm이 배포하는 컴포넌트(component)들을 사용자 정의하는 방법을 다룬다. 컨트롤 플레인 컴포넌트에 대해서는 Cluster Configuration 구조에서 플래그를 사용하거나 노드당 패치를 사용할 수 있다. kubelet과 kube-proxy의 경우, KubeletConfiguration과 KubeProxyConfiguration을 각각 사용할 수 있다.

이 모든 옵션이 kubeadm 구성 API를 통해 가용하다. 구성의 각 필드 상세 사항은 API 참조 페이지에서 찾아볼 수 있다.

ClusterConfiguration의 플래그로 컨트롤 플레인 사용자 정의하기

kubeadm의 ClusterConfiguration 오브젝트는 API 서버, 컨트롤러매니저, 스케줄러, Etcd와 같은 컨트롤 플레인 컴포넌트에 전달되는 기본 플래그를 사용자가 덮어쓸 수 있도록 노출한다. 이 컴포넌트는 다음 구조체를 사용하여 정의된다.

• apiServer
• controllerManager
• scheduler
• etcd

이 구조체들은 공통 필드인 extraArgs를 포함하며, 이 필드는 키: 값 쌍으로 구성된다. 컨트롤 플레인 컴포넌트를 위한 플래그를 덮어쓰려면 다음을 수행한다.

1. 사용자 구성에 적절한 extraArgs 필드를 추가한다.
2. extraArgs 필드에 플래그를 추가한다.
3. kubeadm init에 --config <CONFIG YAML 파일> 파라미터를 추가해서 실행한다.

APIServer 플래그

자세한 내용은 kube-apiserver 레퍼런스 문서를 확인한다.

사용 예시:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: v1.16.0
apiServer:
  extraArgs:
    anonymous-auth: "false"
    enable-admission-plugins: AlwaysPullImages,DefaultStorageClass
    audit-log-path: /home/johndoe/audit.log

컨트롤러매니저 플래그

자세한 내용은 kube-controller-manager 레퍼런스 문서를 확인한다.

사용 예시:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: v1.16.0
controllerManager:
  extraArgs:
    cluster-signing-key-file: /home/johndoe/keys/ca.key
    deployment-controller-sync-period: "50"

스케줄러 플래그

자세한 내용은 kube-scheduler 레퍼런스 문서를 확인한다.

사용 예시:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: v1.16.0
scheduler:
  extraArgs:
    config: /etc/kubernetes/scheduler-config.yaml
  extraVolumes:
    - name: schedulerconfig
      hostPath: /home/johndoe/schedconfig.yaml
      mountPath: /etc/kubernetes/scheduler-config.yaml
      readOnly: true
      pathType: "File"

Etcd 플래그

자세한 사항은 etcd 서버 문서를 확인한다.

사용 예시:

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
etcd:
  local:
    extraArgs:
      election-timeout: 1000

패치를 통해 사용자 정의하기

Kubeadm을 사용하면 패치 파일이 있는 디렉토리를 개별 노드에 대한 InitConfiguration과 JoinConfiguration에 전달할 수 있다. 이 패치는 컴포넌트 구성이 디스크에 기록되기 전에 최종 사용자 정의 단계로 사용될 수 있다.

--config <YOUR CONFIG YAML>을 사용하여 이 파일을 kubeadm init에 전달할 수 있다.

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
  patches:
    directory: /home/user/somedir

--config <YOUR CONFIG YAML>을 사용하여 이 파일을 kubeadm join에 전달할 수 있다.

apiVersion: kubeadm.k8s.io/v1beta3
kind: JoinConfiguration
  patches:
    directory: /home/user/somedir

디렉토리는 target[suffix][+patchtype].extension 형태의 파일을 포함해야 한다. 예를 들면, kube-apiserver0+merge.yaml 또는 단순히 etcd.json의 형태이다.

• target은 kube-apiserver, kube-controller-manager, kube-scheduler, etcd 그리고 kubeletconfiguration 중 하나가 될 수 있다.
• patchtype은 strategic, merge 그리고 json 중 하나가 될 수 있으며 kubectl에서 지원하는 패치 형식을 준수해야 한다. patchtype의 기본값은 strategic이다.
• extension은 json 또는 yaml 중 하나여야 한다.
• suffix는 어떤 패치가 먼저 적용되는지를 결정하는 데 사용할 수 있는 영숫자 형태의 선택적 문자열이다.

kubelet 사용자 정의하기

kubelet을 사용자 정의하려면, KubeletConfiguration을 동일한 구성 파일 내에서 ---로 구분된 ClusterConfiguration이나 InitConfiguration 다음에 추가하면 된다. 그런 다음 kubeadm init에 해당 파일을 전달하면, kubeadm은 동일한 기본 KubeletConfiguration을 클러스터의 모든 노드에 적용한다.

기본 KubeletConfiguration에 더하여 인스턴스별 구성을 적용하기 위해서는 kubeletconfiguration 패치 target을 이용할 수 있다.

다른 방법으로는, kubelet 플래그를 덮어쓰기(overrides)로 사용하여, InitConfiguration 및 JoinConfiguration 모두에서 지원되는 nodeRegistration.kubeletExtraArgs에 전달할 수 있다. 일부 kubelet 플래그는 더 이상 사용되지 않는다(deprecated). 따라서 사용하기 전에 kubelet 참조 문서를 통해 상태를 확인해야 한다.

이 외 더 자세한 사항은 kubeadm을 통해 클러스터의 각 kubelet 구성하기에서 살펴본다.

kube-proxy 사용자 정의하기

kube-proxy를 사용자 정의하려면, KubeProxyConfiguration을 ---로 구분된 ClusterConfiguration이나 InitConfiguration 다음에 두고 kubeadm init에 전달하면 된다.

자세한 사항은 API 참조 페이지에서 살펴볼 수 있다.

1.5 - 고가용성 토폴로지 선택

이 페이지는 고가용성(HA) 쿠버네티스 클러스터의 토플로지를 구성하는 두 가지 선택 사항을 설명한다.

다음과 같이 HA 클러스터를 구성할 수 있다.

• etcd 노드와 컨트롤 플레인 노드를 함께 위치시키는 중첩된(stacked) 컨트롤 플레인 노드 방식
• etcd와 컨트롤 플레인이 분리된 노드에서 운영되는 외부 etcd 노드 방식

HA 클러스터를 구성하기 전에 각 토플로지의 장단점을 주의 깊게 고려해야 한다.

중첩된 etcd 토플로지

중첩된 HA 클러스터는 etcd에서 제공하는 분산 데이터 저장소 클러스터를, 컨트롤 플레인 구성 요소를 실행하는 kubeadm으로 관리되는 노드에 의해서 형성된 클러스터 상단에 중첩하는 토플로지이다.

각 컨트롤 플레인 노드는 kube-apiserver, kube-scheduler, kube-controller-manager 인스턴스를 운영한다. kube-apiserver는 로드 밸런서를 이용하여 워커 노드에 노출되어 있다.

각 컨트롤 플레인 노드는 지역 etcd 맴버를 생성하고 이 etcd 맴버는 오직 해당 노드의 kube-apiserver와 통신한다. 비슷한 방식이 지역의 kube-controller-manager와 kube-scheduler에도 적용된다.

이 토플로지는 컨트롤 플레인과 etcd 맴버가 같은 노드에 묶여 있다. 이는 외부 etcd 노드의 클러스터를 구성하는 것보다는 단순하며 복제 관리도 간단하다.

그러나 중첩된 클러스터는 커플링에 실패할 위험이 있다. 한 노드가 다운되면 etcd 맴버와 컨트롤 플레인을 모두 잃어버리고, 중복성도 손상된다. 더 많은 컨트롤 플레인 노드를 추가하여 이 위험을 완화할 수 있다.

그러므로 HA 클러스터를 위해 최소 3개인 중첩된 컨트롤 플레인 노드를 운영해야 한다.

이는 kubeadm의 기본 토플로지이다. 지역 etcd 맴버는 kubeadm init와 kubeadm join --control-plane 을 이용할 때에 컨트롤 플레인 노드에 자동으로 생성된다.

외부 etcd 토플로지

외부 etcd를 이용하는 HA 클러스터는 etcd로 제공한 분산된 데이터 스토리지 클러스터가 컨트롤 플레인 구성 요소를 운영하는 노드로 형성하는 클러스터의 외부에 있는 토플로지이다.

중첩된 etcd 토플로지와 유사하게, 외부 etcd 토플로지에 각 컨트롤 플레인 노드는 kube-apiserver, kube-scheduler, kube-controller-manager의 인스턴스를 운영한다. 그리고 kube-apiserver는 로드 밸런서를 이용하여 워커노드에 노출한다. 그러나 etcd 맴버는 분리된 호스트에서 운영되고, 각 etcd 호스트는 각 컨트롤 플레인 노드의 kube-apiserver와 통신한다.

이 토플로지는 컨트롤 플레인과 etcd 맴버를 분리한다. 이는 그러므로 컨트롤 플레인 인스턴스나 etcd 맴버를 잃는 충격이 덜하고, 클러스터 중복성에 있어 중첩된 HA 토플로지만큼 영향을 미치지 않는다.

그러나, 이 토플로지는 중첩된 토플로지에 비해 호스트 개수가 두배나 필요하다. 이 토플로지로 HA 클러스터를 구성하기 위해서는 최소한 3개의 컨트롤 플레인과 3개의 etcd 노드가 필요하다.

다음 내용

• kubeadm을 이용하여 고가용성 클러스터 구성하기