이 섹션의 다중 페이지 출력 화면임. 여기를 클릭하여 프린트.

이 페이지의 일반 화면으로 돌아가기.

태스크

쿠버네티스 문서에서 이 섹션은 개별의 태스크를 수행하는 방법을 보여준다. 한 태스크 페이지는 일반적으로 여러 단계로 이루어진 짧은 시퀀스를 제공함으로써, 하나의 일을 수행하는 방법을 보여준다.

만약 태스크 페이지를 작성하고 싶다면, 문서 풀 리퀘스트(Pull Request) 생성하기를 참조한다.

1 - 도구 설치

컴퓨터에서 쿠버네티스 도구를 설정한다.

kubectl

쿠버네티스 커맨드 라인 도구인 kubectl을 사용하면 쿠버네티스 클러스터에 대해 명령을 실행할 수 있다. kubectl 을 사용하여 애플리케이션을 배포하고, 클러스터 리소스를 검사 및 관리하고, 로그를 볼 수 있다. kubectl 전체 명령어를 포함한 추가 정보는 kubectl 레퍼런스 문서에서 확인할 수 있다.

kubectl 은 다양한 리눅스 플랫폼, macOS, 그리고 윈도우에 설치할 수 있다. 각각에 대한 설치 가이드는 다음과 같다.

kind

kind를 사용하면 로컬 컴퓨터에서 쿠버네티스를 실행할 수 있다. 이 도구를 사용하려면 도커를 설치하고 구성해야 한다.

kind 퀵 스타트 페이지는 kind를 시작하고 실행하기 위해 수행해야 하는 작업을 보여준다.

kind 시작하기 가이드 보기

minikube

kind 와 마찬가지로, minikube는 쿠버네티스를 로컬에서 실행할 수 있는 도구이다. minikube 는 개인용 컴퓨터(윈도우, macOS 및 리눅스 PC 포함)에서 단일 노드 쿠버네티스 클러스터를 실행하여 쿠버네티스를 사용해보거나 일상적인 개발 작업을 수행할 수 있다.

도구 설치에 중점을 두고 있다면 공식 사이트에서의 시작하기! 가이드를 따라 해볼 수 있다.

minikube 시작하기! 가이드 보기

minikube 가 작동하면, 이를 사용하여 샘플 애플리케이션을 실행해볼 수 있다.

kubeadm

kubeadm 도구를 사용하여 쿠버네티스 클러스터를 만들고 관리할 수 있다. 사용자 친화적인 방식으로 최소한의 실행 가능하고 안전한 클러스터를 설정하고 실행하는 데 필요한 작업을 수행한다.

kubeadm 설치 페이지는 kubeadm 설치하는 방법을 보여준다. 설치가 끝나면, 클러스터 생성이 가능하다.

kubeadm 설치 가이드 보기

1.1 - macOS에 kubectl 설치 및 설정

시작하기 전에

클러스터의 마이너(minor) 버전 차이 내에 있는 kubectl 버전을 사용해야 한다. 예를 들어, v1.21 클라이언트는 v1.20, v1.21, v1.22의 컨트롤 플레인과 연동될 수 있다. 최신 버전의 kubectl을 사용하면 예기치 않은 문제를 피할 수 있다.

macOS에 kubectl 설치

다음과 같은 방법으로 macOS에 kubectl을 설치할 수 있다.

macOS에서 curl을 사용하여 kubectl 바이너리 설치

  1. 최신 릴리스를 다운로드한다.

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"
    참고:

    특정 버전을 다운로드하려면, $(curl -L -s https://dl.k8s.io/release/stable.txt) 명령 부분을 특정 버전으로 바꾼다.

    예를 들어, Intel macOS에 버전 v1.21.0을 다운로드하려면, 다음을 입력한다.

    curl -LO "https://dl.k8s.io/release/v1.21.0/bin/darwin/amd64/kubectl"

    Apple Silicon의 macOS라면, 다음을 입력한다.

    curl -LO "https://dl.k8s.io/release/v1.21.0/bin/darwin/arm64/kubectl"

  2. 바이너리를 검증한다. (선택 사항)

    kubectl 체크섬 파일을 다운로드한다.

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl.sha256"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl.sha256"

    kubectl 바이너리를 체크섬 파일을 통해 검증한다.

    echo "$(<kubectl.sha256)  kubectl" | shasum -a 256 --check

    검증이 성공한다면, 출력은 다음과 같다.

    kubectl: OK

    검증이 실패한다면, shasum이 0이 아닌 상태로 종료되며 다음과 유사한 결과를 출력한다.

    kubectl: FAILED
shasum: WARNING: 1 computed checksum did NOT match
    참고: 동일한 버전의 바이너리와 체크섬을 다운로드한다.

  3. kubectl 바이너리를 실행 가능하게 한다.

    chmod +x ./kubectl

  4. kubectl 바이너리를 시스템 PATH 의 파일 위치로 옮긴다.

    sudo mv ./kubectl /usr/local/bin/kubectl
sudo chown root: /usr/local/bin/kubectl
    참고: PATH 환경 변수 안에 /usr/local/bin 이 있는지 확인한다.

  5. 설치한 버전이 최신 버전인지 확인한다.

    kubectl version --client

macOS에서 Homebrew를 사용하여 설치

macOS에서 Homebrew 패키지 관리자를 사용하는 경우, Homebrew로 kubectl을 설치할 수 있다.

  1. 설치 명령을 실행한다.

    brew install kubectl

    또는

    brew install kubernetes-cli

  2. 설치한 버전이 최신 버전인지 확인한다.

    kubectl version --client

macOS에서 Macports를 사용하여 설치

macOS에서 Macports 패키지 관리자를 사용하는 경우, Macports로 kubectl을 설치할 수 있다.

  1. 설치 명령을 실행한다.

    sudo port selfupdate
sudo port install kubectl

  2. 설치한 버전이 최신 버전인지 확인한다.

    kubectl version --client

kubectl 구성 확인

kubectl이 쿠버네티스 클러스터를 찾아 접근하려면, kube-up.sh를 사용하여 클러스터를 생성하거나 Minikube 클러스터를 성공적으로 배포할 때 자동으로 생성되는 kubeconfig 파일이 필요하다. 기본적으로, kubectl 구성은 ~/.kube/config 에 있다.

클러스터 상태를 가져와서 kubectl이 올바르게 구성되어 있는지 확인한다.

kubectl cluster-info

URL 응답이 표시되면, kubectl이 클러스터에 접근하도록 올바르게 구성된 것이다.

다음과 비슷한 메시지가 표시되면, kubectl이 올바르게 구성되지 않았거나 쿠버네티스 클러스터에 연결할 수 없다.

The connection to the server <server-name:port> was refused - did you specify the right host or port?

예를 들어, 랩톱에서 로컬로 쿠버네티스 클러스터를 실행하려면, Minikube와 같은 도구를 먼저 설치한 다음 위에서 언급한 명령을 다시 실행해야 한다.

kubectl cluster-info가 URL 응답을 반환하지만 클러스터에 접근할 수 없는 경우, 올바르게 구성되었는지 확인하려면 다음을 사용한다.

kubectl cluster-info dump

선택적 kubectl 구성

셸 자동 완성 활성화

kubectl은 Bash 및 Zsh에 대한 자동 완성 지원을 제공하므로 입력을 위한 타이핑을 많이 절약할 수 있다.

다음은 Bash 및 Zsh에 대한 자동 완성을 설정하는 절차이다.

소개

Bash의 kubectl 자동 완성 스크립트는 kubectl completion bash 로 생성할 수 있다. 이 스크립트를 셸에 소싱하면 kubectl 자동 완성이 가능하다.

그러나 kubectl 자동 완성 스크립트는 미리 bash-completion을 설치해야 동작한다.

경고: bash-completion에는 v1과 v2 두 가지 버전이 있다. v1은 Bash 3.2(macOS의 기본 설치 버전) 버전용이고, v2는 Bash 4.1 이상 버전용이다. kubectl 자동 완성 스크립트는 bash-completion v1과 Bash 3.2 버전에서는 작동하지 않는다. bash-completion v2 와 Bash 4.1 이상 버전 이 필요하다. 따라서, macOS에서 kubectl 자동 완성 기능을 올바르게 사용하려면, Bash 4.1 이상을 설치하고 사용해야 한다(지침). 다음의 내용에서는 Bash 4.1 이상(즉, 모든 Bash 버전 4.1 이상)을 사용한다고 가정한다.

Bash 업그레이드

여기의 지침에서는 Bash 4.1 이상을 사용한다고 가정한다. 다음을 실행하여 Bash 버전을 확인할 수 있다.

echo $BASH_VERSION

너무 오래된 버전인 경우, Homebrew를 사용하여 설치/업그레이드할 수 있다.

brew install bash

셸을 다시 로드하고 원하는 버전을 사용 중인지 확인한다.

echo $BASH_VERSION $SHELL

Homebrew는 보통 /usr/local/bin/bash 에 설치한다.

bash-completion 설치

참고: 언급한 바와 같이, 이 지침에서는 Bash 4.1 이상을 사용한다고 가정한다. 이는 bash-completion v2를 설치한다는 것을 의미한다(Bash 3.2 및 bash-completion v1의 경우, kubectl 자동 완성이 작동하지 않음).

bash-completion v2가 이미 설치되어 있는지 type_init_completion 으로 확인할 수 있다. 그렇지 않은 경우, Homebrew로 설치할 수 있다.

brew install bash-completion@2

이 명령의 출력에 명시된 바와 같이, ~/.bash_profile 파일에 다음을 추가한다.

export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

셸을 다시 로드하고 bash-completion v2가 올바르게 설치되었는지 type _init_completion 으로 확인한다.

kubectl 자동 완성 활성화

이제 kubectl 자동 완성 스크립트가 모든 셸 세션에서 제공되도록 해야 한다. 이를 수행하는 방법에는 여러 가지가 있다.

  • 자동 완성 스크립트를 ~/.bash_profile 파일에서 소싱한다.

    echo 'source <(kubectl completion bash)' >>~/.bash_profile

  • 자동 완성 스크립트를 /usr/local/etc/bash_completion.d 디렉터리에 추가한다.

    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

  • kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하기 위해 셸 자동 완성을 확장할 수 있다.

    echo 'alias k=kubectl' >>~/.bash_profile
echo 'complete -F __start_kubectl k' >>~/.bash_profile

  • Homebrew로 kubectl을 설치한 경우(여기의 설명을 참고), kubectl 자동 완성 스크립트가 이미 /usr/local/etc/bash_completion.d/kubectl 에 있을 것이다. 이 경우, 아무 것도 할 필요가 없다.

    참고: bash-completion v2의 Homebrew 설치는 BASH_COMPLETION_COMPAT_DIR 디렉터리의 모든 파일을 소싱하므로, 후자의 두 가지 방법이 적용된다.

어떤 경우든, 셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

Zsh용 kubectl 자동 완성 스크립트는 kubectl completion zsh 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱하면 kubectl 자동 완성 기능이 활성화된다.

모든 셸 세션에서 사용하려면, ~/.zshrc 파일에 다음을 추가한다.

source <(kubectl completion zsh)

kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.zshrc
echo 'complete -F __start_kubectl k' >>~/.zshrc

셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

complete:13: command not found: compdef 와 같은 오류가 발생하면, ~/.zshrc 파일의 시작 부분에 다음을 추가한다.

autoload -Uz compinit
compinit

다음 내용

1.2 - 리눅스에 kubectl 설치 및 설정

시작하기 전에

클러스터의 마이너(minor) 버전 차이 내에 있는 kubectl 버전을 사용해야 한다. 예를 들어, v1.21 클라이언트는 v1.20, v1.21, v1.22의 컨트롤 플레인과 연동될 수 있다. 최신 버전의 kubectl을 사용하면 예기치 않은 문제를 피할 수 있다.

리눅스에 kubectl 설치

다음과 같은 방법으로 리눅스에 kubectl을 설치할 수 있다.

리눅스에서 curl을 사용하여 kubectl 바이너리 설치

  1. 다음 명령으로 최신 릴리스를 다운로드한다.

    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    참고:

    특정 버전을 다운로드하려면, $(curl -L -s https://dl.k8s.io/release/stable.txt) 명령 부분을 특정 버전으로 바꾼다.

    예를 들어, 리눅스에서 버전 v1.21.0을 다운로드하려면, 다음을 입력한다.

    curl -LO https://dl.k8s.io/release/v1.21.0/bin/linux/amd64/kubectl

  2. 바이너리를 검증한다. (선택 사항)

    kubectl 체크섬(checksum) 파일을 다운로드한다.

    curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"

    kubectl 바이너리를 체크섬 파일을 통해 검증한다.

    echo "$(<kubectl.sha256) kubectl" | sha256sum --check

    검증이 성공한다면, 출력은 다음과 같다.

    kubectl: OK

    검증이 실패한다면, shasum이 0이 아닌 상태로 종료되며 다음과 유사한 결과를 출력한다.

    kubectl: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match
    참고: 동일한 버전의 바이너리와 체크섬을 다운로드한다.

  3. kubectl 설치

    sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
    참고:

    대상 시스템에 root 접근 권한을 가지고 있지 않더라도, ~/.local/bin 디렉터리에 kubectl을 설치할 수 있다.

    mkdir -p ~/.local/bin/kubectl
mv ./kubectl ~/.local/bin/kubectl
# 그리고 ~/.local/bin/kubectl을 $PATH에 추가

  4. 설치한 버전이 최신인지 확인한다.

    kubectl version --client

기본 패키지 관리 도구를 사용하여 설치

  1. apt 패키지 색인을 업데이트하고 쿠버네티스 apt 리포지터리를 사용하는 데 필요한 패키지들을 설치한다.

    sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl

  2. 구글 클라우드 공개 사이닝 키를 다운로드한다.

    sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg

  3. 쿠버네티스 apt 리포지터리를 추가한다.

    echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list

  4. 새 리포지터리의 apt 패키지 색인을 업데이트하고 kubectl을 설치한다.

    sudo apt-get update
sudo apt-get install -y kubectl



cat <<EOF > /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOF
yum install -y kubectl

다른 패키지 관리 도구를 사용하여 설치

snap 패키지 관리자를 지원하는 Ubuntu 또는 다른 리눅스 배포판을 사용하는 경우, kubectl을 snap 애플리케이션으로 설치할 수 있다.

snap install kubectl --classic
kubectl version --client

리눅스 상에서 Homebrew 패키지 관리자를 사용한다면, 설치를 통해 kubectl을 사용할 수 있다.

brew install kubectl
kubectl version --client

kubectl 구성 확인

kubectl이 쿠버네티스 클러스터를 찾아 접근하려면, kube-up.sh를 사용하여 클러스터를 생성하거나 Minikube 클러스터를 성공적으로 배포할 때 자동으로 생성되는 kubeconfig 파일이 필요하다. 기본적으로, kubectl 구성은 ~/.kube/config 에 있다.

클러스터 상태를 가져와서 kubectl이 올바르게 구성되어 있는지 확인한다.

kubectl cluster-info

URL 응답이 표시되면, kubectl이 클러스터에 접근하도록 올바르게 구성된 것이다.

다음과 비슷한 메시지가 표시되면, kubectl이 올바르게 구성되지 않았거나 쿠버네티스 클러스터에 연결할 수 없다.

The connection to the server <server-name:port> was refused - did you specify the right host or port?

예를 들어, 랩톱에서 로컬로 쿠버네티스 클러스터를 실행하려면, Minikube와 같은 도구를 먼저 설치한 다음 위에서 언급한 명령을 다시 실행해야 한다.

kubectl cluster-info가 URL 응답을 반환하지만 클러스터에 접근할 수 없는 경우, 올바르게 구성되었는지 확인하려면 다음을 사용한다.

kubectl cluster-info dump

선택적 kubectl 구성

셸 자동 완성 활성화

kubectl은 Bash 및 Zsh에 대한 자동 완성 지원을 제공하므로 입력을 위한 타이핑을 많이 절약할 수 있다.

다음은 Bash 및 Zsh에 대한 자동 완성을 설정하는 절차이다.

소개

Bash의 kubectl 자동 완성 스크립트는 kubectl completion bash 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱(sourcing)하면 kubectl 자동 완성 기능이 활성화된다.

그러나, 자동 완성 스크립트는 bash-completion에 의존하고 있으며, 이 소프트웨어를 먼저 설치해야 한다(type _init_completion 을 실행하여 bash-completion이 이미 설치되어 있는지 확인할 수 있음).

bash-completion 설치

bash-completion은 많은 패키지 관리자에 의해 제공된다(여기 참고). apt-get install bash-completion 또는 yum install bash-completion 등으로 설치할 수 있다.

위의 명령은 bash-completion의 기본 스크립트인 /usr/share/bash-completion/bash_completion 을 생성한다. 패키지 관리자에 따라, ~/.bashrc 파일에서 이 파일을 수동으로 소스(source)해야 한다.

확인하려면, 셸을 다시 로드하고 type _init_completion 을 실행한다. 명령이 성공하면, 이미 설정된 상태이고, 그렇지 않으면 ~/.bashrc 파일에 다음을 추가한다.

source /usr/share/bash-completion/bash_completion

셸을 다시 로드하고 type _init_completion 을 입력하여 bash-completion이 올바르게 설치되었는지 확인한다.

kubectl 자동 완성 활성화

이제 kubectl 자동 완성 스크립트가 모든 셸 세션에서 제공되도록 해야 한다. 이를 수행할 수 있는 두 가지 방법이 있다.

  • ~/.bashrc 파일에서 자동 완성 스크립트를 소싱한다.

    echo 'source <(kubectl completion bash)' >>~/.bashrc

  • 자동 완성 스크립트를 /etc/bash_completion.d 디렉터리에 추가한다.

    kubectl completion bash >/etc/bash_completion.d/kubectl

kubectl에 대한 앨리어스(alias)가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -F __start_kubectl k' >>~/.bashrc
참고: bash-completion은 /etc/bash_completion.d 에 있는 모든 자동 완성 스크립트를 소싱한다.

두 방법 모두 동일하다. 셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

Zsh용 kubectl 자동 완성 스크립트는 kubectl completion zsh 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱하면 kubectl 자동 완성 기능이 활성화된다.

모든 셸 세션에서 사용하려면, ~/.zshrc 파일에 다음을 추가한다.

source <(kubectl completion zsh)

kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.zshrc
echo 'complete -F __start_kubectl k' >>~/.zshrc

셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

complete:13: command not found: compdef 와 같은 오류가 발생하면, ~/.zshrc 파일의 시작 부분에 다음을 추가한다.

autoload -Uz compinit
compinit

다음 내용

1.3 - 윈도우에 kubectl 설치 및 설정

시작하기 전에

클러스터의 마이너(minor) 버전 차이 내에 있는 kubectl 버전을 사용해야 한다. 예를 들어, v1.21 클라이언트는 v1.20, v1.21, v1.22의 컨트롤 플레인과 연동될 수 있다. 최신 버전의 kubectl을 사용하면 예기치 않은 문제를 피할 수 있다.

윈도우에 kubectl 설치

다음과 같은 방법으로 윈도우에 kubectl을 설치할 수 있다.

윈도우에서 curl을 사용하여 kubectl 바이너리 설치

  1. 최신 릴리스 v1.21.0를 다운로드한다.

    또는 curl 을 설치한 경우, 다음 명령을 사용한다.

    curl -LO https://dl.k8s.io/release/v1.21.0/bin/windows/amd64/kubectl.exe
    참고: 최신의 안정 버전(예: 스크립팅을 위한)을 찾으려면, https://dl.k8s.io/release/stable.txt를 참고한다.

  2. 바이너리를 검증한다. (선택 사항)

    kubectl 체크섬 파일을 다운로드한다.

    curl -LO https://dl.k8s.io/v1.21.0/bin/windows/amd64/kubectl.exe.sha256

    kubectl 바이너리를 체크섬 파일을 통해 검증한다.

    • 수동으로 CertUtil 의 출력과 다운로드한 체크섬 파일을 비교하기 위해서 커맨드 프롬프트를 사용한다.

      CertUtil -hashfile kubectl.exe SHA256
type kubectl.exe.sha256

    • -eq 연산자를 통해 True 또는 False 결과를 얻는 자동 검증을 위해서 PowerShell을 사용한다.

      $($(CertUtil -hashfile .\kubectl.exe SHA256)[1] -replace " ", "") -eq $(type .\kubectl.exe.sha256)

  3. 바이너리를 PATH 가 설정된 디렉터리에 추가한다.

  4. kubectl 의 버전이 다운로드한 버전과 같은지 확인한다.

    kubectl version --client
참고: 윈도우용 도커 데스크톱은 자체 버전의 kubectl 을 PATH 에 추가한다. 도커 데스크톱을 이전에 설치한 경우, 도커 데스크톱 설치 프로그램에서 추가한 PATH 항목 앞에 PATH 항목을 배치하거나 도커 데스크톱의 kubectl 을 제거해야 할 수도 있다.

Chocolatey 또는 Scoop을 사용하여 윈도우에 설치

  1. 윈도우에 kubectl을 설치하기 위해서 Chocolatey 패키지 관리자나 Scoop 커맨드 라인 설치 프로그램을 사용할 수 있다.

     choco install kubernetes-cli


     scoop install kubectl

  2. 설치한 버전이 최신 버전인지 확인한다.

    kubectl version --client

  3. 홈 디렉터리로 이동한다.

    # cmd.exe를 사용한다면, 다음을 실행한다. cd %USERPROFILE%
cd ~

  4. .kube 디렉터리를 생성한다.

    mkdir .kube

  5. 금방 생성한 .kube 디렉터리로 이동한다.

    cd .kube

  6. 원격 쿠버네티스 클러스터를 사용하도록 kubectl을 구성한다.

    New-Item config -type file
참고: 메모장과 같은 텍스트 편집기를 선택하여 구성 파일을 편집한다.

kubectl 구성 확인

kubectl이 쿠버네티스 클러스터를 찾아 접근하려면, kube-up.sh를 사용하여 클러스터를 생성하거나 Minikube 클러스터를 성공적으로 배포할 때 자동으로 생성되는 kubeconfig 파일이 필요하다. 기본적으로, kubectl 구성은 ~/.kube/config 에 있다.

클러스터 상태를 가져와서 kubectl이 올바르게 구성되어 있는지 확인한다.

kubectl cluster-info

URL 응답이 표시되면, kubectl이 클러스터에 접근하도록 올바르게 구성된 것이다.

다음과 비슷한 메시지가 표시되면, kubectl이 올바르게 구성되지 않았거나 쿠버네티스 클러스터에 연결할 수 없다.

The connection to the server <server-name:port> was refused - did you specify the right host or port?

예를 들어, 랩톱에서 로컬로 쿠버네티스 클러스터를 실행하려면, Minikube와 같은 도구를 먼저 설치한 다음 위에서 언급한 명령을 다시 실행해야 한다.

kubectl cluster-info가 URL 응답을 반환하지만 클러스터에 접근할 수 없는 경우, 올바르게 구성되었는지 확인하려면 다음을 사용한다.

kubectl cluster-info dump

선택적 kubectl 구성

셸 자동 완성 활성화

kubectl은 Bash 및 Zsh에 대한 자동 완성 지원을 제공하므로 입력을 위한 타이핑을 많이 절약할 수 있다.

다음은 Zsh에 대한 자동 완성을 설정하는 절차이다.

Zsh용 kubectl 자동 완성 스크립트는 kubectl completion zsh 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱하면 kubectl 자동 완성 기능이 활성화된다.

모든 셸 세션에서 사용하려면, ~/.zshrc 파일에 다음을 추가한다.

source <(kubectl completion zsh)

kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.zshrc
echo 'complete -F __start_kubectl k' >>~/.zshrc

셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

complete:13: command not found: compdef 와 같은 오류가 발생하면, ~/.zshrc 파일의 시작 부분에 다음을 추가한다.

autoload -Uz compinit
compinit

다음 내용

1.4 - 포함된 도구들

메인 kubectl-installs-*.md 페이지에 포함될 스니펫.

1.4.1 - kubectl 설치 검증하기

kubectl을 검증하는 방법에 대해 설명한다.

kubectl이 쿠버네티스 클러스터를 찾아 접근하려면, kube-up.sh를 사용하여 클러스터를 생성하거나 Minikube 클러스터를 성공적으로 배포할 때 자동으로 생성되는 kubeconfig 파일이 필요하다. 기본적으로, kubectl 구성은 ~/.kube/config 에 있다.

클러스터 상태를 가져와서 kubectl이 올바르게 구성되어 있는지 확인한다.

kubectl cluster-info

URL 응답이 표시되면, kubectl이 클러스터에 접근하도록 올바르게 구성된 것이다.

다음과 비슷한 메시지가 표시되면, kubectl이 올바르게 구성되지 않았거나 쿠버네티스 클러스터에 연결할 수 없다.

The connection to the server <server-name:port> was refused - did you specify the right host or port?

예를 들어, 랩톱에서 로컬로 쿠버네티스 클러스터를 실행하려면, Minikube와 같은 도구를 먼저 설치한 다음 위에서 언급한 명령을 다시 실행해야 한다.

kubectl cluster-info가 URL 응답을 반환하지만 클러스터에 접근할 수 없는 경우, 올바르게 구성되었는지 확인하려면 다음을 사용한다.

kubectl cluster-info dump

1.4.2 - macOS에서 bash 자동 완성 사용하기

macOS에서 bash 자동 완성을 위한 몇 가지 선택적 구성에 대해 설명한다.

소개

Bash의 kubectl 자동 완성 스크립트는 kubectl completion bash 로 생성할 수 있다. 이 스크립트를 셸에 소싱하면 kubectl 자동 완성이 가능하다.

그러나 kubectl 자동 완성 스크립트는 미리 bash-completion을 설치해야 동작한다.

경고: bash-completion에는 v1과 v2 두 가지 버전이 있다. v1은 Bash 3.2(macOS의 기본 설치 버전) 버전용이고, v2는 Bash 4.1 이상 버전용이다. kubectl 자동 완성 스크립트는 bash-completion v1과 Bash 3.2 버전에서는 작동하지 않는다. bash-completion v2 와 Bash 4.1 이상 버전 이 필요하다. 따라서, macOS에서 kubectl 자동 완성 기능을 올바르게 사용하려면, Bash 4.1 이상을 설치하고 사용해야 한다(지침). 다음의 내용에서는 Bash 4.1 이상(즉, 모든 Bash 버전 4.1 이상)을 사용한다고 가정한다.

Bash 업그레이드

여기의 지침에서는 Bash 4.1 이상을 사용한다고 가정한다. 다음을 실행하여 Bash 버전을 확인할 수 있다.

echo $BASH_VERSION

너무 오래된 버전인 경우, Homebrew를 사용하여 설치/업그레이드할 수 있다.

brew install bash

셸을 다시 로드하고 원하는 버전을 사용 중인지 확인한다.

echo $BASH_VERSION $SHELL

Homebrew는 보통 /usr/local/bin/bash 에 설치한다.

bash-completion 설치

참고: 언급한 바와 같이, 이 지침에서는 Bash 4.1 이상을 사용한다고 가정한다. 이는 bash-completion v2를 설치한다는 것을 의미한다(Bash 3.2 및 bash-completion v1의 경우, kubectl 자동 완성이 작동하지 않음).

bash-completion v2가 이미 설치되어 있는지 type_init_completion 으로 확인할 수 있다. 그렇지 않은 경우, Homebrew로 설치할 수 있다.

brew install bash-completion@2

이 명령의 출력에 명시된 바와 같이, ~/.bash_profile 파일에 다음을 추가한다.

export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

셸을 다시 로드하고 bash-completion v2가 올바르게 설치되었는지 type _init_completion 으로 확인한다.

kubectl 자동 완성 활성화

이제 kubectl 자동 완성 스크립트가 모든 셸 세션에서 제공되도록 해야 한다. 이를 수행하는 방법에는 여러 가지가 있다.

  • 자동 완성 스크립트를 ~/.bash_profile 파일에서 소싱한다.

    echo 'source <(kubectl completion bash)' >>~/.bash_profile

  • 자동 완성 스크립트를 /usr/local/etc/bash_completion.d 디렉터리에 추가한다.

    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

  • kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하기 위해 셸 자동 완성을 확장할 수 있다.

    echo 'alias k=kubectl' >>~/.bash_profile
echo 'complete -F __start_kubectl k' >>~/.bash_profile

  • Homebrew로 kubectl을 설치한 경우(여기의 설명을 참고), kubectl 자동 완성 스크립트가 이미 /usr/local/etc/bash_completion.d/kubectl 에 있을 것이다. 이 경우, 아무 것도 할 필요가 없다.

    참고: bash-completion v2의 Homebrew 설치는 BASH_COMPLETION_COMPAT_DIR 디렉터리의 모든 파일을 소싱하므로, 후자의 두 가지 방법이 적용된다.

어떤 경우든, 셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

1.4.3 - zsh 자동 완성

zsh 자동 완성을 위한 몇 가지 선택적 구성에 대해 설명한다.

Zsh용 kubectl 자동 완성 스크립트는 kubectl completion zsh 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱하면 kubectl 자동 완성 기능이 활성화된다.

모든 셸 세션에서 사용하려면, ~/.zshrc 파일에 다음을 추가한다.

source <(kubectl completion zsh)

kubectl에 대한 앨리어스가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.zshrc
echo 'complete -F __start_kubectl k' >>~/.zshrc

셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

complete:13: command not found: compdef 와 같은 오류가 발생하면, ~/.zshrc 파일의 시작 부분에 다음을 추가한다.

autoload -Uz compinit
compinit

1.4.4 - 다음 단계는 무엇인가?

kubectl을 설치한 다음 해야 하는 것에 대해 설명한다.

1.4.5 - 리눅스에서 bash 자동 완성 사용하기

리눅스에서 bash 자동 완성을 위한 몇 가지 선택적 구성에 대해 설명한다.

소개

Bash의 kubectl 자동 완성 스크립트는 kubectl completion bash 명령으로 생성할 수 있다. 셸에서 자동 완성 스크립트를 소싱(sourcing)하면 kubectl 자동 완성 기능이 활성화된다.

그러나, 자동 완성 스크립트는 bash-completion에 의존하고 있으며, 이 소프트웨어를 먼저 설치해야 한다(type _init_completion 을 실행하여 bash-completion이 이미 설치되어 있는지 확인할 수 있음).

bash-completion 설치

bash-completion은 많은 패키지 관리자에 의해 제공된다(여기 참고). apt-get install bash-completion 또는 yum install bash-completion 등으로 설치할 수 있다.

위의 명령은 bash-completion의 기본 스크립트인 /usr/share/bash-completion/bash_completion 을 생성한다. 패키지 관리자에 따라, ~/.bashrc 파일에서 이 파일을 수동으로 소스(source)해야 한다.

확인하려면, 셸을 다시 로드하고 type _init_completion 을 실행한다. 명령이 성공하면, 이미 설정된 상태이고, 그렇지 않으면 ~/.bashrc 파일에 다음을 추가한다.

source /usr/share/bash-completion/bash_completion

셸을 다시 로드하고 type _init_completion 을 입력하여 bash-completion이 올바르게 설치되었는지 확인한다.

kubectl 자동 완성 활성화

이제 kubectl 자동 완성 스크립트가 모든 셸 세션에서 제공되도록 해야 한다. 이를 수행할 수 있는 두 가지 방법이 있다.

  • ~/.bashrc 파일에서 자동 완성 스크립트를 소싱한다.

    echo 'source <(kubectl completion bash)' >>~/.bashrc

  • 자동 완성 스크립트를 /etc/bash_completion.d 디렉터리에 추가한다.

    kubectl completion bash >/etc/bash_completion.d/kubectl

kubectl에 대한 앨리어스(alias)가 있는 경우, 해당 앨리어스로 작업하도록 셸 자동 완성을 확장할 수 있다.

echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -F __start_kubectl k' >>~/.bashrc
참고: bash-completion은 /etc/bash_completion.d 에 있는 모든 자동 완성 스크립트를 소싱한다.

두 방법 모두 동일하다. 셸을 다시 로드하면, kubectl 자동 완성 기능이 작동할 것이다.

2 - 클러스터 운영

클러스터를 운영하기 위한 공통 태스크를 배운다.

2.1 - kubeadm으로 관리하기

2.1.1 - kubeadm을 사용한 인증서 관리

FEATURE STATE: Kubernetes v1.15 [stable]

kubeadm으로 생성된 클라이언트 인증서는 1년 후에 만료된다. 이 페이지는 kubeadm으로 인증서 갱신을 관리하는 방법을 설명한다.

시작하기 전에

쿠버네티스의 PKI 인증서와 요구 조건에 익숙해야 한다.

사용자 정의 인증서 사용

기본적으로, kubeadm은 클러스터를 실행하는 데 필요한 모든 인증서를 생성한다. 사용자는 자체 인증서를 제공하여 이 동작을 무시할 수 있다.

이렇게 하려면, --cert-dir 플래그 또는 kubeadm ClusterConfiguration 의 certificatesDir 필드에 지정된 디렉터리에 배치해야 한다. 기본적으로 /etc/kubernetes/pki 이다.

kubeadm init 을 실행하기 전에 지정된 인증서와 개인 키(private key) 쌍이 존재하면, kubeadm은 이를 덮어 쓰지 않는다. 이는 예를 들어, 기존 CA를 /etc/kubernetes/pki/ca.crt 와 /etc/kubernetes/pki/ca.key 에 복사할 수 있고, kubeadm은 이 CA를 사용하여 나머지 인증서에 서명한다는 걸 의미한다.

외부 CA 모드

ca.key 파일이 아닌 ca.crt 파일만 제공할 수도 있다(이는 다른 인증서 쌍이 아닌 루트 CA 파일에만 사용 가능함). 다른 모든 인증서와 kubeconfig 파일이 있으면, kubeadm은 이 조건을 인식하고 "외부 CA" 모드를 활성화한다. kubeadm은 디스크에 CA 키없이 진행한다.

대신, --controllers=csrsigner 사용하여 controller-manager를 독립적으로 실행하고 CA 인증서와 키를 가리킨다.

PKI 인증서와 요구 조건은 외부 CA를 사용하도록 클러스터 설정에 대한 지침을 포함한다.

인증서 만료 확인

check-expiration 하위 명령을 사용하여 인증서가 만료되는 시기를 확인할 수 있다.

kubeadm certs check-expiration

출력 결과는 다음과 비슷하다.

CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY   EXTERNALLY MANAGED
admin.conf                 Dec 30, 2020 23:36 UTC   364d                                    no
apiserver                  Dec 30, 2020 23:36 UTC   364d            ca                      no
apiserver-etcd-client      Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
apiserver-kubelet-client   Dec 30, 2020 23:36 UTC   364d            ca                      no
controller-manager.conf    Dec 30, 2020 23:36 UTC   364d                                    no
etcd-healthcheck-client    Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
etcd-peer                  Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
etcd-server                Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
front-proxy-client         Dec 30, 2020 23:36 UTC   364d            front-proxy-ca          no
scheduler.conf             Dec 30, 2020 23:36 UTC   364d                                    no

CERTIFICATE AUTHORITY   EXPIRES                  RESIDUAL TIME   EXTERNALLY MANAGED
ca                      Dec 28, 2029 23:36 UTC   9y              no
etcd-ca                 Dec 28, 2029 23:36 UTC   9y              no
front-proxy-ca          Dec 28, 2029 23:36 UTC   9y              no

이 명령은 /etc/kubernetes/pki 폴더의 클라이언트 인증서와 kubeadm이 사용하는 KUBECONFIG 파일(admin.conf, controller-manager.conf 및 scheduler.conf)에 포함된 클라이언트 인증서의 만료/잔여 기간을 표시한다.

또한, kubeadm은 인증서가 외부에서 관리되는지를 사용자에게 알린다. 이 경우 사용자는 수동으로 또는 다른 도구를 사용해서 인증서 갱신 관리를 해야 한다.

경고: kubeadm 은 외부 CA가 서명한 인증서를 관리할 수 없다.
참고: kubelet.conf 는 위 목록에 포함되어 있지 않은데, 이는 kubeadm이 자동 인증서 갱신을 위해 /var/lib/kubelet/pki에 있는 갱신 가능한 인증서를 이용하여 kubelet을 구성하기 때문이다. 만료된 kubelet 클라이언트 인증서를 갱신하려면 kubelet 클라이언트 갱신 실패 섹션을 확인한다.
경고:

kubeadm 1.17 이전의 버전에서 kubeadm init 으로 작성된 노드에는 kubelet.conf 의 내용을 수동으로 수정해야 하는 버그가 있다. kubeadm init 수행 완료 후, client-certificate-data 및 client-key-data 를 다음과 같이 교체하여, 로테이트된 kubelet 클라이언트 인증서를 가리키도록 kubelet.conf 를 업데이트해야 한다.

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

자동 인증서 갱신

kubeadm은 컨트롤 플레인 업그레이드 동안 모든 인증서를 갱신한다.

이 기능은 가장 간단한 유스케이스를 해결하기 위해 설계되었다. 인증서 갱신에 대해 특별한 요구 사항이 없고 쿠버네티스 버전 업그레이드를 정기적으로(매 1년 이내 업그레이드 수행) 수행하는 경우, kubeadm은 클러스터를 최신 상태로 유지하고 합리적으로 보안을 유지한다.

참고: 보안을 유지하려면 클러스터를 자주 업그레이드하는 것이 가장 좋다.

인증서 갱신에 대해 보다 복잡한 요구 사항이 있는 경우, --certificate-renewal=false 를 kubeadm upgrade apply 또는 kubeadm upgrade node 와 함께 사용하여 기본 동작이 수행되지 않도록 할 수 있다.

경고: kubeadm 1.17 이전 버전에는 kubeadm upgrade node 명령에서 --certificate-renewal 의 기본값이 false 인 버그가 있다. 이 경우 --certificate-renewal=true 를 명시적으로 설정해야 한다.

수동 인증서 갱신

kubeadm certs renew 명령을 사용하여 언제든지 인증서를 수동으로 갱신할 수 있다.

이 명령은 /etc/kubernetes/pki 에 저장된 CA(또는 프론트 프록시 CA) 인증서와 키를 사용하여 갱신을 수행한다.

경고: HA 클러스터를 실행 중인 경우, 모든 컨트롤 플레인 노드에서 이 명령을 실행해야 한다.
참고: certs renew 는 기존 인증서를 kubeadm-config 컨피그맵(ConfigMap) 대신 속성(공통 이름, 조직, SAN 등)의 신뢰할 수 있는 소스로 사용한다. 둘 다 동기화 상태를 유지하는 것을 강력히 권장한다.

kubeadm certs renew 는 다음의 옵션을 제공한다.

쿠버네티스 인증서는 일반적으로 1년 후 만료일에 도달한다.

  • --csr-only 는 실제로 인증서를 갱신하지 않고 인증서 서명 요청을 생성하여 외부 CA로 인증서를 갱신하는 데 사용할 수 있다. 자세한 내용은 다음 단락을 참고한다.

  • 모든 인증서 대신 단일 인증서를 갱신할 수도 있다.

쿠버네티스 인증서 API를 사용하여 인증서 갱신

이 섹션에서는 쿠버네티스 인증서 API를 사용하여 수동 인증서 갱신을 실행하는 방법에 대한 자세한 정보를 제공한다.

주의: 조직의 인증서 인프라를 kubeadm으로 생성된 클러스터에 통합해야 하는 사용자를 위한 고급 주제이다. 기본 kubeadm 구성이 요구 사항을 충족하면 kubeadm이 인증서를 대신 관리하도록 해야 한다.

서명자 설정

쿠버네티스 인증 기관(Certificate Authority)은 기본적으로 작동하지 않는다. cert-manager와 같은 외부 서명자를 설정하거나, 빌트인 서명자를 사용할 수 있다.

빌트인 서명자는 kube-controller-manager의 일부이다.

빌트인 서명자를 활성화하려면, --cluster-signing-cert-file 와 --cluster-signing-key-file 플래그를 전달해야 한다.

새 클러스터를 생성하는 경우, kubeadm 구성 파일을 사용할 수 있다.

apiVersion: kubeadm.k8s.io/v1beta2
kind: ClusterConfiguration
controllerManager:
  extraArgs:
    cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt
    cluster-signing-key-file: /etc/kubernetes/pki/ca.key

인증서 서명 요청(CSR) 생성

쿠버네티스 API로 CSR을 작성하려면 CertificateSigningRequest 생성을 본다.

외부 CA로 인증서 갱신

이 섹션에서는 외부 CA를 사용하여 수동 인증서 갱신을 실행하는 방법에 대한 자세한 정보를 제공한다.

외부 CA와 보다 효과적으로 통합하기 위해 kubeadm은 인증서 서명 요청(CSR)을 생성할 수도 있다. CSR은 클라이언트의 서명된 인증서에 대한 CA 요청을 나타낸다. kubeadm 관점에서, 일반적으로 온-디스크(on-disk) CA에 의해 서명되는 모든 인증서는 CSR로 생성될 수 있다. 그러나 CA는 CSR로 생성될 수 없다.

인증서 서명 요청(CSR) 생성

kubeadm certs renew --csr-only 로 인증서 서명 요청을 만들 수 있다.

CSR과 함께 제공되는 개인 키가 모두 출력된다. --csr-dir 로 사용할 디텍터리를 전달하여 지정된 위치로 CSR을 출력할 수 있다. --csr-dir 을 지정하지 않으면, 기본 인증서 디렉터리(/etc/kubernetes/pki)가 사용된다.

kubeadm certs renew --csr-only 로 인증서를 갱신할 수 있다. kubeadm init 과 마찬가지로 출력 디렉터리를 --csr-dir 플래그로 지정할 수 있다.

CSR에는 인증서 이름, 도메인 및 IP가 포함되지만, 용도를 지정하지는 않는다. 인증서를 발행할 때 올바른 인증서 용도를 지정하는 것은 CA의 책임이다.

선호하는 방법으로 인증서에 서명한 후, 인증서와 개인 키를 PKI 디렉터리(기본적으로 /etc/kubernetes/pki)에 복사해야 한다.

인증 기관(CA) 순환(rotation)

Kubeadm은 CA 인증서의 순환이나 교체 기능을 기본적으로 지원하지 않는다.

CA의 수동 순환이나 교체에 대한 보다 상세한 정보는 CA 인증서 수동 순환 문서를 참조한다.

서명된 kubelet 인증서 활성화하기

기본적으로 kubeadm에 의해서 배포된 kubelet 인증서는 자가 서명된(self-signed) 것이다. 이것은 metrics-server와 같은 외부 서비스의 kubelet에 대한 연결은 TLS로 보안되지 않음을 의미한다.

제대로 서명된 인증서를 얻기 위해서 신규 kubeadm 클러스터의 kubelet을 구성하려면 다음의 최소 구성을 kubeadm init 에 전달해야 한다.

apiVersion: kubeadm.k8s.io/v1beta2
kind: ClusterConfiguration
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
serverTLSBootstrap: true

만약 이미 클러스터를 생성했다면 다음을 따라 이를 조정해야 한다.

  • kube-system 네임스페이스에서 kubelet-config-1.21 컨피그맵을 찾아서 수정한다. 해당 컨피그맵에는 kubelet 키가 KubeletConfiguration 문서를 값으로 가진다. serverTLSBootstrap: true 가 되도록 KubeletConfiguration 문서를 수정한다.
  • 각 노드에서, serverTLSBootstrap: true 필드를 /var/lib/kubelet/config.yaml 에 추가한다. 그리고 systemctl restart kubelet 로 kubelet을 재시작한다.

serverTLSBootstrap: true 필드는 kubelet 인증서를 이용한 부트스트랩을 certificates.k8s.io API에 요청함으로써 활성화할 것이다. 한 가지 알려진 제약은 이 인증서들에 대한 CSR(인증서 서명 요청)들이 kube-controller-manager - kubernetes.io/kubelet-serving의 기본 서명자(default signer)에 의해서 자동으로 승인될 수 없다는 점이다. 이것은 사용자나 제 3의 컨트롤러의 액션을 필요로 할 것이다.

이 CSR들은 다음을 통해 볼 수 있다.

kubectl get csr
NAME        AGE     SIGNERNAME                        REQUESTOR                      CONDITION
csr-9wvgt   112s    kubernetes.io/kubelet-serving     system:node:worker-1           Pending
csr-lz97v   1m58s   kubernetes.io/kubelet-serving     system:node:control-plane-1    Pending

이를 승인하기 위해서는 다음을 수행한다.

kubectl certificate approve <CSR-name>

기본적으로, 이 인증서는 1년 후에 만기될 것이다. Kubeadm은 KubeletConfiguration 필드의 rotateCertificates 를 true 로 설정한다. 이것은 만기가 다가오면 인증서를 위한 신규 CSR 세트가 생성되는 것을 의미하며, 해당 순환(rotation)을 완료하기 위해서는 승인이 되어야 한다는 것을 의미한다. 더 상세한 이해를 위해서는 인증서 순환를 확인한다.

만약 이 CSR들의 자동 승인을 위한 솔루션을 찾고 있다면 클라우드 제공자와 연락하여 대역 외 메커니즘(out of band mechanism)을 통해 노드의 신분을 검증할 수 있는 CSR 서명자를 가지고 있는지 문의하는 것을 추천한다.

제 3 자 커스텀 컨트롤러도 사용될 수 있다.

이러한 컨트롤러는 CSR의 CommonName과 요청된 IPs 및 도메인 네임을 모두 검증하지 않는 한, 보안이 되는 메커니즘이 아니다. 이것을 통해 악의적 행위자가 kubelet 인증서(클라이언트 인증)를 사용하여 아무 IP나 도메인 네임에 대해 인증서를 요청하는 CSR의 생성을 방지할 수 있을 것이다.

2.1.2 - kubeadm 클러스터 업그레이드

이 페이지는 kubeadm으로 생성된 쿠버네티스 클러스터를 1.20.x 버전에서 1.21.x 버전으로, 1.21.x 버전에서 1.21.y(여기서 y > x) 버전으로 업그레이드하는 방법을 설명한다. 업그레이드가 지원되지 않는 경우 마이너 버전을 건너뛴다.

이전 버전의 kubeadm을 사용하여 생성된 클러스터 업그레이드에 대한 정보를 보려면, 이 페이지 대신 다음의 페이지들을 참고한다.

추상적인 업그레이드 작업 절차는 다음과 같다.

  1. 기본 컨트롤 플레인 노드를 업그레이드한다.
  2. 추가 컨트롤 플레인 노드를 업그레이드한다.
  3. 워커(worker) 노드를 업그레이드한다.

시작하기 전에

  • 릴리스 노트를 주의 깊게 읽어야 한다.
  • 클러스터는 정적 컨트롤 플레인 및 etcd 파드 또는 외부 etcd를 사용해야 한다.
  • 데이터베이스에 저장된 앱-레벨 상태와 같은 중요한 컴포넌트를 반드시 백업한다. kubeadm upgrade 는 워크로드에 영향을 미치지 않고, 쿠버네티스 내부의 컴포넌트만 다루지만, 백업은 항상 모범 사례일 정도로 중요하다.
  • 스왑을 비활성화해야 한다.

추가 정보

  • kubelet 마이너 버전을 업그레이드하기 전에 노드 드레이닝(draining)이 필요하다. 컨트롤 플레인 노드의 경우 CoreNDS 파드 또는 기타 중요한 워크로드를 실행할 수 있다.
  • 컨테이너 사양 해시 값이 변경되므로, 업그레이드 후 모든 컨테이너가 다시 시작된다.

업그레이드할 버전 결정

OS 패키지 관리자를 사용하여 최신의 안정 버전(1.21)을 찾는다.

apt update
apt-cache madison kubeadm
# 목록에서 최신 버전(1.21)을 찾는다
# 1.21.x-00과 같아야 한다. 여기서 x는 최신 패치이다.


yum list --showduplicates kubeadm --disableexcludes=kubernetes
# 목록에서 최신 버전(1.21)을 찾는다
# 1.21.x-0과 같아야 한다. 여기서 x는 최신 패치이다.

컨트롤 플레인 노드 업그레이드

컨트롤 플레인 노드의 업그레이드 절차는 한 번에 한 노드씩 실행해야 한다. 먼저 업그레이드할 컨트롤 플레인 노드를 선택한다. /etc/kubernetes/admin.conf 파일이 있어야 한다.

"kubeadm upgrade" 호출

첫 번째 컨트롤 플레인 노드의 경우

  • kubeadm 업그레이드

# 1.21.x-00에서 x를 최신 패치 버전으로 바꾼다.
apt-mark unhold kubeadm && \
apt-get update && apt-get install -y kubeadm=1.21.x-00 && \
apt-mark hold kubeadm
-
# apt-get 버전 1.1부터 다음 방법을 사용할 수도 있다
apt-get update && \
apt-get install -y --allow-change-held-packages kubeadm=1.21.x-00


# 1.21.x-0에서 x를 최신 패치 버전으로 바꾼다.
yum install -y kubeadm-1.21.x-0 --disableexcludes=kubernetes

  • 다운로드하려는 버전이 잘 받아졌는지 확인한다.

    kubeadm version

  • 업그레이드 계획을 확인한다.

    kubeadm upgrade plan

    이 명령은 클러스터를 업그레이드할 수 있는지를 확인하고, 업그레이드할 수 있는 버전을 가져온다. 또한 컴포넌트 구성 버전 상태가 있는 표를 보여준다.

참고: 또한 kubeadm upgrade 는 이 노드에서 관리하는 인증서를 자동으로 갱신한다. 인증서 갱신을 하지 않으려면 --certificate-renewal=false 플래그를 사용할 수 있다. 자세한 내용은 인증서 관리 가이드를 참고한다.
참고: kubeadm upgrade plan 이 수동 업그레이드가 필요한 컴포넌트 구성을 표시하는 경우, 사용자는 --config 커맨드 라인 플래그를 통해 대체 구성이 포함된 구성 파일을 kubeadm upgrade apply 에 제공해야 한다. 그렇게 하지 않으면 kubeadm upgrade apply 가 오류와 함께 종료되고 업그레이드를 수행하지 않는다.

  • 업그레이드할 버전을 선택하고, 적절한 명령을 실행한다. 예를 들면 다음과 같다.

    # 이 업그레이드를 위해 선택한 패치 버전으로 x를 바꾼다.
sudo kubeadm upgrade apply v1.21.x

    명령이 완료되면 다음을 확인해야 한다.

    [upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.21.x". Enjoy!

[upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.

  • CNI 제공자 플러그인을 수동으로 업그레이드한다.

    CNI(컨테이너 네트워크 인터페이스) 제공자는 자체 업그레이드 지침을 따를 수 있다. 애드온 페이지에서 사용하는 CNI 제공자를 찾고 추가 업그레이드 단계가 필요한지 여부를 확인한다.

    CNI 제공자가 데몬셋(DaemonSet)으로 실행되는 경우 추가 컨트롤 플레인 노드에는 이 단계가 필요하지 않다.

다른 컨트롤 플레인 노드의 경우

첫 번째 컨트롤 플레인 노드와 동일하지만 다음을 사용한다.

sudo kubeadm upgrade node

아래 명령 대신 위의 명령을 사용한다.

sudo kubeadm upgrade apply

kubeadm upgrade plan 을 호출하고 CNI 공급자 플러그인을 업그레이드할 필요가 없다.

노드 드레인

  • Prepare the node for maintenance by marking it unschedulable and evicting the workloads:

    # <node-to-drain>을 드레인하는 노드의 이름으로 바꾼다.
kubectl drain <node-to-drain> --ignore-daemonsets

kubelet과 kubectl 업그레이드

  • 모든 컨트롤 플레인 노드에서 kubelet 및 kubectl을 업그레이드한다.

>
    # 1.21.x-00의 x를 최신 패치 버전으로 바꾼다
    apt-mark unhold kubelet kubectl && \
    apt-get update && apt-get install -y kubelet=1.21.x-00 kubectl=1.21.x-00 && \
    apt-mark hold kubelet kubectl
    -
    # apt-get 버전 1.1부터 다음 방법을 사용할 수도 있다
    apt-get update && \
    apt-get install -y --allow-change-held-packages kubelet=1.21.x-00 kubectl=1.21.x-00
    

    # 1.21.x-0에서 x를 최신 패치 버전으로 바꾼다
    yum install -y kubelet-1.21.x-0 kubectl-1.21.x-0 --disableexcludes=kubernetes
  • kubelet을 다시 시작한다.
sudo systemctl daemon-reload
sudo systemctl restart kubelet

노드 uncordon

  • 노드를 스케줄 가능으로 표시하여 노드를 다시 온라인 상태로 전환한다.

    # <node-to-drain>을 드레인하는 노드의 이름으로 바꾼다.
kubectl uncordon <node-to-drain>

워커 노드 업그레이드

워커 노드의 업그레이드 절차는 워크로드를 실행하는 데 필요한 최소 용량을 보장하면서, 한 번에 하나의 노드 또는 한 번에 몇 개의 노드로 실행해야 한다.

kubeadm 업그레이드

  • 모든 워커 노드에서 kubeadm을 업그레이드한다.

# 1.21.x-00의 x를 최신 패치 버전으로 바꾼다
apt-mark unhold kubeadm && \
apt-get update && apt-get install -y kubeadm=1.21.x-00 && \
apt-mark hold kubeadm
-
# apt-get 버전 1.1부터 다음 방법을 사용할 수도 있다
apt-get update && \
apt-get install -y --allow-change-held-packages kubeadm=1.21.x-00


# 1.21.x-0에서 x를 최신 패치 버전으로 바꾼다
yum install -y kubeadm-1.21.x-0 --disableexcludes=kubernetes

"kubeadm upgrade" 호출

  • 워커 노드의 경우 로컬 kubelet 구성을 업그레이드한다.

    sudo kubeadm upgrade node

노드 드레인

  • 스케줄 불가능(unschedulable)으로 표시하고 워크로드를 축출하여 유지 보수할 노드를 준비한다.

    # <node-to-drain>을 드레이닝하려는 노드 이름으로 바꾼다.
kubectl drain <node-to-drain> --ignore-daemonsets

kubelet과 kubectl 업그레이드

  • kubelet 및 kubectl을 업그레이드한다.

# 1.21.x-00의 x를 최신 패치 버전으로 바꾼다
apt-mark unhold kubelet kubectl && \
apt-get update && apt-get install -y kubelet=1.21.x-00 kubectl=1.21.x-00 && \
apt-mark hold kubelet kubectl
-
# apt-get 버전 1.1부터 다음 방법을 사용할 수도 있다
apt-get update && \
apt-get install -y --allow-change-held-packages kubelet=1.21.x-00 kubectl=1.21.x-00


# 1.21.x-0에서 x를 최신 패치 버전으로 바꾼다
yum install -y kubelet-1.21.x-0 kubectl-1.21.x-0 --disableexcludes=kubernetes

  • kubelet을 다시 시작한다.

    sudo systemctl daemon-reload
sudo systemctl restart kubelet

노드에 적용된 cordon 해제

  • 스케줄 가능(schedulable)으로 표시하여 노드를 다시 온라인 상태로 만든다.

    # <node-to-drain>을 노드의 이름으로 바꾼다.
kubectl uncordon <node-to-drain>

클러스터 상태 확인

모든 노드에서 kubelet을 업그레이드한 후 kubectl이 클러스터에 접근할 수 있는 곳에서 다음의 명령을 실행하여 모든 노드를 다시 사용할 수 있는지 확인한다.

kubectl get nodes

모든 노드에 대해 STATUS 열에 Ready 가 표시되어야 하고, 버전 번호가 업데이트되어 있어야 한다.

장애 상태에서의 복구

예를 들어 kubeadm upgrade 를 실행하는 중에 예기치 못한 종료로 인해 업그레이드가 실패하고 롤백하지 않는다면, kubeadm upgrade 를 다시 실행할 수 있다. 이 명령은 멱등성을 보장하며 결국 실제 상태가 선언한 의도한 상태인지 확인한다.

잘못된 상태에서 복구하기 위해, 클러스터가 실행 중인 버전을 변경하지 않고 kubeadm upgrade apply --force 를 실행할 수도 있다.

업그레이드하는 동안 kubeadm은 /etc/kubernetes/tmp 아래에 다음과 같은 백업 폴더를 작성한다.

  • kubeadm-backup-etcd-<date>-<time>
  • kubeadm-backup-manifests-<date>-<time>

kubeadm-backup-etcd 는 컨트롤 플레인 노드에 대한 로컬 etcd 멤버 데이터의 백업을 포함한다. etcd 업그레이드가 실패하고 자동 롤백이 작동하지 않으면, 이 폴더의 내용을 /var/lib/etcd 에서 수동으로 복원할 수 있다. 외부 etcd를 사용하는 경우 이 백업 폴더는 비어있다.

kubeadm-backup-manifests 는 컨트롤 플레인 노드에 대한 정적 파드 매니페스트 파일의 백업을 포함한다. 업그레이드가 실패하고 자동 롤백이 작동하지 않으면, 이 폴더의 내용을 /etc/kubernetes/manifests 에서 수동으로 복원할 수 있다. 어떤 이유로 특정 컴포넌트의 업그레이드 전 매니페스트 파일과 업그레이드 후 매니페스트 파일 간에 차이가 없는 경우, 백업 파일은 기록되지 않는다.

작동 원리

kubeadm upgrade apply 는 다음을 수행한다.

  • 클러스터가 업그레이드 가능한 상태인지 확인한다.
    • API 서버에 접근할 수 있다
    • 모든 노드가 Ready 상태에 있다
    • 컨트롤 플레인이 정상적으로 동작한다
  • 버전 차이(skew) 정책을 적용한다.
  • 컨트롤 플레인 이미지가 사용 가능한지 또는 머신으로 가져올 수 있는지 확인한다.
  • 컴포넌트 구성에 버전 업그레이드가 필요한 경우 대체 구성을 생성하거나 사용자가 제공한 것으로 덮어 쓰기한다.
  • 컨트롤 플레인 컴포넌트 또는 롤백 중 하나라도 나타나지 않으면 업그레이드한다.
  • 새로운 CoreDNS 와 kube-proxy 매니페스트를 적용하고 필요한 모든 RBAC 규칙이 생성되도록 한다.
  • API 서버의 새 인증서와 키 파일을 작성하고 180일 후에 만료될 경우 이전 파일을 백업한다.

kubeadm upgrade node 는 추가 컨트롤 플레인 노드에서 다음을 수행한다.

  • 클러스터에서 kubeadm ClusterConfiguration 을 가져온다.
  • 선택적으로 kube-apiserver 인증서를 백업한다.
  • 컨트롤 플레인 컴포넌트에 대한 정적 파드 매니페스트를 업그레이드한다.
  • 이 노드의 kubelet 구성을 업그레이드한다.

kubeadm upgrade node 는 워커 노드에서 다음을 수행한다.

  • 클러스터에서 kubeadm ClusterConfiguration 을 가져온다.
  • 이 노드의 kubelet 구성을 업그레이드한다.

2.1.3 - 윈도우 노드 추가

FEATURE STATE: Kubernetes v1.18 [beta]

쿠버네티스를 사용하여 리눅스와 윈도우 노드를 혼합하여 실행할 수 있으므로, 리눅스에서 실행되는 파드와 윈도우에서 실행되는 파드를 혼합할 수 있다. 이 페이지는 윈도우 노드를 클러스터에 등록하는 방법을 보여준다.

시작하기 전에

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: 1.17. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

목적

  • 클러스터에 윈도우 노드 등록
  • 리눅스 및 윈도우의 파드와 서비스가 서로 통신할 수 있도록 네트워킹 구성

시작하기: 클러스터에 윈도우 노드 추가

네트워킹 구성

리눅스 기반 쿠버네티스 컨트롤 플레인 노드가 있으면 네트워킹 솔루션을 선택할 수 있다. 이 가이드는 VXLAN 모드의 플란넬(Flannel)을 사용하는 방법을 짧막하게 보여준다.

플란넬 구성

  1. 플란넬을 위한 쿠버네티스 컨트롤 플레인 준비

    클러스터의 쿠버네티스 컨트롤 플레인에서 약간의 준비가 필요하다. 플란넬을 사용할 때 iptables 체인에 브릿지된 IPv4 트래픽을 활성화하는 것을 권장한다. 아래 명령을 모든 리눅스 노드에서 실행해야만 한다.

    sudo sysctl net.bridge.bridge-nf-call-iptables=1

  2. 리눅스용 플란넬 다운로드 및 구성

    가장 최근의 플란넬 매니페스트를 다운로드한다.

    wget https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

    VNI를 4096으로 설정하고 포트를 4789로 설정하려면 플란넬 매니페스트의 net-conf.json 섹션을 수정한다. 다음과 같을 것이다.

    net-conf.json: |
    {
      "Network": "10.244.0.0/16",
      "Backend": {
        "Type": "vxlan",
        "VNI": 4096,
        "Port": 4789
      }
    }
    참고: 리눅스의 플란넬이 윈도우의 플란넬과 상호 운용되도록 하려면 VNI를 4096으로, 포트를 4789로 설정해야 한다. 이 필드들에 대한 설명은 VXLAN 문서를 참고한다.
    참고: L2Bridge/Host-gateway 모드를 대신 사용하려면 Type 의 값을 "host-gw" 로 변경하고 VNI 와 Port 를 생략한다.

  3. 플란넬 매니페스트 적용 및 유효성 검사

    플란넬 구성을 적용해보자.

    kubectl apply -f kube-flannel.yml

    몇 분 후에, 플란넬 파드 네트워크가 배포되었다면 모든 파드가 실행 중인 것으로 표시된다.

    kubectl get pods -n kube-system

    출력 결과에 리눅스 flannel 데몬셋(DaemonSet)이 실행 중인 것으로 나와야 한다.

    NAMESPACE     NAME                                      READY        STATUS    RESTARTS   AGE
...
kube-system   kube-flannel-ds-54954                     1/1          Running   0          1m

  4. 윈도우 플란넬 및 kube-proxy 데몬셋 추가

    이제 윈도우 호환 버전의 플란넬과 kube-proxy를 추가할 수 있다. 호환 가능한 kube-proxy 버전을 얻으려면, 이미지의 태그를 대체해야 한다. 다음의 예시는 쿠버네티스 v1.21.0의 사용법을 보여주지만, 사용자의 배포에 맞게 버전을 조정해야 한다.

    curl -L https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/kube-proxy.yml | sed 's/VERSION/v1.21.0/g' | kubectl apply -f -
kubectl apply -f https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/flannel-overlay.yml
    참고: host-gateway를 사용하는 경우 https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/flannel-host-gw.yml 을 대신 사용한다.
    참고:

    윈도우 노드에서 이더넷이 아닌 다른 인터페이스(예: "Ethernet0 2")를 사용하는 경우, flannel-host-gw.yml이나 flannel-overlay.yml 파일에서 다음 라인을 수정한다.

    wins cli process run --path /k/flannel/setup.exe --args "--mode=overlay --interface=Ethernet"

    그리고, 이에 따라 인터페이스를 지정해야 한다.

    # 예시
curl -L https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/flannel-overlay.yml | sed 's/Ethernet/Ethernet0 2/g' | kubectl apply -f -

윈도우 워커 노드 조인(joining)

참고: 윈도우 섹션의 모든 코드 스니펫(snippet)은 윈도우 워커 노드의 높은 권한(관리자)이 있는 PowerShell 환경에서 실행해야 한다.

Docker EE 설치

컨테이너 기능 설치

Install-WindowsFeature -Name containers

도커 설치 자세한 내용은 도커 엔진 설치 - 윈도우 서버 엔터프라이즈에서 확인할 수 있다.

wins, kubelet 및 kubeadm 설치

curl.exe -LO https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/PrepareNode.ps1
.\PrepareNode.ps1 -KubernetesVersion v1.21.0

kubeadm 실행하여 노드에 조인

컨트롤 플레인 호스트에서 kubeadm init 실행할 때 제공된 명령을 사용한다. 이 명령이 더 이상 없거나, 토큰이 만료된 경우, kubeadm token create --print-join-command (컨트롤 플레인 호스트에서)를 실행하여 새 토큰 및 조인 명령을 생성할 수 있다.

containerD 설치

curl.exe -LO https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/Install-Containerd.ps1
.\Install-Containerd.ps1
참고:

특정 버전의 containerD를 설치하려면 -ContainerDVersion를 사용하여 버전을 지정한다.

# 예
.\Install-Containerd.ps1 -ContainerDVersion 1.4.1
참고:

윈도우 노드에서 이더넷(예: "Ethernet0 2")이 아닌 다른 인터페이스를 사용하는 경우, -netAdapterName 으로 이름을 지정한다.

# 예
.\Install-Containerd.ps1 -netAdapterName "Ethernet0 2"

wins, kubelet 및 kubeadm 설치

curl.exe -LO https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/PrepareNode.ps1
.\PrepareNode.ps1 -KubernetesVersion v1.21.0 -ContainerRuntime containerD

kubeadm 실행하여 노드에 조인

컨트롤 플레인 호스트에서 `kubeadm init` 실행할 때 제공된 명령을 사용한다.
이 명령이 더 이상 없거나, 토큰이 만료된 경우, `kubeadm token create --print-join-command`
(컨트롤 플레인 호스트에서)를 실행하여 새 토큰 및 조인 명령을 생성할 수 있다.
참고: CRI-containerD 를 사용하는 경우 kubeadm 호출에 --cri-socket "npipe:////./pipe/containerd-containerd" 를 추가한다

설치 확인

이제 다음을 실행하여 클러스터에서 윈도우 노드를 볼 수 있다.

kubectl get nodes -o wide

새 노드가 NotReady 상태인 경우 플란넬 이미지가 여전히 다운로드 중일 수 있다. kube-system 네임스페이스에서 flannel 파드를 확인하여 이전과 같이 진행 상황을 확인할 수 있다.

kubectl -n kube-system get pods -l app=flannel

flannel 파드가 실행되면, 노드는 Ready 상태가 되고 워크로드를 처리할 수 있어야 한다.

다음 내용

2.1.4 - 윈도우 노드 업그레이드

FEATURE STATE: Kubernetes v1.18 [beta]

이 페이지는 kubeadm으로 생성된 윈도우 노드를 업그레이드하는 방법을 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: 1.17. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

워커 노드 업그레이드

kubeadm 업그레이드

  1. 윈도우 노드에서, kubeadm을 업그레이드한다.

    # replace v1.21.0 with your desired version
curl.exe -Lo C:\k\kubeadm.exe https://dl.k8s.io/v1.21.0/bin/windows/amd64/kubeadm.exe

노드 드레인

  1. 쿠버네티스 API에 접근할 수 있는 머신에서, 스케줄 불가능한 것으로 표시하고 워크로드를 축출하여 유지 보수할 노드를 준비한다.

    # <node-to-drain>을 드레이닝하려는 노드 이름으로 바꾼다
kubectl drain <node-to-drain> --ignore-daemonsets

    다음과 비슷한 출력이 표시되어야 한다.

    node/ip-172-31-85-18 cordoned
node/ip-172-31-85-18 drained

kubelet 구성 업그레이드

  1. 윈도우 노드에서, 다음의 명령을 호출하여 새 kubelet 구성을 동기화한다.

    kubeadm upgrade node

kubelet 업그레이드

  1. 윈도우 노드에서, kubelet을 업그레이드하고 다시 시작한다.

    stop-service kubelet
curl.exe -Lo C:\k\kubelet.exe https://dl.k8s.io/v1.21.0/bin/windows/amd64/kubelet.exe
restart-service kubelet

노드에 적용된 cordon 해제

  1. 쿠버네티스 API에 접근할 수 있는 머신에서, 스케줄 가능으로 표시하여 노드를 다시 온라인으로 가져온다.

    # <node-to-drain>을 노드의 이름으로 바꾼다
kubectl uncordon <node-to-drain>

kube-proxy 업그레이드

  1. 쿠버네티스 API에 접근할 수 있는 머신에서, 다음을 실행하여, v1.21.0을 원하는 버전으로 다시 바꾼다.

    curl -L https://github.com/kubernetes-sigs/sig-windows-tools/releases/latest/download/kube-proxy.yml | sed 's/VERSION/v1.21.0/g' | kubectl apply -f -

2.2 - 메모리, CPU 와 API 리소스 관리

2.2.1 - 네임스페이스에 대한 기본 메모리 요청량과 상한 구성

이 페이지는 네임스페이스에 대한 기본 메모리 요청량(request)과 상한(limit)을 구성하는 방법을 보여준다. 기본 메모리 상한이 있는 네임스페이스에서 컨테이너가 생성되고, 컨테이너가 자체 메모리 상한을 지정하지 않으면, 컨테이너에 기본 메모리 상한이 할당된다. 쿠버네티스는 이 문서의 뒷부분에서 설명하는 특정 조건에서 기본 메모리 요청량을 할당한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

클러스터의 각 노드에는 최소 2GiB의 메모리가 있어야 한다.

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 다른 리소스와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace default-mem-example

리밋레인지(LimitRange)와 파드 생성

다음은 리밋레인지 오브젝트의 구성 파일이다. 구성은 메모리 요청량 기본값(default)과 메모리 상한 기본값을 지정한다.

admin/resource/memory-defaults.yaml 
apiVersion: v1
kind: LimitRange
metadata:
  name: mem-limit-range
spec:
  limits:
  - default:
      memory: 512Mi
    defaultRequest:
      memory: 256Mi
    type: Container

default-mem-example 네임스페이스에 리밋레인지를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-defaults.yaml --namespace=default-mem-example

이제 컨테이너가 default-mem-example 네임스페이스에 생성되고, 컨테이너가 메모리 요청량 및 메모리 상한에 대해 고유한 값을 지정하지 않으면, 컨테이너에 메모리 요청량 기본값 256MiB와 메모리 상한 기본값 512MiB가 지정된다.

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 메모리 요청량 및 상한을 지정하지 않는다.

admin/resource/memory-defaults-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-mem-demo
spec:
  containers:
  - name: default-mem-demo-ctr
    image: nginx

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-defaults-pod.yaml --namespace=default-mem-example

파드에 대한 자세한 정보를 본다.

kubectl get pod default-mem-demo --output=yaml --namespace=default-mem-example

출력 결과는 파드의 컨테이너에 256MiB의 메모리 요청량과 512MiB의 메모리 상한이 있음을 나타낸다. 이것은 리밋레인지에 의해 지정된 기본값이다.

containers:
- image: nginx
  imagePullPolicy: Always
  name: default-mem-demo-ctr
  resources:
    limits:
      memory: 512Mi
    requests:
      memory: 256Mi

파드를 삭제한다.

kubectl delete pod default-mem-demo --namespace=default-mem-example

컨테이너 상한은 지정하고, 요청량을 지정하지 않으면 어떻게 되나?

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 메모리 상한을 지정하지만, 요청량은 지정하지 않는다.

admin/resource/memory-defaults-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-mem-demo-2
spec:
  containers:
  - name: default-mem-demo-2-ctr
    image: nginx
    resources:
      limits:
        memory: "1Gi"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-defaults-pod-2.yaml --namespace=default-mem-example

파드에 대한 자세한 정보를 본다.

kubectl get pod default-mem-demo-2 --output=yaml --namespace=default-mem-example

출력 결과는 컨테이너의 메모리 요청량이 메모리 상한과 일치하도록 설정되었음을 보여준다. 참고로 컨테이너에는 기본 메모리 요청량의 값인 256Mi가 할당되지 않았다.

resources:
  limits:
    memory: 1Gi
  requests:
    memory: 1Gi

컨테이너의 요청량은 지정하고, 상한을 지정하지 않으면 어떻게 되나?

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 메모리 요청량을 지정하지만, 상한은 지정하지 않았다.

admin/resource/memory-defaults-pod-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-mem-demo-3
spec:
  containers:
  - name: default-mem-demo-3-ctr
    image: nginx
    resources:
      requests:
        memory: "128Mi"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-defaults-pod-3.yaml --namespace=default-mem-example

파드 사양을 확인한다.

kubectl get pod default-mem-demo-3 --output=yaml --namespace=default-mem-example

출력 결과는 컨테이너의 메모리 요청량이 컨테이너의 구성 파일에 지정된 값으로 설정되었음을 보여준다. 컨테이너의 메모리 상한은 네임스페이스의 기본 메모리 상한인 512Mi로 설정되어 있다.

resources:
  limits:
    memory: 512Mi
  requests:
    memory: 128Mi

기본 메모리 상한 및 요청량에 대한 동기

네임스페이스에 리소스 쿼터가 있는 경우, 메모리 상한에 기본값을 설정하는 것이 좋다. 다음은 리소스 쿼터가 네임스페이스에 적용하는 두 가지 제한 사항이다.

  • 네임스페이스에서 실행되는 모든 컨테이너에는 자체 메모리 상한이 있어야 한다.
  • 네임스페이스의 모든 컨테이너가 사용하는 총 메모리 양은 지정된 상한을 초과하지 않아야 한다.

컨테이너가 자체 메모리 상한을 지정하지 않으면, 기본 상한이 부여되고, 쿼터에 의해 제한되는 네임스페이스에서 실행될 수 있다.

정리

네임스페이스를 삭제한다.

kubectl delete namespace default-mem-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.2.2 - 네임스페이스에 대한 기본 CPU 요청량과 상한 구성

이 페이지는 네임스페이스에 대한 기본 CPU 요청량(request) 및 상한(limit)을 구성하는 방법을 보여준다. 쿠버네티스 클러스터는 네임스페이스로 나눌 수 있다. 기본 CPU 상한이 있는 네임스페이스에서 컨테이너가 생성되고, 컨테이너가 자체 CPU 상한을 지정하지 않으면, 컨테이너에 기본 CPU 상한이 할당된다. 쿠버네티스는 이 문서의 뒷부분에서 설명하는 특정 조건에서 기본 CPU 요청량을 할당한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace default-cpu-example

리밋레인지(LimitRange)와 파드 생성

다음은 리밋레인지 오브젝트의 구성 파일이다. 구성은 기본 CPU 요청량 및 기본 CPU 상한을 지정한다.

admin/resource/cpu-defaults.yaml 
apiVersion: v1
kind: LimitRange
metadata:
  name: cpu-limit-range
spec:
  limits:
  - default:
      cpu: 1
    defaultRequest:
      cpu: 0.5
    type: Container

default-cpu-example 네임스페이스에 리밋레인지를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults.yaml --namespace=default-cpu-example

이제 컨테이너가 default-cpu-example 네임스페이스에 생성되고, 컨테이너가 CPU 요청량 및 CPU 상한에 대해 고유한 값을 지정하지 않으면, 컨테이너에 CPU 요청량의 기본값 0.5와 CPU 상한 기본값 1이 부여된다.

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 CPU 요청량과 상한을 지정하지 않는다.

admin/resource/cpu-defaults-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-cpu-demo
spec:
  containers:
  - name: default-cpu-demo-ctr
    image: nginx

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults-pod.yaml --namespace=default-cpu-example

파드의 사양을 확인한다.

kubectl get pod default-cpu-demo --output=yaml --namespace=default-cpu-example

출력 결과는 파드의 컨테이너에 500 milicpu의 CPU 요청량과 1 cpu의 CPU 상한이 있음을 나타낸다. 이것은 리밋레인지에 의해 지정된 기본값이다.

containers:
- image: nginx
  imagePullPolicy: Always
  name: default-cpu-demo-ctr
  resources:
    limits:
      cpu: "1"
    requests:
      cpu: 500m

컨테이너 상한은 지정하고, 요청량을 지정하지 않으면 어떻게 되나?

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 CPU 상한을 지정하지만, 요청량은 지정하지 않는다.

admin/resource/cpu-defaults-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-cpu-demo-2
spec:
  containers:
  - name: default-cpu-demo-2-ctr
    image: nginx
    resources:
      limits:
        cpu: "1"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults-pod-2.yaml --namespace=default-cpu-example

파드 사양을 확인한다.

kubectl get pod default-cpu-demo-2 --output=yaml --namespace=default-cpu-example

출력 결과는 컨테이너의 CPU 요청량이 CPU 상한과 일치하도록 설정되었음을 보여준다. 참고로 컨테이너에는 CPU 요청량의 기본값인 0.5 cpu가 할당되지 않았다.

resources:
  limits:
    cpu: "1"
  requests:
    cpu: "1"

컨테이너의 요청량은 지정하고, 상한을 지정하지 않으면 어떻게 되나?

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 CPU 요청량을 지정하지만, 상한은 지정하지 않았다.

admin/resource/cpu-defaults-pod-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: default-cpu-demo-3
spec:
  containers:
  - name: default-cpu-demo-3-ctr
    image: nginx
    resources:
      requests:
        cpu: "0.75"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults-pod-3.yaml --namespace=default-cpu-example

파드 사양을 확인한다.

kubectl get pod default-cpu-demo-3 --output=yaml --namespace=default-cpu-example

출력 결과는 컨테이너의 CPU 요청량이 컨테이너의 구성 파일에 지정된 값으로 설정되었음을 보여준다. 컨테이너의 CPU 상한은 1 cpu로 설정되며, 이는 네임스페이스의 CPU 상한 기본값이다.

resources:
  limits:
    cpu: "1"
  requests:
    cpu: 750m

CPU 상한 및 요청량의 기본값에 대한 동기

네임스페이스에 리소스 쿼터가 있는 경우, CPU 상한에 대해 기본값을 설정하는 것이 좋다. 다음은 리소스 쿼터가 네임스페이스에 적용하는 두 가지 제한 사항이다.

  • 네임스페이스에서 실행되는 모든 컨테이너에는 자체 CPU 상한이 있어야 한다.
  • 네임스페이스의 모든 컨테이너가 사용하는 총 CPU 양은 지정된 상한을 초과하지 않아야 한다.

컨테이너가 자체 CPU 상한을 지정하지 않으면, 상한 기본값이 부여되고, 쿼터에 의해 제한되는 네임스페이스에서 실행될 수 있다.

정리

네임스페이스를 삭제한다.

kubectl delete namespace default-cpu-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.2.3 - 네임스페이스에 대한 메모리의 최소 및 최대 제약 조건 구성

이 페이지는 네임스페이스에서 실행되는 컨테이너가 사용하는 메모리의 최솟값과 최댓값을 설정하는 방법을 보여준다. 리밋레인지(LimitRange) 오브젝트에 최소 및 최대 메모리 값을 지정한다. 파드가 리밋레인지에 의해 부과된 제약 조건을 충족하지 않으면, 네임스페이스에서 생성될 수 없다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

클러스터의 각 노드에는 최소 1GiB의 메모리가 있어야 한다.

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace constraints-mem-example

리밋레인지와 파드 생성

다음은 리밋레인지의 구성 파일이다.

admin/resource/memory-constraints.yaml 
apiVersion: v1
kind: LimitRange
metadata:
  name: mem-min-max-demo-lr
spec:
  limits:
  - max:
      memory: 1Gi
    min:
      memory: 500Mi
    type: Container

리밋레인지를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints.yaml --namespace=constraints-mem-example

리밋레인지에 대한 자세한 정보를 본다.

kubectl get limitrange mem-min-max-demo-lr --namespace=constraints-mem-example --output=yaml

출력 결과는 예상대로 메모리의 최소 및 최대 제약 조건을 보여준다. 그러나 참고로 리밋레인지의 구성 파일에 기본값(default)을 지정하지 않아도 자동으로 생성된다.

  limits:
  - default:
      memory: 1Gi
    defaultRequest:
      memory: 1Gi
    max:
      memory: 1Gi
    min:
      memory: 500Mi
    type: Container

이제 constraints-mem-example 네임스페이스에 컨테이너가 생성될 때마다, 쿠버네티스는 다음 단계를 수행한다.

  • 컨테이너가 자체 메모리 요청량(request)과 상한(limit)을 지정하지 않으면, 기본 메모리 요청량과 상한을 컨테이너에 지정한다.

  • 컨테이너에 500MiB 이상의 메모리 요청량이 있는지 확인한다.

  • 컨테이너의 메모리 상한이 1GiB 이하인지 확인한다.

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너 매니페스트는 600MiB의 메모리 요청량과 800MiB의 메모리 상한을 지정한다. 이들은 리밋레인지에 의해 부과된 메모리의 최소 및 최대 제약 조건을 충족한다.

admin/resource/memory-constraints-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-mem-demo
spec:
  containers:
  - name: constraints-mem-demo-ctr
    image: nginx
    resources:
      limits:
        memory: "800Mi"
      requests:
        memory: "600Mi"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod.yaml --namespace=constraints-mem-example

파드의 컨테이너가 실행 중인지 확인한다.

kubectl get pod constraints-mem-demo --namespace=constraints-mem-example

파드에 대한 자세한 정보를 본다.

kubectl get pod constraints-mem-demo --output=yaml --namespace=constraints-mem-example

출력 결과는 컨테이너의 메모리 요청량이 600MiB이고 메모리 상한이 800MiB임을 나타낸다. 이는 리밋레인지에 의해 부과된 제약 조건을 충족한다.

resources:
  limits:
     memory: 800Mi
  requests:
    memory: 600Mi

파드를 삭제한다.

kubectl delete pod constraints-mem-demo --namespace=constraints-mem-example

최대 메모리 제약 조건을 초과하는 파드 생성 시도

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 800MiB의 메모리 요청량과 1.5GiB의 메모리 상한을 지정한다.

admin/resource/memory-constraints-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-mem-demo-2
spec:
  containers:
  - name: constraints-mem-demo-2-ctr
    image: nginx
    resources:
      limits:
        memory: "1.5Gi"
      requests:
        memory: "800Mi"

파드 생성을 시도한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-2.yaml --namespace=constraints-mem-example

컨테이너가 너무 큰 메모리 상한을 지정하므로, 출력 결과에 파드가 생성되지 않은 것으로 표시된다.

Error from server (Forbidden): error when creating "examples/admin/resource/memory-constraints-pod-2.yaml":
pods "constraints-mem-demo-2" is forbidden: maximum memory usage per Container is 1Gi, but limit is 1536Mi.

최소 메모리 요청량을 충족하지 않는 파드 생성 시도

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 100MiB의 메모리 요청량과 800MiB의 메모리 상한을 지정한다.

admin/resource/memory-constraints-pod-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-mem-demo-3
spec:
  containers:
  - name: constraints-mem-demo-3-ctr
    image: nginx
    resources:
      limits:
        memory: "800Mi"
      requests:
        memory: "100Mi"

파드 생성을 시도한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-3.yaml --namespace=constraints-mem-example

컨테이너가 너무 작은 메모리 요청량을 지정하므로, 출력 결과에 파드가 생성되지 않은 것으로 표시된다.

Error from server (Forbidden): error when creating "examples/admin/resource/memory-constraints-pod-3.yaml":
pods "constraints-mem-demo-3" is forbidden: minimum memory usage per Container is 500Mi, but request is 100Mi.

메모리 요청량 또는 상한을 지정하지 않은 파드 생성

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 메모리 요청량을 지정하지 않으며, 메모리 상한을 지정하지 않는다.

admin/resource/memory-constraints-pod-4.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-mem-demo-4
spec:
  containers:
  - name: constraints-mem-demo-4-ctr
    image: nginx

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-4.yaml --namespace=constraints-mem-example

파드에 대한 자세한 정보를 본다.

kubectl get pod constraints-mem-demo-4 --namespace=constraints-mem-example --output=yaml

출력 결과는 파드의 컨테이너에 1GiB의 메모리 요청량과 1GiB의 메모리 상한이 있음을 보여준다. 컨테이너는 이러한 값을 어떻게 얻었을까?

resources:
  limits:
    memory: 1Gi
  requests:
    memory: 1Gi

컨테이너가 자체 메모리 요청량과 상한을 지정하지 않았으므로, 리밋레인지의 메모리의 요청량과 상한 기본값이 제공되었다.

이 시점에서, 컨테이너가 실행 중이거나 실행 중이 아닐 수 있다. 이 태스크의 전제 조건은 노드에 최소 1GiB의 메모리가 있어야 한다는 것이다. 각 노드에 1GiB의 메모리만 있는 경우, 노드에 할당할 수 있는 메모리가 1GiB의 메모리 요청량을 수용하기에 충분하지 않을 수 있다. 메모리가 2GiB인 노드를 사용하는 경우에는, 메모리가 1GiB 요청량을 수용하기에 충분할 것이다.

파드를 삭제한다.

kubectl delete pod constraints-mem-demo-4 --namespace=constraints-mem-example

메모리의 최소 및 최대 제약 조건 적용

리밋레인지에 의해 네임스페이스에 부과된 메모리의 최대 및 최소 제약 조건은 파드를 생성하거나 업데이트할 때만 적용된다. 리밋레인지를 변경해도, 이전에 생성된 파드에는 영향을 미치지 않는다.

메모리의 최소 및 최대 제약 조건에 대한 동기

클러스터 관리자는 파드가 사용할 수 있는 메모리 양에 제한을 둘 수 있다. 예를 들면 다음과 같다.

  • 클러스터의 각 노드에는 2GB의 메모리가 있다. 클러스터의 어떤 노드도 2GB 이상의 요청량을 지원할 수 없으므로, 2GB 이상의 메모리를 요청하는 파드를 수락하지 않으려고 한다.

  • 클러스터는 운영 부서와 개발 부서에서 공유한다. 프로덕션 워크로드가 최대 8GB의 메모리를 소비하도록 하려면, 개발 워크로드를 512MB로 제한해야 한다. 프로덕션 및 개발을 위해 별도의 네임스페이스를 만들고, 각 네임스페이스에 메모리 제약 조건을 적용한다.

정리

네임스페이스를 삭제한다.

kubectl delete namespace constraints-mem-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.2.4 - 네임스페이스에 대한 CPU의 최소 및 최대 제약 조건 구성

이 페이지는 네임스페이스에서 컨테이너와 파드가 사용하는 CPU 리소스의 최솟값과 최댓값을 설정하는 방법을 보여준다. 리밋레인지(LimitRange) 오브젝트에 CPU의 최솟값과 최댓값을 지정한다. 리밋레인지에 의해 부과된 제약 조건을 파드가 충족하지 않으면, 네임스페이스에서 생성될 수 없다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

태스크 예제를 실행하려면 클러스터에 적어도 1 CPU 이상이 사용 가능해야 한다.

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace constraints-cpu-example

리밋레인지와 파드 생성

다음은 리밋레인지에 대한 구성 파일이다.

admin/resource/cpu-constraints.yaml 
apiVersion: v1
kind: LimitRange
metadata:
  name: cpu-min-max-demo-lr
spec:
  limits:
  - max:
      cpu: "800m"
    min:
      cpu: "200m"
    type: Container

리밋레인지를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints.yaml --namespace=constraints-cpu-example

리밋레인지에 대한 자세한 정보를 본다.

kubectl get limitrange cpu-min-max-demo-lr --output=yaml --namespace=constraints-cpu-example

출력 결과는 예상대로 CPU의 최소와 최대 제약 조건을 보여준다. 그러나 참고로 리밋레인지에 대한 구성 파일에 기본값을 지정하지 않아도 자동으로 생성된다.

limits:
- default:
    cpu: 800m
  defaultRequest:
    cpu: 800m
  max:
    cpu: 800m
  min:
    cpu: 200m
  type: Container

이제 constraints-cpu-example 네임스페이스에 컨테이너가 생성될 때마다, 쿠버네티스는 다음 단계를 수행한다.

  • 컨테이너가 자체 CPU 요청량(request)과 상한(limit)을 지정하지 않으면, 컨테이너에 CPU 요청량과 상한의 기본값(default)을 지정한다.

  • 컨테이너가 200 millicpu 이상의 CPU 요청량을 지정하는지 확인한다.

  • 컨테이너가 800 millicpu 이하의 CPU 상한을 지정하는지 확인한다.

참고: LimitRange 오브젝트를 생성할 때, huge-pages 또는 GPU에도 상한을 지정할 수 있다. 그러나, 이 리소스들에 default 와 defaultRequest 가 모두 지정되어 있으면, 두 값은 같아야 한다.

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너 매니페스트는 500 millicpu의 CPU 요청량 및 800 millicpu의 CPU 상한을 지정한다. 이는 리밋레인지에 의해 부과된 CPU의 최소와 최대 제약 조건을 충족시킨다.

admin/resource/cpu-constraints-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-cpu-demo
spec:
  containers:
  - name: constraints-cpu-demo-ctr
    image: nginx
    resources:
      limits:
        cpu: "800m"
      requests:
        cpu: "500m"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod.yaml --namespace=constraints-cpu-example

파드의 컨테이너가 실행 중인지 확인한다.

kubectl get pod constraints-cpu-demo --namespace=constraints-cpu-example

파드에 대한 자세한 정보를 본다.

kubectl get pod constraints-cpu-demo --output=yaml --namespace=constraints-cpu-example

출력 결과는 컨테이너의 CPU 요청량이 500 millicpu이고, CPU 상한이 800 millicpu임을 나타낸다. 이는 리밋레인지에 의해 부과된 제약 조건을 만족시킨다.

resources:
  limits:
    cpu: 800m
  requests:
    cpu: 500m

파드 삭제

kubectl delete pod constraints-cpu-demo --namespace=constraints-cpu-example

CPU 최대 제약 조건을 초과하는 파드 생성 시도

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 500 millicpu의 CPU 요청량과 1.5 cpu의 CPU 상한을 지정한다.

admin/resource/cpu-constraints-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-cpu-demo-2
spec:
  containers:
  - name: constraints-cpu-demo-2-ctr
    image: nginx
    resources:
      limits:
        cpu: "1.5"
      requests:
        cpu: "500m"

파드 생성을 시도한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-2.yaml --namespace=constraints-cpu-example

컨테이너가 너무 큰 CPU 상한을 지정하므로, 출력 결과에 파드가 생성되지 않은 것으로 표시된다.

Error from server (Forbidden): error when creating "examples/admin/resource/cpu-constraints-pod-2.yaml":
pods "constraints-cpu-demo-2" is forbidden: maximum cpu usage per Container is 800m, but limit is 1500m.

최소 CPU 요청량을 충족하지 않는 파드 생성 시도

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 100 millicpu의 CPU 요청량과 800 millicpu의 CPU 상한을 지정한다.

admin/resource/cpu-constraints-pod-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-cpu-demo-3
spec:
  containers:
  - name: constraints-cpu-demo-3-ctr
    image: nginx
    resources:
      limits:
        cpu: "800m"
      requests:
        cpu: "100m"

파드 생성을 시도한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-3.yaml --namespace=constraints-cpu-example

컨테이너가 너무 작은 CPU 요청량을 지정하므로, 출력 결과에 파드가 생성되지 않은 것으로 표시된다.

Error from server (Forbidden): error when creating "examples/admin/resource/cpu-constraints-pod-3.yaml":
pods "constraints-cpu-demo-3" is forbidden: minimum cpu usage per Container is 200m, but request is 100m.

CPU 요청량 또는 상한을 지정하지 않은 파드 생성

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 CPU 요청량을 지정하지 않으며, CPU 상한을 지정하지 않는다.

admin/resource/cpu-constraints-pod-4.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: constraints-cpu-demo-4
spec:
  containers:
  - name: constraints-cpu-demo-4-ctr
    image: vish/stress

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-4.yaml --namespace=constraints-cpu-example

파드에 대한 자세한 정보를 본다.

kubectl get pod constraints-cpu-demo-4 --namespace=constraints-cpu-example --output=yaml

출력 결과는 파드의 컨테이너에 대한 CPU 요청량이 800 millicpu이고, CPU 상한이 800 millicpu임을 나타낸다. 컨테이너는 어떻게 이런 값을 얻었을까?

resources:
  limits:
    cpu: 800m
  requests:
    cpu: 800m

컨테이너가 자체 CPU 요청량과 상한을 지정하지 않았으므로, 리밋레인지로부터 CPU 요청량과 상한의 기본값이 주어졌다.

이 시점에서, 컨테이너는 실행 중이거나 실행 중이 아닐 수 있다. 이 태스크의 전제 조건은 클러스터에 1 CPU 이상 사용 가능해야 한다는 것이다. 각 노드에 1 CPU만 있는 경우, 노드에 할당할 수 있는 CPU가 800 millicpu의 요청량을 수용하기에 충분하지 않을 수 있다. 2 CPU인 노드를 사용하는 경우에는, CPU가 800 millicpu 요청량을 수용하기에 충분할 것이다.

파드를 삭제한다.

kubectl delete pod constraints-cpu-demo-4 --namespace=constraints-cpu-example

CPU의 최소 및 최대 제약 조건의 적용

리밋레인지에 의해 네임스페이스에 부과된 CPU의 최대 및 최소 제약 조건은 파드를 생성하거나 업데이트할 때만 적용된다. 리밋레인지를 변경해도, 이전에 생성된 파드에는 영향을 미치지 않는다.

CPU의 최소 및 최대 제약 조건에 대한 동기

클러스터 관리자는 파드가 사용할 수 있는 CPU 리소스에 제한을 둘 수 있다. 예를 들면 다음과 같다.

  • 클러스터의 각 노드에는 2 CPU가 있다. 클러스터의 어떤 노드도 요청량을 지원할 수 없기 때문에, 2 CPU 이상을 요청하는 파드를 수락하지 않으려고 한다.

  • 클러스터는 프로덕션과 개발 부서에서 공유한다. 프로덕션 워크로드가 최대 3 CPU를 소비하도록 하고 싶지만, 개발 워크로드는 1 CPU로 제한하려고 한다. 프로덕션과 개발을 위해 별도의 네임스페이스를 생성하고, 각 네임스페이스에 CPU 제약 조건을 적용한다.

정리

네임스페이스를 삭제한다.

kubectl delete namespace constraints-cpu-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.2.5 - 네임스페이스에 대한 메모리 및 CPU 쿼터 구성

이 페이지는 네임스페이스에서 실행 중인 모든 컨테이너가 사용할 수 있는 총 메모리 및 CPU 양에 대한 쿼터를 설정하는 방법을 보여준다. 리소스쿼터(ResourceQuota) 오브젝트에 쿼터를 지정한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

클러스터의 각 노드에는 최소 1GiB의 메모리가 있어야 한다.

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace quota-mem-cpu-example

리소스쿼터 생성

다음은 리소스쿼터 오브젝트의 구성 파일이다.

admin/resource/quota-mem-cpu.yaml 
apiVersion: v1
kind: ResourceQuota
metadata:
  name: mem-cpu-demo
spec:
  hard:
    requests.cpu: "1"
    requests.memory: 1Gi
    limits.cpu: "2"
    limits.memory: 2Gi

리소스쿼터를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/quota-mem-cpu.yaml --namespace=quota-mem-cpu-example

리소스쿼터에 대한 자세한 정보를 본다.

kubectl get resourcequota mem-cpu-demo --namespace=quota-mem-cpu-example --output=yaml

리소스쿼터는 이러한 요구 사항을 quota-mem-cpu-example 네임스페이스에 배치한다.

  • 모든 컨테이너에는 메모리 요청량(request), 메모리 상한(limit), CPU 요청량 및 CPU 상한이 있어야 한다.
  • 모든 컨테이너에 대한 총 메모리 요청량은 1GiB를 초과하지 않아야 한다.
  • 모든 컨테이너에 대한 총 메모리 상한은 2GiB를 초과하지 않아야 한다.
  • 모든 컨테이너에 대한 총 CPU 요청량은 1 cpu를 초과해서는 안된다.
  • 모든 컨테이너에 대한 총 CPU 상한은 2 cpu를 초과해서는 안된다.

파드 생성

파드의 구성 파일은 다음과 같다.

admin/resource/quota-mem-cpu-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: quota-mem-cpu-demo
spec:
  containers:
  - name: quota-mem-cpu-demo-ctr
    image: nginx
    resources:
      limits:
        memory: "800Mi"
        cpu: "800m"
      requests:
        memory: "600Mi"
        cpu: "400m"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/quota-mem-cpu-pod.yaml --namespace=quota-mem-cpu-example

파드의 컨테이너가 실행 중인지 확인한다.

kubectl get pod quota-mem-cpu-demo --namespace=quota-mem-cpu-example

다시 한 번, 리소스쿼터에 대한 자세한 정보를 본다.

kubectl get resourcequota mem-cpu-demo --namespace=quota-mem-cpu-example --output=yaml

출력 결과는 쿼터와 사용된 쿼터를 함께 보여준다. 파드의 메모리와 CPU 요청량 및 상한이 쿼터를 초과하지 않은 것을 볼 수 있다.

status:
  hard:
    limits.cpu: "2"
    limits.memory: 2Gi
    requests.cpu: "1"
    requests.memory: 1Gi
  used:
    limits.cpu: 800m
    limits.memory: 800Mi
    requests.cpu: 400m
    requests.memory: 600Mi

두 번째 파드 생성 시도

다음은 두 번째 파드의 구성 파일이다.

admin/resource/quota-mem-cpu-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: quota-mem-cpu-demo-2
spec:
  containers:
  - name: quota-mem-cpu-demo-2-ctr
    image: redis
    resources:
      limits:
        memory: "1Gi"
        cpu: "800m"
      requests:
        memory: "700Mi"
        cpu: "400m"

구성 파일에서, 파드의 메모리 요청량이 700MiB임을 알 수 있다. 사용된 메모리 요청량과 이 새 메모리 요청량의 합계가 메모리 요청량 쿼터를 초과한다. 600MiB + 700MiB > 1GiB

파드 생성을 시도한다.

kubectl apply -f https://k8s.io/examples/admin/resource/quota-mem-cpu-pod-2.yaml --namespace=quota-mem-cpu-example

두 번째 파드는 생성되지 않는다. 출력 결과는 두 번째 파드를 생성하면 메모리 요청량의 총 합계가 메모리 요청량 쿼터를 초과함을 보여준다.

Error from server (Forbidden): error when creating "examples/admin/resource/quota-mem-cpu-pod-2.yaml":
pods "quota-mem-cpu-demo-2" is forbidden: exceeded quota: mem-cpu-demo,
requested: requests.memory=700Mi,used: requests.memory=600Mi, limited: requests.memory=1Gi

토론

이 연습에서 보았듯이, 리소스쿼터를 사용하여 네임스페이스에서 실행 중인 모든 컨테이너에 대한 메모리 요청량의 총 합계를 제한할 수 있다. 메모리 상한, CPU 요청량 및 CPU 상한의 총 합계를 제한할 수도 있다.

모든 컨테이너에 대한 합계 대신 개별 컨테이너를 제한하려면, 리밋레인지(LimitRange)를 사용한다.

정리

네임스페이스를 삭제한다.

kubectl delete namespace quota-mem-cpu-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.2.6 - 네임스페이스에 대한 파드 쿼터 구성

이 페이지는 네임스페이스에서 실행할 수 있는 총 파드 수에 대한 쿼터를 설정하는 방법을 보여준다. 리소스쿼터(ResourceQuota) 오브젝트에 쿼터를 지정한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

네임스페이스 생성

이 실습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace quota-pod-example

리소스쿼터 생성

다음은 리소스쿼터 오브젝트의 구성 파일이다.

admin/resource/quota-pod.yaml 
apiVersion: v1
kind: ResourceQuota
metadata:
  name: pod-demo
spec:
  hard:
    pods: "2"

리소스쿼터를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/quota-pod.yaml --namespace=quota-pod-example

리소스쿼터에 대한 자세한 정보를 본다.

kubectl get resourcequota pod-demo --namespace=quota-pod-example --output=yaml

출력 결과는 네임스페이스에 두 개의 파드 쿼터가 있고, 현재 파드가 없음을 보여준다. 즉, 쿼터 중 어느 것도 사용되지 않았다.

spec:
  hard:
    pods: "2"
status:
  hard:
    pods: "2"
  used:
    pods: "0"

다음은 디플로이먼트(Deployment) 구성 파일이다.

admin/resource/quota-pod-deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pod-quota-demo
spec:
  selector:
    matchLabels:
      purpose: quota-demo
  replicas: 3
  template:
    metadata:
      labels:
        purpose: quota-demo
    spec:
      containers:
      - name: pod-quota-demo
        image: nginx

구성 파일에서, replicas: 3 은 쿠버네티스가 모두 동일한 애플리케이션을 실행하는 세 개의 파드를 만들도록 지시한다.

디플로이먼트를 생성한다.

kubectl apply -f https://k8s.io/examples/admin/resource/quota-pod-deployment.yaml --namespace=quota-pod-example

디플로이먼트에 대한 자세한 정보를 본다.

kubectl get deployment pod-quota-demo --namespace=quota-pod-example --output=yaml

출력 결과는 디플로이먼트에서 3개의 레플리카를 지정하더라도, 쿼터로 인해 2개의 파드만 생성되었음을 보여준다.

spec:
  ...
  replicas: 3
...
status:
  availableReplicas: 2
...
lastUpdateTime: 2017-07-07T20:57:05Z
    message: 'unable to create pods: pods "pod-quota-demo-1650323038-" is forbidden:
      exceeded quota: pod-demo, requested: pods=1, used: pods=2, limited: pods=2'

정리

네임스페이스를 삭제한다.

kubectl delete namespace quota-pod-example

다음 내용

클러스터 관리자를 위한 문서

앱 개발자를 위한 문서

2.3 - 인증서

클라이언트 인증서로 인증을 사용하는 경우 easyrsa, openssl 또는 cfssl 을 통해 인증서를 수동으로 생성할 수 있다.

easyrsa

easyrsa 는 클러스터 인증서를 수동으로 생성할 수 있다.

  1. easyrsa3의 패치 버전을 다운로드하여 압축을 풀고, 초기화한다.

    curl -LO https://storage.googleapis.com/kubernetes-release/easy-rsa/easy-rsa.tar.gz
tar xzf easy-rsa.tar.gz
cd easy-rsa-master/easyrsa3
./easyrsa init-pki

  2. 새로운 인증 기관(CA)을 생성한다. --batch 는 자동 모드를 설정한다. --req-cn 는 CA의 새 루트 인증서에 대한 일반 이름(Common Name (CN))을 지정한다.

    ./easyrsa --batch "--req-cn=${MASTER_IP}@`date +%s`" build-ca nopass

  3. 서버 인증서와 키를 생성한다. --subject-alt-name 인수는 API 서버에 접근이 가능한 IP와 DNS 이름을 설정한다. MASTER_CLUSTER_IP 는 일반적으로 API 서버와 컨트롤러 관리자 컴포넌트에 대해 --service-cluster-ip-range 인수로 지정된 서비스 CIDR의 첫 번째 IP이다. --days 인수는 인증서가 만료되는 일 수를 설정하는데 사용된다. 또한, 아래 샘플은 기본 DNS 이름으로 cluster.local 을 사용한다고 가정한다.

    ./easyrsa --subject-alt-name="IP:${MASTER_IP},"\
"IP:${MASTER_CLUSTER_IP},"\
"DNS:kubernetes,"\
"DNS:kubernetes.default,"\
"DNS:kubernetes.default.svc,"\
"DNS:kubernetes.default.svc.cluster,"\
"DNS:kubernetes.default.svc.cluster.local" \
--days=10000 \
build-server-full server nopass

  4. pki/ca.crt, pki/issued/server.crt 그리고 pki/private/server.key 를 디렉터리에 복사한다.

  5. API 서버 시작 파라미터에 다음 파라미터를 채우고 추가한다.

    --client-ca-file=/yourdirectory/ca.crt
--tls-cert-file=/yourdirectory/server.crt
--tls-private-key-file=/yourdirectory/server.key

openssl

openssl 은 클러스터 인증서를 수동으로 생성할 수 있다.

  1. ca.key를 2048bit로 생성한다.

    openssl genrsa -out ca.key 2048

  2. ca.key에 따라 ca.crt를 생성한다(인증서 유효 기간을 사용하려면 -days를 사용한다).

    openssl req -x509 -new -nodes -key ca.key -subj "/CN=${MASTER_IP}" -days 10000 -out ca.crt

  3. server.key를 2048bit로 생성한다.

    openssl genrsa -out server.key 2048

  4. 인증서 서명 요청(Certificate Signing Request (CSR))을 생성하기 위한 설정 파일을 생성한다. 파일에 저장하기 전에 꺾쇠 괄호(예: <MASTER_IP>)로 표시된 값을 실제 값으로 대체한다(예: csr.conf). MASTER_CLUSTER_IP 의 값은 이전 하위 섹션에서 설명한 대로 API 서버의 서비스 클러스터 IP이다. 또한, 아래 샘플에서는 cluster.local 을 기본 DNS 도메인 이름으로 사용하고 있다고 가정한다.

    [ req ]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ]
C = <국가(country)>
ST = <도(state)>
L = <시(city)>
O = <조직(organization)>
OU = <조직 단위(organization unit)>
CN = <MASTER_IP>

[ req_ext ]
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = kubernetes
DNS.2 = kubernetes.default
DNS.3 = kubernetes.default.svc
DNS.4 = kubernetes.default.svc.cluster
DNS.5 = kubernetes.default.svc.cluster.local
IP.1 = <MASTER_IP>
IP.2 = <MASTER_CLUSTER_IP>

[ v3_ext ]
authorityKeyIdentifier=keyid,issuer:always
basicConstraints=CA:FALSE
keyUsage=keyEncipherment,dataEncipherment
extendedKeyUsage=serverAuth,clientAuth
subjectAltName=@alt_names

  5. 설정 파일을 기반으로 인증서 서명 요청을 생성한다.

    openssl req -new -key server.key -out server.csr -config csr.conf

  6. ca.key, ca.crt 그리고 server.csr을 사용해서 서버 인증서를 생성한다.

    openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
-CAcreateserial -out server.crt -days 10000 \
-extensions v3_ext -extfile csr.conf

  7. 인증서 서명 요청을 확인한다.

    openssl req  -noout -text -in ./server.csr

  8. 인증서를 확인한다.

    openssl x509  -noout -text -in ./server.crt

마지막으로, API 서버 시작 파라미터에 동일한 파라미터를 추가한다.

cfssl

cfssl 은 인증서 생성을 위한 또 다른 도구이다.

  1. 아래에 표시된 대로 커맨드 라인 도구를 다운로드하여 압축을 풀고 준비한다. 사용 중인 하드웨어 아키텍처 및 cfssl 버전에 따라 샘플 명령을 조정해야 할 수도 있다.

    curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssl_1.5.0_linux_amd64 -o cfssl
chmod +x cfssl
curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssljson_1.5.0_linux_amd64 -o cfssljson
chmod +x cfssljson
curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssl-certinfo_1.5.0_linux_amd64 -o cfssl-certinfo
chmod +x cfssl-certinfo

  2. 아티팩트(artifact)를 보유할 디렉터리를 생성하고 cfssl을 초기화한다.

    mkdir cert
cd cert
../cfssl print-defaults config > config.json
../cfssl print-defaults csr > csr.json

  3. CA 파일을 생성하기 위한 JSON 설정 파일을 ca-config.json 예시와 같이 생성한다.

    {
  "signing": {
    "default": {
      "expiry": "8760h"
    },
    "profiles": {
      "kubernetes": {
        "usages": [
          "signing",
          "key encipherment",
          "server auth",
          "client auth"
        ],
        "expiry": "8760h"
      }
    }
  }
}

  4. CA 인증서 서명 요청(CSR)을 위한 JSON 설정 파일을 ca-csr.json 예시와 같이 생성한다. 꺾쇠 괄호로 표시된 값을 사용하려는 실제 값으로 변경한다.

    {
  "CN": "kubernetes",
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names":[{
    "C": "<국가(country)>",
    "ST": "<도(state)>",
    "L": "<시(city)>",
    "O": "<조직(organization)>",
    "OU": "<조직 단위(organization unit)>"
  }]
}

  5. CA 키(ca-key.pem)와 인증서(ca.pem)을 생성한다.

    ../cfssl gencert -initca ca-csr.json | ../cfssljson -bare ca

  6. API 서버의 키와 인증서를 생성하기 위한 JSON 구성파일을 server-csr.json 예시와 같이 생성한다. 꺾쇠 괄호 안의 값을 사용하려는 실제 값으로 변경한다. MASTER_CLUSTER_IP 는 이전 하위 섹션에서 설명한 API 서버의 클러스터 IP이다. 아래 샘플은 기본 DNS 도메인 이름으로 cluster.local 을 사용한다고 가정한다.

    {
  "CN": "kubernetes",
  "hosts": [
    "127.0.0.1",
    "<MASTER_IP>",
    "<MASTER_CLUSTER_IP>",
    "kubernetes",
    "kubernetes.default",
    "kubernetes.default.svc",
    "kubernetes.default.svc.cluster",
    "kubernetes.default.svc.cluster.local"
  ],
  "key": {
    "algo": "rsa",
    "size": 2048
  },
  "names": [{
    "C": "<국가(country)>",
    "ST": "<도(state)>",
    "L": "<시(city)>",
    "O": "<조직(organization)>",
    "OU": "<조직 단위(organization unit)>"
  }]
}

  7. API 서버 키와 인증서를 생성하면, 기본적으로 server-key.pem 과 server.pem 파일에 각각 저장된다.

    ../cfssl gencert -ca=ca.pem -ca-key=ca-key.pem \
--config=ca-config.json -profile=kubernetes \
server-csr.json | ../cfssljson -bare server

자체 서명된 CA 인증서의 배포

클라이언트 노드는 자체 서명된 CA 인증서를 유효한 것으로 인식하지 않을 수 있다. 비-프로덕션 디플로이먼트 또는 회사 방화벽 뒤에서 실행되는 디플로이먼트의 경우, 자체 서명된 CA 인증서를 모든 클라이언트에 배포하고 유효한 인증서의 로컬 목록을 새로 고칠 수 있다.

각 클라이언트에서, 다음 작업을 수행한다.

sudo cp ca.crt /usr/local/share/ca-certificates/kubernetes.crt
sudo update-ca-certificates

Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....
done.

인증서 API

certificates.k8s.io API를 사용해서 여기에 설명된 대로 인증에 사용할 x509 인증서를 프로비전 할 수 있다.

2.4 - 네트워크 폴리시 제공자(Network Policy Provider) 설치

2.4.1 - 네트워크 폴리시로 캘리코(Calico) 사용하기

이 페이지는 쿠버네티스에서 캘리코(Calico) 클러스터를 생성하는 몇 가지 빠른 방법을 살펴본다.

시작하기 전에

클라우드나 지역 클러스터 중에 어디에 배포할지 결정한다.

구글 쿠버네티스 엔진(GKE)에 캘리코 클러스터 생성하기

사전요구사항: gcloud.

  1. 캘리코로 GKE 클러스터를 시작하려면, --enable-network-policy 플래그를 추가한다.

    문법

    gcloud container clusters create [클러스터_이름] --enable-network-policy

    예시

    gcloud container clusters create my-calico-cluster --enable-network-policy

  2. 배포를 확인하기 위해, 다음 커맨드를 이용하자.

    kubectl get pods --namespace=kube-system

    캘리코 파드는 calico로 시작한다. 각각의 상태가 Running임을 확인하자.

kubeadm으로 지역 캘리코 클러스터 생성하기

Kubeadm을 이용해서 15분 이내에 지역 단일 호스트 캘리코 클러스터를 생성하려면, 캘리코 빠른 시작을 참고한다.

다음 내용

클러스터가 동작하면, 쿠버네티스 네트워크 폴리시(NetworkPolicy)를 시도하기 위해 네트워크 폴리시 선언하기를 따라 할 수 있다.

2.4.2 - 네트워크 폴리시로 실리움(Cilium) 사용하기

이 페이지는 어떻게 네트워크 폴리시(NetworkPolicy)로 실리움(Cilium)를 사용하는지 살펴본다.

실리움의 배경에 대해서는 실리움 소개를 읽어보자.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

기본 시험을 위해 실리움을 Minikube에 배포하기

실리움에 쉽게 친숙해지기 위해 Minikube에 실리움을 기본적인 데몬셋으로 설치를 수행하는 실리움 쿠버네티스 시작하기 안내를 따라 해볼 수 있다.

Minikube를 시작하려면 최소 버전으로 >= v1.3.1 이 필요하고, 다음의 실행 파라미터로 실행한다.

minikube version

minikube version: v1.3.1

minikube start --network-plugin=cni --memory=4096

BPF 파일시스템을 마운트한다

minikube ssh -- sudo mount bpffs -t bpf /sys/fs/bpf

Minikube에서 실리움의 데몬셋 구성과 적절한 RBAC 설정을 포함하는 필요한 구성을 간단한 올인원 YAML 파일로 배포할 수 있다.

kubectl create -f  https://raw.githubusercontent.com/cilium/cilium/v1.8/install/kubernetes/quick-install.yaml

configmap/cilium-config created
serviceaccount/cilium created
serviceaccount/cilium-operator created
clusterrole.rbac.authorization.k8s.io/cilium created
clusterrole.rbac.authorization.k8s.io/cilium-operator created
clusterrolebinding.rbac.authorization.k8s.io/cilium created
clusterrolebinding.rbac.authorization.k8s.io/cilium-operator created
daemonset.apps/cilium create
deployment.apps/cilium-operator created

시작하기 안내서의 나머지 부분은 예제 애플리케이션을 이용하여 L3/L4(예, IP 주소 + 포트) 모두의 보안 정책뿐만 아니라 L7(예, HTTP)의 보안 정책을 적용하는 방법을 설명한다.

실리움을 실 서비스 용도로 배포하기

실리움을 실 서비스 용도의 배포에 관련한 자세한 방법은 실리움 쿠버네티스 설치 안내를 살펴본다. 이 문서는 자세한 요구사항, 방법과 실제 데몬셋 예시를 포함한다.

실리움 구성요소 이해하기

실리움으로 클러스터를 배포하면 파드가 kube-system 네임스페이스에 추가된다. 파드의 목록을 보려면 다음을 실행한다.

kubectl get pods --namespace=kube-system

다음과 유사한 파드의 목록을 볼 것이다.

NAME            READY   STATUS    RESTARTS   AGE
cilium-6rxbd    1/1     Running   0          1m
...

cilium 파드는 클러스터 각 노드에서 실행되며, 리눅스 BPF를 사용해서 해당 노드의 파드에 대한 트래픽 네트워크 폴리시를 적용한다.

다음 내용

클러스터가 동작하면, 실리움으로 쿠버네티스 네트워크 폴리시를 시도하기 위해 네트워크 폴리시 선언하기를 따라 할 수 있다. 재미있게 즐기고, 질문이 있다면 실리움 슬랙 채널을 이용하여 연락한다.

2.4.3 - 네트워크 폴리시로 큐브 라우터(Kube-router) 사용하기

이 페이지는 네트워크 폴리시(NetworkPolicy)로 큐브 라우터(Kube-router)를 사용하는 방법을 살펴본다.

시작하기 전에

운영 중인 쿠버네티스 클러스터가 필요하다. 클러스터가 없다면, Kops, Bootkube, Kubeadm 등을 이용해서 클러스터를 생성할 수 있다.

큐브 라우터 애드온 설치하기

큐브 라우터 애드온은 갱신된 모든 네트워크 폴리시 및 파드에 대해 쿠버네티스 API 서버를 감시하고, 정책에 따라 트래픽을 허용하거나 차단하도록 iptables 규칙와 ipset을 구성하는 네트워크 폴리시 컨트롤러와 함께 제공된다. 큐브 라우터 애드온을 설치하는 큐브 라우터를 클러스터 인스톨러와 함께 사용하기 안내서를 따라해 봅니다.

다음 내용

큐브 라우터 애드온을 설치한 후에는, 쿠버네티스 네트워크 폴리시를 시도하기 위해 네트워크 폴리시 선언하기를 따라 할 수 있다.

2.4.4 - 네트워크 폴리시로 로마나(Romana)

이 페이지는 네트워크 폴리시(NetworkPolicy)로 로마나(Romana)를 사용하는 방법을 살펴본다.

시작하기 전에

kubeadm 시작하기의 1, 2, 3 단계를 완료하자.

kubeadm으로 로마나 설치하기

Kubeadm을 위한 컨테이너화된 설치 안내서를 따른다.

네트워크 폴리시 적용하기

네트워크 폴리시를 적용하기 위해 다음 중에 하나를 사용하자.

다음 내용

로마나를 설치한 후에는, 쿠버네티스 네트워크 폴리시를 시도하기 위해 네트워크 폴리시 선언하기를 따라 할 수 있다.

2.4.5 - 네트워크 폴리시로 위브넷(Weave Net) 사용하기

이 페이지는 네트워크 폴리시(NetworkPolicy)로 위브넷(Weave Net)를 사용하는 방법을 살펴본다.

시작하기 전에

쿠버네티스 클러스터가 필요하다. 맨 땅에서부터 시작하기를 위해서 kubeadm 시작하기 안내서를 따른다.

Weave Net 애드온을 설치한다

애드온을 통한 쿠버네티스 통합하기 가이드를 따른다.

쿠버네티스의 위브넷 애드온은 쿠버네티스의 모든 네임스페이스의 네크워크 정책 어노테이션을 자동으로 모니터링하며, 정책에 따라 트래픽을 허용하고 차단하는 iptables 규칙을 구성하는 네트워크 폴리시 컨트롤러와 함께 제공된다.

설치 시험

위브넷이 동작하는지 확인한다.

다음 커맨드를 입력한다.

kubectl get pods -n kube-system -o wide

출력은 다음과 유사하다.

NAME                                    READY     STATUS    RESTARTS   AGE       IP              NODE
weave-net-1t1qg                         2/2       Running   0          9d        192.168.2.10    worknode3
weave-net-231d7                         2/2       Running   1          7d        10.2.0.17       worknodegpu
weave-net-7nmwt                         2/2       Running   3          9d        192.168.2.131   masternode
weave-net-pmw8w                         2/2       Running   0          9d        192.168.2.216   worknode2

위브넷 파드를 가진 각 노드와 모든 파드는 Running이고 2/2 READY이다(2/2는 각 파드가 weave와 weave-npc를 가지고 있음을 뜻한다).

다음 내용

위브넷 애드온을 설치하고 나서, 쿠버네티스 네트워크 폴리시를 시도하기 위해 네트워크 폴리시 선언하기를 따라 할 수 있다. 질문이 있으면 슬랙 #weave-community 이나 Weave 유저그룹에 연락한다.

2.5 - DNS 서비스 사용자 정의하기

이 페이지는 클러스터 안에서 사용자의 DNS 파드(Pod) 를 설정하고 DNS 변환(DNS resolution) 절차를 사용자 정의하는 방법을 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

클러스터는 CoreDNS 애드온을 구동하고 있어야 한다. CoreDNS로 이관하기 는 kubeadm 을 이용하여 kube-dns 로부터 이관하는 방법을 설명한다.

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: v1.12. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

소개

DNS는 애드온 관리자 인 클러스터 애드온을 사용하여 자동으로 시작되는 쿠버네티스 내장 서비스이다.

쿠버네티스 v1.12 부터, CoreDNS는 kube-dns를 대체하여 권장되는 DNS 서버이다. 만약 사용자의 클러스터가 원래 kube-dns를 사용하였을 경우, CoreDNS 대신 kube-dns 를 계속 사용할 수도 있다.

참고: CoreDNS 서비스는 metadata.name 필드에 kube-dns 로 이름이 지정된다. 이를 통해, 기존의 kube-dns 서비스 이름을 사용하여 클러스터 내부의 주소를 확인하는 워크로드에 대한 상호 운용성이 증가된다. kube-dns 로 서비스 이름을 사용하면, 해당 DNS 공급자가 어떤 공통 이름으로 실행되고 있는지에 대한 구현 세부 정보를 추상화한다.

CoreDNS를 디플로이먼트(Deployment)로 실행하고 있을 경우, 일반적으로 고정 IP 주소를 갖는 쿠버네티스 서비스로 노출된다. Kubelet 은 --cluster-dns=<dns-service-ip> 플래그를 사용하여 DNS 확인자 정보를 각 컨테이너에 전달한다.

DNS 이름에도 도메인이 필요하다. 사용자는 kubelet 에 있는 --cluster-domain=<default-local-domain> 플래그를 통하여 로컬 도메인을 설정할 수 있다.

DNS 서버는 정방향 조회(A 및 AAAA 레코드), 포트 조회(SRV 레코드), 역방향 IP 주소 조회(PTR 레코드) 등을 지원한다. 더 자세한 내용은 서비스 및 파드용 DNS를 참고한다.

만약 파드의 dnsPolicy 가 default 로 지정되어 있는 경우, 파드는 자신이 실행되는 노드의 이름 변환(name resolution) 구성을 상속한다. 파드의 DNS 변환도 노드와 동일하게 작동해야 한다. 그 외에는 알려진 이슈를 참고한다.

만약 위와 같은 방식을 원하지 않거나, 파드를 위해 다른 DNS 설정이 필요한 경우, 사용자는 kubelet 의 --resolv-conf 플래그를 사용할 수 있다. 파드가 DNS를 상속받지 못하도록 하기 위해 이 플래그를 ""로 설정한다. DNS 상속을 위해 /etc/resolv.conf 이외의 파일을 지정할 경우 유효한 파일 경로를 설정한다.

CoreDNS

CoreDNS는 dns 명세를 준수하며 클러스터 DNS 역할을 할 수 있는, 범용적인 권한을 갖는 DNS 서버이다.

CoreDNS 컨피그맵(ConfigMap) 옵션

CoreDNS는 모듈형이자 플러그인이 가능한 DNS 서버이며, 각 플러그인들은 CoreDNS에 새로운 기능을 부가한다. 이는 CoreDNS 구성 파일인 Corefile을 관리하여 구성할 수 있다. 클러스터 관리자는 CoreDNS Corefile에 대한 컨피그맵을 수정하여 해당 클러스터에 대한 DNS 서비스 검색 동작을 변경할 수 있다.

쿠버네티스에서 CoreDNS는 아래의 기본 Corefile 구성으로 설치된다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system
data:
  Corefile: |
    .:53 {
        errors
        health {
            lameduck 5s
        }
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
            pods insecure
            fallthrough in-addr.arpa ip6.arpa
            ttl 30
        }
        prometheus :9153
        forward . /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }

Corefile의 구성은 CoreDNS의 아래 플러그인을 포함한다.

  • errors: 오류가 표준 출력(stdout)에 기록된다.
  • health: CoreDNS의 상태(healthy)가 http://localhost:8080/health 에 기록된다. 이 확장 구문에서 lameduck 은 프로세스를 비정상 상태(unhealthy)로 만들고, 프로세스가 종료되기 전에 5초 동안 기다린다.
  • ready: 8181 포트의 HTTP 엔드포인트가, 모든 플러그인이 준비되었다는 신호를 보내면 200 OK 를 반환한다.
  • kubernetes: CoreDNS가 쿠버네티스의 서비스 및 파드의 IP를 기반으로 DNS 쿼리에 대해 응답한다. 해당 플러그인에 대한 세부 사항은 CoreDNS 웹사이트에서 확인할 수 있다. ttl 을 사용하면 응답에 대한 사용자 정의 TTL 을 지정할 수 있으며, 기본값은 5초이다. 허용되는 최소 TTL은 0초이며, 최대값은 3600초이다. 레코드가 캐싱되지 않도록 할 경우, TTL을 0으로 설정한다. pods insecure 옵션은 kube-dns 와의 하위 호환성을 위해 제공된다. pods verified 옵션을 사용하여, 일치하는 IP의 동일 네임스페이스(Namespace)에 파드가 존재하는 경우에만 A 레코드를 반환하게 할 수 있다. pods disabled 옵션은 파드 레코드를 사용하지 않을 경우 사용된다.
  • prometheus: CoreDNS의 메트릭은 프로메테우스 형식(OpenMetrics 라고도 알려진)의 http://localhost:9153/metrics 에서 사용 가능하다.
  • forward: 쿠버네티스 클러스터 도메인에 없는 쿼리들은 모두 사전에 정의된 리졸버(/etc/resolv.conf)로 전달된다.
  • cache: 프론트 엔드 캐시를 활성화한다.
  • loop: 간단한 전달 루프(loop)를 감지하고, 루프가 발견되면 CoreDNS 프로세스를 중단(halt)한다.
  • reload: 변경된 Corefile을 자동으로 다시 로드하도록 한다. 컨피그맵 설정을 변경한 후에 변경 사항이 적용되기 위하여 약 2분정도 소요된다.
  • loadbalance: 응답에 대하여 A, AAAA, MX 레코드의 순서를 무작위로 선정하는 라운드-로빈 DNS 로드밸런서이다.

사용자는 컨피그맵을 변경하여 기본 CoreDNS 동작을 변경할 수 있다.

CoreDNS를 사용하는 스텁 도메인(Stub-domain)과 업스트림 네임서버(nameserver)의 설정

CoreDNS는 포워드 플러그인을 사용하여 스텁 도메인 및 업스트림 네임서버를 구성할 수 있다.

예시

만약 클러스터 운영자가 10.150.0.1 에 위치한 Consul 도메인 서버를 가지고 있고, 모든 Consul 이름의 접미사가 .consul.local 인 경우, CoreDNS에서 이를 구성하기 위해 클러스터 관리자는 CoreDNS 컨피그맵에서 다음 구문을 생성한다.

consul.local:53 {
        errors
        cache 30
        forward . 10.150.0.1
    }

모든 비 클러스터의 DNS 조회가 172.16.0.1 의 특정 네임서버를 통과하도록 할 경우, /etc/resolv.conf 대신 forward 를 네임서버로 지정한다.

forward .  172.16.0.1

기본 Corefile 구성에 따른 최종 컨피그맵은 다음과 같다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system
data:
  Corefile: |
    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           fallthrough in-addr.arpa ip6.arpa
        }
        prometheus :9153
        forward . 172.16.0.1
        cache 30
        loop
        reload
        loadbalance
    }
    consul.local:53 {
        errors
        cache 30
        forward . 10.150.0.1
    }

Kubeadm 툴은 kube-dns 컨피그맵에서 동일한 설정의 CoreDNS 컨피그맵으로의 자동 변환을 지원한다.

참고: kube-dns는 스텁 도메인 및 네임서버(예: ns.foo.com)에 대한 FQDN을 허용하지만 CoreDNS에서는 이 기능을 지원하지 않는다. 변환 과정에서, 모든 FQDN 네임서버는 CoreDNS 설정에서 생략된다.

kube-dns에 대응되는 CoreDNS 설정

CoreDNS는 kube-dns 이상의 기능을 지원한다. StubDomains 과 upstreamNameservers 를 지원하도록 생성된 kube-dns의 컨피그맵은 CoreDNS의 forward 플러그인으로 변환된다.

예시

kube-dns에 대한 이 컨피그맵 예제는 stubDomains 및 upstreamNameservers를 지정한다.

apiVersion: v1
data:
  stubDomains: |
        {"abc.com" : ["1.2.3.4"], "my.cluster.local" : ["2.3.4.5"]}
  upstreamNameservers: |
        ["8.8.8.8", "8.8.4.4"]
kind: ConfigMap

CoreDNS에서는 동등한 설정으로 Corefile을 생성한다.

  • stubDomains 에 대응하는 설정:
abc.com:53 {
    errors
    cache 30
    forward . 1.2.3.4
}
my.cluster.local:53 {
    errors
    cache 30
    forward . 2.3.4.5
}

기본 플러그인으로 구성된 완전한 Corefile.

.:53 {
    errors
    health
    kubernetes cluster.local in-addr.arpa ip6.arpa {
        pods insecure
        fallthrough in-addr.arpa ip6.arpa
    }
    federation cluster.local {
        foo foo.feddomain.com
    }
    prometheus :9153
    forward . 8.8.8.8 8.8.4.4
    cache 30
}
abc.com:53 {
    errors
    cache 30
    forward . 1.2.3.4
}
my.cluster.local:53 {
    errors
    cache 30
    forward . 2.3.4.5
}

CoreDNS로의 이관

kube-dns에서 CoreDNS로 이관하기 위하여, kube-dns를 CoreDNS로 교체하여 적용하는 방법에 대한 상세 정보는 블로그 기사를 참고한다.

또한 공식적인 CoreDNS 배포 스크립트를 사용하여 이관할 수도 있다.

다음 내용

2.6 - 고가용성 쿠버네티스 클러스터 컨트롤 플레인 설정하기

FEATURE STATE: Kubernetes v1.5 [alpha]

구글 컴퓨트 엔진(Google Compute Engine, 이하 GCE)의 kube-up이나 kube-down 스크립트에 쿠버네티스 컨트롤 플레인 노드를 복제할 수 있다. 이 문서는 kube-up/down 스크립트를 사용하여 고가용(HA) 컨트롤 플레인을 관리하는 방법과 GCE와 함께 사용하기 위해 HA 컨트롤 플레인을 구현하는 방법에 관해 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

HA 호환 클러스터 시작

새 HA 호환 클러스터를 생성하려면, kube-up 스크립트에 다음 플래그를 설정해야 한다.

  • MULTIZONE=true - 서버의 기본 영역(zone)과 다른 영역에서 컨트롤 플레인 kubelet이 제거되지 않도록 한다. 여러 영역에서 컨트롤 플레인 노드를 실행(권장됨)하려는 경우에 필요하다.

  • ENABLE_ETCD_QUORUM_READ=true - 모든 API 서버에서 읽은 내용이 최신 데이터를 반환하도록 하기 위한 것이다. true인 경우, Etcd의 리더 복제본에서 읽는다. 이 값을 true로 설정하는 것은 선택 사항이다. 읽기는 더 안정적이지만 느리게 된다.

선택적으로, 첫 번째 컨트롤 플레인 노드가 생성될 GCE 영역을 지정할 수 있다. 다음 플래그를 설정한다.

  • KUBE_GCE_ZONE=zone - 첫 번째 컨트롤 플레인 노드가 실행될 영역.

다음 샘플 커맨드는 europe-west1-b GCE 영역에 HA 호환 클러스터를 구성한다.

MULTIZONE=true KUBE_GCE_ZONE=europe-west1-b  ENABLE_ETCD_QUORUM_READS=true ./cluster/kube-up.sh

위의 커맨드는 하나의 컨트롤 플레인 노드를 포함하는 클러스터를 생성한다. 그러나 후속 커맨드로 새 컨트롤 플레인 노드를 추가할 수 있다.

새 컨트롤 플레인 노드 추가

HA 호환 클러스터를 생성했다면, 여기에 컨트롤 플레인 노드를 추가할 수 있다. kube-up 스크립트에 다음 플래그를 사용하여 컨트롤 플레인 노드를 추가한다.

  • KUBE_REPLICATE_EXISTING_MASTER=true - 기존 컨트롤 플레인 노드의 복제본을 만든다.

  • KUBE_GCE_ZONE=zone - 컨트롤 플레인 노드가 실행될 영역. 반드시 다른 컨트롤 플레인 노드가 존재하는 영역과 동일한 지역(region)에 있어야 한다.

HA 호환 클러스터를 시작할 때, 상속되는 MULTIZONE이나 ENABLE_ETCD_QUORUM_READS 플래그를 따로 설정할 필요는 없다.

다음 샘플 커맨드는 기존 HA 호환 클러스터에서 컨트롤 플레인 노드를 복제한다.

KUBE_GCE_ZONE=europe-west1-c KUBE_REPLICATE_EXISTING_MASTER=true ./cluster/kube-up.sh

컨트롤 플레인 노드 제거

다음 플래그가 있는 kube-down 스크립트를 사용하여 HA 클러스터에서 컨트롤 플레인 노드를 제거할 수 있다.

  • KUBE_DELETE_NODES=false - kubelet을 삭제하지 않기 위한 것이다.

  • KUBE_GCE_ZONE=zone - 컨트롤 플레인 노드가 제거될 영역.

  • KUBE_REPLICA_NAME=replica_name - (선택) 제거할 컨트롤 플레인 노드의 이름. 명시하지 않으면, 해당 영역의 모든 복제본이 제거된다.

다음 샘플 커맨드는 기존 HA 클러스터에서 컨트롤 플레인 노드를 제거한다.

KUBE_DELETE_NODES=false KUBE_GCE_ZONE=europe-west1-c ./cluster/kube-down.sh

동작에 실패한 컨트롤 플레인 노드 처리

HA 클러스터의 컨트롤 플레인 노드 중 하나가 동작에 실패하면, 클러스터에서 해당 노드를 제거하고 동일한 영역에 새 컨트롤 플레인 노드를 추가하는 것이 가장 좋다. 다음 샘플 커맨드로 이 과정을 시연한다.

  1. 손상된 복제본을 제거한다.
KUBE_DELETE_NODES=false KUBE_GCE_ZONE=replica_zone KUBE_REPLICA_NAME=replica_name ./cluster/kube-down.sh
  1. 기존 복제본을 대신할 새 노드를 추가한다.
KUBE_GCE_ZONE=replica-zone KUBE_REPLICATE_EXISTING_MASTER=true ./cluster/kube-up.sh

HA 클러스터에서 컨트롤 플레인 노드 복제에 관한 모범 사례

  • 다른 영역에 컨트롤 플레인 노드를 배치하도록 한다. 한 영역이 동작에 실패하는 동안, 해당 영역에 있는 컨트롤 플레인 노드도 모두 동작에 실패할 것이다. 영역 장애를 극복하기 위해 노드를 여러 영역에 배치한다 (더 자세한 내용은 멀티 영역를 참조한다).

  • 두 개의 노드로 구성된 컨트롤 플레인은 사용하지 않는다. 두 개의 노드로 구성된 컨트롤 플레인에서의 합의를 위해서는 지속적 상태(persistent state) 변경 시 두 컨트롤 플레인 노드가 모두 정상적으로 동작 중이어야 한다. 결과적으로 두 컨트롤 플레인 노드 모두 필요하고, 둘 중 한 컨트롤 플레인 노드에만 장애가 발생해도 클러스터의 심각한 장애 상태를 초래한다. 따라서 HA 관점에서는 두 개의 노드로 구성된 컨트롤 플레인은 단일 노드로 구성된 컨트롤 플레인보다도 못하다.

  • 컨트롤 플레인 노드를 추가하면, 클러스터의 상태(Etcd)도 새 인스턴스로 복사된다. 클러스터가 크면, 이 상태를 복제하는 시간이 오래 걸릴 수 있다. 이 작업은 etcd 관리 가이드에 기술한 대로 Etcd 데이터 디렉터리를 마이그레이션하여 속도를 높일 수 있다. (향후에 Etcd 데이터 디렉터리 마이그레이션 지원 추가를 고려 중이다)

구현 지침

ha-master-gce

개요

각 컨트롤 플레인 노드는 다음 모드에서 다음 구성 요소를 실행한다.

  • Etcd 인스턴스: 모든 인스턴스는 합의를 사용하여 함께 클러스터화 한다.

  • API 서버: 각 서버는 내부 Etcd와 통신한다. 클러스터의 모든 API 서버가 가용하게 된다.

  • 컨트롤러, 스케줄러, 클러스터 오토스케일러: 임대 방식을 이용한다. 각 인스턴스 중 하나만이 클러스터에서 활성화된다.

  • 애드온 매니저: 각 매니저는 애드온의 동기화를 유지하려고 독립적으로 작업한다.

또한 API 서버 앞단에 외부/내부 트래픽을 라우팅하는 로드 밸런서가 있을 것이다.

로드 밸런싱

두 번째 컨트롤 플레인 노드를 배치할 때, 두 개의 복제본에 대한 로드 밸런서가 생성될 것이고, 첫 번째 복제본의 IP 주소가 로드 밸런서의 IP 주소로 승격된다. 비슷하게 끝에서 두 번째의 컨트롤 플레인 노드를 제거한 후에는 로드 밸런서가 제거되고 해당 IP 주소는 마지막으로 남은 복제본에 할당된다. 로드 밸런서 생성 및 제거는 복잡한 작업이며, 이를 전파하는 데 시간(~20분)이 걸릴 수 있다.

컨트롤 플레인 서비스와 Kubelet

쿠버네티스 서비스에서 최신의 쿠버네티스 API 서버 목록을 유지하는 대신, 시스템은 모든 트래픽을 외부 IP 주소로 보낸다.

  • 단일 노드 컨트롤 플레인의 경우, IP 주소는 단일 컨트롤 플레인 노드를 가리킨다.

  • 고가용성 컨트롤 플레인의 경우, IP 주소는 컨트롤 플레인 노드 앞의 로드밸런서를 가리킨다.

마찬가지로 Kubelet은 외부 IP 주소를 사용하여 컨트롤 플레인과 통신한다.

컨트롤 플레인 노드 인증서

쿠버네티스는 각 컨트롤 플레인 노드의 외부 퍼블릭 IP 주소와 내부 IP 주소를 대상으로 TLS 인증서를 발급한다. 컨트롤 플레인 노드의 임시 퍼블릭 IP 주소에 대한 인증서는 없다. 임시 퍼블릭 IP 주소를 통해 컨트롤 플레인 노드에 접근하려면, TLS 검증을 건너뛰어야 한다.

etcd 클러스터화

etcd를 클러스터로 구축하려면, etcd 인스턴스간 통신에 필요한 포트를 열어야 한다(클러스터 내부 통신용). 이러한 배포를 안전하게 하기 위해, etcd 인스턴스간의 통신은 SSL을 이용하여 승인한다.

API 서버 신원

FEATURE STATE: Kubernetes v1.20 [alpha]

API 서버 식별 기능은 기능 게이트에 의해 제어되며 기본적으로 활성화되지 않는다. API 서버 시작 시 APIServerIdentity 라는 기능 게이트를 활성화하여 API 서버 신원을 활성화할 수 있다.

kube-apiserver \
--feature-gates=APIServerIdentity=true \
 # …다른 플래그는 평소와 같다.

부트스트랩 중에 각 kube-apiserver는 고유한 ID를 자신에게 할당한다. ID는 kube-apiserver-{UUID} 형식이다. 각 kube-apiserver는 kube-system 네임스페이스에 임대를 생성한다. 임대 이름은 kube-apiserver의 고유 ID이다. 임대에는 k8s.io/component=kube-apiserver 라는 레이블이 있다. 각 kube-apiserver는 IdentityLeaseRenewIntervalSeconds (기본값은 10초)마다 임대를 새로 갱신한다. 각 kube-apiserver는 IdentityLeaseDurationSeconds (기본값은 3600초)마다 모든 kube-apiserver 식별 ID 임대를 확인하고, IdentityLeaseDurationSeconds 이상 갱신되지 않은 임대를 삭제한다. IdentityLeaseRenewIntervalSeconds 및 IdentityLeaseDurationSeconds는 kube-apiserver 플래그 identity-lease-renew-interval-seconds 및 identity-lease-duration-seconds로 구성된다.

이 기능을 활성화하는 것은 HA API 서버 조정과 관련된 기능을 사용하기 위한 전제조건이다(예: StorageVersionAPI 기능 게이트).

추가 자료

자동화된 HA 마스터 배포 - 제안 문서

2.7 - 기본 스토리지클래스(StorageClass) 변경하기

이 페이지는 특별한 요구사항이 없는 퍼시스턴트볼륨클레임(PersistentVolumeClaim)의 볼륨을 프로비저닝 하는데 사용되는 기본 스토리지 클래스를 변경하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

왜 기본 스토리지 클래스를 변경하는가?

설치 방법에 따라, 사용자의 쿠버네티스 클러스터는 기본으로 표시된 기존 스토리지클래스와 함께 배포될 수 있다. 이 기본 스토리지클래스는 특정 스토리지 클래스가 필요하지 않은 퍼시스턴트볼륨클레임에 대해 스토리지를 동적으로 프로비저닝 하기 위해 사용된다. 더 자세한 내용은 퍼시스턴트볼륨클레임 문서를 보자.

미리 설치된 기본 스토리지클래스가 사용자의 예상되는 워크로드에 적합하지 않을수도 있다. 예를 들어, 너무 가격이 높은 스토리지를 프로비저닝 해야할 수도 있다. 이런 경우에, 기본 스토리지 클래스를 변경하거나 완전히 비활성화 하여 스토리지의 동적 프로비저닝을 방지할 수 있다.

기본 스토리지클래스를 삭제하는 경우, 사용자의 클러스터에서 구동 중인 애드온 매니저에 의해 자동으로 다시 생성될 수 있으므로 정상적으로 삭제가 되지 않을 수도 있다. 애드온 관리자 및 개별 애드온을 비활성화 하는 방법에 대한 자세한 내용은 설치 문서를 참조하자.

기본 스토리지클래스 변경하기

  1. 사용자의 클러스터에 있는 스토리지클래스 목록을 조회한다.

    kubectl get storageclass

    결과는 아래와 유사하다.

    NAME                 PROVISIONER               AGE
standard (default)   kubernetes.io/gce-pd      1d
gold                 kubernetes.io/gce-pd      1d

    기본 스토리지클래스는 (default) 로 표시되어 있다.

  2. 기본 스토리지클래스를 기본값이 아닌 것으로 표시한다.

    기본 스토리지클래스에는 storageclass.kubernetes.io/is-default-class 의 값이 true 로 설정되어 있다. 다른 값이거나 어노테이션이 없을 경우 false 로 처리된다.

    스토리지클래스를 기본값이 아닌 것으로 표시하려면, 그 값을 false 로 변경해야 한다.

    kubectl patch storageclass standard -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

    여기서 standard 는 사용자가 선택한 스토리지클래스의 이름이다.

  3. 스토리지클래스를 기본값으로 표시한다.

    이전 과정과 유사하게, 어노테이션을 추가/설정해야 한다. storageclass.kubernetes.io/is-default-class=true.

    kubectl patch storageclass gold -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

    최대 1개의 스토리지클래스를 기본값으로 표시할 수 있다는 것을 알아두자. 만약 2개 이상이 기본값으로 표시되면, 명시적으로 storageClassName 가 지정되지 않은 PersistentVolumeClaim 은 생성될 수 없다.

  4. 사용자가 선택한 스토리지클래스가 기본값으로 되어있는지 확인한다.

    kubectl get storageclass

    결과는 아래와 유사하다.

    NAME             PROVISIONER               AGE
standard         kubernetes.io/gce-pd      1d
gold (default)   kubernetes.io/gce-pd      1d

다음 내용

2.8 - 네트워크 폴리시(Network Policy) 선언하기

이 문서는 사용자가 쿠버네티스 네트워크폴리시 API를 사용하여 파드(Pod)가 서로 통신하는 방법을 제어하는 네트워크 폴리시를 선언하는데 도움을 준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: v1.8. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

네트워크 폴리시를 지원하는 네트워크 제공자를 구성하였는지 확인해야 한다. 다음과 같이 네트워크폴리시를 지원하는 많은 네트워크 제공자들이 있다.

nginx 디플로이먼트(Deployment)를 생성하고 서비스(Service)를 통해 노출하기

쿠버네티스 네트워크 폴리시가 어떻게 동작하는지 확인하기 위해서, nginx 디플로이먼트를 생성한다.

kubectl create deployment nginx --image=nginx

deployment.apps/nginx created

nginx 라는 이름의 서비스를 통해 디플로이먼트를 노출한다.

kubectl expose deployment nginx --port=80

service/nginx exposed

위 명령어들은 nginx 파드에 대한 디플로이먼트를 생성하고, nginx 라는 이름의 서비스를 통해 디플로이먼트를 노출한다. nginx 파드와 디플로이먼트는 default 네임스페이스(namespace)에 존재한다.

kubectl get svc,pod

NAME                        CLUSTER-IP    EXTERNAL-IP   PORT(S)    AGE
service/kubernetes          10.100.0.1    <none>        443/TCP    46m
service/nginx               10.100.0.16   <none>        80/TCP     33s

NAME                        READY         STATUS        RESTARTS   AGE
pod/nginx-701339712-e0qfq   1/1           Running       0          35s

다른 파드에서 접근하여 서비스 테스트하기

사용자는 다른 파드에서 새 nginx 서비스에 접근할 수 있어야 한다. default 네임스페이스에 있는 다른 파드에서 nginx 서비스에 접근하기 위하여, busybox 컨테이너를 생성한다.

kubectl run busybox --rm -ti --image=busybox -- /bin/sh

사용자 쉘에서, 다음의 명령을 실행한다.

wget --spider --timeout=1 nginx

Connecting to nginx (10.100.0.16:80)
remote file exists

nginx 서비스에 대해 접근 제한하기

access: true 레이블을 가지고 있는 파드만 nginx 서비스에 접근할 수 있도록 하기 위하여, 다음과 같은 네트워크폴리시 오브젝트를 생성한다.

service/networking/nginx-policy.yaml 
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: access-nginx
spec:
  podSelector:
    matchLabels:
      app: nginx
  ingress:
  - from:
    - podSelector:
        matchLabels:
          access: "true"

네트워크폴리시 오브젝트의 이름은 유효한 DNS 서브도메인 이름이어야 한다.

참고: 네트워크폴리시는 정책이 적용되는 파드의 그룹을 선택하는 podSelector 를 포함한다. 사용자는 이 정책이 app=nginx 레이블을 갖는 파드를 선택하는 것을 볼 수 있다. 레이블은 nginx 디플로이먼트에 있는 파드에 자동으로 추가된다. 빈 podSelector 는 네임스페이스의 모든 파드를 선택한다.

서비스에 정책 할당하기

kubectl을 사용하여 위 nginx-policy.yaml 파일로부터 네트워크폴리시를 생성한다.

kubectl apply -f https://k8s.io/examples/service/networking/nginx-policy.yaml

networkpolicy.networking.k8s.io/access-nginx created

access 레이블이 정의되지 않은 서비스에 접근 테스트

올바른 레이블이 없는 파드에서 nginx 서비스에 접근하려 할 경우, 요청 타임 아웃이 발생한다.

kubectl run busybox --rm -ti --image=busybox -- /bin/sh

사용자 쉘에서, 다음의 명령을 실행한다.

wget --spider --timeout=1 nginx

Connecting to nginx (10.100.0.16:80)
wget: download timed out

접근 레이블을 정의하고 다시 테스트

사용자는 요청이 허용되도록 하기 위하여 올바른 레이블을 갖는 파드를 생성한다.

kubectl run busybox --rm -ti --labels="access=true" --image=busybox -- /bin/sh

사용자 쉘에서, 다음의 명령을 실행한다.

wget --spider --timeout=1 nginx

Connecting to nginx (10.100.0.16:80)
remote file exists

2.9 - 노드에 대한 확장 리소스 알리기

이 페이지는 노드의 확장 리소스를 지정하는 방법을 보여준다. 확장 리소스를 통해 클러스터 관리자는 쿠버네티스에게 알려지지 않은 노드-레벨 리소스를 알릴 수 있다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

노드의 이름을 확인한다

kubectl get nodes

이 연습에 사용할 노드 중 하나를 선택한다.

노드 중 하나에 새로운 확장 리소스를 알린다

노드에서 새로운 확장 리소스를 알리려면, 쿠버네티스 API 서버에 HTTP PATCH 요청을 보낸다. 예를 들어, 노드 중 하나에 4개의 동글(dongle)이 있다고 가정한다. 다음은 노드에 4개의 동글 리소스를 알리는 PATCH 요청의 예이다.

PATCH /api/v1/nodes/<your-node-name>/status HTTP/1.1
Accept: application/json
Content-Type: application/json-patch+json
Host: k8s-master:8080

[
  {
    "op": "add",
    "path": "/status/capacity/example.com~1dongle",
    "value": "4"
  }
]

참고로 쿠버네티스는 동글이 무엇인지 또는 동글이 무엇을 위한 것인지 알 필요가 없다. 위의 PATCH 요청은 노드에 동글이라고 하는 네 가지 항목이 있음을 쿠버네티스에 알려준다.

쿠버네티스 API 서버에 요청을 쉽게 보낼 수 있도록 프록시를 시작한다.

kubectl proxy

다른 명령 창에서 HTTP PATCH 요청을 보낸다. <your-node-name> 을 노드의 이름으로 바꾼다.

curl --header "Content-Type: application/json-patch+json" \
--request PATCH \
--data '[{"op": "add", "path": "/status/capacity/example.com~1dongle", "value": "4"}]' \
http://localhost:8001/api/v1/nodes/<your-node-name>/status
참고: 이전 요청에서 ~1 은 패치 경로의 / 문자에 대한 인코딩이다. JSON-Patch의 작업 경로값은 JSON-Pointer로 해석된다. 자세한 내용은 IETF RFC 6901의 섹션 3을 참고한다.

출력은 노드가 4개의 동글 용량을 가졌음을 나타낸다.

"capacity": {
  "cpu": "2",
  "memory": "2049008Ki",
  "example.com/dongle": "4",

노드의 정보를 확인한다.

kubectl describe node <your-node-name>

다시 한 번, 출력에 동글 리소스가 표시된다.

Capacity:
 cpu:  2
 memory:  2049008Ki
 example.com/dongle:  4

이제, 애플리케이션 개발자는 특정 개수의 동글을 요청하는 파드를 만들 수 있다. 컨테이너에 확장 리소스 할당하기를 참고한다.

토론

확장 리소스는 메모리 및 CPU 리소스와 비슷하다. 예를 들어, 노드에서 실행 중인 모든 컴포넌트가 공유할 특정 양의 메모리와 CPU가 노드에 있는 것처럼, 노드에서 실행 중인 모든 컴포넌트가 특정 동글을 공유할 수 있다. 또한 애플리케이션 개발자가 특정 양의 메모리와 CPU를 요청하는 파드를 생성할 수 있는 것처럼, 특정 동글을 요청하는 파드를 생성할 수 있다.

확장 리소스는 쿠버네티스에게 불투명하다. 쿠버네티스는 그것들이 무엇인지 전혀 모른다. 쿠버네티스는 노드에 특정 개수의 노드만 있다는 것을 알고 있다. 확장 리소스는 정수로 알려야 한다. 예를 들어, 노드는 4.5개의 동글이 아닌, 4개의 동글을 알릴 수 있다.

스토리지 예제

노드에 800GiB의 특별한 종류의 디스크 스토리지가 있다고 가정한다. example.com/special-storage와 같은 특별한 스토리지의 이름을 생성할 수 있다. 그런 다음 특정 크기, 100GiB의 청크로 알릴 수 있다. 이 경우, 노드에는 example.com/special-storage 유형의 8가지 리소스가 있다고 알린다.

Capacity:
 ...
 example.com/special-storage: 8

이 특별한 스토리지에 대한 임의 요청을 허용하려면, 1바이트 크기의 청크로 특별한 스토리지를 알릴 수 있다. 이 경우, example.com/special-storage 유형의 800Gi 리소스를 알린다.

Capacity:
 ...
 example.com/special-storage:  800Gi

그런 다음 컨테이너는 최대 800Gi의 임의 바이트 수의 특별한 스토리지를 요청할 수 있다.

정리

다음은 노드에서 동글 알림을 제거하는 PATCH 요청이다.

PATCH /api/v1/nodes/<your-node-name>/status HTTP/1.1
Accept: application/json
Content-Type: application/json-patch+json
Host: k8s-master:8080

[
  {
    "op": "remove",
    "path": "/status/capacity/example.com~1dongle",
  }
]

쿠버네티스 API 서버에 요청을 쉽게 보낼 수 있도록 프록시를 시작한다.

kubectl proxy

다른 명령 창에서 HTTP PATCH 요청을 보낸다. <your-node-name>을 노드의 이름으로 바꾼다.

curl --header "Content-Type: application/json-patch+json" \
--request PATCH \
--data '[{"op": "remove", "path": "/status/capacity/example.com~1dongle"}]' \
http://localhost:8001/api/v1/nodes/<your-node-name>/status

동글 알림이 제거되었는지 확인한다.

kubectl describe node <your-node-name> | grep dongle

(출력이 보이지 않아야 함)

다음 내용

애플리케이션 개발자를 위한 문서

클러스터 관리자를 위한 문서

2.10 - 서비스 디스커버리를 위해 CoreDNS 사용하기

이 페이지는 CoreDNS 업그레이드 프로세스와 kube-dns 대신 CoreDNS를 설치하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: v1.9. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

CoreDNS 소개

CoreDNS는 쿠버네티스 클러스터의 DNS 역할을 수행할 수 있는, 유연하고 확장 가능한 DNS 서버이다. 쿠버네티스와 동일하게, CoreDNS 프로젝트도 CNCF가 관리한다.

사용자는 기존 디플로이먼트인 kube-dns를 교체하거나, 클러스터를 배포하고 업그레이드하는 kubeadm과 같은 툴을 사용하여 클러스터 안의 kube-dns 대신 CoreDNS를 사용할 수 있다.

CoreDNS 설치

Kube-dns의 배포나 교체에 관한 매뉴얼은 CoreDNS GitHub 프로젝트에 있는 문서를 확인하자.

CoreDNS로 이관하기

Kubeadm을 사용해 기존 클러스터 업그레이드하기

쿠버네티스 버전 1.10 이상에서, kube-dns 를 사용하는 클러스터를 업그레이드하기 위하여 kubeadm 을 사용할 때 CoreDNS로 전환할 수도 있다. 이 경우, kubeadm 은 kube-dns 컨피그맵(ConfigMap)을 기반으로 스텁 도메인(stub domain), 업스트림 네임 서버의 설정을 유지하며 CoreDNS 설정("Corefile")을 생성한다.

만약 kube-dns에서 CoreDNS로 이동하는 경우, 업그레이드 과정에서 기능 게이트의 CoreDNS 값을 true 로 설정해야 한다. 예를 들어, v1.11.0 로 업그레이드 하는 경우는 다음과 같다.

kubeadm upgrade apply v1.11.0 --feature-gates=CoreDNS=true

쿠버네티스 1.13 이상에서 기능 게이트의 CoreDNS 항목은 제거되었으며, CoreDNS가 기본적으로 사용된다.

1.11 미만 버전일 경우 업그레이드 과정에서 만들어진 파일이 Corefile을 덮어쓴다. 만약 컨피그맵을 사용자 정의한 경우, 기존의 컨피그맵을 저장해야 한다. 새 컨피그맵이 시작된 후에 변경 사항을 다시 적용해야 할 수도 있다.

만약 쿠버네티스 1.11 이상 버전에서 CoreDNS를 사용하는 경우, 업그레이드 과정에서, 기존의 Corefile이 유지된다.

쿠버네티스 버전 1.21에서, kubeadm 의 kube-dns 지원 기능이 삭제되었다.

CoreDNS 업그레이드하기

CoreDNS는 쿠버네티스 1.9 버전부터 사용할 수 있다. 쿠버네티스와 함께 제공되는 CoreDNS의 버전과 CoreDNS의 변경 사항은 여기에서 확인할 수 있다.

CoreDNS는 사용자 정의 이미지를 사용하거나 CoreDNS만 업그레이드 하려는 경우에 수동으로 업그레이드할 수 있다. 업그레이드를 원활하게 수행하는 데 유용한 가이드라인 및 연습을 참고하자.

CoreDNS 튜닝하기

리소스 활용이 중요한 경우, CoreDNS 구성을 조정하는 것이 유용할 수 있다. 더 자세한 내용은 CoreDNS 스케일링에 대한 설명서를 확인하자.

다음 내용

Corefile 을 수정하여 kube-dns 보다 더 많은 유스케이스를 지원하도록 CoreDNS를 구성할 수 있다. 더 자세한 내용은 CoreDNS 웹사이트을 확인하자.

2.11 - 쿠버네티스 API를 사용하여 클러스터에 접근하기

이 페이지는 쿠버네티스 API를 사용하여 클러스터에 접근하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

쿠버네티스 API에 접근

kubectl을 사용하여 처음으로 접근

쿠버네티스 API에 처음 접근하는 경우, 쿠버네티스 커맨드 라인 도구인 kubectl 을 사용한다.

클러스터에 접근하려면, 클러스터 위치를 알고 접근할 수 있는 자격 증명이 있어야 한다. 일반적으로, 시작하기 가이드를 통해 작업하거나, 다른 사람이 클러스터를 설정하고 자격 증명과 위치를 제공할 때 자동으로 설정된다.

다음의 명령으로 kubectl이 알고 있는 위치와 자격 증명을 확인한다.

kubectl config view

많은 예제는 kubectl 사용에 대한 소개를 제공한다. 전체 문서는 kubectl 매뉴얼에 있다.

REST API에 직접 접근

kubectl은 API 서버 찾기와 인증을 처리한다. curl 이나 wget 과 같은 http 클라이언트 또는 브라우저를 사용하여 REST API에 직접 접근하려는 경우, API 서버를 찾고 인증할 수 있는 여러 가지 방법이 있다.

  1. 프록시 모드에서 kubectl을 실행한다(권장). 이 방법은 저장된 API 서버 위치를 사용하고 자체 서명된 인증서를 사용하여 API 서버의 ID를 확인하므로 권장한다. 이 방법을 사용하면 중간자(man-in-the-middle, MITM) 공격이 불가능하다.
  2. 또는, 위치와 자격 증명을 http 클라이언트에 직접 제공할 수 있다. 이 방법은 프록시를 혼란스럽게 하는 클라이언트 코드와 동작한다. 중간자 공격으로부터 보호하려면, 브라우저로 루트 인증서를 가져와야 한다.

Go 또는 Python 클라이언트 라이브러리를 사용하면 프록시 모드에서 kubectl에 접근할 수 있다.

kubectl 프록시 사용

다음 명령은 kubectl을 리버스 프록시로 작동하는 모드에서 실행한다. API 서버 찾기와 인증을 처리한다.

다음과 같이 실행한다.

kubectl proxy --port=8080 &

자세한 내용은 kubectl 프록시를 참고한다.

그런 다음 curl, wget 또는 브라우저를 사용하여 API를 탐색할 수 있다.

curl http://localhost:8080/api/

출력은 다음과 비슷하다.

{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

kubectl 프록시 없이 접근

다음과 같이 인증 토큰을 API 서버에 직접 전달하여 kubectl 프록시 사용을 피할 수 있다.

grep/cut 방식을 사용한다.

# .KUBECONFIG에 여러 콘텍스트가 있을 수 있으므로, 가능한 모든 클러스터를 확인한다.
kubectl config view -o jsonpath='{"Cluster name\tServer\n"}{range .clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'

# 위의 출력에서 상호 작용하려는 클러스터의 이름을 선택한다.
export CLUSTER_NAME="some_server_name"

# 클러스터 이름을 참조하는 API 서버를 가리킨다.
APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")

# 토큰 값을 얻는다
TOKEN=$(kubectl get secrets -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='default')].data.token}"|base64 --decode)

# TOKEN으로 API 탐색
curl -X GET $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure

출력은 다음과 비슷하다.

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

jsonpath 방식을 사용한다.

APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
TOKEN=$(kubectl get secret $(kubectl get serviceaccount default -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.token}' | base64 --decode )
curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

위의 예는 --insecure 플래그를 사용한다. 이로 인해 MITM 공격이 발생할 수 있다. kubectl이 클러스터에 접근하면 저장된 루트 인증서와 클라이언트 인증서를 사용하여 서버에 접근한다. (~/.kube 디렉터리에 설치된다.) 클러스터 인증서는 일반적으로 자체 서명되므로, http 클라이언트가 루트 인증서를 사용하도록 하려면 특별한 구성이 필요할 수 있다.

일부 클러스터에서, API 서버는 인증이 필요하지 않다. 로컬 호스트에서 제공되거나, 방화벽으로 보호될 수 있다. 이에 대한 표준은 없다. 쿠버네티스 API에 대한 접근 제어은 클러스터 관리자로서 이를 구성하는 방법에 대해 설명한다. 이러한 접근 방식은 향후 고 가용성 지원과 충돌할 수 있다.

API에 프로그래밍 방식으로 접근

쿠버네티스는 공식적으로 Go, Python, Java, dotnet, Javascript 및 Haskell 용 클라이언트 라이브러리를 지원한다. 쿠버네티스 팀이 아닌 작성자가 제공하고 유지 관리하는 다른 클라이언트 라이브러리가 있다. 다른 언어에서 API에 접근하고 인증하는 방법에 대해서는 클라이언트 라이브러리를 참고한다.

Go 클라이언트

  • 라이브러리를 얻으려면, 다음 명령을 실행한다. go get k8s.io/client-go@kubernetes-<kubernetes-version-number> 어떤 버전이 지원되는지를 확인하려면 https://github.com/kubernetes/client-go/releases를 참고한다.
  • client-go 클라이언트 위에 애플리케이션을 작성한다.
참고: client-go는 자체 API 오브젝트를 정의하므로, 필요한 경우, 기본 리포지터리가 아닌 client-go에서 API 정의를 가져온다. 예를 들어, import "k8s.io/client-go/kubernetes" 가 맞다.

Go 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

package main

import (
  "context"
  "fmt"
  "k8s.io/apimachinery/pkg/apis/meta/v1"
  "k8s.io/client-go/kubernetes"
  "k8s.io/client-go/tools/clientcmd"
)

func main() {
  // kubeconfig에서 현재 콘텍스트를 사용한다
  // path-to-kubeconfig -- 예를 들어, /root/.kube/config
  config, _ := clientcmd.BuildConfigFromFlags("", "<path-to-kubeconfig>")
  // clientset을 생성한다
  clientset, _ := kubernetes.NewForConfig(config)
  // 파드를 나열하기 위해 API에 접근한다
  pods, _ := clientset.CoreV1().Pods("").List(context.TODO(), v1.ListOptions{})
  fmt.Printf("There are %d pods in the cluster\n", len(pods.Items))
}

애플리케이션이 클러스터 내의 파드로 배치된 경우, 파드 내에서 API 접근을 참고한다.

Python 클라이언트

Python 클라이언트를 사용하려면, 다음 명령을 실행한다. pip install kubernetes 추가 설치 옵션은 Python Client Library 페이지를 참고한다.

Python 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

from kubernetes import client, config

config.load_kube_config()

v1=client.CoreV1Api()
print("Listing pods with their IPs:")
ret = v1.list_pod_for_all_namespaces(watch=False)
for i in ret.items:
    print("%s\t%s\t%s" % (i.status.pod_ip, i.metadata.namespace, i.metadata.name))

Java 클라이언트

Java 클라이언트를 설치하려면, 다음을 실행한다.

# java 라이브러리를 클론한다
git clone --recursive https://github.com/kubernetes-client/java

# 프로젝트 아티팩트, POM 등을 설치한다
cd java
mvn install

어떤 버전이 지원되는지를 확인하려면 https://github.com/kubernetes-client/java/releases를 참고한다.

Java 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

package io.kubernetes.client.examples;

import io.kubernetes.client.ApiClient;
import io.kubernetes.client.ApiException;
import io.kubernetes.client.Configuration;
import io.kubernetes.client.apis.CoreV1Api;
import io.kubernetes.client.models.V1Pod;
import io.kubernetes.client.models.V1PodList;
import io.kubernetes.client.util.ClientBuilder;
import io.kubernetes.client.util.KubeConfig;
import java.io.FileReader;
import java.io.IOException;

/**
 * 쿠버네티스 클러스터 외부의 애플리케이션에서 Java API를 사용하는 방법에 대한 간단한 예
 *
 * <p>이것을 실행하는 가장 쉬운 방법: mvn exec:java
 * -Dexec.mainClass="io.kubernetes.client.examples.KubeConfigFileClientExample"
 *
 */
public class KubeConfigFileClientExample {
  public static void main(String[] args) throws IOException, ApiException {

    // KubeConfig의 파일 경로
    String kubeConfigPath = "~/.kube/config";

    // 파일시스템에서 클러스터 외부 구성인 kubeconfig 로드
    ApiClient client =
        ClientBuilder.kubeconfig(KubeConfig.loadKubeConfig(new FileReader(kubeConfigPath))).build();

    // 전역 디폴트 api-client를 위에서 정의한 클러스터 내 클라이언트로 설정
    Configuration.setDefaultApiClient(client);

    // CoreV1Api는 전역 구성에서 디폴트 api-client를 로드
    CoreV1Api api = new CoreV1Api();

    // CoreV1Api 클라이언트를 호출한다
    V1PodList list = api.listPodForAllNamespaces(null, null, null, null, null, null, null, null, null);
    System.out.println("Listing all pods: ");
    for (V1Pod item : list.getItems()) {
      System.out.println(item.getMetadata().getName());
    }
  }
}

dotnet 클라이언트

dotnet 클라이언트를 사용하려면, 다음 명령을 실행한다. dotnet add package KubernetesClient --version 1.6.1 추가 설치 옵션은 dotnet Client Library 페이지를 참고한다. 어떤 버전이 지원되는지를 확인하려면 https://github.com/kubernetes-client/csharp/releases를 참고한다.

dotnet 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

using System;
using k8s;

namespace simple
{
    internal class PodList
    {
        private static void Main(string[] args)
        {
            var config = KubernetesClientConfiguration.BuildDefaultConfig();
            IKubernetes client = new Kubernetes(config);
            Console.WriteLine("Starting Request!");

            var list = client.ListNamespacedPod("default");
            foreach (var item in list.Items)
            {
                Console.WriteLine(item.Metadata.Name);
            }
            if (list.Items.Count == 0)
            {
                Console.WriteLine("Empty!");
            }
        }
    }
}

JavaScript 클라이언트

JavaScript 클라이언트를 설치하려면, 다음 명령을 실행한다. npm install @kubernetes/client-node 어떤 버전이 지원되는지를 확인하려면 https://github.com/kubernetes-client/javascript/releases를 참고한다.

JavaScript 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

const k8s = require('@kubernetes/client-node');

const kc = new k8s.KubeConfig();
kc.loadFromDefault();

const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

k8sApi.listNamespacedPod('default').then((res) => {
    console.log(res.body);
});

Haskell 클라이언트

어떤 버전이 지원되는지를 확인하려면 https://github.com/kubernetes-client/haskell/releases를 참고한다.

Haskell 클라이언트는 kubectl CLI가 API 서버를 찾아 인증하기 위해 사용하는 것과 동일한 kubeconfig 파일을 사용할 수 있다. 이 예제를 참고한다.

exampleWithKubeConfig :: IO ()
exampleWithKubeConfig = do
    oidcCache <- atomically $ newTVar $ Map.fromList []
    (mgr, kcfg) <- mkKubeClientConfig oidcCache $ KubeConfigFile "/path/to/kubeconfig"
    dispatchMime
            mgr
            kcfg
            (CoreV1.listPodForAllNamespaces (Accept MimeJSON))
        >>= print

다음 내용

2.12 - 클러스터에서 실행되는 서비스에 접근

이 페이지는 쿠버네티스 클러스터에서 실행되는 서비스에 연결하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

클러스터에서 실행되는 서비스에 접근

쿠버네티스에서, 노드, 파드 및 서비스는 모두 고유한 IP를 가진다. 당신의 데스크탑 PC와 같은 클러스터 외부 장비에서는 클러스터 상의 노드 IP, 파드 IP, 서비스 IP로 라우팅되지 않아서 접근할 수 없을 것이다.

연결하는 방법

클러스터 외부에서 노드, 파드 및 서비스에 접속하기 위한 몇 가지 옵션이 있다.

  • 퍼블릭 IP를 통해 서비스에 접근한다.
    • 클러스터 외부에서 접근할 수 있도록 NodePort 또는 LoadBalancer 타입의 서비스를 사용한다. 서비스와 kubectl expose 문서를 참고한다.
    • 클러스터 환경에 따라, 서비스는 회사 네트워크에만 노출되기도 하며, 인터넷에 노출되는 경우도 있다. 이 경우 노출되는 서비스의 보안 여부를 고려해야 한다. 해당 서비스는 자체적으로 인증을 수행하는가?
    • 파드는 서비스 뒤에 위치시킨다. 디버깅과 같은 목적으로 레플리카 집합에서 특정 파드에 접근하려면, 파드에 고유한 레이블을 배치하고 이 레이블을 선택하는 새 서비스를 생성한다.
    • 대부분의 경우, 애플리케이션 개발자가 nodeIP를 통해 노드에 직접 접근할 필요는 없다.
  • 프록시 작업(Proxy Verb)을 사용하여 서비스, 노드 또는 파드에 접근한다.
    • 원격 서비스에 접근하기 전에 apiserver 인증과 권한 부여를 수행한다. 서비스가 인터넷에 노출되거나, 노드 IP의 포트에 접근하거나, 디버깅하기에 충분히 안전하지 않은 경우 사용한다.
    • 프록시는 일부 웹 애플리케이션에 문제를 일으킬 수 있다.
    • HTTP/HTTPS에서만 작동한다.
    • 여기에 설명되어 있다.
  • 클러스터의 노드 또는 파드에서 접근한다.
    • 파드를 실행한 다음, kubectl exec를 사용하여 셸에 연결한다. 해당 셸에서 다른 노드, 파드 및 서비스에 연결한다.
    • 일부 클러스터는 클러스터의 노드로 ssh를 통해 접근하는 것을 허용한다. 거기에서 클러스터 서비스에 접근할 수 있다. 이것은 비표준 방법이며, 일부 클러스터에서는 작동하지만 다른 클러스터에서는 작동하지 않는다. 브라우저 및 기타 도구가 설치되거나 설치되지 않을 수 있다. 클러스터 DNS가 작동하지 않을 수도 있다.

빌트인 서비스 검색

일반적으로 kube-system에 의해 클러스터에 실행되는 몇 가지 서비스가 있다. kubectl cluster-info 커맨드로 이 서비스의 리스트를 볼 수 있다.

kubectl cluster-info

출력은 다음과 비슷하다.

Kubernetes master is running at https://104.197.5.247
elasticsearch-logging is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy
kibana-logging is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/kibana-logging/proxy
kube-dns is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/kube-dns/proxy
grafana is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/monitoring-grafana/proxy
heapster is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/monitoring-heapster/proxy

각 서비스에 접근하기 위한 프록시-작업 URL이 표시된다. 예를 들어, 이 클러스터에는 https://104.197.5.247/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy/ 로 접근할 수 있는 (Elasticsearch를 사용한) 클러스터 수준 로깅이 활성화되어 있다. 적합한 자격 증명이 전달되는 경우나 kubectl proxy를 통해 도달할 수 있다. 예를 들어 다음의 URL에서 확인할 수 있다. http://localhost:8080/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy/.

참고: 자격 증명을 전달하거나 kubectl proxy를 사용하는 방법은 쿠버네티스 API를 사용하여 클러스터에 접근하기를 참고한다.

apiserver 프록시 URL 수동 구성

위에서 언급한 것처럼, kubectl cluster-info 명령을 사용하여 서비스의 프록시 URL을 검색한다. 서비스 엔드포인트, 접미사 및 매개 변수를 포함하는 프록시 URL을 작성하려면, 서비스의 프록시 URL에 추가하면 된다. http://kubernetes_master_address/api/v1/namespaces/namespace_name/services/[https:]service_name[:port_name]/proxy

포트에 대한 이름을 지정하지 않은 경우, URL에 port_name 을 지정할 필요가 없다.

예제

  • Elasticsearch 서비스 엔드포인트 _search?q=user:kimchy 에 접근하려면, 다음을 사용한다.

    http://104.197.5.247/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy/_search?q=user:kimchy

  • Elasticsearch 클러스터 상태 정보 _cluster/health?pretty=true 에 접근하려면, 다음을 사용한다.

    https://104.197.5.247/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy/_cluster/health?pretty=true

    상태 정보는 다음과 비슷하다.

    {
  "cluster_name" : "kubernetes_logging",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 5,
  "active_shards" : 5,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 5
}

  • https Elasticsearch 서비스 상태 정보 _cluster/health?pretty=true 에 접근하려면, 다음을 사용한다.

    https://104.197.5.247/api/v1/namespaces/kube-system/services/https:elasticsearch-logging/proxy/_cluster/health?pretty=true

웹 브라우저를 사용하여 클러스터에서 실행되는 서비스에 접근

브라우저의 주소 표시줄에 apiserver 프록시 URL을 넣을 수 있다. 그러나,

  • 웹 브라우저는 일반적으로 토큰을 전달할 수 없으므로, 기본 (비밀번호) 인증을 사용해야 할 수도 있다. Apiserver는 기본 인증을 수락하도록 구성할 수 있지만, 클러스터는 기본 인증을 수락하도록 구성되지 않을 수 있다.
  • 일부 웹 앱, 특히 프록시 경로 접두사를 인식하지 못하는 방식으로 URL을 구성하는 클라이언트 측 자바스크립트가 있는 웹 앱이 작동하지 않을 수 있다.

2.13 - 퍼시스턴트볼륨 반환 정책 변경하기

이 페이지는 쿠버네티스 퍼시트턴트볼륨(PersistentVolume)의 반환 정책을 변경하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

왜 퍼시스턴트볼륨 반환 정책을 변경하는가?

퍼시스턴트볼륨은 "Retain(보존)", "Recycle(재활용)", "Delete(삭제)" 를 포함한 다양한 반환 정책을 갖는다. 동적으로 프로비저닝 된 퍼시스턴트볼륨의 경우 기본 반환 정책은 "Delete" 이다. 이는 사용자가 해당 PersistentVolumeClaim 을 삭제하면, 동적으로 프로비저닝 된 볼륨이 자동적으로 삭제됨을 의미한다. 볼륨에 중요한 데이터가 포함된 경우, 이러한 자동 삭제는 부적절 할 수 있다. 이 경우에는, "Retain" 정책을 사용하는 것이 더 적합하다. "Retain" 정책에서, 사용자가 퍼시스턴트볼륨클레임을 삭제할 경우 해당하는 퍼시스턴트볼륨은 삭제되지 않는다. 대신, Released 단계로 이동되어, 모든 데이터를 수동으로 복구할 수 있다.

퍼시스턴트볼륨 반환 정책 변경하기

  1. 사용자의 클러스터에서 퍼시스턴트볼륨을 조회한다.

    kubectl get pv

    결과는 아래와 같다.

     NAME                                       CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS    CLAIM             STORAGECLASS     REASON    AGE
 pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Delete          Bound     default/claim1    manual                     10s
 pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Delete          Bound     default/claim2    manual                     6s
 pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Delete          Bound     default/claim3    manual                     3s

    이 목록은 동적으로 프로비저닝 된 볼륨을 쉽게 식별할 수 있도록 각 볼륨에 바인딩 되어 있는 퍼시스턴트볼륨클레임(PersistentVolumeClaim)의 이름도 포함한다.

  2. 사용자의 퍼시스턴트볼륨 중 하나를 선택한 후에 반환 정책을 변경한다.

    kubectl patch pv <your-pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

    <your-pv-name> 는 사용자가 선택한 퍼시스턴트볼륨의 이름이다.

    참고: 
    윈도우에서는, 공백이 포함된 모든 JSONPath 템플릿에 _겹_ 따옴표를 사용해야 한다.(bash에 대해 위에서 표시된 홑 따옴표가 아니다.) 따라서 템플릿의 모든 표현식에서 홑 따옴표를 쓰거나, 이스케이프 처리된 겹 따옴표를 써야 한다. 예를 들면 다음과 같다.

    kubectl patch pv <your-pv-name> -p "{\"spec\":{\"persistentVolumeReclaimPolicy\":\"Retain\"}}"

  3. 선택한 PersistentVolume이 올바른 정책을 갖는지 확인한다.

    kubectl get pv

    결과는 아래와 같다.

     NAME                                       CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS    CLAIM             STORAGECLASS     REASON    AGE
 pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Delete          Bound     default/claim1    manual                     40s
 pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Delete          Bound     default/claim2    manual                     36s
 pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94   4Gi        RWO           Retain          Bound     default/claim3    manual                     33s

    위 결과에서, default/claim3 클레임과 바인딩 되어 있는 볼륨이 Retain 반환 정책을 갖는 것을 볼 수 있다. 사용자가 default/claim3 클레임을 삭제할 경우, 볼륨은 자동으로 삭제 되지 않는다.

다음 내용

Reference

3 - 파드와 컨테이너 설정

파드와 컨테이너에 대한 공통 구성 태스크들을 수행한다.

3.1 - 컨테이너 및 파드 메모리 리소스 할당

이 페이지는 메모리 요청량 과 메모리 상한 을 컨테이너에 어떻게 지정하는지 보여준다. 컨테이너는 요청량 만큼의 메모리 확보가 보장되나 상한보다 더 많은 메모리는 사용할 수 없다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

클러스터의 각 노드에 최소 300 MiB 메모리가 있어야 한다.

이 페이지의 몇 가지 단계를 수행하기 위해서는 클러스터 내 metrics-server 서비스 실행이 필요하다. 이미 실행 중인 metrics-server가 있다면 다음 단계를 건너뛸 수 있다.

Minikube를 사용 중이라면, 다음 명령어를 실행해 metric-server를 활성화할 수 있다.

minikube addons enable metrics-server

metric-server가 실행 중인지 확인하거나 다른 제공자의 리소스 메트릭 API (metrics.k8s.io)를 확인하기 위해 다음의 명령어를 실행한다.

kubectl get apiservices

리소스 메트릭 API를 사용할 수 있다면 출력에 metrics.k8s.io에 대한 참조가 포함되어 있다.

NAME      
v1beta1.metrics.k8s.io

네임스페이스 생성

이 예제에서 생성할 자원과 클러스터 내 나머지를 분리하기 위해 네임스페이스를 생성한다.

kubectl create namespace mem-example

메모리 요청량 및 상한을 지정

컨테이너에 메모리 요청량을 지정하기 위해서는 컨테이너의 리소스 매니페스트에 resources:requests 필드를 포함한다. 리소스 상한을 지정하기 위해서는 resources:limits 필드를 포함한다.

이 예제에서 하나의 컨테이너를 가진 파드를 생성한다. 생성된 컨테이너는 100 MiB 메모리 요청량과 200 MiB 메모리 상한을 갖는다. 이 것이 파드 구성 파일이다.

pods/resource/memory-request-limit.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: memory-demo
  namespace: mem-example
spec:
  containers:
  - name: memory-demo-ctr
    image: polinux/stress
    resources:
      limits:
        memory: "200Mi"
      requests:
        memory: "100Mi"
    command: ["stress"]
    args: ["--vm", "1", "--vm-bytes", "150M", "--vm-hang", "1"]

구성 파일 내 args 섹션은 컨테이너가 시작될 때 아규먼트를 제공한다. "--vm-bytes", "150M" 아규먼트는 컨테이너가 150 MiB 할당을 시도 하도록 한다.

파드 생성:

kubectl apply -f https://k8s.io/examples/pods/resource/memory-request-limit.yaml --namespace=mem-example

파드 컨테이너가 실행 중인지 확인:

kubectl get pod memory-demo --namespace=mem-example

파드에 대한 자세한 정보 보기:

kubectl get pod memory-demo --output=yaml --namespace=mem-example

출력은 파드 내 하나의 컨테이너에 100MiB 메모리 요청량과 200 MiB 메모리 상한이 있는 것을 보여준다.

...
resources:
  limits:
    memory: 200Mi
  requests:
    memory: 100Mi
...

kubectl top을 실행하여 파드 메트릭 가져오기:

kubectl top pod memory-demo --namespace=mem-example

출력은 파드가 약 150 MiB 해당하는 약 162,900,000 바이트 메모리를 사용하는 것을 보여준다. 이는 파드의 100 MiB 요청 보다 많으나 파드의 200 MiB 상한보다는 적다.

NAME                        CPU(cores)   MEMORY(bytes)
memory-demo                 <something>  162856960

파드 삭제:

kubectl delete pod memory-demo --namespace=mem-example

컨테이너의 메모리 상한을 초과

노드 내 메모리가 충분하다면 컨테이너는 지정한 요청량보다 많은 메모리를 사용 할 수 있다. 그러나 컨테이너는 지정한 메모리 상한보다 많은 메모리를 사용할 수 없다. 만약 컨테이너가 지정한 메모리 상한보다 많은 메모리를 할당하면 해당 컨테이너는 종료 대상 후보가 된다. 만약 컨테이너가 지속적으로 지정된 상한보다 많은 메모리를 사용한다면, 해당 컨테이너는 종료된다. 만약 종료된 컨테이너가 재실행 가능하다면 다른 런타임 실패와 마찬가지로 kubelet에 의해 재실행된다.

이 예제에서는 상한보다 많은 메모리를 할당하려는 파드를 생성한다. 이 것은 50 MiB 메모리 요청량과 100 MiB 메모리 상한을 갖는 하나의 컨테이너를 갖는 파드의 구성 파일이다.

pods/resource/memory-request-limit-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: memory-demo-2
  namespace: mem-example
spec:
  containers:
  - name: memory-demo-2-ctr
    image: polinux/stress
    resources:
      requests:
        memory: "50Mi"
      limits:
        memory: "100Mi"
    command: ["stress"]
    args: ["--vm", "1", "--vm-bytes", "250M", "--vm-hang", "1"]

구성 파일의 args 섹션에서 컨테이너가 100 MiB 상한을 훨씬 초과하는 250 MiB의 메모리를 할당하려는 것을 볼 수 있다.

파드 생성:

kubectl apply -f https://k8s.io/examples/pods/resource/memory-request-limit-2.yaml --namespace=mem-example

파드에 대한 자세한 정보 보기:

kubectl get pod memory-demo-2 --namespace=mem-example

이 시점에 컨테이너가 실행되거나 종료되었을 수 있다. 컨테이너가 종료될 때까지 이전의 명령을 반복한다.

NAME            READY     STATUS      RESTARTS   AGE
memory-demo-2   0/1       OOMKilled   1          24s

컨테이너 상태의 상세 상태 보기:

kubectl get pod memory-demo-2 --output=yaml --namespace=mem-example

컨테이너가 메모리 부족 (OOM) 으로 종료되었음이 출력된다.

lastState:
   terminated:
     containerID: docker://65183c1877aaec2e8427bc95609cc52677a454b56fcb24340dbd22917c23b10f
     exitCode: 137
     finishedAt: 2017-06-20T20:52:19Z
     reason: OOMKilled
     startedAt: null

이 예제에서 컨테이너는 재실행 가능하여 kubelet에 의해 재실행된다. 컨테이너가 종료되었다 재실행되는 것을 보기 위해 다음 명령을 몇 번 반복한다.

kubectl get pod memory-demo-2 --namespace=mem-example

출력은 컨테이너의 종료, 재실행, 재종료, 재실행 등을 보여준다.

kubectl get pod memory-demo-2 --namespace=mem-example
NAME            READY     STATUS      RESTARTS   AGE
memory-demo-2   0/1       OOMKilled   1          37s


kubectl get pod memory-demo-2 --namespace=mem-example
NAME            READY     STATUS    RESTARTS   AGE
memory-demo-2   1/1       Running   2          40s

파드 내역에 대한 상세 정보 보기:

kubectl describe pod memory-demo-2 --namespace=mem-example

컨테이너가 반복적으로 시작하고 실패 하는 출력을 보여준다.

... Normal  Created   Created container with id 66a3a20aa7980e61be4922780bf9d24d1a1d8b7395c09861225b0eba1b1f8511
... Warning BackOff   Back-off restarting failed container

클러스터 노드에 대한 자세한 정보 보기:

kubectl describe nodes

출력에는 컨테이너가 메모리 부족으로 종료된 기록이 포함된다.

Warning OOMKilling Memory cgroup out of memory: Kill process 4481 (stress) score 1994 or sacrifice child

파드 삭제:

kubectl delete pod memory-demo-2 --namespace=mem-example

노드에 비해 너무 큰 메모리 요청량의 지정

메모리 요청량과 상한은 컨테이너와 관련있지만, 파드가 가지는 메모리 요청량과 상한으로 이해하면 유용하다. 파드의 메모리 요청량은 파드 내 모든 컨테이너의 메모리 요청량의 합이다. 마찬가지로 파드의 메모리 상한은 파드 내 모든 컨테이너의 메모리 상한의 합이다.

파드는 요청량을 기반하여 스케줄링된다. 노드에 파드의 메모리 요청량을 충족하기에 충분한 메모리가 있는 경우에만 파드가 노드에서 스케줄링된다.

이 예제에서는 메모리 요청량이 너무 커 클러스터 내 모든 노드의 용량을 초과하는 파드를 생성한다. 다음은 클러스터 내 모든 노드의 용량을 초과할 수 있는 1000 GiB 메모리 요청을 포함하는 컨테이너를 갖는 파드의 구성 파일이다.

pods/resource/memory-request-limit-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: memory-demo-3
  namespace: mem-example
spec:
  containers:
  - name: memory-demo-3-ctr
    image: polinux/stress
    resources:
      limits:
        memory: "1000Gi"
      requests:
        memory: "1000Gi"
    command: ["stress"]
    args: ["--vm", "1", "--vm-bytes", "150M", "--vm-hang", "1"]

파드 생성:

kubectl apply -f https://k8s.io/examples/pods/resource/memory-request-limit-3.yaml --namespace=mem-example

파드 상태 보기:

kubectl get pod memory-demo-3 --namespace=mem-example

파드 상태가 PENDING 상태임이 출력된다. 즉 파드는 어떤 노드에서도 실행되도록 스케줄 되지 않고 PENDING가 계속 지속된다.

kubectl get pod memory-demo-3 --namespace=mem-example
NAME            READY     STATUS    RESTARTS   AGE
memory-demo-3   0/1       Pending   0          25s

이벤트를 포함한 파드 상세 정보 보기:

kubectl describe pod memory-demo-3 --namespace=mem-example

출력은 노드 내 메모리가 부족하여 파드가 스케줄링될 수 없음을 보여준다.

Events:
  ...  Reason            Message
       ------            -------
  ...  FailedScheduling  No nodes are available that match all of the following predicates:: Insufficient memory (3).

메모리 단위

메모리 리소스는 byte 단위로 측정된다. 다음 접미사 중 하나로 정수 또는 고정 소수점으로 메모리를 표시할 수 있다. E, P, T, G, M, K, Ei, Pi, Ti, Gi, Mi, Ki. 예를 들어 다음은 거의 유사한 값을 나타낸다.

128974848, 129e6, 129M , 123Mi

파드 삭제:

kubectl delete pod memory-demo-3 --namespace=mem-example

메모리 상한을 지정하지 않으면

컨테이너에 메모리 상한을 지정하지 않으면 다음 중 하나가 적용된다.

  • 컨테이너가 사용할 수 있는 메모리 상한은 없다. 컨테이너가 실행 중인 노드에서 사용 가능한 모든 메모리를 사용하여 OOM Killer가 실행될 수 있다. 또한 메모리 부족으로 인한 종료 시 메모리 상한이 없는 컨테이너가 종료될 가능성이 크다.

  • 기본 메모리 상한을 갖는 네임스페이스 내에서 실행중인 컨테이너는 자동으로 기본 메모리 상한이 할당된다. 클러스터 관리자들은 LimitRange를 사용해 메모리 상한의 기본 값을 지정 가능하다.

메모리 요청량과 상한 동기부여

클러스터에서 실행되는 컨테이너에 메모리 요청량과 상한을 구성하여 클러스터 내 노드들의 메모리 리소스를 효율적으로 사용할 수 있게 할 수 있다. 파드의 메모리 요청량을 적게 유지하여 파드가 높은 확률로 스케줄링 될 수 있도록 한다. 메모리 상한이 메모리 요청량보다 크면 다음 두 가지가 수행된다.

  • 가용한 메모리가 있는 경우 파드가 이를 사용할 수 있는 버스트(burst) 활동을 할 수 있다.
  • 파드가 버스트 중 사용 가능한 메모리 양이 적절히 제한된다.

정리

네임스페이스를 지운다. 이 작업을 통해 네임스페이스 내 생성했던 모든 파드들은 삭제된다.

kubectl delete namespace mem-example

다음 내용

앱 개발자들을 위한

클러스터 관리자들을 위한

3.2 - 윈도우 파드 및 컨테이너에서 RunAsUserName 구성

FEATURE STATE: Kubernetes v1.18 [stable]

이 페이지에서는 윈도우 노드에서 실행될 파드 및 컨테이너에 runAsUserName 설정을 사용하는 방법을 소개한다. 이는 리눅스 관련 runAsUser 설정과 거의 동일하여, 컨테이너의 기본값과 다른 username으로 애플리케이션을 실행할 수 있다.

시작하기 전에

쿠버네티스 클러스터가 있어야 하며 클러스터와 통신하도록 kubectl 명령줄 도구를 구성해야 한다. 클러스터에는 윈도우 워커 노드가 있어야 하고, 해당 노드에서 윈도우 워크로드를 실행하는 컨테이너의 파드가 스케쥴 된다.

파드의 username 설정

파드의 컨테이너 프로세스를 실행할 username을 지정하려면 파드 명세에 securityContext 필드 (PodSecurityContext) 를 포함시키고, 그 안에 runAsUserName 필드를 포함하는 windowsOptions (WindowsSecurityContextOptions) 필드를 추가한다.

파드에 지정하는 윈도우 보안 컨텍스트 옵션은 파드의 모든 컨테이너 및 초기화 컨테이너에 적용된다.

다음은 runAsUserName 필드가 설정된 윈도우 파드의 구성 파일이다.

windows/run-as-username-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: run-as-username-pod-demo
spec:
  securityContext:
    windowsOptions:
      runAsUserName: "ContainerUser"
  containers:
  - name: run-as-username-demo
    image: mcr.microsoft.com/windows/servercore:ltsc2019
    command: ["ping", "-t", "localhost"]
  nodeSelector:
    kubernetes.io/os: windows

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/windows/run-as-username-pod.yaml

파드의 컨테이너가 실행 중인지 확인한다.

kubectl get pod run-as-username-pod-demo

실행 중인 컨테이너의 셸에 접근한다.

kubectl exec -it run-as-username-pod-demo -- powershell

셸이 올바른 username인 사용자로 실행 중인지 확인한다.

echo $env:USERNAME

결과는 다음과 같다.

ContainerUser

컨테이너의 username 설정

컨테이너의 프로세스를 실행할 username을 지정하려면, 컨테이너 매니페스트에 securityContext 필드 (SecurityContext) 를 포함시키고 그 안에 runAsUserName 필드를 포함하는 windowsOptions (WindowsSecurityContextOptions) 필드를 추가한다.

컨테이너에 지정하는 윈도우 보안 컨텍스트 옵션은 해당 개별 컨테이너에만 적용되며 파드 수준에서 지정한 설정을 재정의한다.

다음은 한 개의 컨테이너에 runAsUserName 필드가 파드 수준 및 컨테이너 수준에서 설정되는 파드의 구성 파일이다.

windows/run-as-username-container.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: run-as-username-container-demo
spec:
  securityContext:
    windowsOptions:
      runAsUserName: "ContainerUser"
  containers:
  - name: run-as-username-demo
    image: mcr.microsoft.com/windows/servercore:ltsc2019
    command: ["ping", "-t", "localhost"]
    securityContext:
        windowsOptions:
            runAsUserName: "ContainerAdministrator"
  nodeSelector:
    kubernetes.io/os: windows

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/windows/run-as-username-container.yaml

파드의 컨테이너가 실행 중인지 확인한다.

kubectl get pod run-as-username-container-demo

실행 중인 컨테이너의 셸에 접근한다.

kubectl exec -it run-as-username-container-demo -- powershell

셸이 사용자에게 올바른 username(컨테이너 수준에서 설정된 사용자)을 실행 중인지 확인한다.

echo $env:USERNAME

결과는 다음과 같다.

ContainerAdministrator

윈도우 username 제약사항

이 기능을 사용하려면 runAsUserName 필드에 설정된 값이 유효한 username이어야 한다. 형식은 DOMAIN\USER 여야하고, 여기서 DOMAIN\은 선택 사항이다. 윈도우 username은 대소문자를 구분하지 않는다. 또한 DOMAIN 및 USER 와 관련된 몇 가지 제약사항이 있다.

  • runAsUserName 필드는 비워 둘 수 없으며 제어 문자를 포함할 수 없다. (ASCII 값: 0x00-0x1F, 0x7F)
  • DOMAIN은 NetBios 이름 또는 DNS 이름이어야 하며 각각 고유한 제한이 있다.
    • NetBios 이름: 최대 15 자, .(마침표)으로 시작할 수 없으며 다음 문자를 포함할 수 없다. \ / : * ? " < > |
    • DNS 이름: 최대 255 자로 영숫자, 마침표(.), 대시(-)로만 구성되며, 마침표 또는 대시로 시작하거나 끝날 수 없다.
  • USER는 최대 20자이며, 오직 마침표나 공백들로는 구성할 수 없고, 다음 문자는 포함할 수 없다. " / \ [ ] : ; | = , + * ? < > @.

runAsUserName 필드에 허용되는 값의 예 : ContainerAdministrator,ContainerUser, NT AUTHORITY\NETWORK SERVICE, NT AUTHORITY\LOCAL SERVICE.

이러한 제약사항에 대한 자세한 내용은 여기 와 여기를 확인한다.

다음 내용

3.3 - 파드에 대한 서비스 품질(QoS) 구성

이 페이지는 특정 서비스 품질(QoS) 클래스를 할당하기 위해 어떻게 파드를 구성해야 하는지 보여준다. 쿠버네티스는 QoS 클래스를 사용하여 파드 스케줄링과 축출을 결정한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

QoS 클래스

쿠버네티스가 파드를 생성할 때, 파드에 다음의 QoS 클래스 중 하나를 할당한다.

  • Guaranteed
  • Burstable
  • BestEffort

네임스페이스 생성

이 연습에서 생성한 리소스가 클러스터의 나머지와 격리되도록 네임스페이스를 생성한다.

kubectl create namespace qos-example

Guaranteed QoS 클래스가 할당되는 파드 생성

파드에 Guaranteed QoS 클래스 할당을 위한 전제 조건은 다음과 같다.

  • 파드 내 모든 컨테이너는 메모리 상한과 메모리 요청량을 가지고 있어야 한다.
  • 파드 내 모든 컨테이너의 메모리 상한이 메모리 요청량과 일치해야 한다.
  • 파드 내 모든 컨테이너는 CPU 상한과 CPU 요청량을 가지고 있어야 한다.
  • 파드 내 모든 컨테이너의 CPU 상한이 CPU 요청량과 일치해야 한다.

이러한 제약은 초기화 컨테이너와 앱 컨테이너 모두에 동일하게 적용된다.

다음은 하나의 컨테이너를 갖는 파드의 구성 파일이다. 해당 컨테이너는 메모리 상한과 메모리 요청량을 갖고 있고, 200MiB로 동일하다. 해당 컨테이너는 CPU 상한과 CPU 요청량을 가지며, 700 milliCPU로 동일하다.

pods/qos/qos-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: qos-demo
  namespace: qos-example
spec:
  containers:
  - name: qos-demo-ctr
    image: nginx
    resources:
      limits:
        memory: "200Mi"
        cpu: "700m"
      requests:
        memory: "200Mi"
        cpu: "700m"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod.yaml --namespace=qos-example

파드의 상세 정보를 본다.

kubectl get pod qos-demo --namespace=qos-example --output=yaml

출력 결과는 쿠버네티스가 파드에 Guaranteed QoS 클래스를 부여했음을 보여준다. 또한 파드의 컨테이너가 메모리 요청량과 일치하는 메모리 상한을 가지며, CPU 요청량과 일치하는 CPU 상한을 갖고 있음을 확인할 수 있다.

spec:
  containers:
    ...
    resources:
      limits:
        cpu: 700m
        memory: 200Mi
      requests:
        cpu: 700m
        memory: 200Mi
    ...
status:
  qosClass: Guaranteed
참고: 컨테이너가 자신의 메모리 상한을 지정하지만, 메모리 요청량을 지정하지 않는 경우, 쿠버네티스는 상한과 일치하는 메모리 요청량을 자동으로 할당한다. 이와 유사하게, 만약 컨테이너가 자신의 CPU 상한을 지정하지만, CPU 요청량을 지정하지 않은 경우, 쿠버네티스는 상한과 일치하는 CPU 요청량을 자동으로 할당한다.

파드를 삭제한다.

kubectl delete pod qos-demo --namespace=qos-example

Burstable QoS 클래스가 할당되는 파드 생성

다음의 경우 파드에 Burstable QoS 클래스가 부여된다.

  • 파드가 Guaranteed QoS 클래스 기준을 만족하지 않는다.
  • 파드 내에서 최소한 하나의 컨테이너가 메모리 또는 CPU 요청량을 가진다.

컨테이너가 하나인 파드의 구성 파일은 다음과 같다. 컨테이너는 200MiB의 메모리 상한과 100MiB의 메모리 요청량을 가진다.

pods/qos/qos-pod-2.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: qos-demo-2
  namespace: qos-example
spec:
  containers:
  - name: qos-demo-2-ctr
    image: nginx
    resources:
      limits:
        memory: "200Mi"
      requests:
        memory: "100Mi"

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-2.yaml --namespace=qos-example

파드의 상세 정보를 본다.

kubectl get pod qos-demo-2 --namespace=qos-example --output=yaml

출력 결과는 쿠버네티스가 파드에 Burstable QoS 클래스를 부여했음을 보여준다.

spec:
  containers:
  - image: nginx
    imagePullPolicy: Always
    name: qos-demo-2-ctr
    resources:
      limits:
        memory: 200Mi
      requests:
        memory: 100Mi
  ...
status:
  qosClass: Burstable

파드를 삭제한다.

kubectl delete pod qos-demo-2 --namespace=qos-example

BestEffort QoS 클래스가 할당되는 파드 생성

파드에 QoS 클래스 BestEffort를 제공하려면, 파드의 컨테이너에 메모리 또는 CPU의 상한이나 요청량이 없어야 한다.

컨테이너가 하나인 파드의 구성 파일이다. 해당 컨테이너는 메모리 또는 CPU의 상한이나 요청량을 갖지 않는다.

pods/qos/qos-pod-3.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: qos-demo-3
  namespace: qos-example
spec:
  containers:
  - name: qos-demo-3-ctr
    image: nginx

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-3.yaml --namespace=qos-example

파드의 상세 정보를 본다.

kubectl get pod qos-demo-3 --namespace=qos-example --output=yaml

출력 결과는 쿠버네티스가 파드에 BestEffort QoS 클래스를 부여했음을 보여준다.

spec:
  containers:
    ...
    resources: {}
  ...
status:
  qosClass: BestEffort

파드를 삭제한다.

kubectl delete pod qos-demo-3 --namespace=qos-example

컨테이너가 두 개인 파드 생성

컨테이너가 두 개인 파드의 구성 파일이다. 한 컨테이너는 200MiB의 메모리 요청량을 지정한다. 다른 컨테이너는 어떤 요청량이나 상한을 지정하지 않는다.

pods/qos/qos-pod-4.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: qos-demo-4
  namespace: qos-example
spec:
  containers:

  - name: qos-demo-4-ctr-1
    image: nginx
    resources:
      requests:
        memory: "200Mi"

  - name: qos-demo-4-ctr-2
    image: redis

참고로 이 파드는 Burstable QoS 클래스의 기준을 충족한다. 즉, Guaranteed QoS 클래스에 대한 기준을 충족하지 않으며, 해당 컨테이너 중 하나가 메모리 요청량을 갖는다.

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/qos/qos-pod-4.yaml --namespace=qos-example

파드의 상세 정보를 본다.

kubectl get pod qos-demo-4 --namespace=qos-example --output=yaml

출력 결과는 쿠버네티스가 파드에 Burstable QoS 클래스를 부여했음을 보여준다.

spec:
  containers:
    ...
    name: qos-demo-4-ctr-1
    resources:
      requests:
        memory: 200Mi
    ...
    name: qos-demo-4-ctr-2
    resources: {}
    ...
status:
  qosClass: Burstable

파드를 삭제한다.

kubectl delete pod qos-demo-4 --namespace=qos-example

정리

네임스페이스를 삭제한다.

kubectl delete namespace qos-example

다음 내용

앱 개발자를 위한 문서

클러스터 관리자를 위한 문서

3.4 - 스토리지의 볼륨을 사용하는 파드 구성

이 페이지는 스토리지의 볼륨을 사용하는 파드를 구성하는 방법을 설명한다.

컨테이너 파일 시스템은 컨테이너가 살아있는 동안만 존재한다. 따라서 컨테이너가 종료되고 재시작할 때, 파일 시스템 변경사항이 손실된다. 컨테이너와 독립적이며 보다 일관된 스토리지를 위해 사용자는 볼륨을 사용할 수 있다. 이것은 레디스(Redis)와 같은 키-값 저장소나 데이터베이스와 같은 스테이트풀 애플리케이션에 매우 중요하다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

파드에 볼륨 구성

이 연습에서는 하나의 컨테이너를 실행하는 파드를 생성한다. 이 파드는 컨테이너가 종료되고, 재시작 하더라도 파드의 수명동안 지속되는 emptyDir 유형의 볼륨이 있다. 파드의 구성 파일은 다음과 같다.

pods/storage/redis.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: redis
spec:
  containers:
  - name: redis
    image: redis
    volumeMounts:
    - name: redis-storage
      mountPath: /data/redis
  volumes:
  - name: redis-storage
    emptyDir: {}

  1. 파드 생성

    kubectl apply -f https://k8s.io/examples/pods/storage/redis.yaml

  2. 파드의 컨테이너가 Running 중인지 확인하고, 파드의 변경사항을 지켜본다.

    kubectl get pod redis --watch

    출력은 이와 유사하다.

    NAME      READY     STATUS    RESTARTS   AGE
redis     1/1       Running   0          13s

  3. 다른 터미널에서 실행 중인 컨테이너의 셸을 획득한다.

    kubectl exec -it redis -- /bin/bash

  4. 셸에서 /data/redis 로 이동하고, 파일을 생성한다.

    root@redis:/data# cd /data/redis/
root@redis:/data/redis# echo Hello > test-file

  5. 셸에서 실행 중인 프로세스 목록을 확인한다.

    root@redis:/data/redis# apt-get update
root@redis:/data/redis# apt-get install procps
root@redis:/data/redis# ps aux

    출력은 이와 유사하다.

    USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
redis        1  0.1  0.1  33308  3828 ?        Ssl  00:46   0:00 redis-server *:6379
root        12  0.0  0.0  20228  3020 ?        Ss   00:47   0:00 /bin/bash
root        15  0.0  0.0  17500  2072 ?        R+   00:48   0:00 ps aux

  6. 셸에서 Redis 프로세스를 강제종료(kill)한다.

    root@redis:/data/redis# kill <pid>

    여기서 <pid>는 Redis 프로세스 ID(PID) 이다.

  7. 원래 터미널에서, Redis 파드의 변경을 지켜본다. 결국, 다음과 유사한 것을 보게 될 것이다.

    NAME      READY     STATUS     RESTARTS   AGE
redis     1/1       Running    0          13s
redis     0/1       Completed  0         6m
redis     1/1       Running    1         6m

이때, 컨테이너는 종료되고 재시작된다. 이는 Redis 파드의 restartPolicy는 Always 이기 때문이다.

  1. 재시작된 컨테이너의 셸을 획득한다.

    kubectl exec -it redis -- /bin/bash

  2. 셸에서 /data/redis 로 이동하고, test-file 이 여전히 존재하는지 확인한다.

    root@redis:/data/redis# cd /data/redis/
root@redis:/data/redis# ls
test-file

  3. 이 연습을 위해 생성한 파드를 삭제한다.

    kubectl delete pod redis

다음 내용

  • 볼륨을 참고한다.

  • 파드을 참고한다.

  • 쿠버네티스는 emptyDir 이 제공하는 로컬 디스크 스토리지뿐만 아니라, 중요한 데이터에 선호하는 GCE의 PD, EC2의 EBS를 포함해서 네트워크 연결 스토리지(NAS) 솔루션을 지원하며, 노드의 디바이스 마운트, 언마운트와 같은 세부사항을 처리한다. 자세한 내용은 볼륨을 참고한다.

3.5 - 스토리지로 퍼시스턴트볼륨(PersistentVolume)을 사용하도록 파드 설정하기

이 페이지는 스토리지에 대해 퍼시스턴트볼륨클레임(PersistentVolumeClaim)을 사용하도록 파드를 설정하는 방법을 보여준다. 과정의 요약은 다음과 같다.

  1. 클러스터 관리자로서, 물리적 스토리지와 연결되는 퍼시스턴트볼륨을 생성한다. 볼륨을 특정 파드와 연결하지 않는다.

  2. 그 다음 개발자 / 클러스터 사용자의 역할로서, 적합한 퍼시스턴트볼륨에 자동으로 바인딩되는 퍼시스턴트볼륨클레임을 생성한다.

  3. 스토리지에 대해 위의 퍼시스턴트볼륨클레임을 사용하는 파드를 생성한다.

시작하기 전에

  • 사용자는 노드가 단 하나만 있는 쿠버네티스 클러스터가 필요하고, kubectl 커맨드라인 툴이 사용자의 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 만약 사용자가 아직 단일 노드 클러스터를 가지고 있지 않다면, Minikube를 사용하여 클러스터 하나를 생성할 수 있다.

  • 퍼시스턴트 볼륨의 관련 자료에 익숙해지도록 한다.

사용자 노드에 index.html 파일 생성하기

사용자 클러스터의 단일 노드에 연결되는 셸을 연다. 셸을 여는 방법은 클러스터 설정에 따라 달라진다. 예를 들어 Minikube를 사용하는 경우, minikube ssh 명령어를 입력하여 노드로 연결되는 셸을 열 수 있다.

해당 노드의 셸에서 /mnt/data 디렉터리를 생성한다.

# 사용자 노드에서 슈퍼유저로 명령을 수행하기 위하여
# "sudo"를 사용한다고 가정한다
sudo mkdir /mnt/data

/mnt/data 디렉터리에서 index.html 파일을 생성한다.

# 이번에도 사용자 노드에서 슈퍼유저로 명령을 수행하기 위하여
# "sudo"를 사용한다고 가정한다
sudo sh -c "echo 'Hello from Kubernetes storage' > /mnt/data/index.html"
참고: 사용자 노드에서 sudo 이외의 슈퍼유저 접근 툴을 사용하는 경우, sudo 를 해당 툴의 이름으로 바꾸면, 동일하게 작업을 수행할 수 있다.

index.html 파일이 존재하는지 테스트한다.

cat /mnt/data/index.html

결과는 다음과 같다.

Hello from Kubernetes storage

이제 사용자 노드에서 셸을 종료해도 된다.

퍼시스턴트볼륨 생성하기

이 예제에서, 사용자는 hostPath 퍼시스턴트볼륨을 생성한다. 쿠버네티스는 단일 노드에서의 개발과 테스트를 위해 hostPath를 지원한다. hostPath 퍼시스턴트볼륨은 네트워크로 연결된 스토리지를 모방하기 위해, 노드의 파일이나 디렉터리를 사용한다.

운영 클러스터에서, 사용자가 hostPath를 사용하지는 않는다. 대신, 클러스터 관리자는 Google Compute Engine 영구 디스크, NFS 공유 또는 Amazone Elastic Block Store 볼륨과 같은 네트워크 자원을 프로비저닝한다. 클러스터 관리자는 스토리지클래스(StorageClasses)를 사용하여 동적 프로비저닝을 설정할 수도 있다.

hostPath 퍼시스턴트볼륨의 설정 파일은 아래와 같다.

pods/storage/pv-volume.yaml 
apiVersion: v1
kind: PersistentVolume
metadata:
  name: task-pv-volume
  labels:
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data"

설정 파일에 클러스터 노드의 /mnt/data 에 볼륨이 있다고 지정한다. 또한 설정에서 볼륨 크기를 10 기가바이트로 지정하고 단일 노드가 읽기-쓰기 모드로 볼륨을 마운트할 수 있는 ReadWriteOnce 접근 모드를 지정한다. 여기서는 퍼시스턴트볼륨클레임의 스토리지클래스 이름을 manual 로 정의하며, 퍼시스턴트볼륨클레임의 요청을 이 퍼시스턴트볼륨에 바인딩하는데 사용한다.

퍼시스턴트볼륨을 생성한다.

kubectl apply -f https://k8s.io/examples/pods/storage/pv-volume.yaml

퍼시스턴트볼륨에 대한 정보를 조회한다.

kubectl get pv task-pv-volume

결과는 퍼시스턴트볼륨의 STATUS 가 Available 임을 보여준다. 이는 아직 퍼시스턴트볼륨클레임이 바인딩되지 않았다는 것을 의미한다.

NAME             CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS      CLAIM     STORAGECLASS   REASON    AGE
task-pv-volume   10Gi       RWO           Retain          Available             manual                   4s

퍼시스턴트볼륨클레임 생성하기

다음 단계는 퍼시스턴트볼륨클레임을 생성하는 단계이다. 파드는 퍼시스턴트볼륨클레임을 사용하여 물리적인 스토리지를 요청한다. 이 예제에서, 사용자는 적어도 하나 이상의 노드에 대해 읽기-쓰기 접근을 지원하며 최소 3 기가바이트의 볼륨을 요청하는 퍼시스턴트볼륨클레임을 생성한다.

퍼시스턴트볼륨클레임에 대한 설정 파일은 다음과 같다.

pods/storage/pv-claim.yaml 
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: task-pv-claim
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi

퍼시스턴트볼륨클레임을 생성한다.

kubectl apply -f https://k8s.io/examples/pods/storage/pv-claim.yaml

사용자가 퍼시스턴트볼륨클레임을 생성한 후에, 쿠버네티스 컨트롤 플레인은 클레임의 요구사항을 만족하는 퍼시스턴트볼륨을 찾는다. 컨트롤 플레인이 동일한 스토리지클래스를 갖는 적절한 퍼시스턴트볼륨을 찾으면, 볼륨에 클레임을 바인딩한다.

퍼시스턴트볼륨을 다시 확인한다.

kubectl get pv task-pv-volume

이제 결과는 STATUS 가 Bound 임을 보여준다.

NAME             CAPACITY   ACCESSMODES   RECLAIMPOLICY   STATUS    CLAIM                   STORAGECLASS   REASON    AGE
task-pv-volume   10Gi       RWO           Retain          Bound     default/task-pv-claim   manual                   2m

퍼시스턴트볼륨클레임을 확인한다.

kubectl get pvc task-pv-claim

결과는 퍼시스턴트볼륨클레임이 사용자의 퍼시스턴트볼륨인 task-pv-volume 에 바인딩되어 있음을 보여준다.

NAME            STATUS    VOLUME           CAPACITY   ACCESSMODES   STORAGECLASS   AGE
task-pv-claim   Bound     task-pv-volume   10Gi       RWO           manual         30s

파드 생성하기

다음 단계는 볼륨으로 퍼시스턴트볼륨클레임을 사용하는 파드를 만드는 단계이다.

파드에 대한 설정 파일은 다음과 같다.

pods/storage/pv-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: task-pv-pod
spec:
  volumes:
    - name: task-pv-storage
      persistentVolumeClaim:
        claimName: task-pv-claim
  containers:
    - name: task-pv-container
      image: nginx
      ports:
        - containerPort: 80
          name: "http-server"
      volumeMounts:
        - mountPath: "/usr/share/nginx/html"
          name: task-pv-storage

파드의 설정 파일은 퍼시스턴트볼륨클레임을 지정하지만, 퍼시스턴트볼륨을 지정하지는 않는다는 것을 유념하자. 파드의 관점에서 볼때, 클레임은 볼륨이다.

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/storage/pv-pod.yaml

파드의 컨테이너가 실행 중임을 확인한다.

kubectl get pod task-pv-pod

사용자 파드에서 구동되고 있는 컨테이너에 셸로 접근한다.

kubectl exec -it task-pv-pod -- /bin/bash

사용자의 셸에서, nginx가 hostPath 볼륨으로부터 index.html 파일을 제공하는지 확인한다.

# 이전 단계에서 "kubectl exec" 명령을 실행한 root 셸 안에서 
# 다음의 3개 명령을 실행해야 한다.
apt update
apt install curl
curl http://localhost/

결과는 hostPath 볼륨에 있는 index.html 파일에 사용자가 작성한 텍스트를 보여준다.

Hello from Kubernetes storage

만약 사용자가 위와 같은 메시지를 확인하면, 파드가 퍼시스턴트볼륨클레임의 스토리지를 사용하도록 성공적으로 설정한 것이다.

정리하기

파드, 퍼시스턴트볼륨클레임, 퍼시스턴트볼륨을 삭제한다.

kubectl delete pod task-pv-pod
kubectl delete pvc task-pv-claim
kubectl delete pv task-pv-volume

만약 클러스터의 노드에 대한 셸이 열려져 있지 않은 경우, 이전과 동일한 방식으로 새로운 셸을 연다.

사용자 노드의 셸에서, 생성한 파일과 디렉터리를 제거한다.

# 사용자 노드에서 슈퍼유저로 명령을 수행하기 위하여
# "sudo"를 사용한다고 가정한다
sudo rm /mnt/data/index.html
sudo rmdir /mnt/data

이제 사용자 노드에서 셸을 종료해도 된다.

접근 제어

그룹 ID(GID)로 설정된 스토리지는 동일한 GID를 사용하는 파드에서만 쓰기 작업을 허용한다. GID가 일치하지 않거나 누락되었을 경우 권한 거부 오류가 발생한다. 사용자와의 조정 필요성을 줄이기 위하여 관리자는 퍼시스턴트 볼륨에 GID로 어노테이션을 달 수 있다. 그 뒤에, 퍼시스턴트볼륨을 사용하는 모든 파드에 대하여 GID가 자동으로 추가된다.

다음과 같이 pv.beta.kubernetes.io/gid 어노테이션을 사용한다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv1
  annotations:
    pv.beta.kubernetes.io/gid: "1234"

파드가 GID 어노테이션이 있는 퍼시스턴트볼륨을 사용하면, 어노테이션으로 달린 GID가 파드의 보안 컨텍스트에 지정된 GID와 동일한 방식으로 파드의 모든 컨테이너에 적용된다. 파드의 명세 혹은 퍼시스턴트볼륨의 어노테이션으로부터 생성된 모든 GID는, 각 컨테이너에서 실행되는 첫 번째 프로세스에 적용된다.

참고: 파드가 퍼시스턴트볼륨을 사용할 때, 퍼시스턴트볼륨과 연관된 GID는 파드 리소스 자체에는 존재하지 않는다.

다음 내용

Reference

3.6 - 프라이빗 레지스트리에서 이미지 받아오기

이 페이지는 프라이빗 도커 레지스트리나 리포지터리로부터 이미지를 받아오기 위해 시크릿(Secret)을 사용하는 파드를 생성하는 방법을 보여준다.

시작하기 전에

  • 쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

    버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

  • 이 실습을 수행하기 위해, 도커 ID와 비밀번호가 필요하다.

도커 로그인

노트북에 프라이빗 이미지를 받아오기 위하여 레지스트리 인증을 필수로 수행해야 한다.

docker login

프롬프트가 나타나면, 도커 사용자 이름(username)과 비밀번호(password)를 입력하자.

로그인 프로세스는 권한 토큰 정보를 가지고 있는 config.json 파일을 생성하거나 업데이트 한다.

config.json 파일을 확인하자.

cat ~/.docker/config.json

하단과 유사한 결과를 확인할 수 있다.

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "c3R...zE2"
        }
    }
}
참고: 도커 자격 증명 저장소를 사용하는 경우, auth 항목이 아닌, 저장소의 이름을 값으로 사용하는 credsStore 항목을 확인할 수 있다.

기존의 도커 자격 증명을 기반으로 시크릿 생성하기

쿠버네티스 클러스터는 프라이빗 이미지를 받아올 때, 컨테이너 레지스트리에 인증하기 위하여 kubernetes.io/dockerconfigjson 타입의 시크릿을 사용한다.

만약 이미 docker login 을 수행하였다면, 이 때 생성된 자격 증명을 쿠버네티스 클러스터로 복사할 수 있다.

kubectl create secret generic regcred \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

오브젝트에 대한 더 세밀한 제어(새로운 시크릿에 대한 네임스페이스나 레이블을 지정하는 등)가 필요할 경우, 시크릿을 사용자 정의한 후에 저장할 수도 있다. 다음을 확인하자.

  • 데이터 항목의 이름을 .dockerconfigjson 으로 설정한다
  • 도커 파일을 base64로 인코딩하고 그 문자열을 data[".dockerconfigjson"] 필드에 자르지 않고 한 줄로 이어서 붙여넣는다
  • type 을 kubernetes.io/dockerconfigjson 으로 설정한다

예:

apiVersion: v1
kind: Secret
metadata:
  name: myregistrykey
  namespace: awesomeapps
data:
  .dockerconfigjson: UmVhbGx5IHJlYWxseSByZWVlZWVlZWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGx5eXl5eXl5eXl5eXl5eXl5eXl5eSBsbGxsbGxsbGxsbGxsbG9vb29vb29vb29vb29vb29vb29vb29vb29vb25ubm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==
type: kubernetes.io/dockerconfigjson

만약 error: no objects passed to create 메세지가 출력될 경우, base64로 인코딩된 문자열이 유효하지 않음을 의미한다. 또한 Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ... 메세지가 출력될 경우, base64로 인코딩된 문자열이 정상적으로 디코딩되었으나, .docker/config.json 파일로 파싱되지 못한 것을 의미한다.

커맨드 라인에서 자격 증명을 통하여 시크릿 생성하기

regcred 라는 이름의 시크릿을 생성하자.

kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>

아래의 각 항목에 대한 설명을 참고한다.

  • <your-registry-server> 은 프라이빗 도커 저장소의 FQDN 주소이다. 도커허브(DockerHub)는 https://index.docker.io/v2/ 를 사용한다.
  • <your-name> 은 도커 사용자의 계정이다.
  • <your-pword> 은 도커 사용자의 비밀번호이다.
  • <your-email> 은 도커 사용자의 이메일 주소이다.

이를 통해 regcred 라는 시크릿으로 클러스터 내에서 도커 자격 증명을 생성했다.

참고: 커맨드 라인에서 시크릿을 입력하는 경우, 보호되지 않는 셸 히스토리에 내용이 저장될 수 있으며, 이러한 시크릿들은 kubectl 이 구동 중인 동안 사용자의 PC의 다른 사용자들에게 보일 수도 있다.

시크릿 regcred 검증하기

방금 생성한 regcred 시크릿의 내용을 확인하기 위하여, YAML 형식으로 시크릿을 확인하자.

kubectl get secret regcred --output=yaml

결과는 다음과 같다.

apiVersion: v1
kind: Secret
metadata:
  ...
  name: regcred
  ...
data:
  .dockerconfigjson: eyJodHRwczovL2luZGV4L ... J0QUl6RTIifX0=
type: kubernetes.io/dockerconfigjson

.dockerconfigjson 필드의 값은 도커 자격 증명의 base64 인코딩 결과이다.

.dockerconfigjson 필드의 값을 확인하기 위하여, 시크릿 데이터를 읽을 수 있는 형식으로 변경한다.

kubectl get secret regcred --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

결과는 다음과 같다.

{"auths":{"your.private.registry.example.com":{"username":"janedoe","password":"xxxxxxxxxxx","email":"jdoe@example.com","auth":"c3R...zE2"}}}

auth 필드의 값을 확인하기 위하여, base64로 인코딩된 데이터를 읽을 수 있는 형식으로 변경한다.

echo "c3R...zE2" | base64 --decode

결과로, 사용자 이름과 비밀번호가 : 로 연결되어 아래와 같이 표현된다.

janedoe:xxxxxxxxxxx

참고로 시크릿 데이터에는 사용자의 로컬에 있는 ~/.docker/config.json 파일과 유사한 인증 토큰이 포함되어 있다.

이를 통해 regcred 라는 시크릿으로 클러스터 내에서 도커 자격 증명을 생성했다.

시크릿을 사용하는 파드 생성하기

다음은 regcred 에 있는 도커 자격 증명에 접근해야 하는 파드의 구성 파일이다.

pods/private-reg-pod.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: <your-private-image>
  imagePullSecrets:
  - name: regcred

아래의 파일을 다운로드받는다.

wget -O my-private-reg-pod.yaml https://k8s.io/examples/pods/private-reg-pod.yaml

my-private-reg-pod.yaml 파일 안에서, <your-private-image> 값을 다음과 같은 프라이빗 저장소 안의 이미지 경로로 변경한다.

your.private.registry.example.com/janedoe/jdoe-private:v1

프라이빗 저장소에서 이미지를 받아오기 위하여, 쿠버네티스에서 자격 증명이 필요하다. 구성 파일의 imagePullSecrets 필드를 통해 쿠버네티스가 regcred 라는 시크릿으로부터 자격 증명을 가져올 수 있다.

시크릿을 사용해서 파드를 생성하고, 파드가 실행되는지 확인하자.

kubectl apply -f my-private-reg-pod.yaml
kubectl get pod private-reg

다음 내용

3.7 - 노드 어피니티를 사용해 노드에 파드 할당

이 문서는 쿠버네티스 클러스터의 특정 노드에 노드 어피니티를 사용해 쿠버네티스 파드를 할당하는 방법을 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

쿠버네티스 서버의 버전은 다음과 같거나 더 높아야 함. 버전: v1.10. 버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

노드에 레이블 추가

  1. 클러스터의 노드를 레이블과 함께 나열하자.

    kubectl get nodes --show-labels

    결과는 아래와 같다.

    NAME      STATUS    ROLES    AGE     VERSION        LABELS
worker0   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker0
worker1   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker1
worker2   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker2

  2. 노드 한 개를 선택하고, 레이블을 추가하자.

    kubectl label nodes <your-node-name> disktype=ssd

    <your-node-name> 는 선택한 노드의 이름이다.

  3. 선택한 노드가 disktype=ssd 레이블을 갖고 있는지 확인하자.

    kubectl get nodes --show-labels

    결과는 아래와 같다.

    NAME      STATUS    ROLES    AGE     VERSION        LABELS
worker0   Ready     <none>   1d      v1.13.0        ...,disktype=ssd,kubernetes.io/hostname=worker0
worker1   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker1
worker2   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker2

    위의 결과에서, worker0 노드에 disktype=ssd 레이블이 있는 것을 확인할 수 있다.

필수적인 노드 어피니티를 사용해 파드 스케줄하기

이 매니페스트는 disktype: ssd 라는 requiredDuringSchedulingIgnoredDuringExecution 노드 어피니티를 가진 파드를 설명한다. 파드가 disktype=ssd 레이블이 있는 노드에만 스케줄될 것이라는 것을 의미한다.

pods/pod-nginx-required-affinity.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: disktype
            operator: In
            values:
            - ssd            
  containers:
  - name: nginx
    image: nginx
    imagePullPolicy: IfNotPresent

  1. 매니페스트를 적용하여 선택한 노드에 스케줄된 파드를 생성한다.

    kubectl apply -f https://k8s.io/examples/pods/pod-nginx-required-affinity.yaml

  2. 파드가 선택한 노드에서 실행 중인지 확인하자.

    kubectl get pods --output=wide

    결과는 아래와 같다.

    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

선호하는 노드 어피니티를 사용해 파드 스케줄하기

이 매니페스트는 disktype: ssd 라는 preferredDuringSchedulingIgnoredDuringExecution 노드 어피니티를 가진 파드를 설명한다. 파드가 disktype=ssd 레이블이 있는 노드를 선호한다는 것을 의미한다.

pods/pod-nginx-preferred-affinity.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 1
        preference:
          matchExpressions:
          - key: disktype
            operator: In
            values:
            - ssd          
  containers:
  - name: nginx
    image: nginx
    imagePullPolicy: IfNotPresent

  1. 매니페스트를 적용하여 선택한 노드에 스케줄된 파드를 생성한다.

    kubectl apply -f https://k8s.io/examples/pods/pod-nginx-preferred-affinity.yaml

  2. 파드가 선택한 노드에서 실행 중인지 확인하자.

    kubectl get pods --output=wide

    결과는 아래와 같다.

    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

다음 내용

노드 어피니티에 대해 더 알아보기.

3.8 - 노드에 파드 할당

이 문서는 쿠버네티스 클러스터의 특정 노드에 쿠버네티스 파드를 할당하는 방법을 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

노드에 레이블 추가

  1. 클러스터의 노드를 레이블과 함께 나열하자.

    kubectl get nodes --show-labels

    결과는 아래와 같다.

    NAME      STATUS    ROLES    AGE     VERSION        LABELS
worker0   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker0
worker1   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker1
worker2   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker2

  2. 노드 한 개를 선택하고, 레이블을 추가하자.

    kubectl label nodes <your-node-name> disktype=ssd

    <your-node-name>는 선택한 노드의 이름이다.

  3. 선택한 노드가 disktype=ssd 레이블을 갖고 있는지 확인하자.

    kubectl get nodes --show-labels

    결과는 아래와 같다.

    NAME      STATUS    ROLES    AGE     VERSION        LABELS
worker0   Ready     <none>   1d      v1.13.0        ...,disktype=ssd,kubernetes.io/hostname=worker0
worker1   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker1
worker2   Ready     <none>   1d      v1.13.0        ...,kubernetes.io/hostname=worker2

    위의 결과에서, worker0 노드에 disktype=ssd 레이블이 있는 것을 확인할 수 있다.

선택한 노드에 스케줄되도록 파드 생성하기

이 파드 구성 파일은 disktype: ssd라는 선택하는 노드 셀렉터를 가진 파드를 설명한다. 즉, disktype=ssd 레이블이 있는 노드에 파드가 스케줄될 것이라는 것을 의미한다.

pods/pod-nginx.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    env: test
spec:
  containers:
  - name: nginx
    image: nginx
    imagePullPolicy: IfNotPresent
  nodeSelector:
    disktype: ssd

  1. 구성 파일을 사용해서 선택한 노드로 스케줄되도록 파드를 생성하자.

    kubectl apply -f https://k8s.io/examples/pods/pod-nginx.yaml

  2. 파드가 선택한 노드에서 실행 중인지 확인하자.

    kubectl get pods --output=wide

    결과는 아래와 같다.

    NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

특정 노드에 스케줄되도록 파드 생성하기

nodeName 설정을 통해 특정 노드로 파드를 배포할 수 있다.

pods/pod-nginx-specific-node.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  nodeName: foo-node # 특정 노드에 파드 스케줄
  containers:
  - name: nginx
    image: nginx
    imagePullPolicy: IfNotPresent

설정 파일을 사용해 foo-node 노드에 파드를 스케줄되도록 만들어 보자.

다음 내용

3.9 - 초기화 컨테이너에 대한 구성

이 페이지는 애플리케이션 실행 전에 파드를 초기화하기 위해 어떻게 초기화 컨테이너를 구성해야 하는지 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

초기화 컨테이너를 갖는 파드 생성

이 연습에서 하나의 애플리케이션 컨테이너와 하나의 초기화 컨테이너를 갖는 파드를 생성한다. 초기화 컨테이너는 애플리케이션 시작 전에 실행을 종료한다.

아래는 해당 파드의 구성 파일이다.

pods/init-containers.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: init-demo
spec:
  containers:
  - name: nginx
    image: nginx
    ports:
    - containerPort: 80
    volumeMounts:
    - name: workdir
      mountPath: /usr/share/nginx/html
  # 이 컨테이너들은 파드 초기화 중에 실행된다.
  initContainers:
  - name: install
    image: busybox
    command:
    - wget
    - "-O"
    - "/work-dir/index.html"
    - http://info.cern.ch
    volumeMounts:
    - name: workdir
      mountPath: "/work-dir"
  dnsPolicy: Default
  volumes:
  - name: workdir
    emptyDir: {}

이 구성 파일에서, 파드가 가진 볼륨을 초기화 컨테이너와 애플리케이션 컨테이너가 공유하는 것을 볼 수 있다.

초기화 컨테이너는 공유된 볼륨을 /work-dir 에 마운트하고, 애플리케이션 컨테이너는 공유된 볼륨을 /usr/share/nginx/html 에 마운트한다. 초기화 컨테이너는 다음 명령을 실행 후 종료한다.

wget -O /work-dir/index.html http://info.cern.ch

초기화 컨테이너는 nginx 서버의 루트 디렉터리 내 index.html 파일을 저장한다.

파드를 생성한다.

kubectl apply -f https://k8s.io/examples/pods/init-containers.yaml

nginx 컨테이너가 실행 중인지 확인한다.

kubectl get pod init-demo

출력 결과는 nginx 컨테이너가 실행 중임을 보여준다.

NAME        READY     STATUS    RESTARTS   AGE
init-demo   1/1       Running   0          1m

init-demo 파드 내 실행 중인 nginx 컨테이너의 셸을 실행한다.

kubectl exec -it init-demo -- /bin/bash

셸에서 GET 요청을 nginx 서버로 전송한다.

root@nginx:~# apt-get update
root@nginx:~# apt-get install curl
root@nginx:~# curl localhost

출력 결과는 nginx가 초기화 컨테이너에 의해 저장된 웹 페이지를 제공하고 있음을 보여준다.

<html><head></head><body><header>
<title>http://info.cern.ch</title>
</header>

<h1>http://info.cern.ch - home of the first website</h1>
  ...
  <li><a href="http://info.cern.ch/hypertext/WWW/TheProject.html">Browse the first website</a></li>
  ...

다음 내용

3.10 - 스태틱(static) 파드 생성하기

스태틱 파드 는 API 서버 없이 특정 노드에 있는 kubelet 데몬에 의해 직접 관리된다. 컨트롤 플레인에 의해 관리되는 파드(예를 들어 디플로이먼트(Deployment))와는 달리, kubelet 이 각각의 스태틱 파드를 감시한다. (만약 실패할 경우 다시 구동한다.)

스태틱 파드는 항상 특정 노드에 있는 하나의 Kubelet에 매여 있다.

Kubelet 은 각각의 스태틱 파드에 대하여 쿠버네티스 API 서버에서 미러 파드(mirror pod)를 생성하려고 자동으로 시도한다. 즉, 노드에서 구동되는 파드는 API 서버에 의해서 볼 수 있지만, API 서버에서 제어될 수는 없다. 파드 이름에는 노드 호스트 이름 앞에 하이픈을 붙여 접미사로 추가된다.

참고: 만약 클러스터로 구성된 쿠버네티스를 구동하고 있고, 스태틱 파드를 사용하여 모든 노드에서 파드를 구동하고 있다면, 스태틱 파드를 사용하는 대신 데몬셋(DaemonSet) 을 사용하는 것이 바람직하다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

이 페이지는 파드를 실행하기 위해 도커(Docker)를 사용하며, 노드에서 Fedora 운영 체제를 구동하고 있다고 가정한다. 다른 배포판이나 쿠버네티스 설치 지침과는 다소 상이할 수 있다.

스태틱 파드 생성하기

파일 시스템이 호스팅하는 구성 파일이나 웹이 호스팅하는 구성 파일을 사용하여 스태틱 파드를 구성할 수 있다.

파일시스템이 호스팅 하는 스태틱 파드 매니페스트

매니페스트는 특정 디렉터리에 있는 JSON 이나 YAML 형식의 표준 파드 정의이다. kubelet 구성 파일의 staticPodPath: <the directory> 필드를 사용하자. 명시한 디렉터리를 정기적으로 스캔하여, 디렉터리 안의 YAML/JSON 파일이 생성되거나 삭제되었을 때 스태틱 파드를 생성하거나 삭제한다. Kubelet 이 특정 디렉터리를 스캔할 때 점(.)으로 시작하는 단어를 무시한다는 점을 유의하자.

예를 들어, 다음은 스태틱 파드로 간단한 웹 서버를 구동하는 방법을 보여준다.

  1. 스태틱 파드를 실행할 노드를 선택한다. 이 예제에서는 my-model 이다.

    ssh my-node1

  2. /etc/kubelet.d 와 같은 디렉터리를 선택하고 웹 서버 파드의 정의를 해당 위치에, 예를 들어 /etc/kubelet.d/static-web.yaml 에 배치한다.

      # kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
mkdir /etc/kubelet.d/
cat <<EOF >/etc/kubelet.d/static-web.yaml
apiVersion: v1
kind: Pod
metadata:
  name: static-web
  labels:
    role: myrole
spec:
  containers:
    - name: web
      image: nginx
      ports:
        - name: web
          containerPort: 80
          protocol: TCP
EOF

  3. 노드에서 kubelet 실행 시에 --pod-manifest-path=/etc/kubelet.d/ 와 같이 인자를 제공하여 해당 디렉터리를 사용하도록 구성한다. Fedora 의 경우 이 줄을 포함하기 위하여 /etc/kubernetes/kubelet 파일을 다음과 같이 수정한다.

    KUBELET_ARGS="--cluster-dns=10.254.0.10 --cluster-domain=kube.local --pod-manifest-path=/etc/kubelet.d/"

    혹은 kubelet 구성 파일에 staticPodPath: <the directory> 필드를 추가한다.

  4. kubelet을 재시작한다. Fedora의 경우 아래와 같이 수행한다.

    # kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
systemctl restart kubelet

웹이 호스팅 하는 스태틱 파드 매니페스트

Kubelet은 --manifest-url=<URL> 의 인수로 지정된 파일을 주기적으로 다운로드하여 해당 파일을 파드의 정의가 포함된 JSON/YAML 파일로 해석한다. 파일시스템이 호스팅 하는 매니페스트 의 작동 방식과 유사하게 kubelet은 스케줄에 맞춰 매니페스트 파일을 다시 가져온다. 스태틱 파드의 목록에 변경된 부분이 있을 경우, kubelet 은 이를 적용한다.

이 방법을 사용하기 위하여 다음을 수행한다.

  1. kubelet 에게 파일의 URL을 전달하기 위하여 YAML 파일을 생성하고 이를 웹 서버에 저장한다.

    apiVersion: v1
kind: Pod
metadata:
  name: static-web
  labels:
    role: myrole
spec:
  containers:
    - name: web
      image: nginx
      ports:
        - name: web
          containerPort: 80
          protocol: TCP

  2. 선택한 노드에서 --manifest-url=<manifest-url> 을 실행하여 웹 메니페스트를 사용하도록 kubelet을 구성한다. Fedora 의 경우 이 줄을 포함하기 위하여 /etc/kubernetes/kubelet 파일을 수정한다.

    KUBELET_ARGS="--cluster-dns=10.254.0.10 --cluster-domain=kube.local --manifest-url=<manifest-url>"

  3. Kubelet을 재시작한다. Fedora의 경우 아래와 같이 수행한다.

    # kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
systemctl restart kubelet

스태틱 파드 행동 관찰하기

Kubelet 을 시작하면, 정의된 모든 스태틱 파드가 자동으로 시작된다. 스태틱 파드를 정의하고, kubelet을 재시작했으므로, 새로운 스태틱 파드가 이미 실행 중이어야 한다.

(노드에서) 구동되고 있는 (스태틱 파드를 포함한) 컨테이너들을 볼 수 있다.

# kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
docker ps

결과는 다음과 유사하다.

CONTAINER ID IMAGE         COMMAND  CREATED        STATUS         PORTS     NAMES
f6d05272b57e nginx:latest  "nginx"  8 minutes ago  Up 8 minutes             k8s_web.6f802af4_static-web-fk-node1_default_67e24ed9466ba55986d120c867395f3c_378e5f3c

API 서버에서 미러 파드를 볼 수 있다.

kubectl get pods

NAME                       READY     STATUS    RESTARTS   AGE
static-web-my-node1        1/1       Running   0          2m
참고: Kubelet에 API 서버에서 미러 파드를 생성할 수 있는 권한이 있는지 미리 확인해야 한다. 그렇지 않을 경우 API 서버에 의해서 생성 요청이 거부된다. 파드시큐리티폴리시(PodSecurityPolicy) 에 대해 보기.

스태틱 파드에 있는 레이블 은 미러 파드로 전파된다. 셀렉터 등을 통하여 이러한 레이블을 사용할 수 있다.

만약 API 서버로부터 미러 파드를 지우기 위하여 kubectl 을 사용하려 해도, kubelet 은 스태틱 파드를 지우지 않는다.

kubectl delete pod static-web-my-node1

pod "static-web-my-node1" deleted

파드가 여전히 구동 중인 것을 볼 수 있다.

kubectl get pods

NAME                       READY     STATUS    RESTARTS   AGE
static-web-my-node1        1/1       Running   0          12s

kubelet 이 구동 중인 노드로 돌아가서 도커 컨테이너를 수동으로 중지할 수 있다. 일정 시간이 지나면, kubelet이 파드를 자동으로 인식하고 다시 시작하는 것을 볼 수 있다.

# kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
docker stop f6d05272b57e # 예제를 수행하는 사용자의 컨테이너 ID로 변경한다.
sleep 20
docker ps

CONTAINER ID        IMAGE         COMMAND                CREATED       ...
5b920cbaf8b1        nginx:latest  "nginx -g 'daemon of   2 seconds ago ...

스태틱 파드의 동적 추가 및 제거

실행 중인 kubelet 은 주기적으로, 설정된 디렉터리(예제에서는 /etc/kubelet.d)에서 변경 사항을 스캔하고, 이 디렉터리에 새로운 파일이 생성되거나 삭제될 경우, 파드를 생성/삭제 한다.

# 예제를 수행하는 사용자가 파일시스템이 호스팅하는 스태틱 파드 설정을 사용한다고 가정한다.
# kubelet 이 동작하고 있는 노드에서 이 명령을 수행한다.
#
mv /etc/kubelet.d/static-web.yaml /tmp
sleep 20
docker ps
# 구동 중인 nginx 컨테이너가 없는 것을 확인한다.
mv /tmp/static-web.yaml  /etc/kubelet.d/
sleep 20
docker ps

CONTAINER ID        IMAGE         COMMAND                CREATED           ...
e7a62e3427f1        nginx:latest  "nginx -g 'daemon of   27 seconds ago

4 - 쿠버네티스 오브젝트 관리

쿠버네티스 API와 상호 작용하기 위한 선언적이고 명령적인 패러다임

4.1 - 구성 파일을 이용한 쿠버네티스 오브젝트의 선언형 관리

쿠버네티스 오브젝트는 여러 개의 오브젝트 구성 파일을 디렉터리에 저장하고 필요에 따라 kubectl apply를 사용하여 재귀적으로 오브젝트를 생성하고 업데이트함으로써 생성, 업데이트 및 삭제할 수 있다. 이 방식은 변경사항을 되돌려 오브젝트 구성 파일에 병합하지 않고 활성 오브젝트에 가해진 기록을 유지한다. kubectl diff는 또한 apply가 어떠한 변경사항을 이루어질지에 대한 프리뷰를 제공한다.

시작하기 전에

kubectl를 설치한다.

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

트레이드 오프

kubectl 툴은 세 가지 방식의 오브젝트 관리를 지원한다.

  • 명령형 커맨드
  • 명령형 오브젝트 구성
  • 선언형 오브젝트 구성

오브젝트 관리 방식의 종류별 장단점에 대한 논의는 쿠버네티스 오브젝트 관리를 참고한다.

개요

선언형 오브젝트 구성은 쿠버네티스 오브젝트 정의와 구성에 대한 확실한 이해가 필요하다. 아직 그렇지 못하다면, 먼저 다음 문서를 읽고 이해한다.

다음은 이 문서에서 사용되는 용어에 대한 정의이다.

  • 오브젝트 구성 파일 / 구성 파일: 쿠버네티스 오브젝트에 대한 구성을 정의하는 하나의 파일. 이 주제는 어떻게 kubectl apply에 구성 파일을 전달하는지에 대해 보여준다. 구성 파일은 일반적으로 Git과 같은, 소스 컨트롤에 저장된다.
  • 활성 오브젝트 구성 / 활성 구성: 쿠버네티스 클러스터에 의해 관측된 오브젝트에 대한 활성 구성 값. 이것들은 쿠버네티스 클러스터 저장소에 유지된다. 일반적으로 etcd가 사용된다.
  • 선언형 구성 작성자 / 선언형 작성자: 활성 오브젝트를 업데이트해 주는 사람이나 소프트웨어. 이 주제에서 언급하는 활성 작성자는 오브젝트 구성 파일에 변경을 가하고 kubectl apply를 실행하여 변경사항을 기록한다.

오브젝트 생성 방법

기존에 존재하는 것을 제외한, 지정한 디렉터리 내 구성 파일에 의해 정의된 모든 오브젝트를 생성하기 위해 kubectl apply를 사용한다.

kubectl apply -f <디렉터리>/

이것은 각 오브젝트에 대해 kubectl.kubernetes.io/last-applied-configuration: '{...}' 어노테이션을 설정한다. 해당 어노테이션은 오브젝트를 생성하기 위해 사용했던 오브젝트 구성 파일의 내용을 포함한다. 

참고: 재귀적으로 디렉터리를 처리하기 위해서 -R 플래그를 추가한다.

다음은 오브젝트 구성 파일에 대한 예시이다.

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

생성될 오브젝트를 출력하려면 kubectl diff를 실행한다. 

kubectl diff -f https://k8s.io/examples/application/simple_deployment.yaml
참고:

diff는 kube-apiserver의 활성화가 필요한 서버사이드 dry-run을 사용한다.

diff 는 dry-run 모드에서 서버 측 적용 요청을 수행하므로, PATCH, CREATE, 그리고 UPDATE 권한을 부여해야 한다. 자세한 것은 Dry-Run 인증을 본다.

kubectl apply를 사용하여 오브젝트를 생성한다.

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml

kubectl get을 사용하여 활성 구성을 출력한다.

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

출력은 kubectl.kubernetes.io/last-applied-configuration 어노테이션이 활성 구성에 기록된 것을 보여주며, 그것은 구성 파일과 일치한다.

kind: Deployment
metadata:
  annotations:
    # ...
    # This is the json representation of simple_deployment.yaml
    # It was written by kubectl apply when the object was created
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

오브젝트 업데이트 방법

또한 오브젝트가 기존에 존재하더라도 디렉터리 내 정의된 모든 오브젝트를 업데이트하기 위해 kubectl apply를 사용할 수 있다. 이러한 접근방식은 다음을 수행할 수 있게 해준다.

  1. 활성 구성 내 구성 파일에 나타나는 필드 설정
  2. 활성 구성 내 구성 파일로부터 제거된 필드 정리
kubectl diff -f <디렉터리>/
kubectl apply -f <디렉터리>/
참고: 재귀적으로 디렉터리를 처리하기 위해서 -R플래그를 추가한다.

다음은 구성 파일의 예시이다.

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

kubectl apply를 사용하여 오브젝트를 생성한다.

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml
참고: 설명을 위해, 앞선 명령은 디렉터리 대신 하나의 구성 파일을 참조한다.

kubectl get을 사용하여 활성 구성을 출력한다.

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

출력은 kubectl.kubernetes.io/last-applied-configuration 어노테이션이 활성 구성에 기록된 것을 보여주며, 그것은 구성 파일과 일치한다.

kind: Deployment
metadata:
  annotations:
    # ...
    # This is the json representation of simple_deployment.yaml
    # It was written by kubectl apply when the object was created
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

kubectl scale을 사용하여 활성 구성 내 replicas 필드를 직접 업데이트한다. 이는 kubectl apply를 사용하지 않는다.

kubectl scale deployment/nginx-deployment --replicas=2

kubectl get을 사용하여 활성 구성을 출력한다.

kubectl get deployment nginx-deployment -o yaml

출력은 replicas 필드가 2로 설정된 것을 보여주며, last-applied-configuration 어노테이션은 replicas 필드를 포함하지 않는다.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # note that the annotation does not contain replicas
    # because it was not updated through apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  replicas: 2 # written by scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

nginx:1.14.2에서 nginx:1.16.1로 이미지를 변경하기 위해 simple_deployment.yaml 구성 파일을 업데이트 하고, minReadySeconds 필드를 삭제한다.

application/update_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

구성 파일에 이루어진 변경사항을 적용한다.

kubectl diff -f https://k8s.io/examples/application/update_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/update_deployment.yaml

kubectl get을 사용하여 활성 구성을 출력한다.

kubectl get -f https://k8s.io/examples/application/update_deployment.yaml -o yaml

출력은 활성 구성에 다음의 변경사항을 보여준다.

  • replicas 필드는 kubectl scale에 의해 설정된 값 2를 유지한다.
    이는 구성 파일에서 생략되었기 때문에 가능하다.
  • image 필드는 nginx:1.14.2에서 nginx:1.16.1로 업데이트되었다.
  • last-applied-configuration 어노테이션은 새로운 이미지로 업데이트되었다.
  • minReadySeconds 필드는 지워졌다.
  • last-applied-configuration 어노테이션은 더 이상 minReadySeconds 필드를 포함하지 않는다.
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # The annotation contains the updated image to nginx 1.11.9,
    # but does not contain the updated replicas to 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
    # ...
spec:
  replicas: 2 # Set by `kubectl scale`.  Ignored by `kubectl apply`.
  # minReadySeconds cleared by `kubectl apply`
  # ...
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Set by `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...
경고: 명령형 오브젝트 구성 커맨드 create와 replace와 함께 kubectl apply를 혼합하는 것은 지원하지 않는다. 이는 kubectl apply가 업데이트 사항을 계산하는데 사용하는 kubectl.kubernetes.io/last-applied-configuration을 create와 replace가 유지하지 하지 않기 때문이다.

오브젝트 삭제 방법

kubectl apply에 의해 관리되는 오브젝트를 삭제하는데 2가지 접근 방법이 있다.

권장 방법: kubectl delete -f <파일명>

명령형 커맨드를 사용하여 오브젝트를 수동으로 삭제하는 것이 권장되는 방식인데, 무엇이 삭제되는지에 대해 더 명확하게 나타내므로 사용자가 의도하지 않게 무언가를 삭제할 가능성이 작아지기 때문이다.

kubectl delete -f <파일명>

대안: kubectl apply -f <디렉터리/> --prune -l your=레이블

무엇을 하는지 파악하는 경우에만 이를 사용한다.

경고: kubectl apply --prune은 알파 상태이며, 후속 릴리스에서는 하위 호환되지 않는 변경 사항이 도입될 수 있다.
경고: 이 명령을 사용할 때는 의도하지 않게 오브젝트를 삭제하지 않도록 주의해야만 한다.

kubectl delete에 대한 대안으로, 디렉터리로부터 구성 파일이 삭제된 후에 삭제될 오브젝트를 식별하기 위해 kubectl apply를 사용할 수 있다. --prune을 사용하여 적용하면 일련의 레이블의 집합과 일치하는 모든 오브젝트에 대해API 서버에 쿼리하고, 반환된 활성 오브젝트 구성을 오브젝트 구성 파일에 일치시키려고 시도한다. 오브젝트가 쿼리에 일치하고, 해당 디렉터리 내 구성 파일이 없고 last-applied-configuration어노테이션이 있는 경우, 삭제된다.

kubectl apply -f <디렉터리/> --prune -l <레이블>
경고: prune을 사용하여 적용하는 것은 오브젝트 구성 파일을 포함하는 루트 디렉터리에 대해서만 실행해야 한다. 하위 디렉터리에 대해 실행하게 되면, -l <레이블>로 지정된 레이블 셀렉터에 의해 반환되고 하위 디렉터리에 나타나지 않는 경우, 오브젝트가 의도하지 않게 삭제될 수 있다.

오브젝트 확인 방법

활성 오브젝트의 구성을 확인하기 위해 -o yaml과 함께 kubectl get을 사용할 수 있다.

kubectl get -f <파일명|url> -o yaml

어떻게 apply가 차이를 계산하고 변경을 병합하는가

주의: patch 는 전체 오브젝트 대신 오브젝트의 특정 필드 범위의 오퍼레이션을 업데이트한다. 이는 먼저 오브젝트를 읽지 않고도 오브젝트의 특정 필드 집합만을 업데이트할 수 있도록 해준다.

kubectl apply가 하나의 오브젝트에 대한 활성 구성을 업데이트할 때, API 서버에 패치 요청을 보냄으로써 그것을 수행한다. 그 패치는 활성 오브젝트 구성의 특정 필드에 대한 범위의 업데이트로 한정한다. kubectl apply 커맨드는 구성 파일, 활성 구성, 그리고 활성 구성에 저장된 last-applied-configuration어노테이션을 사용하여 이 패치 요청을 계산한다.

패치 계산 병합

kubectl apply 명령은 kubectl.kubernetes.io/last-applied-configuration 어노테이션에 구성 파일의 내용을 기록한다. 이것은 구성 파일로부터 제거되었고 활성 구성으로부터 지워질 필요가 있는 필드를 확인하는 데 사용된다. 다음은 어떤 필드가 삭제 또는 설정돼야 하는지 계산하기 위해 사용되는 단계이다.

  1. 삭제할 필드를 계산한다. 이것은 last-applied-configuration 내 존재하고 구성 파일로부터 유실된 필드이다.
  2. 추가 또는 설정되어야 할 필드를 계산한다. 이것은 활성 구성과 불일치하는 값을 가지는 구성 파일 내 존재하는 필드이다.

다음은 예시이다. 디플로이먼트 오브젝트에 대한 구성 파일이라고 가정한다.

application/update_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

또한, 이것은 동일한 디플로이먼트 오브젝트에 대한 활성 구성이라고 가정한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # note that the annotation does not contain replicas
    # because it was not updated through apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  replicas: 2 # written by scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

다음은 kubectl apply에 의해 수행될 병합 계산이다.

  1. last-applied-configuration으로부터 값을 읽어 구성 파일의 값과 비교하여 삭제할 필드를 계산한다. last-applied-configuration에 보이는 것과는 무관하게 로컬의 오브젝트 구성 파일 내 null이라고 명시적으로 설정된 필드를 지운다. 이 예시에서, minReadySeconds은 last-applied-configuration 어노테이션 내 나타나지만, 구성 파일 내에는 보여지지 않는다. 조치: 활성 구성으로부터 minReadySeconds을 지운다.
  2. 구성 파일로부터 값을 읽어 활성 구성 내 값과 비교하여 설정할 필드를 계산한다. 이 예시에서, 구성 파일 내 image 값은 활성 구성 내 값과 불일치한다. 조치: 활성 구성 내 image 값을 설정한다.
  3. 구성 파일의 값과 일치시키기 위해 last-applied-configuration 어노테이션을 설정한다.
  4. 1, 2, 3으로부터의 결과를 API 서버에 단일 패치 요청으로 병합한다.

다음은 병합의 결과인 활성 구성이다.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # The annotation contains the updated image to nginx 1.11.9,
    # but does not contain the updated replicas to 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
    # ...
spec:
  selector:
    matchLabels:
      # ...
      app: nginx
  replicas: 2 # Set by `kubectl scale`.  Ignored by `kubectl apply`.
  # minReadySeconds cleared by `kubectl apply`
  # ...
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Set by `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

어떻게 상이한 필드 타입이 병합되는가

구성 파일 내 특정 필드가 필드의 타입에 따라 어떻게 활성 구성과 함께 병합되는가. 여러 가지 필드 타입이 있다.

  • 기본(primitives): 문자열, 숫자 또는 불리언 타입의 필드. 예를 들어, image와 replicas는 기본 필드다. 조치: 교체.

  • 맵, 또한 오브젝트 라 칭함: 맵 타입 또는 서브필드를 포함하는 복합 타입의 필드. 예를 들어, 레이블, 어노테이션,스펙 및 메타데이터는 모두 맵이다. 조치: 구성요소 또는 서브필드 병합.

  • 리스트: 기본타입 또는 맵이 될 수 있는 아이템의 리스트를 포함하는 필드. 예를 들어, 컨테이너, 포트, 그리고 args는 리스트다. 조치: 다양함.

kubectl apply가 맵 또는 리스트 필드를 업데이트하는 경우, 일반적으로 전체 필드를 교체하는 대신, 개별 부 구성요소를 업데이트한다, 예를 들어, 디플로이먼트에 대한 spec을 병합할 경우, 전체 spec이 교체되지 않는다. 대신 replicas와 같은 spec의 서브필드가 비교되고 병합된다.

기본 필드에 대한 변경사항 병합하기

기본 필드는 교체되거나 지워진다.

참고: - 는 값이 사용되지 않기 때문에 "해당 없음"으로 사용된다.
Field in object configuration file Field in live object configuration Field in last-applied-configuration Action
Yes Yes - 구성 파일 값 활성으로 설정.
Yes No - 활성을 로컬 구성으로 설정.
No - Yes 활성 구성으로부터 지움.
No - No 아무것도 안함. 활성값 유지.

맵 필드에 변경사항 병합하기

맵을 요청하는 필드는 서브필드의 각각 또는 맵의 구성요소를 비교함으로써 병합된다.

참고: - 는 값이 사용되지 않기 때문에 "해당 없음"으로 사용된다.
Key in object configuration file Key in live object configuration Field in last-applied-configuration Action
Yes Yes - 서브필드 값 비교.
Yes No - 활성을 로컬 구성으로 설정.
No - Yes 활성 구성으로부터 삭제.
No - No 아무것도 안함. 활성값 유지.

타입 리스트의 필드에 대한 변경사항 병합하기

리스트에 대한 변경사항을 병합하는 것은 세 가지 전략 중 하나를 사용한다.

  • 구성요소가 모두 기본형인 경우 리스트를 교체한다.
  • 복합 구성요소의 리스트에서 개별 구성요소를 병합한다.
  • 기초 구성요소의 리스트를 병합한다.

전략에 대한 선택은 필드별로 이루어진다.

구성요소가 모두 기본형인 경우 리스트 교체

기초 필드와 동일한 리스트로 취급한다. 전체 리스트를 교체 또는 삭제한다. 이것은 순서를 유지한다.

예시: 파드 내 컨테이너의 args 필드를 업데이트하기 위해 kubectl apply를 사용한다. 이것은 활성 구성 내 args의 값을 구성 파일 내 값으로 설정한다. 활성 구성에 추가했던 이전의 모든 args구성요소들은 유실된다. 구성 파일 내 정의한 args 구성요소의 순서는 활성 구성 내 유지된다.

# last-applied-configuration value
    args: ["a", "b"]

# configuration file value
    args: ["a", "c"]

# live configuration
    args: ["a", "b", "d"]

# result after merge
    args: ["a", "c"]

설명: 병합은 새로운 리스트 값으로 구성 파일 값을 사용했다.

복합 구성요소 리스트에 대한 개별 구성요소 병합

리스트를 맵으로 취급하고 각 구성요소의 특정 필드를 키로 취급한다. 개별 구성요소를 추가, 삭제, 또는 업데이트 한다. 이것은 순서를 보존하지 않는다.

이 병합 전략은 각 필드에 patchMergeKey라 칭하는 특별한 태그를 사용한다. patchMergeKey는 쿠버네티스 소스 코드: types.go 의 각 필드에 대해 정의한다. 맵 리스트를 병합할 때, 주어진 구성요소에 대한 patchMergeKey로 지정한 필드는 해당 구성요소에 대한 맵키와 같이 사용된다.

예시: kubectl apply를 사용하여 PodSpec에 대한 containers필드를 업데이트한다.
이렇게 하면 각 구성요소가 name별로 키로 되어 있는 맵인 것처럼 리스트를 병합한다.

# last-applied-configuration value
    containers:
    - name: nginx
      image: nginx:1.10
    - name: nginx-helper-a # key: nginx-helper-a; will be deleted in result
      image: helper:1.3
    - name: nginx-helper-b # key: nginx-helper-b; will be retained
      image: helper:1.3

# configuration file value
    containers:
    - name: nginx
      image: nginx:1.10
    - name: nginx-helper-b
      image: helper:1.3
    - name: nginx-helper-c # key: nginx-helper-c; will be added in result
      image: helper:1.3

# live configuration
    containers:
    - name: nginx
      image: nginx:1.10
    - name: nginx-helper-a
      image: helper:1.3
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Field will be retained
    - name: nginx-helper-d # key: nginx-helper-d; will be retained
      image: helper:1.3

# result after merge
    containers:
    - name: nginx
      image: nginx:1.10
      # Element nginx-helper-a was deleted
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Field was retained
    - name: nginx-helper-c # Element was added
      image: helper:1.3
    - name: nginx-helper-d # Element was ignored
      image: helper:1.3

설명:

  • 구성 파일에 "nginx-helper-a"라는 이름을 가진 컨테이너가 나타나지 않았기 때문에 "nginx-helper-a"라는 컨테이너는 삭제되었다.
  • "nginx-helper-b"라는 컨테이너는 활성 구성에 args에
    대한 변경사항을 유지했다. kubectl apply는
    필드 값이 다름에도 불구하고(구성 파일에 args가 없음) 활성 구성에
    "nginx-helper-b"가 구성 파일과 동일한 "nginx-helper-b"임을 식별할 수 있었다. 이것은 patchMergeKey 필드 값(이름)이 둘 다 같았기 때문이다..
  • "nginx-helper-c"라는 이름의 컨테이너가 활성 구성에 나타나지 않았지만, 구성 파일에 그 이름을 가진 컨테이너가 나타났기 때문에 추가되었다.
  • last-applied-configuration에 그 이름을 가진 구성요소가 없었기 때문에 "nginx-helper-d"라는 이름의 컨테이너는 유지되었다.

기초 구성요소 리스트 병합

쿠버네티스 1.5로부터 기초 구성요소 병합하기는 지원되지 않는다.

참고: 주어진 필드에 대해 위 전략 중 어떤 것을 선택할지에 대해서는 types.go의 patchStrategy 태그에 의해 제어된다. 타입 필드에 대해 patchStrategy가 지정되지 않으면, 리스트는 대체된다.

기본 필드값

오브젝트가 생성될 때 값이 지정되지 않는 경우, API 서버는 활성 구성 내 특정 필드를 기본값으로 설정한다.

다음은 디플로이먼트에 대한 구성 파일이다. 파일에는 strategy가 지정되지 않았다.

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

kubectl apply를 사용하여 오브젝트를 생성한다.

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml

kubectl get을 사용하여 활성 구성을 출력한다.

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

출력은 API 서버가 활성 구성 내 여러 필드를 기본값으로 설정한 것을 보여준다. 이 필드들은 구성 파일에 지정되지 않았다.

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  replicas: 1 # defaulted by apiserver
  strategy:
    rollingUpdate: # defaulted by apiserver - derived from strategy.type
      maxSurge: 1
      maxUnavailable: 1
    type: RollingUpdate # defaulted by apiserver
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        imagePullPolicy: IfNotPresent # defaulted by apiserver
        name: nginx
        ports:
        - containerPort: 80
          protocol: TCP # defaulted by apiserver
        resources: {} # defaulted by apiserver
        terminationMessagePath: /dev/termination-log # defaulted by apiserver
      dnsPolicy: ClusterFirst # defaulted by apiserver
      restartPolicy: Always # defaulted by apiserver
      securityContext: {} # defaulted by apiserver
      terminationGracePeriodSeconds: 30 # defaulted by apiserver
# ...

패치 요청에서, 패치 요청의 부분으로서 명시적으로 지워지지 않은 경우 기본 처리된 필드는 다시 기본으로 설정되지 않는다. 이것은 다른 필드에 대한 값에 따라 기본 처리된 필드에 대해 예상하지 못한 동작을 유발할 수 있다. 다른 필드가 나중에 변경되면, 그로부터 기본 처리된 것이 명시적으로 지워지지 않은 한 업데이트되지 않을 것이다.

이러한 사유로, 의도한 값이 서버의 기본값과 일치하더라도, 서버에 의해 기본 처리된 특정 필드는 구성 파일 내 명시적으로 정의할 것을 권고한다. 이렇게 하면 서버에 의해 다시 기본 처리되지 않게 될 충돌하는 값을 보다 쉽게 인식할 수 있도록 해준다.

Example:

# last-applied-configuration
spec:
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# configuration file
spec:
  strategy:
    type: Recreate # updated value
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# live configuration
spec:
  strategy:
    type: RollingUpdate # defaulted value
    rollingUpdate: # defaulted value derived from type
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# result after merge - ERROR!
spec:
  strategy:
    type: Recreate # updated value: incompatible with rollingUpdate
    rollingUpdate: # defaulted value: incompatible with "type: Recreate"
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

설명:

  1. 사용자가 strategy.type을 정의하지 않고 디플로이먼트를 생성한다.
  2. 서버는 strategy.type을 RollingUpdate로 기본 설정하고 strategy.rollingUpdate값을 기본 값으로 처리한다.
  3. 사용자가 strategy.type를 Recreate로 변경한다. 서버에서 해당 값이 삭제될 거라 예상하지만 strategy.rollingUpdate값은 기본값으로 남아 있다.
    strategy.rollingUpdate값이 처음에 구성 파일에서 지정되었다면, 이것을 삭제해야 한다는 것이 더 분명했을 것이다.
  4. strategy.rollingUpdate가 지워지지 않았기 때문에 적용은 실패한다. strategy.rollingupdate 필드는 Recreate의 strategy.type으로 정의될 수 없다.

권고: 이들 필드는 오브젝트 구성 파일 내 명시적으로 정의돼야 한다.

  • 디플로이먼트, 스테이트풀셋, 잡, 데몬셋, 레플리카셋 및 레플리케이션컨트롤러와 같은 워크로드에 대한 셀렉터와 파드템플릿 레이블
  • 디플로이먼트 롤아웃 전략

서버 기본 필드 또는 다른 작성자에 의해 설정된 필드 지우는 방법

구성 파일 내 나타나지 않는 필드는 그 값을 null로 설정하고 나서 구성 파일을 적용함으로써 지워질 수 있다. 서버가 기본 값을 할당했던 필드에 대해서, 이는 다시 기본 값을 할당하도록 한다.

구성 파일과 직접 명령형 작성자 간의 필드 소유권을 변경시키는 방법

개별 오브젝트 필드를 변경시키는 데 사용해야 하는 유일한 방법은 다음과 같다.

  • kubectl apply를 사용한다.
  • 구성 파일을 수정하지 않고 활성 구성을 직접 작성한다. 예를 들어, kubectl scale을 사용한다.

직접 명령형 작성자에서 구성 파일로 소유자 변경하기

구성 파일에 필드를 추가한다. 해당 필드의 경우 kubectl apply를 거치지 않는 활성 구성에 대해 직접 업데이트를 적용하지 않는다.

구성 파일에서 직접 명령형 작성자로 소유자 변경하기

쿠버네티스 1.5로부터 구성 파일에서 명령형 작성자로 소유권을 변경하는데 수동 단계 필요하다.

  • 구성 파일에서 필드를 제거한다.
  • 활성 오브젝트 상의 kubectl.kubernetes.io/last-applied-configuration 어노테이션에서 필드를 제거한다.

관리 방법 변경하기

쿠버네티스 오브젝트는 한 번에 오직 하나의 방법을 사용하여 관리돼야 한다. 하나의 방법에서 다른 방법으로 전환하는 것은 가능하나, 수동 프로세스이다.

참고: 선언형 관리와 함께 명령형 삭제를 사용하는 것은 괜찮다.

명령형 커맨드 관리에서 오브젝트 구성으로 이전하기

명령형 커맨드 관리에서 오브젝트 구성으로 이전하는 것은 여러 수동 단계를 포함한다.

  1. 활성 오브젝트를 로컬 구성 파일로 내보낸다.

    kubectl get <종류>/<이름> -o yaml > <종류>_<이름>.yaml

  2. 구성 파일에서 수동으로 status 필드를 제거한다.

    참고: kubectl apply 구성 파일에 존재한다고 하더라도 상태 필드가 업데이트되지 않기 때문에, 이 단계는 선택적이다.

  3. 오브젝트의 kubectl.kubernetes.io/last-applied-configuration 어노테이션을 설정한다.

    kubectl replace --save-config -f <종류>_<이름>.yaml

  4. 오직 오브젝트를 관리하기 위해 kubectl apply를 사용하도록 프로세스를 변경한다.

명령형 오브젝트 구성에서 선언형 오브젝트 구성으로 이전하기

  1. 오브젝트의 kubectl.kubernetes.io/last-applied-configuration 어노테이션을 설정한다.

    kubectl replace --save-config -f <종류>_<이름>.yaml

  2. 오직 오브젝트를 관리하기 위해 kubectl apply를 사용하도록 프로세스를 변경한다.

컨트롤러 셀렉터와 파드템플릿 레이블 정의하기

경고: 컨트롤러에서 셀렉터를 업데이트하는 것은 추천되지 않는다.

권고되는 접근 방법은 다른 의미론적 의미를 가지지 않고 컨트롤러에 의해서만 사용되는 단일, 불변의 파드템플릿 레이블을 정의하는 것이다.

예시:

selector:
  matchLabels:
      controller-selector: "apps/v1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "apps/v1/deployment/nginx"

다음 내용

4.2 - Kustomize를 이용한 쿠버네티스 오브젝트의 선언형 관리

Kustomize는 kustomization 파일을 통해 쿠버네티스 오브젝트를 사용자가 원하는 대로 변경하는(customize) 독립형 도구이다.

1.14 이후로, kubectl도 kustomization 파일을 사용한 쿠버네티스 오브젝트의 관리를 지원한다. kustomization 파일을 포함하는 디렉터리 내의 리소스를 보려면 다음 명령어를 실행한다.

kubectl kustomize <kustomization_directory>

이 리소스를 적용하려면 kubectl apply를 --kustomize 또는 -k 플래그와 함께 실행한다.

kubectl apply -k <kustomization_directory>

시작하기 전에

kubectl을 설치한다.

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

Kustomize 개요

Kustomize는 쿠버네티스 구성을 사용자 정의화하는 도구이다. 이는 애플리케이션 구성 파일을 관리하기 위해 다음 기능들을 가진다.

  • 다른 소스에서 리소스 생성
  • 리소스에 대한 교차 편집 필드 설정
  • 리소스 집합을 구성하고 사용자 정의

리소스 생성

컨피그맵과 시크릿은 파드와 같은 다른 쿠버네티스 오브젝트에서 사용되는 설정이나 민감한 데이터를 가지고 있다. 컨피그맵이나 시크릿의 실질적인 소스는 일반적으로 .properties 파일이나 ssh key 파일과 같은 것들은 클러스터 외부에 있다. Kustomize는 시크릿과 컨피그맵을 파일이나 문자열에서 생성하는 secretGenerator와 configMapGenerator를 가지고 있다.

configMapGenerator

파일에서 컨피그맵을 생성하려면 configMapGenerator 내의 files 리스트에 항목을 추가한다. 다음은 하나의 .properties 파일에서 데이터 항목으로 컨피그맵을 생성하는 예제이다.

# application.properties 파일을 생성
cat <<EOF >application.properties
FOO=Bar
EOF

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
  files:
  - application.properties
EOF

생성된 컨피그맵은 다음 명령어로 검사할 수 있다.

kubectl kustomize ./

생성된 컨피그맵은 다음과 같다.

apiVersion: v1
data:
  application.properties: |
        FOO=Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-8mbdf7882g

env 파일에서 컨피그맵을 생성하려면, configMapGenerator의 envs 리스트에 항목을 추가한다. 다음은 .env 파일의 데이터 항목으로 컨피그맵을 생성하는 예시를 보여준다.

# .env 파일 생성
cat <<EOF >.env
FOO=Bar
EOF

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
  envs:
  - .env
EOF

생성된 컨피그맵은 다음 명령어로 검사할 수 있다.

kubectl kustomize ./

생성된 컨피그맵은 다음과 같다.

apiVersion: v1
data:
    FOO=Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-8mbdf7882g
참고: .env 파일의 각 변수는 생성한 컨피그맵에서 분리된 키가 된다. .properties 라는 이름의 파일을 내장하는 이전 예시(그리고 모든 항목들)는 단일 키를 위한 값이므로 이 예시와는 다르다.

컨피그맵은 문자로된 키-값 쌍들로도 생성할 수 있다. 문자로된 키-값 쌍에서 컨피그맵을 생성하려면, configMapGenerator 내의 literals 리스트에 항목을 추가한다. 다음은 키-값 쌍을 데이터 항목으로 받는 컨피그맵을 생성하는 예제이다.

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-2
  literals:
  - FOO=Bar
EOF

생성된 컨피그맵은 다음 명령어로 확인할 수 있다.

kubectl kustomize ./

생성된 컨피그맵은 다음과 같다.

apiVersion: v1
data:
  FOO: Bar
kind: ConfigMap
metadata:
  name: example-configmap-2-g2hdhfc6tk

디플로이먼트에서 생성된 컨피그맵을 사용하기 위해서는, configMapGenerator의 이름을 참조한다. Kustomize는 자동으로 해당 이름을 생성된 이름으로 교체할 것이다.

다음은 생성된 컨피그맵을 사용하는 디플로이먼트의 예시다.

# application.properties 파일을 생성한다.
cat <<EOF >application.properties
FOO=Bar
EOF

cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app
        volumeMounts:
        - name: config
          mountPath: /config
      volumes:
      - name: config
        configMap:
          name: example-configmap-1
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
configMapGenerator:
- name: example-configmap-1
  files:
  - application.properties
EOF

컨피그맵과 디플로이먼트를 생성한다.

kubectl kustomize ./

생성된 디플로이먼트는 이름을 통해서 생성된 컨피그맵을 참조한다.

apiVersion: v1
data:
  application.properties: |
        FOO=Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-g4hk9g2ff8
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: my-app
  name: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - image: my-app
        name: app
        volumeMounts:
        - mountPath: /config
          name: config
      volumes:
      - configMap:
          name: example-configmap-1-g4hk9g2ff8
        name: config

secretGenerator

파일 또는 문자로된 키-값 쌍들로 시크릿을 생성할 수 있다. 파일에서 시크릿을 생성하려면 secretGenerator 내의 files 리스트에 항목을 추가한다. 다음은 파일을 데이터 항목으로 받는 시크릿을 생성하는 예제이다.

# password.txt 파일을 생성
cat <<EOF >./password.txt
username=admin
password=secret
EOF

cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-1
  files:
  - password.txt
EOF

생성된 시크릿은 다음과 같다.

apiVersion: v1
data:
  password.txt: dXNlcm5hbWU9YWRtaW4KcGFzc3dvcmQ9c2VjcmV0Cg==
kind: Secret
metadata:
  name: example-secret-1-t2kt65hgtb
type: Opaque

문자로된 키-값 쌍으로 시크릿을 생성하려면, secretGenerator 내의 literals 리스트에 항목을 추가한다. 다음은 키-값 쌍을 데이터 항목으로 받는 시크릿을 생성하는 예제이다.

cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-2
  literals:
  - username=admin
  - password=secret
EOF

생성된 시크릿은 다음과 같다.

apiVersion: v1
data:
  password: c2VjcmV0
  username: YWRtaW4=
kind: Secret
metadata:
  name: example-secret-2-t52t6g96d8
type: Opaque

컨피그맵과 유사하게, 생성된 시크릿도 secretGenerator의 이름을 참조함으로써 디플로이먼트에서 사용될 수 있다.

# password.txt 파일을 생성한다.
cat <<EOF >./password.txt
username=admin
password=secret
EOF

cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app
        volumeMounts:
        - name: password
          mountPath: /secrets
      volumes:
      - name: password
        secret:
          secretName: example-secret-1
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
secretGenerator:
- name: example-secret-1
  files:
  - password.txt
EOF

generatorOptions

생성된 컨피그맵과 시크릿은 콘텐츠 해시 접미사가 추가된다. 이는 콘텐츠가 변경될 때 새로운 컨피그맵 이나 시크릿이 생성되는 것을 보장한다. 접미사를 추가하는 동작을 비활성화하는 방법으로 generatorOptions를 사용할 수 있다. 그밖에, 생성된 컨피그맵과 시크릿에 교차 편집 옵션들을 지정해주는 것도 가능하다.

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-3
  literals:
  - FOO=Bar
generatorOptions:
  disableNameSuffixHash: true
  labels:
    type: generated
  annotations:
    note: generated
EOF

생성된 컨피그맵을 보려면 kubectl kustomize ./를 실행한다.

apiVersion: v1
data:
  FOO: Bar
kind: ConfigMap
metadata:
  annotations:
    note: generated
  labels:
    type: generated
  name: example-configmap-3

교차 편집 필드 설정

프로젝트 내 모든 쿠버네티스 리소스에 교차 편집 필드를 설정하는 것은 꽤나 일반적이다. 교차 편집 필드를 설정하는 몇 가지 사용 사례는 다음과 같다.

  • 모든 리소스에 동일한 네임스페이스를 설정
  • 동일한 네임 접두사 또는 접미사를 추가
  • 동일한 레이블들을 추가
  • 동일한 어노테이션들을 추가

다음은 예제이다.

# deployment.yaml을 생성
cat <<EOF >./deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
EOF

cat <<EOF >./kustomization.yaml
namespace: my-namespace
namePrefix: dev-
nameSuffix: "-001"
commonLabels:
  app: bingo
commonAnnotations:
  oncallPager: 800-555-1212
resources:
- deployment.yaml
EOF

이 필드들이 디플로이먼트 리소스에 모두 설정되었는지 보려면 kubectl kustomize ./를 실행한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    oncallPager: 800-555-1212
  labels:
    app: bingo
  name: dev-nginx-deployment-001
  namespace: my-namespace
spec:
  selector:
    matchLabels:
      app: bingo
  template:
    metadata:
      annotations:
        oncallPager: 800-555-1212
      labels:
        app: bingo
    spec:
      containers:
      - image: nginx
        name: nginx

리소스 구성과 사용자 정의

프로젝트 내 리소스의 집합을 구성하여 이들을 동일한 파일이나 디렉터리 내에서 관리하는 것은 일반적이다. Kustomize는 서로 다른 파일들로 리소스를 구성하고 패치나 다른 사용자 정의를 이들에 적용하는 것을 제공한다.

구성

Kustomize는 서로 다른 리소스들의 구성을 지원한다. kustomization.yaml 파일 내 resources 필드는 구성 내에 포함하려는 리소스들의 리스트를 정의한다. resources 리스트 내에 리소스의 구성 파일의 경로를 설정한다. 다음 예제는 디플로이먼트와 서비스로 구성된 NGINX 애플리케이션이다.

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# service.yaml 파일 생성
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF

# 이들을 구성하는 kustomization.yaml 생성
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF

kubectl kustomize ./의 리소스에는 디플로이먼트와 서비스 오브젝트가 모두 포함되어 있다.

사용자 정의

패치는 리소스에 다른 사용자 정의를 적용하는 데 사용할 수 있다. Kustomize는 patchesStrategicMerge와 patchesJson6902를 통해 서로 다른 패치 메커니즘을 지원한다. patchesStrategicMerge는 파일 경로들의 리스트이다. 각각의 파일은 전략적 병합 패치로 분석될 수 있어야 한다. 패치 내부의 네임은 반드시 이미 읽혀진 리소스 네임과 일치해야 한다. 한 가지 일을 하는 작은 패치가 권장된다. 예를 들기 위해 디플로이먼트 레플리카 숫자를 증가시키는 하나의 패치와 메모리 상한을 설정하는 다른 패치를 생성한다.

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# increase_replicas.yaml 패치 생성
cat <<EOF > increase_replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
EOF

# 다른 패치로 set_memory.yaml 생성
cat <<EOF > set_memory.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  template:
    spec:
      containers:
      - name: my-nginx
        resources:
          limits:
            memory: 512Mi
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
patchesStrategicMerge:
- increase_replicas.yaml
- set_memory.yaml
EOF

디플로이먼트를 보려면 kubectl kustomize ./를 실행한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: nginx
        name: my-nginx
        ports:
        - containerPort: 80
        resources:
          limits:
            memory: 512Mi

모든 리소스 또는 필드가 전략적 병합 패치를 지원하는 것은 아니다. 임의의 리소스 내 임의의 필드의 수정을 지원하기 위해, Kustomize는 patchesJson6902를 통한 JSON 패치 적용을 제공한다. Json 패치의 정확한 리소스를 찾기 위해, 해당 리소스의 group, version, kind, name이 kustomization.yaml 내에 명시될 필요가 있다. 예를 들면, patchesJson6902를 통해 디플로이먼트 오브젝트의 레플리카 개수를 증가시킬 수 있다.

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# json 패치 생성
cat <<EOF > patch.yaml
- op: replace
  path: /spec/replicas
  value: 3
EOF

# kustomization.yaml 생성
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml

patchesJson6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: my-nginx
  path: patch.yaml
EOF

kubectl kustomize ./를 실행하여 replicas 필드가 갱신되었는지 확인한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: nginx
        name: my-nginx
        ports:
        - containerPort: 80

패치 기능에 추가로 Kustomize는 패치를 생성하지 않고 컨테이너 이미지를 사용자 정의하거나 다른 오브젝트의 필드 값을 컨테이너에 주입하는 기능도 제공한다. 예를 들어 kustomization.yaml의 images 필드에 신규 이미지를 지정하여 컨테이너에서 사용되는 이미지를 변경할 수 있다.

cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
images:
- name: nginx
  newName: my.image.registry/nginx
  newTag: 1.4.0
EOF

사용된 이미지가 갱신되었는지 확인하려면 kubectl kustomize ./를 실행한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: my.image.registry/nginx:1.4.0
        name: my-nginx
        ports:
        - containerPort: 80

가끔, 파드 내에서 실행되는 애플리케이션이 다른 오브젝트의 설정 값을 사용해야 할 수도 있다. 예를 들어, 디플로이먼트 오브젝트의 파드는 Env 또는 커맨드 인수로 해당 서비스 네임을 읽어야 한다고 하자. kustomization.yaml 파일에 namePrefix 또는 nameSuffix가 추가되면 서비스 네임이 변경될 수 있다. 커맨드 인수 내에 서비스 네임을 하드 코딩하는 것을 권장하지 않는다. 이 용도에서 Kustomize는 vars를 통해 containers에 서비스 네임을 삽입할 수 있다.

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        command: ["start", "--host", "$(MY_SERVICE_NAME)"]
EOF

# service.yaml 파일 생성
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF

cat <<EOF >./kustomization.yaml
namePrefix: dev-
nameSuffix: "-001"

resources:
- deployment.yaml
- service.yaml

vars:
- name: MY_SERVICE_NAME
  objref:
    kind: Service
    name: my-nginx
    apiVersion: v1
EOF

kubectl kustomize ./를 실행하면 dev-my-nginx-001로 컨테이너에 삽입된 서비스 네임을 볼 수 있다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dev-my-nginx-001
spec:
  replicas: 2
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - command:
        - start
        - --host
        - dev-my-nginx-001
        image: nginx
        name: my-nginx

Base와 Overlay

Kustomize는 base 와 overlay 의 개념을 가지고 있다. base 는 kustomization.yaml 과 함께 사용되는 디렉터리다. 이는 사용자 정의와 관련된 리소스들의 집합을 포함한다. kustomization.yaml의 내부에 표시되는 base는 로컬 디렉터리이거나 원격 리포지터리의 디렉터리가 될 수 있다. overlay 는 kustomization.yaml이 있는 디렉터리로 다른 kustomization 디렉터리들을 bases로 참조한다. base 는 overlay에 대해서 알지 못하며 여러 overlay들에서 사용될 수 있다. 한 overlay는 다수의 base들을 가질 수 있고, base들에서 모든 리소스를 구성할 수 있으며, 이들의 위에 사용자 정의도 가질 수 있다.

다음은 base에 대한 예이다.

# base를 가지는 디렉터리 생성
mkdir base
# base/deployment.yaml 생성
cat <<EOF > base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
EOF

# base/service.yaml 파일 생성
cat <<EOF > base/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF
# base/kustomization.yaml 생성
cat <<EOF > base/kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF

이 base는 다수의 overlay에서 사용될 수 있다. 다른 namePrefix 또는 다른 교차 편집 필드들을 서로 다른 overlay에 추가할 수 있다. 다음 예제는 동일한 base를 사용하는 두 overlay들이다.

mkdir dev
cat <<EOF > dev/kustomization.yaml
bases:
- ../base
namePrefix: dev-
EOF

mkdir prod
cat <<EOF > prod/kustomization.yaml
bases:
- ../base
namePrefix: prod-
EOF

Kustomize를 이용하여 오브젝트를 적용/확인/삭제하는 방법

kustomization.yaml에서 관리되는 리소스를 인식하려면 kubectl 명령어에 --kustomize 나 -k를 사용한다. -k는 다음과 같이 kustomization 디렉터리를 가리키고 있어야 한다는 것을 주의한다.

kubectl apply -k <kustomization directory>/

다음 kustomization.yaml이 주어지고,

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# kustomization.yaml 생성
cat <<EOF >./kustomization.yaml
namePrefix: dev-
commonLabels:
  app: my-nginx
resources:
- deployment.yaml
EOF

디플로이먼트 오브젝트 dev-my-nginx를 적용하려면 다음 명령어를 실행한다.

> kubectl apply -k ./
deployment.apps/dev-my-nginx created

디플로이먼트 오브젝트 dev-my-nginx를 보려면 다음 명령어들 중에 하나를 실행한다.

kubectl get -k ./

kubectl describe -k ./

다음 명령을 실행해서 디플로이먼트 오브젝트 dev-my-nginx 를 매니페스트가 적용된 경우의 클러스터 상태와 비교한다.

kubectl diff -k ./

디플로이먼트 오브젝트 dev-my-nginx를 삭제하려면 다음 명령어를 실행한다.

> kubectl delete -k ./
deployment.apps "dev-my-nginx" deleted

Kustomize 기능 리스트

필드 유형 설명
namespace string 모든 리소스에 네임스페이스 추가
namePrefix string 모든 리소스 네임에 이 필드의 값이 접두사로 추가된다
nameSuffix string 모든 리소스 네임에 이 필드의 값이 접미사로 추가된다
commonLabels map[string]string 모든 리소스와 셀렉터에 추가될 레이블
commonAnnotations map[string]string 모든 리소스에 추가될 어노테이션
resources []string 이 리스트 내 각각의 항목은 반드시 존재하는 리소스 구성 파일로 해석되어야 한다.
configMapGenerator []ConfigMapArgs 이 리스트의 각 항목은 컨피그맵을 생성한다.
secretGenerator []SecretArgs 이 리스트의 각 항목은 시크릿을 생성한다.
generatorOptions GeneratorOptions 모든 컨피그맵 및 시크릿 생성자(generator)의 동작을 수정한다.
bases []string 이 리스트 내 각각의 항목은 kustomization.yaml 파일을 가지는 디렉터리로 해석되어야 한다.
patchesStrategicMerge []string 이 리스트 내 각각의 항목은 쿠버네티스 오브젝트의 전략적 병합 패치로 해석되어야 한다.
patchesJson6902 []Patch 이 리스트 내 각각의 항목은 쿠버네티스 오브젝트와 Json 패치로 해석되어야 한다.
vars []Var 각각의 항목은 한 리소스의 필드에서 텍스트를 캡쳐한다.
images []Image 각각의 항목은 패치를 생성하지 않고 하나의 이미지에 대한 name, tags 그리고/또는 digest를 수정한다.
configurations []string 이 리스트 내 각각의 항목은 Kustomize 변환 설정을 포함하는 파일로 해석되어야 한다.
crds []string 이 리스트 내 각각의 항목은 쿠버네티스 타입에 대한 OpenAPI 정의 파일로 해석되어야 한다.

다음 내용

4.3 - 명령형 커맨드를 이용한 쿠버네티스 오브젝트 관리하기

쿠버네티스 오브젝트는 kubectl 커맨드 라인 툴 속에 내장된 명령형 커맨드를 이용함으로써 바로 신속하게 생성, 업데이트 및 삭제할 수 있다. 이 문서는 어떻게 커맨드가 구성되어 있으며, 이를 사용하여 활성 오브젝트를 어떻게 관리하는 지에 대해 설명한다.

시작하기 전에

kubectl을 설치한다.

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

트레이드 오프

kubectl툴은 3가지 종류의 오브젝트 관리를 지원한다.

  • 명령형 커맨드
  • 명령형 오브젝트 구성
  • 선언형 오브젝트 구성

각 종류별 오브젝트 관리의 장점과 단점에 대한 논의는 쿠버네티스 오브젝트 관리 를 참고한다.

오브젝트 생성 방법

kubectl 툴은 가장 일반적인 오브젝트 타입을 생성하는데 동사 형태 기반의 커맨드를 지원한다. 쿠버네티스 오브젝트 타입에 익숙하지 않은 사용자가 인지할 수 있도록 커맨드 이름이 지어졌다.

  • run: 컨테이너를 실행할 새로운 파드를 생성한다.
  • expose: 파드에 걸쳐 트래픽을 로드 밸런스하도록 새로운 서비스 오브젝트를 생성한다.
  • autoscale: 디플로이먼트와 같이, 하나의 컨트롤러에 대해 자동으로 수평적 스케일이 이루어 지도록 새로운 Autoscaler 오브젝트를 생성한다.

또한 kubectl 툴은 오브젝트 타입에 의해 구동되는 생성 커맨드를 지원한다. 이러한 커맨드는 더 많은 오브젝트 타입을 지원해주며 그 의도하는 바에 대해 보다 명확하게 해주지만, 사용자가 생성하고자 하는 오브젝트 타입에 대해 알 수 있도록 해야 한다.

  • create <오브젝트 타입> [<서브 타입>] <인스턴스명>

일부 오브젝트 타입은 create 커맨드 내 정의할 수 있는 서브 타입을 가진다. 예를 들어, 서비스 오브젝트는 ClusterIP, LoadBalancer 및 NodePort 등을 포함하는 여러 서브 타입을 가진다, 다음은 NodePort 서브 타입을 통해 서비스를 생성하는 예제이다.

kubectl create service nodeport <사용자 서비스 명칭>

이전 예제에서, create service nodeport 커맨드는 create service 커맨드의 서브 커맨드라고 칭한다.

-h 플래그를 사용하여 서브 커맨드에 의해 지원되는 인수 및 플래그를 찾아 볼 수 있다.

kubectl create service nodeport -h

오브젝트 업데이트 방법

kubectl 커맨드는 일반적인 몇몇의 업데이트 작업을 위해 동사 형태 기반의 커맨드를 지원한다. 이 커맨드는 쿠버네티스 오브젝트에 익숙하지 않은 사용자가 설정되어야 하는 특정 필드를 모르는 상태에서도 업데이트를 수행할 수 있도록 이름 지어졌다.

  • scale: 컨트롤러의 레플리카 수를 업데이트 함으로써 파드를 추가 또는 제거하는 컨트롤러를 수평적으로 스케일한다.
  • annotate: 오브젝트로부터 어노테이션을 추가 또는 제거한다.
  • label: 오브젝트에서 레이블을 추가 또는 제거한다.

kubectl 커맨드는 또한 오브젝트 측면에서 구동되는 업데이트 커맨드를 지원한다. 이 측면의 설정은 다른 오브젝트 타입에 대한 다른 필드를 설정 할 수도 있다.

  • set <field>: 오브젝트의 측면을 설정한다.
참고: 쿠버네티스 1.5 버전에서는 모든 동사 형태 기반의 커맨드가 관련된 측면 중심의 커맨드를 가지는 것은 아니다.

kubectl 툴은 활성 오브젝트를 직접 업데이트하기 위해 추가적인 방법을 지원하지만, 쿠버네티스 오브젝트 스키마에 대한 추가적인 이해를 요구한다.

  • edit: 편집기에서 구성을 열어 활성 오브젝트에 대한 원래 그대로의 구성을 바로 편집한다.
  • patch: 패치 문자열를 사용하여 활성 오브젝트를 바로 편집한다. 패치 문자열에 대한 보다 자세한 정보를 보려면 API 규정에서 패치 섹션을 참고한다.

오브젝트 삭제 방법

클러스터에서 오브젝트를 삭제하기 위해 delete 커맨드을 사용할 수 있다.

  • delete <타입>/<이름>
참고: 명령형 커맨드와 명령형 오브젝트 구성 모두 kubectl delete를 사용할 수 있다. 차이점은 커맨드에 전해지는 인수에 있다. 명령형 커맨드로 kubectl delete을 사용하기 위해, 삭제할 오브젝트를 인수로 전한다. 다음은 nginx라는 디플로이먼트 오브젝트를 전하는 예제이다.
kubectl delete deployment/nginx

오브젝트 확인 방법

오브젝트에 대한 정보를 출력하는 몇 가지 커맨드가 있다.

  • get: 일치하는 오브젝트에 대한 기본 정보를 출력한다. 옵션 리스트를 확인하기 위해 get -h를 사용한다.
  • describe: 일치하는 오브젝트에 대해 수집한 상세한 정보를 출력한다.
  • logs: 파드에서 실행 중인 컨테이너에 대한 stdout과 stderr를 출력한다.

생성 전 오브젝트 수정을 위해 set 커맨드 사용하기

create 커맨드에 사용할 수 있는 플래그가 없는 몇 가지 오브젝트 필드가 있다. 이러한 경우, 오브젝트 생성 전에 필드에 대한 값을 정의하기 위해 set과 create을 조합해서 사용할 수 있다. 이는 set 커맨드에 create 커맨드의 출력을 파이프 함으로써 수행할 수 있다. 다음은 관련 예제이다.

kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client | kubectl set selector --local -f - 'environment=qa' -o yaml | kubectl create -f -
  1. kubectl create service -o yaml --dry-run=client 커맨드는 서비스에 대한 구성을 생성하지만, 이를 쿠버네티스 API 서버에 전송하는 대신 YAML 형식으로 stdout에 출력한다.
  2. kubectl set selector --local -f - -o yaml 커맨드는 stdin으로부터 구성을 읽어, YAML 형식으로 stdout에 업데이트된 구성을 기록한다.
  3. kubectl create -f - 커맨드는 stdin을 통해 제공된 구성을 사용하여 오브젝트를 생성한다.

생성 전 오브젝트 수정을 위해 --edit 사용하기

생성 전에 오브젝트에 임의의 변경을 가하기 위해 kubectl create --edit 을 사용할 수 있다. 다음은 관련 예제이다.

kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client > /tmp/srv.yaml
kubectl create --edit -f /tmp/srv.yaml
  1. kubectl create service 커맨드는 서비스에 대한 구성을 생성하고 이를 /tmp/srv.yaml에 저장한다.
  2. kubectl create --edit 커맨드는 오브젝트를 생성하기 전에 편집을 위해 구성파일을 열어준다.

다음 내용

4.4 - 구성파일을 이용한 명령형 쿠버네티스 오브젝트 관리

쿠버네티스 오브젝트는 YAML 또는 JSON으로 작성된 오프젝트 구성파일과 함께 kubectl 커맨드 라인 툴을 이용하여 생성, 업데이트 및 삭제할 수 있다. 이 문서는 구성파일을 이용하여 어떻게 오브젝트를 정의하고 관리할 수 있는지에 대해 설명한다.

시작하기 전에

kubectl을 설치한다.

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

트레이드 오프

kubectl 툴은 3가지 종류의 오브젝트 관리를 지원한다.

  • 명령형 커맨드
  • 명령형 오브젝트 구성
  • 선언형 오브젝트 구성

각 종류별 오브젝트 관리의 장점과 단점에 대한 논의는 쿠버네티스 오브젝트 관리를 참고한다.

오브젝트 생성 방법

구성파일로부터 오브젝트를 생성하기 위해 kubectl create -f를 사용할 수 있다. 보다 상세한 정보는 쿠버네티스 API 참조를 참조한다.

  • kubectl create -f <파일명|url>

오브젝트 업데이트 방법

경고: replace 커맨드로 오브젝트를 업데이트 하게되면, 구성파일에 정의되지 않은 스펙의 모든 부분이 삭제된다. 이는 externalIPs필드가 구성파일로부터 독립적으로 관리되는 LoadBalancer타입의 서비스와 같이, 클러스터 의해 부분적으로 관리되는 스펙의 오브젝트와 함께 사용되어서는 안된다. 독립적으로 관리되는 필드는 replace로 삭제되는 것을 방지하기 위해 구성파일에 복사되어져야만 한다.

구성파일에 따라 활성 오브젝트를 업데이트하기 위해 kubectl replace -f 를 사용할 수 있다.

  • kubectl replace -f <파일명|url>

오브젝트 삭제 방법

구성파일에 정의한 오브젝트를 삭제하기 위해 kubectl delete -f를 사용할 수 있다.

  • kubectl delete -f <파일명|url>
참고:

구성 파일이 metadata 섹션에서 name 필드 대신 generateName 필드를 지정한 경우, kubectl delete -f <filename|url> 을 사용하여 오브젝트를 삭제할 수 없다. 오브젝트를 삭제하려면 다른 플래그를 사용해야 한다. 예를 들면, 다음과 같다.

kubectl delete <type> <name>
kubectl delete <type> -l <label>

오브젝트 확인 방법

구성파일에 정의한 오브젝트에 관한 정보 확인을 위해 kubectl get -f 명령을 사용할 수 있다.

  • kubectl get -f <파일명|url> -o yaml

-o yaml 플래그는 전체 오브젝트 구성이 출력되도록 정의한다. 옵션의 리스트를 확인하기 위해서는 kubectl get -h를 사용한다.

제약사항

create, replace, 그리고 delete 명령은 각 오브젝트의 구성이 그 구성파일 내에 완전하게 정의되고 기록되어질 경우 잘 동작한다. 그러나 활성 오브젝트가 업데이트 되고, 구성파일 안에 병합되지 않으면, 업데이트 내용은 다음번 replace가 실행될 때 삭제될 것이다. 이는 HorizontalPodAutoscaler와 같은 컨트롤러가 활성 오브젝트를 직접적으로 업데이트하도록 할 경우 발생한다. 여기 예시가 있다.

  1. 구성파일로부터 오브젝트를 생성할 경우
  2. 또 다른 소스가 일부 필드를 변경함으로써 오브젝트가 업데이트 되는 경우
  3. 구성파일로부터 오브젝트를 대체할 경우. 스텝 2에서의 다른 소스에 의해 이루어진 변경은 유실된다.

동일 오브젝트에 대해 여러 명의 작성자들로부터의 지원이 필요한 경우, 오브젝트를 관리하기 위해 kubectl apply를 사용할 수 있다.

구성 저장 없이 URL로부터 오브젝트 생성과 편집하기

구성파일에 대한 URL을 가진다고 가정해보자. kubectl create --edit을 사용하여 오브젝트가 생성되기 전에 구성을 변경할 수 있다. 이는 독자가 수정할 수 있는 구성파일을 가르키는 튜토리얼과 작업에 특히 유용하다.

kubectl create -f <url> --edit

명령형 커맨드에서 명령형 오브젝트 구성으로 전환하기

령형 커맨드에서 명령형 오브젝트 구성으로 전환하기 위해 몇 가지 수동 단계를 포함한다.

  1. 다음과 같이 활성 오브젝트를 로컬 오브젝트 구성파일로 내보낸다.

    kubectl get <종류>/<이름> -o yaml > <종류>_<이름>.yaml

  2. 수동으로 오브젝트 구성파일에서 상태 필드를 제거한다.

  3. 이후 오브젝트 관리를 위해, replace만 사용한다.

    kubectl replace -f <종류>_<이름>.yaml

컨트롤러 셀렉터와 PodTemplate 레이블 삭제하기

경고: 컨트롤러에서 셀렉터를 업데이트하지 않도록 강력하게 권고한다.

권고되는 접근방법은 다른 의미론적 의미가 없는 컨트롤러 셀렉터의 의해서만 사용되는 단일, 불변의 PodTemplate 레이블로 정의하는 것이다.

레이블 예시:

selector:
  matchLabels:
      controller-selector: "apps/v1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "apps/v1/deployment/nginx"

다음 내용

5 - 애플리케이션에 데이터 주입하기

워크로드를 실행하는 파드에 대한 구성과 기타 데이터를 지정한다.

5.1 - 컨테이너를 위한 커맨드와 인자 정의하기

본 페이지는 파드 안에서 컨테이너를 실행할 때 커맨드와 인자를 정의하는 방법에 대해 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

파드를 생성할 때 커맨드와 인자를 정의하기

파드를 생성할 때, 파드 안에서 동작하는 컨테이너를 위한 커맨드와 인자를 정의할 수 있다. 커맨드를 정의하기 위해서는, 파드 안에서 실행되는 컨테이너에 command 필드를 포함시킨다. 커맨드에 대한 인자를 정의하기 위해서는, 구성 파일에 args 필드를 포함시킨다. 정의한 커맨드와 인자들은 파드가 생성되고 난 이후에는 변경될 수 없다.

구성 파일 안에서 정의하는 커맨드와 인자들은 컨테이너 이미지가 제공하는 기본 커맨드와 인자들보다 우선시 된다. 만약 인자들을 정의하고 커맨드를 정의하지 않는다면, 기본 커맨드가 새로운 인자와 함께 사용된다.

참고: command 필드는 일부 컨테이너 런타임에서 entrypoint에 해당된다. 아래의 참고사항을 확인하자.

이 예제에서는 한 개의 컨테이너를 실행하는 파드를 생성한다. 파드를 위한 구성 파일에서 커맨드와 두 개의 인자를 정의한다.

pods/commands.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: command-demo
  labels:
    purpose: demonstrate-command
spec:
  containers:
  - name: command-demo-container
    image: debian
    command: ["printenv"]
    args: ["HOSTNAME", "KUBERNETES_PORT"]
  restartPolicy: OnFailure

  1. YAML 구성 파일을 활용해 파드를 생성한다.

    kubectl apply -f https://k8s.io/examples/pods/commands.yaml

  2. 실행 중인 파드들의 목록을 조회한다.

    kubectl get pods

    출력은 command-demo라는 파드 안에서 실행된 컨테이너가 완료되었다고 표시할 것이다.

  3. 컨테이너 안에서 실행된 커맨드의 출력을 보기 위해, 파드의 로그를 확인한다.

    kubectl logs command-demo

    출력은 HOSTNAME과 KUBERNETES_PORT 환경 변수들의 값들을 표시할 것이다.

    command-demo
tcp://10.3.240.1:443

인자를 정의하기 위해 환경 변수를 사용하기

이전 예제에서는, 문자열을 제공하면서 직접 인자를 정의해보았다. 문자열을 직접 제공하는 것에 대한 대안으로, 환경 변수들을 사용하여 인자들을 정의할 수 있다.

env:
- name: MESSAGE
  value: "hello world"
command: ["/bin/echo"]
args: ["$(MESSAGE)"]

이것은 컨피그 맵과 시크릿을 포함해, 환경 변수를 정의하는데 활용할 수 있는 모든 방법들을 활용해서 파드를 위한 인자를 정의할 수 있다는 것을 의미한다.

참고: 환경 변수는 "$(VAR)"와 같이 괄호 안에 나타난다. 이는 변수가 command나 args 필드 안에서 전개되기 위해 필요한 것이다.

셸 안에서 커맨드 실행하기

일부 경우들에서는 커맨드를 셸 안에서 실행해야할 필요가 있다. 예를 들어, 실행할 커맨드가 서로 연결되어 있는 여러 개의 커맨드들로 구성되어 있거나, 셸 스크립트일 수도 있다. 셸 안에서 커맨드를 실행하려고 한다면, 이런 방식으로 감싸주면 된다.

command: ["/bin/sh"]
args: ["-c", "while true; do echo hello; sleep 10;done"]

참고사항

이 테이블은 도커와 쿠버네티스에서 사용되는 필드 이름들을 정리한 것이다.

설명 도커 필드 이름 쿠버네티스 필드 이름
컨테이너에서 실행되는 커맨드 Entrypoint command
커맨드에 전달되는 인자들 Cmd arg

기본 Entrypoint와 Cmd 값을 덮어쓰려고 한다면, 아래의 규칙들이 적용된다.

  • 만약 컨테이너를 위한 command 값이나 args 값을 제공하지 않는다면, 도커 이미지 안에 제공되는 기본 값들이 사용된다.

  • 만약 컨테이너를 위한 command 값을 제공하고, args 값을 제공하지 않는다면, 제공된 command 값만이 사용된다. 도커 이미지 안에 정의된 기본 EntryPoint 값과 기본 Cmd 값은 덮어쓰여진다.

  • 만약 컨테이너를 위한 args 값만 제공한다면, 도커 이미지 안에 정의된 기본 EntryPoint 값이 정의한 args 값들과 함께 실행된다.

  • command 값과 args 값을 동시에 정의한다면, 도커 이미지 안에 정의된 기본 EntryPoint 값과 기본 Cmd 값이 덮어쓰여진다. command가 args 값과 함께 실행된다.

여기 몇 가지 예시들이 있다.

이미지 Entrypoint 이미지 Cmd 컨테이너 command 컨테이너 args 실행되는 커맨드
[/ep-1] [foo bar] <설정되지 않음> <설정되지 않음> [ep-1 foo bar]
[/ep-1] [foo bar] [/ep-2] <설정되지 않음> [ep-2]
[/ep-1] [foo bar] <설정되지 않음> [zoo boo] [ep-1 zoo boo]
[/ep-1] [foo bar] [/ep-2] [zoo boo] [ep-2 zoo boo]

다음 내용

5.2 - 컨테이너를 위한 환경 변수 정의하기

본 페이지는 쿠버네티스 파드의 컨테이너를 위한 환경 변수를 정의하는 방법에 대해 설명한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

컨테이너를 위한 환경 변수 정의하기

파드를 생성할 때, 파드 안에서 동작하는 컨테이너를 위한 환경 변수를 설정할 수 있다. 환경 변수를 설정하려면, 구성 파일에 env나 envFrom 필드를 포함시켜야 한다.

이 예제에서, 한 개의 컨테이너를 실행하는 파드를 생성한다. 파드를 위한 구성 파일은 DEMO_GREETING 이라는 이름과 "Hello from the environment"이라는 값을 가지는 환경 변수를 정의한다. 다음은 파드를 위한 구성 매니페스트 예시이다.

pods/inject/envars.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: envar-demo
  labels:
    purpose: demonstrate-envars
spec:
  containers:
  - name: envar-demo-container
    image: gcr.io/google-samples/node-hello:1.0
    env:
    - name: DEMO_GREETING
      value: "Hello from the environment"
    - name: DEMO_FAREWELL
      value: "Such a sweet sorrow"

  1. YAML 구성 파일을 활용해 파드를 생성한다.

    kubectl apply -f https://k8s.io/examples/pods/inject/envars.yaml

  2. 실행 중인 파드들의 목록을 조회한다.

    kubectl get pods -l purpose=demonstrate-envars

    출력은 아래와 비슷할 것이다.

    NAME            READY     STATUS    RESTARTS   AGE
envar-demo      1/1       Running   0          9s

  3. 파드의 컨테이너 환경 변수를 나열한다.

    kubectl exec envar-demo -- printenv

    출력은 아래와 비슷할 것이다.

    NODE_VERSION=4.4.2
EXAMPLE_SERVICE_PORT_8080_TCP_ADDR=10.3.245.237
HOSTNAME=envar-demo
...
DEMO_GREETING=Hello from the environment
DEMO_FAREWELL=Such a sweet sorrow
참고: env 나 envFrom 필드를 이용해 설정된 환경 변수들은 컨테이너 이미지 안에서 명시된 모든 환경 변수들을 오버라이딩한다.
참고: 환경 변수는 서로를 참조할 수 있는데, 이 때 순서에 주의해야 한다. 동일한 컨텍스트에서 정의된 다른 변수를 참조하는 변수는 목록의 뒤쪽에 나와야 한다. 또한, 순환 참조는 피해야 한다.

설정 안에서 환경 변수 사용하기

파드의 구성 파일 안에서 정의한 환경 변수는 파드의 컨테이너를 위해 설정하는 커맨드와 인자들과 같이, 구성 파일 안의 다른 곳에서 사용할 수 있다. 아래의 구성 파일 예시에서, GREETING, HONORIFIC, 그리고 NAME 환경 변수들이 각각 Warm greetings to, The Most honorable, 그리고 Kubernetes로 설정되어 있다. 이 환경 변수들은 이후 env-print-demo 컨테이너에 전달되어 CLI 인자에서 사용된다.

apiVersion: v1
kind: Pod
metadata:
  name: print-greeting
spec:
  containers:
  - name: env-print-demo
    image: bash
    env:
    - name: GREETING
      value: "Warm greetings to"
    - name: HONORIFIC
      value: "The Most Honorable"
    - name: NAME
      value: "Kubernetes"
    command: ["echo"]
    args: ["$(GREETING) $(HONORIFIC) $(NAME)"]

컨테이너가 생성되면, echo Warm greetings to The Most Honorable Kubernetes 커맨드가 컨테이너에서 실행된다.

다음 내용

6 - 애플리케이션 실행

스테이트리스와 스테이트풀 애플리케이션 모두를 실행하고 관리한다.

6.1 - 단일 인스턴스 스테이트풀 애플리케이션 실행하기

이 페이지에서는 쿠버네티스 클러스터에서 퍼시스턴트볼륨(PersistentVolume)과 디플로이먼트(Deployment)를 사용하여, 단일 인스턴스 스테이트풀 애플리케이션을 실행하는 방법을 보인다. 해당 애플리케이션은 MySQL이다.

목적

  • 사용자 환경의 디스크를 참조하는 퍼시스턴트볼륨 생성하기
  • MySQL 디플로이먼트 생성하기
  • 알려진 DNS 이름으로 클러스터의 다른 파드에 MySQL 서비스 노출하기

시작하기 전에

  • 쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

    버전 확인을 위해서, 다음 커맨드를 실행 kubectl version.

  • 여기에서 사용된 퍼시스턴트볼륨클레임을 만족하기 위하여, 기본 스토리지클래스나 정적으로(statically) 프로비저닝 된 퍼시스턴트볼륨을 갖는 퍼시스턴트 볼륨 프로비저너가 필요하다.

MySQL 배포하기

쿠버네티스 디플로이먼트를 생성하고 퍼시스턴트볼륨클레임(PersistentVolumeClaim)을 사용하는 기존 퍼시스턴트볼륨에 연결하여 스테이트풀 애플리케이션을 실행할 수 있다. 예를 들어, 다음 YAML 파일은 MySQL을 실행하고 퍼시스턴트볼륨클레임을 참조하는 디플로이먼트를 기술한다. 이 파일은 /var/lib/mysql에 대한 볼륨 마운트를 정의한 후에, 20G의 볼륨을 요청하는 퍼시트턴트볼륨클레임을 생성한다. 이 클레임은 요구 사항에 적합한 기존 볼륨이나 동적 프로비저너에 의해서 충족된다.

참고: config yaml 파일에 정의된 비밀번호는 안전하지 않다. 더 안전한 해결방법을 위해 쿠버네티스 시크릿 을 보자

application/mysql/mysql-deployment.yaml 
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  ports:
  - port: 3306
  selector:
    app: mysql
  clusterIP: None
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  selector:
    matchLabels:
      app: mysql
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - image: mysql:5.6
        name: mysql
        env:
          # Use secret in real usage
        - name: MYSQL_ROOT_PASSWORD
          value: password
        ports:
        - containerPort: 3306
          name: mysql
        volumeMounts:
        - name: mysql-persistent-storage
          mountPath: /var/lib/mysql
      volumes:
      - name: mysql-persistent-storage
        persistentVolumeClaim:
          claimName: mysql-pv-claim
application/mysql/mysql-pv.yaml 
apiVersion: v1
kind: PersistentVolume
metadata:
  name: mysql-pv-volume
  labels:
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 20Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mysql-pv-claim
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi

  1. YAML 파일의 PV와 PVC를 배포한다.

     kubectl apply -f https://k8s.io/examples/application/mysql/mysql-pv.yaml

  2. YAML 파일의 다른 오브젝트들을 배포한다.

     kubectl apply -f https://k8s.io/examples/application/mysql/mysql-deployment.yaml

  3. 디플로이먼트에 관한 정보를 확인한다.

     kubectl describe deployment mysql

    출력은 다음과 유사하다.

     Name:                 mysql
 Namespace:            default
 CreationTimestamp:    Tue, 01 Nov 2016 11:18:45 -0700
 Labels:               app=mysql
 Annotations:          deployment.kubernetes.io/revision=1
 Selector:             app=mysql
 Replicas:             1 desired | 1 updated | 1 total | 0 available | 1 unavailable
 StrategyType:         Recreate
 MinReadySeconds:      0
 Pod Template:
   Labels:       app=mysql
   Containers:
    mysql:
     Image:      mysql:5.6
     Port:       3306/TCP
     Environment:
       MYSQL_ROOT_PASSWORD:      password
     Mounts:
       /var/lib/mysql from mysql-persistent-storage (rw)
   Volumes:
    mysql-persistent-storage:
     Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
     ClaimName:  mysql-pv-claim
     ReadOnly:   false
 Conditions:
   Type          Status  Reason
   ----          ------  ------
   Available     False   MinimumReplicasUnavailable
   Progressing   True    ReplicaSetUpdated
 OldReplicaSets:       <none>
 NewReplicaSet:        mysql-63082529 (1/1 replicas created)
 Events:
   FirstSeen    LastSeen    Count    From                SubobjectPath    Type        Reason            Message
   ---------    --------    -----    ----                -------------    --------    ------            -------
   33s          33s         1        {deployment-controller }             Normal      ScalingReplicaSet Scaled up replica set mysql-63082529 to 1

  4. 디플로이먼트로 생성된 파드를 나열한다.

     kubectl get pods -l app=mysql

    출력은 다음과 유사하다.

     NAME                   READY     STATUS    RESTARTS   AGE
 mysql-63082529-2z3ki   1/1       Running   0          3m

  5. 퍼시스턴트볼륨클레임을 살펴본다.

     kubectl describe pvc mysql-pv-claim

    출력은 다음과 유사하다.

     Name:         mysql-pv-claim
 Namespace:    default
 StorageClass:
 Status:       Bound
 Volume:       mysql-pv-volume
 Labels:       <none>
 Annotations:    pv.kubernetes.io/bind-completed=yes
                 pv.kubernetes.io/bound-by-controller=yes
 Capacity:     20Gi
 Access Modes: RWO
 Events:       <none>

MySQL 인스턴스 접근하기

이전의 YAML 파일은 클러스터의 다른 파드가 데이터베이스에 접근할 수 있는 서비스를 생성한다. clusterIP: None 서비스 옵션을 사용하면 서비스의 DNS 이름을 직접 파드의 IP 주소로 해석하도록 처리한다. 이 방법은 서비스에서 연결되는 파드가 오직 하나 뿐이고, 파드의 수를 더 늘릴 필요가 없는 경우에 가장 적합하다.

서버에 접속하기 위하여 MySQL 클라이언트를 실행한다.

kubectl run -it --rm --image=mysql:5.6 --restart=Never mysql-client -- mysql -h mysql -ppassword

이 명령어는 MySQL 클라이언트를 실행하는 파드를 클러스터에 생성하고, 서비스를 통하여 서버에 연결한다. 연결된다면, 스테이트풀 MySQL 데이터베이스가 실행 중임을 알 수 있다.

Waiting for pod default/mysql-client-274442439-zyp6i to be running, status is Pending, pod ready: false
If you don't see a command prompt, try pressing enter.

mysql>

업데이트하기

kubectl apply 명령을 사용하여 기존과 동일한 방식으로 디플로이먼트의 이미지나 다른 부분을 변경할 수 있다. 스테이트풀 애플리케이션과 관련하여 몇 가지 주의 사항이 있다.

  • 애플리케이션을 스케일링하지 않는다. 이 설정은 단일 인스턴스 애플리케이션 전용이다. 기본적인 퍼시스턴트볼륨은 하나의 파드에서만 마운트할 수 있다. 클러스터 형태의 스테이트풀 애플리케이션에 대해서는 스테이트풀셋을 보자.
  • 디플로이먼트 구성 YAML 파일에서 strategy: type: Recreate 를 사용한다. 이는 쿠버네티스가 롤링 업데이트를 사용하지 않도록 지시한다. 동시에 두 개 이상의 파드를 생성할 수 없으므로, 롤링 업데이트는 일어나지 않게 된다. Recreate 전략을 사용하면 변경된 구성으로 새로운 파드를 생성하기에 앞서 기존의 파드를 중단한다.

디플로이먼트 삭제하기

이름으로 배포된 오브젝트를 삭제한다.

kubectl delete deployment,svc mysql
kubectl delete pvc mysql-pv-claim
kubectl delete pv mysql-pv-volume

퍼시스턴트볼륨을 수동으로 프로비저닝한 경우라면, 동일하게 수동으로 삭제하고 기본 리소스도 해제해야 한다. 동적 프로비저너를 사용한 경우, 퍼시스턴트볼륨클레임이 삭제되었을 때에 퍼시스턴트볼륨 또한 자동으로 삭제된다. 일부 동적 프로비저너(EBS 와 PD와 같은)는 퍼시스턴트볼륨을 삭제할 때에 기본 리소스도 해제한다.

다음 내용

6.2 - 스테이트풀셋(StatefulSet) 삭제하기

이 작업은 스테이트풀셋을 삭제하는 방법을 설명한다.

시작하기 전에

  • 이 작업은 클러스터에 스테이트풀셋으로 표시되는 애플리케이션이 있다고 가정한다.

스테이트풀셋 삭제

쿠버네티스에서 다른 리소스를 삭제하는 것과 같은 방식으로 스테이트풀셋을 삭제할 수 있다. kubectl delete 명령어를 사용하고 파일 또는 이름으로 스테이트풀셋을 지정하자.

kubectl delete -f <file.yaml>

kubectl delete statefulsets <statefulset-name>

스테이트풀셋 자체를 삭제한 후 연결된 헤드리스 서비스는 별도로 삭제해야 할 수도 있다.

kubectl delete service <service-name>

kubectl을 통해 스테이트풀셋을 삭제하면, 스테이트풀셋의 크기가 0으로 설정되고 이로 인해 스테이트풀셋에 포함된 모든 파드가 삭제된다. 파드가 아닌 스테이트풀셋만 삭제하려면, --cascade=orphan 옵션을 사용한다. 예시는 다음과 같다.

kubectl delete -f <file.yaml> --cascade=orphan

kubectl delete 에 --cascade=orphan 를 사용하면 스테이트풀셋 오브젝트가 삭제된 후에도 스테이트풀셋에 의해 관리된 파드는 남게 된다. 만약 파드가 app=myapp 레이블을 갖고 있다면, 다음과 같이 파드를 삭제할 수 있다.

kubectl delete pods -l app=myapp

퍼시스턴트볼륨(PersistentVolume)

스테이트풀셋의 파드들을 삭제하는 것이 연결된 볼륨을 삭제하는 것은 아니다. 이것은 볼륨을 삭제하기 전에 볼륨에서 데이터를 복사할 수 있는 기회를 준다. 파드가 종료된 후 PVC를 삭제하면 스토리지 클래스와 반환 정책에 따라 백업 퍼시스턴트볼륨 삭제가 트리거될 수 있다. 클레임 삭제 후 볼륨에 접근할 수 있다고 가정하면 안된다.

참고: PVC를 삭제할 때 데이터 손실될 수 있음에 주의하자.

스테이트풀셋의 완벽한 삭제

연결된 파드를 포함해서 스테이트풀셋의 모든 것을 삭제하기 위해 다음과 같이 일련의 명령을 실행한다.

grace=$(kubectl get pods <stateful-set-pod> --template '{{.spec.terminationGracePeriodSeconds}}')
kubectl delete statefulset -l app=myapp
sleep $grace
kubectl delete pvc -l app=myapp

위의 예에서 파드에는 app=myapp 라는 레이블이 있다. 사용자에게 적절한 레이블로 대체하자.

스테이트풀셋 파드의 강제 삭제

스테이트풀셋의 일부 파드가 오랫동안 'Terminating' 또는 'Unknown' 상태에 있는 경우, apiserver에 수동적으로 개입하여 파드를 강제 삭제할 수도 있다. 이것은 잠재적으로 위험한 작업이다. 자세한 설명은 스테이트풀셋 파드 강제 삭제하기를 참고한다.

다음 내용

스테이트풀셋 파드 강제 삭제하기에 대해 더 알아보기.

6.3 - Horizontal Pod Autoscaler

Horizontal Pod Autoscaler는 CPU 사용량 (또는 사용자 정의 메트릭, 아니면 다른 애플리케이션 지원 메트릭)을 관찰하여 레플리케이션 컨트롤러(ReplicationController), 디플로이먼트(Deployment), 레플리카셋(ReplicaSet) 또는 스테이트풀셋(StatefulSet)의 파드 개수를 자동으로 스케일한다. Horizontal Pod Autoscaler는 크기를 조정할 수 없는 오브젝트(예: 데몬셋(DaemonSet))에는 적용되지 않는다.

Horizontal Pod Autoscaler는 쿠버네티스 API 리소스 및 컨트롤러로 구현된다. 리소스는 컨트롤러의 동작을 결정한다. 컨트롤러는 평균 CPU 사용률, 평균 메모리 사용률 또는 다른 커스텀 메트릭과 같은 관찰 대상 메트릭이 사용자가 지정한 목표값과 일치하도록 레플리케이션 컨트롤러 또는 디플로이먼트에서 레플리카 개수를 주기적으로 조정한다.

Horizontal Pod Autoscaler는 어떻게 작동하는가?

Horizontal Pod Autoscaler 다이어그램

Horizontal Pod Autoscaler는 컨트롤러 관리자의 --horizontal-pod-autoscaler-sync-period 플래그(기본값은 15초)에 의해 제어되는 주기를 가진 컨트롤 루프로 구현된다.

각 주기 동안 컨트롤러 관리자는 각 HorizontalPodAutoscaler 정의에 지정된 메트릭에 대해 리소스 사용률을 질의한다. 컨트롤러 관리자는 리소스 메트릭 API(파드 단위 리소스 메트릭 용) 또는 사용자 지정 메트릭 API(다른 모든 메트릭 용)에서 메트릭을 가져온다.

  • 파드 단위 리소스 메트릭(예 : CPU)의 경우 컨트롤러는 HorizontalPodAutoscaler가 대상으로하는 각 파드에 대한 리소스 메트릭 API에서 메트릭을 가져온다. 그런 다음, 목표 사용률 값이 설정되면, 컨트롤러는 각 파드의 컨테이너에 대한 동등한 자원 요청을 퍼센트 단위로 하여 사용률 값을 계산한다. 대상 원시 값이 설정된 경우 원시 메트릭 값이 직접 사용된다. 그리고, 컨트롤러는 모든 대상 파드에서 사용된 사용률의 평균 또는 원시 값(지정된 대상 유형에 따라 다름)을 가져와서 원하는 레플리카의 개수를 스케일하는데 사용되는 비율을 생성한다.

    파드의 컨테이너 중 일부에 적절한 리소스 요청이 설정되지 않은 경우, 파드의 CPU 사용률은 정의되지 않으며, 따라서 오토스케일러는 해당 메트릭에 대해 아무런 조치도 취하지 않는다. 오토스케일링 알고리즘의 작동 방식에 대한 자세한 내용은 아래 알고리즘 세부 정보 섹션을 참조하기 바란다.

  • 파드 단위 사용자 정의 메트릭의 경우, 컨트롤러는 사용률 값이 아닌 원시 값을 사용한다는 점을 제외하고는 파드 단위 리소스 메트릭과 유사하게 작동한다.

  • 오브젝트 메트릭 및 외부 메트릭의 경우, 문제의 오브젝트를 표현하는 단일 메트릭을 가져온다. 이 메트릭은 목표 값과 비교되어 위와 같은 비율을 생성한다. autoscaling/v2beta2 API 버전에서는, 비교가 이루어지기 전에 해당 값을 파드의 개수로 선택적으로 나눌 수 있다.

HorizontalPodAutoscaler는 보통 일련의 API 집합(metrics.k8s.io, custom.metrics.k8s.io, external.metrics.k8s.io)에서 메트릭을 가져온다. metrics.k8s.io API는 대개 별도로 시작해야 하는 메트릭-서버에 의해 제공된다. 가이드는 메트릭-서버를 참조한다. HorizontalPodAutoscaler는 힙스터(Heapster)에서 직접 메트릭을 가져올 수도 있다.

참고:
FEATURE STATE: Kubernetes v1.11 [deprecated]

힙스터에서 메트릭 가져오기는 Kubernetes 1.11에서 사용 중단(deprecated)됨.

자세한 사항은 메트릭 API를 위한 지원을 참조한다.

오토스케일러는 스케일 하위 리소스를 사용하여 상응하는 확장 가능 컨트롤러(예: 레플리케이션 컨트롤러, 디플로이먼트, 레플리케이션 셋)에 접근한다. 스케일은 레플리카의 개수를 동적으로 설정하고 각 현재 상태를 검사 할 수 있게 해주는 인터페이스이다. 하위 리소스 스케일에 대한 자세한 내용은 여기에서 확인할 수 있다.

알고리즘 세부 정보

가장 기본적인 관점에서, Horizontal Pod Autoscaler 컨트롤러는 원하는(desired) 메트릭 값과 현재(current) 메트릭 값 사이의 비율로 작동한다.

원하는 레플리카 수 = ceil[현재 레플리카 수 * ( 현재 메트릭 값 / 원하는 메트릭 값 )]

예를 들어 현재 메트릭 값이 200m이고 원하는 값이 100m인 경우 200.0 / 100.0 == 2.0이므로 복제본 수가 두 배가 된다. 만약 현재 값이 50m 이면, 50.0 / 100.0 == 0.5 이므로 복제본 수를 반으로 줄일 것이다. 비율이 1.0(0.1을 기본값으로 사용하는 -horizontal-pod-autoscaler-tolerance 플래그를 사용하여 전역적으로 구성 가능한 허용 오차 내)에 충분히 가깝다면 스케일링을 건너 뛸 것이다.

targetAverageValue 또는 targetAverageUtilization가 지정되면, currentMetricValue는 HorizontalPodAutoscaler의 스케일 목표 안에 있는 모든 파드에서 주어진 메트릭의 평균을 취하여 계산된다. 허용치를 확인하고 최종 값을 결정하기 전에, 파드 준비 상태와 누락된 메트릭을 고려한다.

삭제 타임 스탬프가 설정된 모든 파드(즉, 종료 중인 파드) 및 실패한 파드는 모두 폐기된다.

특정 파드에 메트릭이 누락된 경우, 나중을 위해 처리를 미뤄두는데, 이와 같이 누락된 메트릭이 있는 모든 파드는 최종 스케일 량을 조정하는데 사용된다.

CPU를 스케일할 때, 어떤 파드라도 아직 준비가 안되었거나 (즉, 여전히 초기화 중인 경우) * 또는 * 파드의 최신 메트릭 포인트가 준비되기 전이라면, 마찬가지로 해당 파드는 나중에 처리된다.

기술적 제약으로 인해, HorizontalPodAutoscaler 컨트롤러는 특정 CPU 메트릭을 나중에 사용할지 말지 결정할 때, 파드가 준비되는 시작 시간을 정확하게 알 수 없다. 대신, 파드가 아직 준비되지 않았고 시작 이후 짧은 시간 내에 파드가 준비되지 않은 상태로 전환된다면, 해당 파드를 "아직 준비되지 않음(not yet ready)"으로 간주한다. 이 값은 --horizontal-pod-autoscaler-initial-readiness-delay 플래그로 설정되며, 기본값은 30초 이다. 일단 파드가 준비되고 시작된 후 구성 가능한 시간 이내이면, 준비를 위한 어떠한 전환이라도 이를 시작 시간으로 간주한다. 이 값은 --horizontal-pod-autoscaler-cpu-initialization-period 플래그로 설정되며 기본값은 5분이다.

현재 메트릭 값 / 원하는 메트릭 값 기본 스케일 비율은 나중에 사용하기로 되어 있거나 위에서 폐기되지 않은 남아있는 파드를 사용하여 계산된다.

누락된 메트릭이 있는 경우, 파드가 스케일 다운의 경우 원하는 값의 100%를 소비하고 스케일 업의 경우 0%를 소비한다고 가정하여 평균을 보다 보수적으로 재계산한다. 이것은 잠재적인 스케일의 크기를 약화시킨다.

또한 아직-준비되지-않은 파드가 있는 경우 누락된 메트릭이나 아직-준비되지-않은 파드를 고려하지 않고 스케일 업했을 경우, 아직-준비되지-않은 파드가 원하는 메트릭의 0%를 소비한다고 보수적으로 가정하고 스케일 확장의 크기를 약화시킨다.

아직-준비되지-않은 파드나 누락된 메트릭을 고려한 후에 사용 비율을 다시 계산한다. 새 비율이 스케일 방향을 바꾸거나, 허용 오차 내에 있으면 스케일링을 건너뛴다. 그렇지 않으면, 새 비율을 사용하여 스케일한다.

평균 사용량에 대한 원래 값은 새로운 사용 비율이 사용되는 경우에도 아직-준비되지-않은 파드 또는 누락된 메트릭에 대한 고려없이 HorizontalPodAutoscaler 상태를 통해 다시 보고된다.

HorizontalPodAutoscaler에 여러 메트릭이 지정된 경우, 이 계산은 각 메트릭에 대해 수행된 다음 원하는 레플리카 수 중 가장 큰 값이 선택된다. 이러한 메트릭 중 어떠한 것도 원하는 레플리카 수로 변환할 수 없는 경우(예 : 메트릭 API에서 메트릭을 가져오는 중 오류 발생) 스케일을 건너뛴다. 이는 하나 이상의 메트릭이 현재 값보다 높은 desiredReplicas 을 제공하는 경우 HPA가 여전히 확장할 수 있음을 의미한다.

마지막으로, HPA가 목표를 스케일하기 직전에 스케일 권장 사항이 기록된다. 컨트롤러는 구성 가능한 창(window) 내에서 가장 높은 권장 사항을 선택하도록 해당 창 내의 모든 권장 사항을 고려한다. 이 값은 --horizontal-pod-autoscaler-downscale-stabilization 플래그를 사용하여 설정할 수 있고, 기본값은 5분이다. 즉, 스케일 다운이 점진적으로 발생하여 급격히 변동하는 메트릭 값의 영향을 완만하게 한다.

API 오브젝트

Horizontal Pod Autoscaler는 쿠버네티스 autoscaling API 그룹의 API 리소스이다. CPU에 대한 오토스케일링 지원만 포함하는 안정된 버전은 autoscaling/v1 API 버전에서 찾을 수 있다.

메모리 및 사용자 정의 메트릭에 대한 스케일링 지원을 포함하는 베타 버전은 autoscaling/v2beta2에서 확인할 수 있다. autoscaling/v2beta2에서 소개된 새로운 필드는 autoscaling/v1로 작업할 때 어노테이션으로 보존된다.

HorizontalPodAutoscaler API 오브젝트 생성시 지정된 이름이 유효한 DNS 서브도메인 이름인지 확인해야 한다. API 오브젝트에 대한 자세한 내용은 HorizontalPodAutoscaler 오브젝트에서 찾을 수 있다.

kubectl에서 Horizontal Pod Autoscaler 지원

Horizontal Pod Autoscaler는 모든 API 리소스와 마찬가지로 kubectl에 의해 표준 방식으로 지원된다. kubectl create 커맨드를 사용하여 새로운 오토스케일러를 만들 수 있다. kubectl get hpa로 오토스케일러 목록을 조회할 수 있고, kubectl describe hpa로 세부 사항을 확인할 수 있다. 마지막으로 kubectl delete hpa를 사용하여 오토스케일러를 삭제할 수 있다.

또한 Horizontal Pod Autoscaler를 생성할 수 있는 kubectl autoscale이라는 특별한 명령이 있다. 예를 들어 kubectl autoscale rs foo --min=2 --max=5 --cpu-percent=80을 실행하면 레플리케이션 셋 foo 에 대한 오토스케일러가 생성되고, 목표 CPU 사용률은 80 %, 그리고 2와 5 사이의 레플리카 개수로 설정된다. kubectl autoscale에 대한 자세한 문서는 여기에서 찾을 수 있다.

롤링 업데이트 중 오토스케일링

현재 쿠버네티스에서는 기본 레플리카셋를 관리하는 디플로이먼트 오브젝트를 사용하여 롤링 업데이트를 수행할 수 있다. Horizontal Pod Autoscaler는 후자의 방법을 지원한다. Horizontal Pod Autoscaler는 디플로이먼트 오브젝트에 바인딩되고, 디플로이먼트 오브젝트를 위한 크기를 설정하며, 디플로이먼트는 기본 레플리카셋의 크기를 결정한다.

Horizontal Pod Autoscaler는 레플리케이션 컨트롤러를 직접 조작하는 롤링 업데이트에서 작동하지 않는다. 즉, Horizontal Pod Autoscaler를 레플리케이션 컨트롤러에 바인딩하고 롤링 업데이트를 수행할 수 없다. (예 : kubectl rolling-update) 작동하지 않는 이유는 롤링 업데이트에서 새 레플리케이션 컨트롤러를 만들 때, Horizontal Pod Autoscaler가 새 레플리케이션 컨트롤러에 바인딩되지 않기 때문이다.

쿨-다운 / 지연에 대한 지원

Horizontal Pod Autoscaler를 사용하여 레플리카 그룹의 스케일을 관리할 때, 평가된 메트릭의 동적인 특징 때문에 레플리카 수가 자주 변동할 수 있다. 이것은 때로는 스래싱 (thrashing) 이라고도 한다.

v1.6 부터 클러스터 운영자는 kube-controller-manager 컴포넌트의 플래그로 노출된 글로벌 HPA 설정을 튜닝하여 이 문제를 완화할 수 있다.

v1.12부터는 새로운 알고리즘 업데이트가 업스케일 지연에 대한 필요성을 제거하였다.

  • --horizontal-pod-autoscaler-downscale-delay : 다운스케일이 안정화되기까지의 시간 간격을 지정한다. Horizontal Pod Autoscaler는 이전의 권장하는 크기를 기억하고, 이 시간 간격에서의 가장 큰 크기에서만 작동한다. 기본값은 5분(5m0s)이다.
참고: 이러한 파라미터 값을 조정할 때 클러스터 운영자는 가능한 결과를 알아야 한다. 지연(쿨-다운) 값이 너무 길면, Horizontal Pod Autoscaler가 워크로드 변경에 반응하지 않는다는 불만이 있을 수 있다. 그러나 지연 값을 너무 짧게 설정하면, 레플리카셋의 크기가 평소와 같이 계속 스래싱될 수 있다.

리소스 메트릭 지원

모든 HPA 대상은 스케일링 대상에서 파드의 리소스 사용량을 기준으로 스케일링할 수 있다. 파드의 명세를 정의할 때는 cpu 및 memory 와 같은 리소스 요청을 지정해야 한다. 이것은 리소스 사용률을 결정하는 데 사용되며 HPA 컨트롤러에서 대상을 스케일링하거나 축소하는 데 사용한다. 리소스 사용률 기반 스케일링을 사용하려면 다음과 같은 메트릭 소스를 지정해야 한다.

type: Resource
resource:
  name: cpu
  target:
    type: Utilization
    averageUtilization: 60

이 메트릭을 사용하면 HPA 컨트롤러는 스케일링 대상에서 파드의 평균 사용률을 60%로 유지한다. 사용률은 파드의 요청된 리소스에 대한 현재 리소스 사용량 간의 비율이다. 사용률 계산 및 평균 산출 방법에 대한 자세한 내용은 알고리즘을 참조한다.

참고: 모든 컨테이너의 리소스 사용량이 합산되므로 총 파드 사용량이 개별 컨테이너 리소스 사용량을 정확하게 나타내지 못할 수 있다. 이로 인해 단일 컨테이너가 높은 사용량으로 실행될 수 있고 전체 파드 사용량이 여전히 허용 가능한 한도 내에 있기 때문에 HPA가 스케일링되지 않는 상황이 발생할 수 있다.

컨테이너 리소스 메트릭

FEATURE STATE: Kubernetes v1.20 [alpha]

HorizontalPodAutoscaler 는 대상 리소스를 스케일링하기 위해 HPA가 파드 집합에서 개별 컨테이너의 리소스 사용량을 추적할 수 있는 컨테이너 메트릭 소스도 지원한다. 이를 통해 특정 파드에서 가장 중요한 컨테이너의 스케일링 임계값을 구성할 수 있다. 예를 들어 웹 애플리케이션 프로그램과 로깅 사이드카가 있는 경우 사이드카 컨테이너와 해당 리소스 사용을 무시하고 웹 애플리케이션의 리소스 사용을 기준으로 스케일링할 수 있다.

대상 리소스를 다른 컨테이너 세트를 사용하여 새 파드 명세를 갖도록 수정하는 경우 새로 추가된 컨테이너도 스케일링에 사용해야 한다면 HPA 사양을 수정해야 한다. 메트릭 소스에 지정된 컨테이너가 없거나 파드의 하위 집합에만 있는 경우 해당 파드는 무시되고 권장 사항이 다시 계산된다. 계산에 대한 자세한 내용은 알고리즘을 을 참조한다. 컨테이너 리소스를 오토스케일링에 사용하려면 다음과 같이 메트릭 소스를 정의한다.

type: ContainerResource
containerResource:
  name: cpu
  container: application
  target:
    type: Utilization
    averageUtilization: 60

위의 예에서 HPA 컨트롤러는 모든 파드의 application 컨테이너에 있는 CPU의 평균 사용률이 60%가 되도록 대상을 조정한다.

참고:

HorizontalPodAutoscaler가 추적하는 컨테이너의 이름을 변경하는 경우 특정 순서로 변경을 수행하여 변경 사항이 적용되는 동안 스케일링을 계속 사용할 수 있고 효율적으로 유지할 수 있다. 컨테이너를 정의하는 리소스(예: 배포)를 업데이트하기 전에 연결된 HPA를 업데이트하여 새 컨테이너 이름과 이전 컨테이너 이름을 모두 추적해야 한다. 이러한 방식으로 HPA는 업데이트 프로세스 전반에 걸쳐 스케일링 권장 사항을 계산할 수 있다.

컨테이너 이름 변경을 워크로드 리소스로 롤아웃한 후에는 HPA 사양에서 이전 컨테이너 이름을 제거하여 정리한다.

멀티 메트릭을 위한 지원

Kubernetes 1.6은 멀티 메트릭을 기반으로 스케일링을 지원한다. autoscaling/v2beta2 API 버전을 사용하여 Horizontal Pod Autoscaler가 스케일을 조정할 멀티 메트릭을 지정할 수 있다. 그런 다음 Horizontal Pod Autoscaler 컨트롤러가 각 메트릭을 평가하고, 해당 메트릭을 기반으로 새 스케일을 제안한다. 제안된 스케일 중 가장 큰 것이 새로운 스케일로 사용된다.

사용자 정의 메트릭을 위한 지원

참고: 쿠버네티스 1.2는 특수 어노테이션을 사용하여 애플리케이션 관련 메트릭을 기반으로 하는 스케일의 알파 지원을 추가했다. 쿠버네티스 1.6에서는 이러한 어노테이션 지원이 제거되고 새로운 오토스케일링 API가 추가되었다. 이전 사용자 정의 메트릭 수집 방법을 계속 사용할 수는 있지만, Horizontal Pod Autoscaler에서는 이 메트릭을 사용할 수 없다. 그리고 Horizontal Pod Autoscaler 컨트롤러에서는 더 이상 스케일 할 사용자 정의 메트릭을 지정하는 이전 어노테이션을 사용할 수 없다.

쿠버네티스 1.6에서는 Horizontal Pod Autoscaler에서 사용자 정의 메트릭을 사용할 수 있도록 지원한다. autoscaling/v2beta2 API에서 사용할 Horizontal Pod Autoscaler에 대한 사용자 정의 메트릭을 추가 할 수 있다. 그리고 쿠버네티스는 새 사용자 정의 메트릭 API에 질의하여 적절한 사용자 정의 메트릭의 값을 가져온다.

요구 사항은 메트릭을 위한 지원을 참조한다.

메트릭 API를 위한 지원

기본적으로 HorizontalPodAutoscaler 컨트롤러는 일련의 API에서 메트릭을 검색한다. 이러한 API에 접속하려면 클러스터 관리자는 다음을 확인해야 한다.

  • API 애그리게이션 레이어 활성화

  • 해당 API 등록:

    • 리소스 메트릭의 경우, 일반적으로 이것은 메트릭-서버가 제공하는 metrics.k8s.io API이다. 클러스터 애드온으로 시작할 수 있다.

    • 사용자 정의 메트릭의 경우, 이것은 custom.metrics.k8s.io API이다. 메트릭 솔루션 공급 업체에서 제공하는 "어댑터" API 서버에서 제공한다. 메트릭 파이프라인 또는 알려진 솔루션 목록으로 확인한다. 직접 작성하고 싶다면 샘플을 확인한다.

    • 외부 메트릭의 경우, 이것은 external.metrics.k8s.io API이다. 위에 제공된 사용자 정의 메트릭 어댑터에서 제공될 수 있다.

  • --horizontal-pod-autoscaler-use-rest-clients는 true이거나 설정되지 않음. 이것을 false로 설정하면 더 이상 사용되지 않는 힙스터 기반 오토스케일링으로 전환된다.

이런 다양한 메트릭 경로와 각각의 다른 점에 대한 상세 내용은 관련 디자인 제안서인 HPA V2, custom.metrics.k8s.io, external.metrics.k8s.io를 참조한다.

어떻게 사용하는지에 대한 예시는 커스텀 메트릭 사용하는 작업 과정과 외부 메트릭스 사용하는 작업 과정을 참조한다.

구성가능한 스케일링 동작 지원

v1.18 부터 v2beta2 API는 HPA behavior 필드를 통해 스케일링 동작을 구성할 수 있다. 동작은 behavior 필드 아래의 scaleUp 또는 scaleDown 섹션에서 스케일링 업과 다운을 위해 별도로 지정된다. 안정화 윈도우는 스케일링 대상에서 레플리카 수의 플래핑(flapping)을 방지하는 양방향에 대해 지정할 수 있다. 마찬가지로 스케일링 정책을 지정하면 스케일링 중 레플리카 변경 속도를 제어할 수 있다.

스케일링 정책

스펙의 behavior 섹션에 하나 이상의 스케일링 폴리시를 지정할 수 있다. 폴리시가 여러 개 지정된 경우 가장 많은 양의 변경을 허용하는 정책이 기본적으로 선택된 폴리시이다. 다음 예시는 스케일 다운 중 이 동작을 보여준다.

behavior:
  scaleDown:
    policies:
    - type: Pods
      value: 4
      periodSeconds: 60
    - type: Percent
      value: 10
      periodSeconds: 60

periodSeconds 는 폴리시가 참(true)으로 유지되어야 하는 기간을 나타낸다. 첫 번째 정책은 (파드들) 이 1분 내에 최대 4개의 레플리카를 스케일 다운할 수 있도록 허용한다. 두 번째 정책은 비율 로 현재 레플리카의 최대 10%를 1분 내에 스케일 다운할 수 있도록 허용한다.

기본적으로 가장 많은 변경을 허용하는 정책이 선택되기에 두 번째 정책은 파드의 레플리카 수가 40개를 초과하는 경우에만 사용된다. 레플리카가 40개 이하인 경우 첫 번째 정책이 적용된다. 예를 들어 80개의 레플리카가 있고 대상을 10개의 레플리카로 축소해야 하는 경우 첫 번째 단계에서 8개의 레플리카가 스케일 다운 된다. 레플리카의 수가 72개일 때 다음 반복에서 파드의 10%는 7.2 이지만, 숫자는 8로 올림된다. 오토스케일러 컨트롤러의 각 루프에서 변경될 파드의 수는 현재 레플리카의 수에 따라 재계산된다. 레플리카의 수가 40 미만으로 떨어지면 첫 번째 폴리시 (파드들) 가 적용되고 한번에 4개의 레플리카가 줄어든다.

확장 방향에 대해 selectPolicy 필드를 확인하여 폴리시 선택을 변경할 수 있다. 레플리카의 수를 최소로 변경할 수 있는 폴리시를 선택하는 최소(Min)로 값을 설정한다. 값을 Disabled 로 설정하면 해당 방향으로 스케일링이 완전히 비활성화 된다.

안정화 윈도우

안정화 윈도우는 스케일링에 사용되는 메트릭이 계속 변동할 때 레플리카의 플래핑을 다시 제한하기 위해 사용된다. 안정화 윈도우는 스케일링을 방지하기 위해 과거부터 계산된 의도한 상태를 고려하는 오토스케일링 알고리즘에 의해 사용된다. 다음의 예시에서 scaleDown 에 대해 안정화 윈도우가 지정되어있다.

scaleDown:
  stabilizationWindowSeconds: 300

메트릭이 대상을 축소해야하는 것을 나타내는 경우 알고리즘은 이전에 계산된 의도한 상태를 살펴보고 지정된 간격의 최고 값을 사용한다. 위의 예시에서 지난 5분 동안 모든 의도한 상태가 고려된다.

기본 동작

사용자 지정 스케일링을 사용하려면 일부 필드를 지정해야 한다. 사용자 정의해야 하는 값만 지정할 수 있다. 이러한 사용자 지정 값은 기본값과 병합된다. 기본값은 HPA 알고리즘의 기존 동작과 일치한다.

behavior:
  scaleDown:
    stabilizationWindowSeconds: 300
    policies:
    - type: Percent
      value: 100
      periodSeconds: 15
  scaleUp:
    stabilizationWindowSeconds: 0
    policies:
    - type: Percent
      value: 100
      periodSeconds: 15
    - type: Pods
      value: 4
      periodSeconds: 15
    selectPolicy: Max

안정화 윈도우의 스케일링 다운의 경우 300 초 (또는 제공된 경우--horizontal-pod-autoscaler-downscale-stabilization 플래그의 값)이다. 스케일링 다운에서는 현재 실행 중인 레플리카의 100%를 제거할 수 있는 단일 정책만 있으며, 이는 스케일링 대상을 최소 허용 레플리카로 축소할 수 있음을 의미한다. 스케일링 업에는 안정화 윈도우가 없다. 메트릭이 대상을 스케일 업해야 한다고 표시된다면 대상이 즉시 스케일 업된다. 두 가지 폴리시가 있다. HPA가 정상 상태에 도달 할 때까지 15초 마다 4개의 파드 또는 현재 실행 중인 레플리카의 100% 가 추가된다.

예시: 다운스케일 안정화 윈도우 변경

사용자 지정 다운스케일 안정화 윈도우를 1분 동안 제공하기 위해 다음 동작이 HPA에 추가된다.

behavior:
  scaleDown:
    stabilizationWindowSeconds: 60

예시: 스케일 다운 비율 제한

HPA에 의해 파드가 제거되는 속도를 분당 10%로 제한하기 위해 다음 동작이 HPA에 추가된다.

behavior:
  scaleDown:
    policies:
    - type: Percent
      value: 10
      periodSeconds: 60

마지막으로 5개의 파드를 드롭하기 위해 다른 폴리시를 추가하고, 최소 선택 전략을 추가할 수 있다. 분당 5개 이하의 파드가 제거되지 않도록, 고정 크기가 5인 두 번째 축소 정책을 추가하고, selectPolicy 를 최소로 설정하면 된다. selectPolicy 를 Min 으로 설정하면 자동 스케일러가 가장 적은 수의 파드에 영향을 주는 정책을 선택함을 의미한다.

behavior:
  scaleDown:
    policies:
    - type: Percent
      value: 10
      periodSeconds: 60
    - type: Pods
      value: 5
      periodSeconds: 60
    selectPolicy: Min

예시: 스케일 다운 비활성화

selectPolicy 의 Disabled 값은 주어진 방향으로의 스케일링을 끈다. 따라서 다운 스케일링을 방지하기 위해 다음 폴리시가 사용된다.

behavior:
  scaleDown:
    selectPolicy: Disabled

암시적 유지 관리 모드 비활성화

HPA 구성 자체를 변경할 필요없이 대상에 대한 HPA를 암시적으로 비활성화할 수 있다. 대상의 의도한 레플리카 수가 0으로 설정되고, HPA의 최소 레플리카 수가 0 보다 크면, 대상의 의도한 레플리카 수 또는 HPA의 최소 레플리카 수를 수동으로 조정하여 다시 활성화할 때까지 HPA는 대상 조정을 중지한다(그리고 ScalingActive 조건 자체를 false로 설정).

다음 내용

6.4 - Horizontal Pod Autoscaler 연습

Horizontal Pod Autoscaler는 CPU 사용량(또는 베타 지원의 다른 애플리케이션 지원 메트릭)을 관찰하여 레플리케이션 컨트롤러, 디플로이먼트, 레플리카셋(ReplicaSet) 또는 스테이트풀셋(StatefulSet)의 파드 개수를 자동으로 스케일한다.

이 문서는 php-apache 서버를 대상으로 Horizontal Pod Autoscaler를 동작해보는 예제이다. Horizontal Pod Autoscaler 동작과 관련된 더 많은 정보를 위해서는 Horizontal Pod Autoscaler 사용자 가이드를 참고하기 바란다.

시작하기 전에

이 예제는 버전 1.2 또는 이상의 쿠버네티스 클러스터와 kubectl을 필요로 한다. 메트릭 서버 모니터링을 클러스터에 배포하여 메트릭 API를 통해 메트릭을 제공해야 한다. Horizontal Pod Autoscaler가 메트릭을 수집할때 해당 API를 사용한다. 메트릭-서버를 배포하는 방법에 대해 배우려면, 메트릭-서버 문서를 참고한다.

Horizontal Pod Autoscaler에 다양한 자원 메트릭을 적용하고자 하는 경우, 버전 1.6 또는 이상의 쿠버네티스 클러스터와 kubectl를 사용해야 한다. 사용자 정의 메트릭을 사용하기 위해서는, 클러스터가 사용자 정의 메트릭 API를 제공하는 API 서버와 통신할 수 있어야 한다. 마지막으로 쿠버네티스 오브젝트와 관련이 없는 메트릭을 사용하는 경우, 버전 1.10 또는 이상의 쿠버네티스 클러스터와 kubectl을 사용해야 하며, 외부 메트릭 API와 통신이 가능해야 한다. 자세한 사항은 Horizontal Pod Autoscaler 사용자 가이드를 참고하길 바란다.

php-apache 서버 구동 및 노출

Horizontal Pod Autoscaler 시연을 위해 php-apache 이미지를 맞춤 제작한 Docker 이미지를 사용한다. Dockerfile은 다음과 같다.

FROM php:5-apache
COPY index.php /var/www/html/index.php
RUN chmod a+rx index.php

index.php는 CPU 과부하 연산을 수행한다.

<?php
  $x = 0.0001;
  for ($i = 0; $i <= 1000000; $i++) {
    $x += sqrt($x);
  }
  echo "OK!";
?>

첫 번째 단계로, 다음 구성을 사용해서 실행 중인 이미지의 디플로이먼트를 시작하고 서비스로 노출시킨다.

application/php-apache.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: php-apache
spec:
  selector:
    matchLabels:
      run: php-apache
  replicas: 1
  template:
    metadata:
      labels:
        run: php-apache
    spec:
      containers:
      - name: php-apache
        image: k8s.gcr.io/hpa-example
        ports:
        - containerPort: 80
        resources:
          limits:
            cpu: 500m
          requests:
            cpu: 200m

---

apiVersion: v1
kind: Service
metadata:
  name: php-apache
  labels:
    run: php-apache
spec:
  ports:
  - port: 80
  selector:
    run: php-apache

다음의 명령어를 실행한다.

kubectl apply -f https://k8s.io/examples/application/php-apache.yaml

deployment.apps/php-apache created
service/php-apache created

Horizontal Pod Autoscaler 생성

이제 서비스가 동작중이므로, kubectl autoscale를 사용하여 오토스케일러를 생성한다. 다음 명령어는 첫 번째 단계에서 만든 php-apache 디플로이먼트 파드의 개수를 1부터 10 사이로 유지하는 Horizontal Pod Autoscaler를 생성한다. 간단히 얘기하면, HPA는 (디플로이먼트를 통한) 평균 CPU 사용량을 50%로 유지하기 위하여 레플리카의 개수를 늘리고 줄인다. (kubectl run으로 각 파드는 200 밀리코어까지 요청할 수 있고, 따라서 여기서 말하는 평균 CPU 사용은 100 밀리코어를 말한다). 이에 대한 자세한 알고리즘은 여기를 참고하기 바란다.

kubectl autoscale deployment php-apache --cpu-percent=50 --min=1 --max=10

horizontalpodautoscaler.autoscaling/php-apache autoscaled

실행 중인 오토스케일러의 현재 상태를 확인해본다.

kubectl get hpa

NAME         REFERENCE                     TARGET    MINPODS   MAXPODS   REPLICAS   AGE
php-apache   Deployment/php-apache/scale   0% / 50%  1         10        1          18s

아직 서버로 어떠한 요청도 하지 않았기 때문에, 현재 CPU 소비는 0%임을 확인할 수 있다 (TARGET은 디플로이먼트에 의해 제어되는 파드들의 평균을 나타낸다).

부하 증가

이번에는 부하가 증가함에 따라 오토스케일러가 어떻게 반응하는지를 살펴볼 것이다. 먼저 컨테이너를 하나 실행하고, php-apache 서비스에 무한루프의 쿼리를 전송한다(다른 터미널을 열어 수행하기 바란다).

kubectl run -i --tty load-generator --rm --image=busybox --restart=Never -- /bin/sh -c "while sleep 0.01; do wget -q -O- http://php-apache; done"

실행 후, 약 1분 정도 후에 CPU 부하가 올라가는 것을 볼 수 있다.

kubectl get hpa

NAME         REFERENCE                     TARGET      MINPODS   MAXPODS   REPLICAS   AGE
php-apache   Deployment/php-apache/scale   305% / 50%  1         10        1          3m

CPU 소비가 305%까지 증가하였다. 결과적으로, 디플로이먼트의 레플리카 개수는 7개까지 증가하였다.

kubectl get deployment php-apache

NAME         READY   UP-TO-DATE   AVAILABLE   AGE
php-apache   7/7      7           7           19m
참고: 레플리카의 개수를 안정화시키는데 몇 분이 걸릴 수 있다. 부하의 양은 환경에 따라 다르기 때문에, 최종 레플리카의 개수는 본 예제와 다를 수 있다.

부하 중지

본 예제를 마무리하기 위해 부하를 중단시킨다.

busybox 컨테이너를 띄운 터미널에서, <Ctrl> + C로 부하 발생을 중단시킨다.

그런 다음 (몇 분 후에) 결과를 확인한다.

kubectl get hpa

NAME         REFERENCE                     TARGET       MINPODS   MAXPODS   REPLICAS   AGE
php-apache   Deployment/php-apache/scale   0% / 50%     1         10        1          11m

kubectl get deployment php-apache

NAME         READY   UP-TO-DATE   AVAILABLE   AGE
php-apache   1/1     1            1           27m

CPU 사용량은 0으로 떨어졌고, HPA는 레플리카의 개수를 1로 낮췄다.

참고: 레플리카 오토스케일링은 몇 분 정도 소요된다.

다양한 메트릭 및 사용자 정의 메트릭을 기초로한 오토스케일링

php-apache 디플로이먼트를 오토스케일링할 때, autoscaling/v2beta2 API 버전을 사용하여 추가적인 메트릭을 제공할 수 있다.

첫 번째로, autoscaling/v2beta2 형식으로 HorizontalPodAutoscaler YAML 파일을 생성한다.

kubectl get hpa.v2beta2.autoscaling -o yaml > /tmp/hpa-v2.yaml

에디터로 /tmp/hpa-v2.yaml 파일을 열면, 다음과 같은 YAML을 확인할 수 있다.

apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  name: php-apache
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: php-apache
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
status:
  observedGeneration: 1
  lastScaleTime: <some-time>
  currentReplicas: 1
  desiredReplicas: 1
  currentMetrics:
  - type: Resource
    resource:
      name: cpu
      current:
        averageUtilization: 0
        averageValue: 0

targetCPUUtilizationPercentage 필드가 metrics 배열로 대체되었다. CPU 사용량 메트릭은 resource metric 으로 파드 컨테이너 자원의 백분율로 표현된다. CPU 외에 다른 메트릭을 지정할 수 있는데, 기본적으로 지원되는 다른 메트릭은 메모리뿐이다. 이 자원들은 한 클러스터에서 다른 클러스터로 이름을 변경할 수 없으며, metrics.k8s.io API가 가용한 경우 언제든지 사용할 수 있어야 한다.

또한, Utilization 대신 AverageValue의 target 타입을, 그리고 target.averageUtilization 대신 target.averageValue로 설정하여 자원 메트릭을 퍼센트 대신 값으로 명시할 수 있다.

파드 메트릭과 오브젝트 메트릭 두 가지의 사용자 정의 메트릭 이 있다. 파드 메트릭과 오브젝트 메트릭. 이 메트릭은 클러스터에 특화된 이름을 가지고 있으며, 더 고급화된 클러스터 모니터링 설정이 필요하다.

이러한 대체 메트릭 타입중 첫 번째는 파드 메트릭 이다. 이 메트릭은 파드들을 설명하고, 파드들간의 평균을 내며, 대상 값과 비교하여 레플리카 개수를 결정한다.

이것들은 AverageValue의 target만을 지원한다는 것을 제외하면, 자원 메트릭과 매우 유사하게 동작한다.

파드 메트릭은 이처럼 메트릭 블록을 사용하여 정의된다.

type: Pods
pods:
  metric:
    name: packets-per-second
  target:
    type: AverageValue
    averageValue: 1k

두 번째 대체 메트릭 타입은 오브젝트 메트릭 이다. 이 메트릭은 파드를 기술하는 대신에 동일한 네임스페이스 내에 다른 오브젝트를 표현한다. 이 메트릭은 반드시 오브젝트로부터 가져올 필요는 없다. 단지 오브젝트를 기술할 뿐이다. 오브젝트 메트릭은 Value과 AverageValue의 target 타입을 지원한다. Value를 사용할 경우 대상은 API로부터 반환되는 메트릭과 직접 비교된다. AverageValue를 사용할 경우, 대상 값과 비교되기 이전에 사용자 정의 메트릭 API로부터 반환된 값은 파드의 개수로 나눠진다. 다음은 requests-per-second 메트릭을 YAML로 기술한 예제이다.

type: Object
object:
  metric:
    name: requests-per-second
  describedObject:
    apiVersion: networking.k8s.io/v1beta1
    kind: Ingress
    name: main-route
  target:
    type: Value
    value: 2k

이러한 메트릭 블록을 여러 개 제공하면, HorizontalPodAutoscaler는 각 메트릭을 차례로 고려한다. HorizontalPodAutoscaler는 각 메트릭에 대해 제안된 레플리카 개수를 계산하고, 그중 가장 높은 레플리카 개수를 선정한다.

예를 들어, 네트워크 트래픽 메트릭을 수집하는 모니터링 시스템이 있는 경우, kubectl edit 명령어를 이용하여 다음과 같이 정의를 업데이트 할 수 있다.

apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  name: php-apache
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: php-apache
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
  - type: Pods
    pods:
      metric:
        name: packets-per-second
      target:
        type: AverageValue
        averageValue: 1k
  - type: Object
    object:
      metric:
        name: requests-per-second
      describedObject:
        apiVersion: networking.k8s.io/v1beta1
        kind: Ingress
        name: main-route
      target:
        type: Value
        value: 10k
status:
  observedGeneration: 1
  lastScaleTime: <some-time>
  currentReplicas: 1
  desiredReplicas: 1
  currentMetrics:
  - type: Resource
    resource:
      name: cpu
    current:
      averageUtilization: 0
      averageValue: 0
  - type: Object
    object:
      metric:
        name: requests-per-second
      describedObject:
        apiVersion: networking.k8s.io/v1beta1
        kind: Ingress
        name: main-route
      current:
        value: 10k

이후, HorizontalPodAutoscaler는 각 파드가 요청 된 약 50%의 CPU 사용률을 소모하는지, 초당 1000 패킷을 처리하는지, 메인-루트 인그레스 뒤의 모든 파드들이 초당 10000 요청을 처리하는지 확인한다.

보다 구체적인 메트릭을 기초로한 오토스케일링

많은 메트릭 파이프라인들을 사용하면 이름 또는 labels 이라 불리는 추가적인 식별자로 메트릭을 설명할 수 있다. 그리고, 모든 비 자원 메트릭 타입(파드, 오브젝트 그리고 아래 기술된 외부 타입)에 대해, 메트릭 파이프라인으로 전달되는 추가 레이블 셀렉터를 지정할 수 있다. 예를 들면, verb 레이블로 http_requests 메트릭을 수집하는 경우, 다음과 같이 메트릭 블록을 지정하여 GET 요청에 대해 크기를 조정할 수 있다.

type: Object
object:
  metric:
    name: http_requests
    selector: {matchLabels: {verb: GET}}

이 셀렉터는 쿠버네티스의 레이블 셀렉터와 동일한 문법이다. 모니터링 파이프라인은 네임과 셀렉터가 여러 시리즈와 일치하는 경우, 해당 여러 시리즈를 단일 값으로 축소하는 방법을 결정한다. 셀렉터는 부가적인 속성이며, 대상 오브젝트(Pods 타입의 대상 파드, Object 타입으로 기술된 오브젝트)가 아닌 메트릭을 선택할 수 없다.

쿠버네티스 오브젝트와 관련이 없는 메트릭을 기초로한 오토스케일링

쿠버네티스 위에서 동작하는 애플리케이션은, 쿠버네티스 클러스터의 어떤 오브젝트와도 관련이 없는 메트릭에 기반하여 오토스케일링을 할 수도 있다. 예로, 쿠버네티스 네임스페이스와 관련이 없는 서비스를 기초로한 메트릭을 들 수 있다. 쿠버네티스 버전 1.10 포함 이후 버전에서, 외부 메트릭 을 사용하여 이러한 유스케이스를 해결할 수 있다.

외부 메트릭 사용시, 먼저 모니터링 시스템에 대한 이해가 있어야 한다. 이 설치는 사용자 정의 메트릭과 유사하다. 외부 메트릭을 사용하면 모니터링 시스템의 사용 가능한 메트릭에 기반하여 클러스터를 오토스케일링 할 수 있다. 위의 예제처럼 name과 selector를 갖는 metric 블록을 명시하고, Object 대신에 External 메트릭 타입을 사용한다. 만일 여러 개의 시계열이 metricSelector와 일치하면, HorizontalPodAutoscaler가 값의 합을 사용한다. 외부 메트릭들은 Value와 AverageValue 대상 타입을 모두 지원하고, Object 타입을 사용할 때와 똑같이 동작한다.

예를 들면 애플리케이션이 호스팅 된 대기열 서비스에서 작업을 처리하는 경우, 다음과 같이 HorizontalPodAutoscaler 매니퍼스트에 30개의 미해결 태스크 당 한 개의 워커를 지정하도록 추가할 수 있다.

- type: External
  external:
    metric:
      name: queue_messages_ready
      selector: "queue=worker_tasks"
    target:
      type: AverageValue
      averageValue: 30

가능하다면, 외부 메트릭 대신 사용자 정의 메트릭 대상 타입을 사용하길 권장한다. 왜냐하면, 클러스터 관리자가 사용자 정의 메트릭 API를 보안관점에서 더 쉽게 보호할 수 있기 때문이다. 외부 메트릭 API는 잠재적으로 어떠한 메트릭에도 접근할 수 있기에, 클러스터 관리자는 API를 노출시킬때 신중해야 한다.

부록: Horizontal Pod Autoscaler 상태 조건

HorizontalPodAutoscaler의 autoscaling/v2beta2 형식을 사용하면, HorizontalPodAutoscaler에서 쿠버네티스가 설정한 상태 조건 을 확인할 수 있다. 이 상태 조건들은 HorizontalPodAutoscaler가 스케일을 할 수 있는지, 어떤 방식으로든 제한되어 있는지 여부를 나타낸다.

이 조건은 status.conditions에 나타난다. HorizontalPodAutoscaler에 영향을 주는 조건을 보기 위해 kubectl describe hpa를 사용할 수 있다.

kubectl describe hpa cm-test

Name:                           cm-test
Namespace:                      prom
Labels:                         <none>
Annotations:                    <none>
CreationTimestamp:              Fri, 16 Jun 2017 18:09:22 +0000
Reference:                      ReplicationController/cm-test
Metrics:                        ( current / target )
  "http_requests" on pods:      66m / 500m
Min replicas:                   1
Max replicas:                   4
ReplicationController pods:     1 current / 1 desired
Conditions:
  Type                  Status  Reason                  Message
  ----                  ------  ------                  -------
  AbleToScale           True    ReadyForNewScale        the last scale time was sufficiently old as to warrant a new scale
  ScalingActive         True    ValidMetricFound        the HPA was able to successfully calculate a replica count from pods metric http_requests
  ScalingLimited        False   DesiredWithinRange      the desired replica count is within the acceptable range
Events:

이 HorizontalPodAutoscaler 경우, 건강 상태의 여러 조건들을 볼 수 있다. 첫 번째 AbleToScale는 HPA가 스케일을 가져오고 업데이트할 수 있는지, 백 오프 관련 조건으로 스케일링이 방지되는지 여부를 나타낸다. 두 번째 ScalingActive는 HPA가 활성화되어있는지(즉 대상 레플리카 개수가 0이 아닌지), 원하는 스케일을 계산할 수 있는지 여부를 나타낸다. 만약 False 인 경우, 일반적으로 메트릭을 가져오는데 문제가 있다. 마지막으로, 마지막 조건인 ScalingLimited는 원하는 스케일 한도가 HorizontalPodAutoscaler의 최대/최소값으로 제한돼있음을 나타낸다. 이는 HorizontalPodAutoscaler에서 레플리카의 개수 제한을 최대/최소값으로 올리거나 낮추려는 것이다.

부록: 수량

HorizontalPodAutoscaler와 메트릭 API에서 모든 메트릭은 쿠버네티스에서 사용하는 수량 숫자 표기법을 사용한다. 예를 들면, 10500m 수량은 10진법 10.5으로 쓰인다. 메트릭 API들은 가능한 경우 접미사 없이 정수를 반환하며, 일반적으로 수량을 밀리단위로 반환한다. 10진수로 표현했을때, 1과 1500m 또는 1과 1.5 로 메트릭 값을 나타낼 수 있다.

부록: 다른 가능한 시나리오

명시적으로 오토스케일러 만들기

HorizontalPodAutoscaler를 생성하기 위해 kubectl autoscale 명령어를 사용하지 않고, 명시적으로 다음 파일을 사용하여 만들 수 있다.

application/hpa/php-apache.yaml 
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: php-apache
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: php-apache
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 50

다음 명령어를 실행하여 오토스케일러를 생성할 것이다.

kubectl create -f https://k8s.io/examples/application/hpa/php-apache.yaml

horizontalpodautoscaler.autoscaling/php-apache created

6.5 - 파드 내에서 쿠버네티스 API에 접근

이 페이지는 파드 내에서 쿠버네티스 API에 접근하는 방법을 보여준다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

파드 내에서 API에 접근

파드 내에서 API에 접근할 때, API 서버를 찾아 인증하는 것은 위에서 설명한 외부 클라이언트 사례와 약간 다르다.

파드에서 쿠버네티스 API를 사용하는 가장 쉬운 방법은 공식 클라이언트 라이브러리 중 하나를 사용하는 것이다. 이러한 라이브러리는 API 서버를 자동으로 감지하고 인증할 수 있다.

공식 클라이언트 라이브러리 사용

파드 내에서, 쿠버네티스 API에 연결하는 권장 방법은 다음과 같다.

각각의 경우, 파드의 서비스 어카운트 자격 증명은 API 서버와 안전하게 통신하는 데 사용된다.

REST API에 직접 접근

파드에서 실행되는 동안, 쿠버네티스 apiserver는 default 네임스페이스에서 kubernetes라는 서비스를 통해 접근할 수 있다. 따라서, 파드는 kubernetes.default.svc 호스트 이름을 사용하여 API 서버를 쿼리할 수 있다. 공식 클라이언트 라이브러리는 이를 자동으로 수행한다.

API 서버를 인증하는 권장 방법은 서비스 어카운트 자격 증명을 사용하는 것이다. 기본적으로, 파드는 서비스 어카운트와 연결되어 있으며, 해당 서비스 어카운트에 대한 자격 증명(토큰)은 해당 파드에 있는 각 컨테이너의 파일시스템 트리의 /var/run/secrets/kubernetes.io/serviceaccount/token 에 있다.

사용 가능한 경우, 인증서 번들은 각 컨테이너의 파일시스템 트리의 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 에 배치되며, API 서버의 제공 인증서를 확인하는 데 사용해야 한다.

마지막으로, 네임스페이스가 지정된 API 작업에 사용되는 기본 네임스페이스는 각 컨테이너의 /var/run/secrets/kubernetes.io/serviceaccount/namespace 에 있는 파일에 배치된다.

kubectl 프록시 사용

공식 클라이언트 라이브러리 없이 API를 쿼리하려면, 파드에서 새 사이드카 컨테이너의 명령으로 kubectl proxy 를 실행할 수 있다. 이런 식으로, kubectl proxy 는 API를 인증하고 이를 파드의 localhost 인터페이스에 노출시켜서, 파드의 다른 컨테이너가 직접 사용할 수 있도록 한다.

프록시를 사용하지 않고 접근

인증 토큰을 API 서버에 직접 전달하여 kubectl 프록시 사용을 피할 수 있다. 내부 인증서는 연결을 보호한다.

# 내부 API 서버 호스트 이름을 가리킨다
APISERVER=https://kubernetes.default.svc

# 서비스어카운트(ServiceAccount) 토큰 경로
SERVICEACCOUNT=/var/run/secrets/kubernetes.io/serviceaccount

# 이 파드의 네임스페이스를 읽는다
NAMESPACE=$(cat ${SERVICEACCOUNT}/namespace)

# 서비스어카운트 베어러 토큰을 읽는다
TOKEN=$(cat ${SERVICEACCOUNT}/token)

# 내부 인증 기관(CA)을 참조한다
CACERT=${SERVICEACCOUNT}/ca.crt

# TOKEN으로 API를 탐색한다
curl --cacert ${CACERT} --header "Authorization: Bearer ${TOKEN}" -X GET ${APISERVER}/api

출력은 다음과 비슷하다.

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

7 - 잡(Job) 실행

병렬 처리를 사용하여 잡을 실행한다.

7.1 - 크론잡(CronJob)으로 자동화된 작업 실행

쿠버네티스 버전 1.21에서 크론잡이 GA (General Availability)로 승격되었다. 이전 버전의 쿠버네티스를 사용하고 있다면, 해당 쿠버네티스 버전의 문서를 참고하여 정확한 정보를 확인할 수 있다. 이전 버전의 쿠버네티스는 batch/v1 크론잡 API를 지원하지 않는다.

시간 기반의 스케줄에 따라 크론잡을 이용해서 잡(Job)을 실행할 수 있다. 이러한 자동화된 잡은 리눅스 또는 유닉스 시스템에서 크론 작업처럼 실행된다.

크론 잡은 백업을 수행하거나 이메일을 보내는 것과 같이 주기적이고 반복적인 작업들을 생성하는 데 유용하다. 크론 잡은 시스템 사용이 적은 시간에 잡을 스케줄하려는 경우처럼 특정 시간에 개별 작업을 스케줄할 수도 있다.

크론 잡에는 제한 사항과 특이점이 있다. 예를 들어, 특정 상황에서는 하나의 크론 잡이 여러 잡을 생성할 수 있다. 따라서, 잡은 멱등성을 가져야 한다.

제한 사항에 대한 자세한 내용은 크론잡을 참고한다.

시작하기 전에

  • 쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

크론 잡 생성

크론 잡은 구성 파일이 필요하다. 아래의 크론 잡 구성 .spec 파일의 예제는 매 분마다 현재 시간과 hello 메시지를 출력한다.

application/job/cronjob.yaml 
apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hello
            image: busybox
            imagePullPolicy: IfNotPresent
            command:
            - /bin/sh
            - -c
            - date; echo Hello from the Kubernetes cluster
          restartPolicy: OnFailure

다음 명령을 사용하여 크론잡 예제를 실행한다.

kubectl create -f https://k8s.io/examples/application/job/cronjob.yaml

출력 결과는 다음과 비슷하다.

cronjob.batch/hello created

크론 잡을 생성한 후, 다음 명령을 사용하여 상태를 가져온다.

kubectl get cronjob hello

출력 결과는 다음과 비슷하다.

NAME    SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
hello   */1 * * * *   False     0        <none>          10s

명령의 결과에서 알 수 있듯이, 크론 잡은 아직 잡을 스케줄하거나 실행하지 않았다. 약 1분 내로 잡이 생성되는지 확인한다.

kubectl get jobs --watch

출력 결과는 다음과 비슷하다.

NAME               COMPLETIONS   DURATION   AGE
hello-4111706356   0/1                      0s
hello-4111706356   0/1           0s         0s
hello-4111706356   1/1           5s         5s

이제 "hello" 크론 잡에 의해 스케줄된 실행 중인 작업을 확인했다. 잡 감시를 중지한 뒤에 크론 잡이 다시 스케줄되었는지를 확인할 수 있다.

kubectl get cronjob hello

출력 결과는 다음과 비슷하다.

NAME    SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
hello   */1 * * * *   False     0        50s             75s

크론 잡 hello 가 LAST SCHEDULE 에 지정된 시간에 성공적으로 잡을 스케줄했는지 확인해야 한다. 현재는 0개의 활성 잡이 있고, 이는 작업이 완료되었거나 실패했음을 의미한다.

이제, 마지막으로 스케줄된 잡이 생성한 파드를 찾고 생성된 파드 중 하나의 표준 출력을 확인한다.

참고: 잡 이름과 파드 이름은 다르다.
# "hello-4111706356"을 사용자의 시스템에 있는 잡 이름으로 바꾼다
pods=$(kubectl get pods --selector=job-name=hello-4111706356 --output=jsonpath={.items[*].metadata.name})

파드의 로그를 출력한다.

kubectl logs $pods

출력 결과는 다음과 비슷하다.

Fri Feb 22 11:02:09 UTC 2019
Hello from the Kubernetes cluster

크론 잡 삭제

더 이상 크론 잡이 필요하지 않으면, kubectl delete cronjob <cronjob name> 명령을 사용해서 삭제한다.

kubectl delete cronjob hello

크론 잡을 삭제하면 생성된 모든 잡과 파드가 제거되고 추가 잡 생성이 중지된다. 가비지(garbage) 수집에서 잡 제거에 대해 상세한 내용을 읽을 수 있다.

크론 잡 명세 작성

다른 모든 쿠버네티스 구성과 마찬가지로, 크론 잡은 apiVersion, kind 그리고 metadata 필드가 필요하다. 구성 파일 작업에 대한 일반적인 정보는 애플리케이션 배포와 kubectl을 사용하여 리소스 관리하기 문서를 참고한다.

크론 잡 구성에는 .spec 섹션도 필요하다.

참고: 크론 잡, 특히 해당 잡의 .spec 에 대한 모든 수정 사항은 다음 번 실행에만 적용된다.

스케줄

.spec.schedule 은 .spec 의 필수 필드이다. 이는 해당 잡이 생성되고 실행되는 스케줄 시간으로 0 * * * * 또는 @hourly 와 같이 크론 형식의 문자열을 받아들인다.

이 형식은 확장된 "Vixie cron" 스텝(step) 값도 포함한다. 이 내용은 FreeBSD 매뉴얼에 설명되어 있다.

스텝 값은 범위(range)와 함께 사용할 수 있다. 범위 뒤에 /<number> 를 지정하여 범위 내에서 숫자만큼의 값을 건너뛴다. 예를 들어, 시간 필드에 0-23/2 를 사용하여 매 2시간마다 명령 실행을 지정할 수 있다(V7 표준의 대안은 0,2,4,6,8,10,12,14,16,18,20,22 이다). 별표(asterisk) 뒤에 붙이는 스텝도 허용되며, "2시간마다"라고 지정하고 싶으면, 간단히 */2 를 사용하면 된다.

참고: 스케줄에서 물음표(?)는 별표 * 와 동일한 의미를 가지며, 주어진 필드에 대해 사용할 수 있는 모든 값을 나타낸다.

잡 템플릿

.spec.jobTemplate 은 잡에 대한 템플릿이며, 이것은 필수 필드다. 이것은 중첩되고 apiVersion 이나 kind 가 없는 것을 제외하고 잡과 정확히 같은 스키마를 가진다. 잡 .spec 을 작성하는 것에 대한 내용은 잡 명세 작성하기를 참고한다.

시작 기한

.spec.startingDeadlineSeconds 필드는 선택 사항이다. 어떤 이유로든 스케줄된 시간을 놓친 경우 잡의 시작 기한을 초 단위로 나타낸다. 기한이 지나면, 크론 잡이 잡을 시작하지 않는다. 이러한 방식으로 기한을 맞추지 못한 잡은 실패한 작업으로 간주된다. 이 필드를 지정하지 않으면, 잡에 기한이 없다.

.spec.startingDeadlineSeconds 필드가 (null이 아닌 값으로) 설정되어 있다면, 크론잡 컨트롤러는 잡 생성 완료 예상 시각과 현재 시각의 차이를 측정하고, 시각 차이가 설정한 값보다 커지면 잡 생성 동작을 스킵한다.

예를 들어, 200 으로 설정되었다면, 잡 생성 완료 예상 시각으로부터 200초까지는 잡이 생성될 수 있다.

동시성 정책

.spec.concurrencyPolicy 필드도 선택 사항이다. 이것은 이 크론 잡에 의해 생성된 잡의 동시 실행을 처리하는 방법을 지정한다. 명세는 다음의 동시성 정책 중 하나만 지정할 수 있다.

  • Allow(기본값): 크론 잡은 동시에 실행되는 잡을 허용한다.
  • Forbid: 크론 잡은 동시 실행을 허용하지 않는다. 새로운 잡을 실행할 시간이고 이전 잡 실행이 아직 완료되지 않은 경우, 크론 잡은 새로운 잡 실행을 건너뛴다.
  • Replace: 새로운 잡을 실행할 시간이고 이전 잡 실행이 아직 완료되지 않은 경우, 크론 잡은 현재 실행 중인 잡 실행을 새로운 잡 실행으로 대체한다.

참고로 동시성 정책은 동일한 크론 잡에 의해 생성된 잡에만 적용된다. 크론 잡이 여러 개인 경우, 각각의 잡은 항상 동시에 실행될 수 있다.

일시 정지

.spec.suspend 필드도 선택 사항이다. true 로 설정되면, 모든 후속 실행이 일시 정지된다. 이 설정은 이미 시작된 실행에는 적용되지 않는다. 기본값은 false이다.

주의: 스케줄된 시간 동안 잡이 일시 정지되어 있다면 누락된 잡으로 간주한다. 시작 기한 없이 기존의 크론 잡에 대해 .spec.suspend 가 true 에서 false 로 변경되면, 누락된 잡들이 즉시 스케줄된다.

잡 히스토리 한도

.spec.successfulJobsHistoryLimit 와 .spec.failedJobsHistoryLimit 필드는 선택 사항이다. 이들 필드는 기록을 보관해야 하는 완료 및 실패한 잡의 개수를 지정한다. 기본적으로, 각각 3과 1로 설정된다. 한도를 0 으로 설정하는 것은 잡 완료 후에 해당 잡 유형의 기록을 보관하지 않는다는 것이다.

7.2 - 작업 대기열을 사용한 거친 병렬 처리

이 예제에서는, 여러 병렬 워커 프로세스를 활용해 쿠버네티스 잡(Job)을 실행한다.

이 예제에서는, 각 파드가 생성될 때 작업 대기열에서 하나의 작업 단위를 선택하여, 완료하고, 대기열에서 삭제하고, 종료한다.

이 예제에서의 단계에 대한 개요는 다음과 같다.

  1. 메시지 대기열 서비스를 시작한다. 이 예에서는, RabbitMQ를 사용하지만, 다른 메시지 대기열을 이용해도 된다. 실제로 사용할 때는, 한 번 메시지 대기열 서비스를 구축하고서 이를 여러 잡을 위해 재사용하기도 한다.
  2. 대기열을 만들고, 메시지로 채운다. 각 메시지는 수행할 하나의 작업을 나타낸다. 이 예제에서, 메시지는 긴 계산을 수행할 정수다.
  3. 대기열에서 작업을 수행하는 잡을 시작한다. 잡은 여러 파드를 시작한다. 각 파드는 메시지 대기열에서 하나의 작업을 가져와서, 처리한 다음, 대기열이 비워질 때까지 반복한다.

시작하기 전에

기본적이고, 병렬 작업이 아닌, 잡의 사용법에 대해 잘 알고 있어야 한다.

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

메시지 대기열 서비스 시작

이 예시에서는 RabbitMQ를 사용하지만, 다른 AMQP 유형의 메시지 서비스를 사용하도록 예시를 조정할 수 있다.

실제로 사용할 때는, 클러스터에 메시지 대기열 서비스를 한 번 구축하고서, 여러 많은 잡이나 오래 동작하는 서비스에 재사용할 수 있다.

다음과 같이 RabbitMQ를 시작한다.

kubectl create -f https://raw.githubusercontent.com/kubernetes/kubernetes/release-1.3/examples/celery-rabbitmq/rabbitmq-service.yaml

service "rabbitmq-service" created

kubectl create -f https://raw.githubusercontent.com/kubernetes/kubernetes/release-1.3/examples/celery-rabbitmq/rabbitmq-controller.yaml

replicationcontroller "rabbitmq-controller" created

이 문서에서는 celery-rabbitmq 예제에 나오는 정도로만 rabbitmq를 사용한다.

메시지 대기열 서비스 테스트하기

이제, 메시지 대기열을 이용해 실험할 수 있다. 임시 대화형 파드를 만들어 그 위에 도구들을 설치하고, 대기열을 실험해본다.

먼저 임시 대화형 파드를 만든다.

# 임시 대화형 컨테이너를 만든다.
kubectl run -i --tty temp --image ubuntu:18.04

Waiting for pod default/temp-loe07 to be running, status is Pending, pod ready: false
... [ previous line repeats several times .. hit return when it stops ] ...

참고로 파드 이름과 명령 프롬프트는 위와 다를 수 있다.

다음으로 amqp-tools를 설치하여 메시지 대기열을 활용할 수 있게 한다.

# 도구들을 설치한다.
root@temp-loe07:/# apt-get update
.... [ lots of output ] ....
root@temp-loe07:/# apt-get install -y curl ca-certificates amqp-tools python dnsutils
.... [ lots of output ] ....

후에, 이 패키지들을 포함하는 도커 이미지를 만든다.

다음으로, rabbitmq 서비스를 발견할 수 있는지 확인한다.

# rabbitmq-service가 쿠버네티스로부터 주어진 DNS 이름을 갖는다.

root@temp-loe07:/# nslookup rabbitmq-service
Server:        10.0.0.10
Address:    10.0.0.10#53

Name:    rabbitmq-service.default.svc.cluster.local
Address: 10.0.147.152

# 주소는 다를 수 있다.

만약 Kube-DNS가 적절히 구축되지 않았다면, 전 단계 작업이 작동하지 않을 수 있다. 환경 변수를 통해서도 서비스 IP를 찾을 수 있다.

# env | grep RABBIT | grep HOST
RABBITMQ_SERVICE_SERVICE_HOST=10.0.147.152
# 주소는 다를 수 있다.

다음으로 대기열을 생성하고, 메시지를 발행하고 사용할 수 있는지 확인한다.

# 다음 줄에서, rabbitmq-service는 rabbitmq-service에 접근할 수 있는 
# 호스트네임이다. 5672는 rabbitmq의 표준 포트이다.

root@temp-loe07:/# export BROKER_URL=amqp://guest:guest@rabbitmq-service:5672
# 만약 전 단계에서 "rabbitmq-service"가 주소로 변환되지 않는다면,
# 이 커맨드를 대신 사용하면 된다.
# root@temp-loe07:/# BROKER_URL=amqp://guest:guest@$RABBITMQ_SERVICE_SERVICE_HOST:5672

# 이제 대기열을 생성한다.

root@temp-loe07:/# /usr/bin/amqp-declare-queue --url=$BROKER_URL -q foo -d
foo

# 대기열에 메시지를 하나 발행한다.

root@temp-loe07:/# /usr/bin/amqp-publish --url=$BROKER_URL -r foo -p -b Hello

# 다시 메시지를 돌려받는다.

root@temp-loe07:/# /usr/bin/amqp-consume --url=$BROKER_URL -q foo -c 1 cat && echo
Hello
root@temp-loe07:/#

마지막 커맨드에서, amqp-consume 도구는 대기열로부터 하나의 메시지를 받고(-c 1), 그 메시지를 임의의 명령 표준입력으로 전달한다. 이 경우에는, cat 프로그램이 표준입력으로부터 받은 값을 출력하고, echo가 캐리지 리턴을 더해주어 출력 결과가 보여진다.

작업으로 대기열 채우기

이제 몇 가지 "작업"으로 대기열을 채운다. 이 예제에서의 작업은 문자열을 출력하는 것이다.

실제로 사용할 때는, 메시지의 내용이 다음과 같을 수 있다.

  • 처리되어야 하는 파일들의 이름
  • 프로그램의 추가 플래그
  • 데이터베이스 테이블의 키(key) 범위
  • 시뮬레이션의 구성 파라미터
  • 렌더링해야 하는 씬(scene)의 프레임 번호

실제로는, 잡의 모든 파드에서 읽기-전용 모드로 필요한 큰 데이터가 있다면, 일반적으로 그 데이터를 NFS와 같은 공유 파일시스템에 넣고 모든 파드에 읽기 전용으로 마운트하거나, 파드 안에 있는 프로그램이 기본적으로 HDFS와 같은 클러스터 파일시스템으로부터 데이터를 불러들인다.

본 예제에서는, 대기열을 만들고 amqp 커맨드라인 도구를 이용해 대기열을 채울 것이다. 실제로는, amqp 라이브러리를 이용해 대기열을 채우는 프로그램을 작성하게 된다.

/usr/bin/amqp-declare-queue --url=$BROKER_URL -q job1  -d
job1

for f in apple banana cherry date fig grape lemon melon
do
  /usr/bin/amqp-publish --url=$BROKER_URL -r job1 -p -b $f
done

8개의 메시지로 대기열을 채웠다.

이미지 생성

이제 잡으로 실행할 이미지를 만들 준비가 되었다.

amqp-consume 유틸리티를 이용해 대기열로부터 메시지를 읽고, 실제 프로그램을 실행해 볼 것이다. 여기에 아주 간단한 예제 프로그램이 있다.

application/job/rabbitmq/worker.py 
#!/usr/bin/env python

# 표준 출력만 출력하고 10초 동안 대기한다.
import sys
import time
print("Processing " + sys.stdin.readlines()[0])
time.sleep(10)

스크립트에 실행 권한을 준다.

chmod +x worker.py

이제 이미지를 빌드한다. 만약 소스 트리 안에서 작업하고 있다면, examples/job/work-queue-1로 디렉터리를 옮긴다. 아니면, 임시 디렉터리를 만들고, 그 디렉터리로 옮긴다. Dockerfile과 worker.py를 다운로드한다. 위 두 경우 모두, 다음의 명령을 이용해 이미지를 빌드한다.

docker build -t job-wq-1 .

도커 허브를 이용하기 위해, 앱 이미지를 사용자의 username으로 태깅하고 아래의 명령어를 이용해 허브에 푸시한다. <username>을 사용자의 허브 username으로 대체한다.

docker tag job-wq-1 <username>/job-wq-1
docker push <username>/job-wq-1

만약 구글 컨테이너 레지스트리를 이용하고 있다면, 앱 이미지를 사용자의 프로젝트 ID를 이용해 태깅하고, GCR에 푸시한다. <proejct> 부분을 사용자의 프로젝트 ID로 대체한다.

docker tag job-wq-1 gcr.io/<project>/job-wq-1
gcloud docker -- push gcr.io/<project>/job-wq-1

잡 정의

다음은 잡 정의이다. 잡의 사본을 만들고 위에서 정한 이름에 맞게 이미지를 수정하고, 파일 이름을 ./job.yaml이라 정한다.

application/job/rabbitmq/job.yaml 
apiVersion: batch/v1
kind: Job
metadata:
  name: job-wq-1
spec:
  completions: 8
  parallelism: 2
  template:
    metadata:
      name: job-wq-1
    spec:
      containers:
      - name: c
        image: gcr.io/<project>/job-wq-1
        env:
        - name: BROKER_URL
          value: amqp://guest:guest@rabbitmq-service:5672
        - name: QUEUE
          value: job1
      restartPolicy: OnFailure

이 예시에서는, 각 파드가 대기열로부터 얻은 하나의 아이템을 수행하고 종료한다. 그래서, 잡의 완료 횟수가 완료된 작업 아이템의 숫자에 대응한다. 예시에서 .spec.completions: 8이라 정한 것도, 대기열에 8개의 아이템을 넣었기 때문이다.

잡 실행

이제 잡을 실행한다.

kubectl apply -f ./job.yaml

이제 조금 기다린 다음, 잡을 확인한다.

kubectl describe jobs/job-wq-1

Name:             job-wq-1
Namespace:        default
Selector:         controller-uid=41d75705-92df-11e7-b85e-fa163ee3c11f
Labels:           controller-uid=41d75705-92df-11e7-b85e-fa163ee3c11f
                  job-name=job-wq-1
Annotations:      <none>
Parallelism:      2
Completions:      8
Start Time:       Wed, 06 Sep 2017 16:42:02 +0800
Pods Statuses:    0 Running / 8 Succeeded / 0 Failed
Pod Template:
  Labels:       controller-uid=41d75705-92df-11e7-b85e-fa163ee3c11f
                job-name=job-wq-1
  Containers:
   c:
    Image:      gcr.io/causal-jigsaw-637/job-wq-1
    Port:
    Environment:
      BROKER_URL:       amqp://guest:guest@rabbitmq-service:5672
      QUEUE:            job1
    Mounts:             <none>
  Volumes:              <none>
Events:
  FirstSeen  LastSeen   Count    From    SubobjectPath    Type      Reason              Message
  ─────────  ────────   ─────    ────    ─────────────    ──────    ──────              ───────
  27s        27s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-hcobb
  27s        27s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-weytj
  27s        27s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-qaam5
  27s        27s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-b67sr
  26s        26s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-xe5hj
  15s        15s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-w2zqe
  14s        14s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-d6ppa
  14s        14s        1        {job }                   Normal    SuccessfulCreate    Created pod: job-wq-1-p17e0

모든 파드가 성공했다. 야호.

대안

이러한 접근은 "워커" 프로그램을 작업 대기열에 맞게 수정하지 않아도 된다는 장점이 있다.

이 접근을 이용하려면, 메시지 대기열 서비스를 실행해야만 한다. 만약 메시지 대기열 서비스를 실행하는 게 불편하다면, 다른 잡 패턴을 고려해볼 수 있다.

이 접근은 모든 작업 아이템에 대해 파드를 생성한다. 만약 작업 아이템이 오직 몇 초밖에 걸리지 않는 작업이라면, 매 작업마다 파드를 생성하는 것은 아주 큰 오버헤드를 더할 수 있다. 하나의 파드가 여러 작업 아이템을 수행하는 이 예제를 고려해보자.

이 예제에서는, amqp-consume 유틸리티를 이용해 대기열로부터 메시지를 읽어 실제 프로그램을 실행했다. 이러면 메시지 대기열을 이용하기 위해 프로그램을 수정하지 않아도 된다는 장점이 있다. 다른 예제는 클라이언트 라이브러리를 이용해 작업 대기열과 소통하는 방법을 보여준다.

주의 사항

만약 작업 완료 수가 대기열에 있는 아이템의 숫자보다 적게 설정되면, 모든 아이템 처리되지 않는다.

만약 작업 완료 수가 큐에 있는 아이템의 숫자보다 많게 설정되면, 대기열에 있는 아이템이 모두 처리되어도, 잡이 완료됐다고 표시되지 않고, 메시지를 기다리는 과정에서 막히는 파드를 추가적으로 실행시킨다.

이 패턴에서는 경쟁 상태(race)가 잘 나타나지 않는다. 만약 amqp-consume 명령으로부터 메시지가 인정되는 시간과 컨테이너가 성공적으로 종료되는 시간 사이에 컨테이너가 종료되거나, kubelet이 api-server에게 파드가 성공했음을 알리기 전에 노드가 비정상적으로 종료되면, 대기열의 모든 아이템이 처리되었다 해도, 잡이 완료되었다고 표시되지 않는다.

7.3 - 작업 대기열을 사용한 정밀 병렬 처리

이 예에서는, 지정된 파드에서 여러 병렬 워커 프로세스가 있는 쿠버네티스 잡(Job)을 실행한다.

이 예에서는, 각 파드가 생성될 때, 작업 대기열에서 하나의 작업 단위를 선택하여, 처리하고, 대기열이 비워질 때까지 반복한다.

이 예에서의 단계에 대한 개요는 다음과 같다.

  1. 작업 대기열을 보관할 스토리지 서비스를 시작한다. 이 예에서는, Redis를 사용하여 작업 항목을 저장한다. 이전 예에서는, RabbitMQ를 사용했다. 이 예에서는, AMQP가 길이가 정해져 있는 작업 대기열이 비어있을 때 클라이언트가 이를 감지할 수 있는 좋은 방법을 제공하지 않기 때문에 Redis 및 사용자 지정의 작업 대기열 클라이언트 라이브러리를 사용한다. 실제로는 Redis와 같은 저장소를 한 번 설정하고 여러 작업과 다른 것들의 작업 대기열로 재사용한다.
  2. 대기열을 만들고, 메시지로 채운다. 각 메시지는 수행할 하나의 작업을 나타낸다. 이 예에서, 메시지는 긴 계산을 수행할 정수다.
  3. 대기열에서 작업을 수행하는 잡을 시작한다. 잡은 여러 파드를 시작한다. 각 파드는 메시지 대기열에서 하나의 작업을 가져와서, 처리한 다음, 대기열이 비워질 때까지 반복한다.

시작하기 전에

쿠버네티스 클러스터가 필요하고, kubectl 커맨드-라인 툴이 클러스터와 통신할 수 있도록 설정되어 있어야 한다. 이 튜토리얼은 컨트롤 플레인 호스트가 아닌 노드가 적어도 2개 포함된 클러스터에서 실행하는 것을 추천한다. 만약, 아직 클러스터를 가지고 있지 않다면, minikube를 사용해서 생성하거나 다음의 쿠버네티스 플레이그라운드 중 하나를 사용할 수 있다.

잡의 기본적이고, 병렬 작업이 아닌, 사용법에 대해 잘 알고 있어야 한다.

Redis 시작

이 문서의 예시에서는, 단순함을 위해, Redis의 단일 인스턴스를 시작한다. Redis를 확장 가능하고 중복적으로 배포하는 예에 대해서는 Redis 예시를 참고한다.

다음 파일을 직접 다운로드할 수도 있다.

작업으로 대기열 채우기

이제 몇 가지 "작업"으로 대기열을 채운다. 이 예제의 작업은 문자열을 출력하는 것이다.

Redis CLI를 실행하기 위한 임시 대화형 파드를 시작한다.

kubectl run -i --tty temp --image redis --command "/bin/sh"
Waiting for pod default/redis2-c7h78 to be running, status is Pending, pod ready: false
Hit enter for command prompt

이제 엔터 키를 누르고, redis CLI를 시작하고, 몇몇 작업 항목이 포함된 목록을 생성한다.

# redis-cli -h redis
redis:6379> rpush job2 "apple"
(integer) 1
redis:6379> rpush job2 "banana"
(integer) 2
redis:6379> rpush job2 "cherry"
(integer) 3
redis:6379> rpush job2 "date"
(integer) 4
redis:6379> rpush job2 "fig"
(integer) 5
redis:6379> rpush job2 "grape"
(integer) 6
redis:6379> rpush job2 "lemon"
(integer) 7
redis:6379> rpush job2 "melon"
(integer) 8
redis:6379> rpush job2 "orange"
(integer) 9
redis:6379> lrange job2 0 -1
1) "apple"
2) "banana"
3) "cherry"
4) "date"
5) "fig"
6) "grape"
7) "lemon"
8) "melon"
9) "orange"

자, 키 job2 가 있는 목록이 작업 대기열이 된다.

참고: Kube DNS를 올바르게 설정하지 않은 경우, 위 블록의 첫 번째 단계를 redis-cli -h $REDIS_SERVICE_HOST 로 변경해야 할 수 있다.

이미지 생성

이제 실행할 이미지를 만들 준비가 되었다.

redis 클라이언트와 함께 python 워커 프로그램을 사용하여 메시지 큐에서 메시지를 읽는다.

rediswq.py(다운로드)라는 간단한 Redis 작업 대기열 클라이언트 라이브러리가 제공된다.

잡의 각 파드에 있는 "워커" 프로그램은 작업 대기열 클라이언트 라이브러리를 사용하여 작업을 가져온다. 다음은 워커 프로그램이다.

application/job/redis/worker.py 
#!/usr/bin/env python

import time
import rediswq

host="redis"
# Uncomment next two lines if you do not have Kube-DNS working.
# import os
# host = os.getenv("REDIS_SERVICE_HOST")

q = rediswq.RedisWQ(name="job2", host=host)
print("Worker with sessionID: " +  q.sessionID())
print("Initial queue state: empty=" + str(q.empty()))
while not q.empty():
  item = q.lease(lease_secs=10, block=True, timeout=2)
  if item is not None:
    itemstr = item.decode("utf-8")
    print("Working on " + itemstr)
    time.sleep(10) # Put your actual work here instead of sleep.
    q.complete(item)
  else:
    print("Waiting for work")
print("Queue empty, exiting")

worker.py, rediswq.py 및 Dockerfile 파일을 다운로드할 수 있고, 그런 다음 이미지를 만들 수도 있다.

docker build -t job-wq-2 .

이미지 푸시

도커 허브(Docker Hub)를 위해, 아래 명령으로 사용자의 username과 앱 이미지에 태그하고 허브에 푸시한다. <username> 을 사용자의 허브 username으로 바꾼다.

docker tag job-wq-2 <username>/job-wq-2
docker push <username>/job-wq-2

공용 저장소로 푸시하거나 개인 저장소에 접근할 수 있도록 클러스터를 구성해야 한다.

Google Container Registry를 사용하는 경우, 사용자의 프로젝트 ID로 앱 이미지에 태그를 지정하고 GCR로 푸시한다. <project> 를 사용자의 프로젝트 ID로 바꾼다.

docker tag job-wq-2 gcr.io/<project>/job-wq-2
gcloud docker -- push gcr.io/<project>/job-wq-2

잡 정의

다음은 잡 정의이다.

application/job/redis/job.yaml 
apiVersion: batch/v1
kind: Job
metadata:
  name: job-wq-2
spec:
  parallelism: 2
  template:
    metadata:
      name: job-wq-2
    spec:
      containers:
      - name: c
        image: gcr.io/myproject/job-wq-2
      restartPolicy: OnFailure

사용자 자신의 경로로 gcr.io/myproject 를 변경하려면 잡 템플릿을 편집해야 한다.

이 예에서, 각 파드는 대기열의 여러 항목에 대해 작업한 다음 더 이상 항목이 없을 때 종료된다. 워커는 작업 대기열이 비어있을 때를 감지하고 잡 컨트롤러는 작업 대기열에 대해 알지 못하기 때문에, 작업이 완료되면 워커에게 신호를 보낸다. 워커는 성공적으로 종료하여 대기열이 비어 있음을 알린다. 따라서, 워커가 성공적으로 종료하자마자, 컨트롤러는 작업이 완료되었음을 인식하고, 파드가 곧 종료된다. 따라서, 잡 완료 횟수를 1로 설정했다. 잡 컨트롤러는 다른 파드도 완료될 때까지 기다린다.

잡 실행

이제 잡을 실행한다.

kubectl apply -f ./job.yaml

이제 조금 기다린 다음, 잡을 확인한다.

kubectl describe jobs/job-wq-2
Name:             job-wq-2
Namespace:        default
Selector:         controller-uid=b1c7e4e3-92e1-11e7-b85e-fa163ee3c11f
Labels:           controller-uid=b1c7e4e3-92e