레퍼런스

• 1: 용어집
• 2: API 개요
• 2.1: 클라이언트 라이브러리
• 2.2: 쿠버네티스 API 헬스(health) 엔드포인트
• 3: API 접근 제어
• 3.1: 부트스트랩 토큰을 사용한 인증
• 3.2: 서비스 어카운트 관리하기
• 3.3: 인가 개요
• 3.4: Kubelet 인증/인가
• 4: 잘 알려진 레이블, 어노테이션, 테인트(Taint)
• 5: 노드 메트릭 데이터
• 6: 쿠버네티스 이슈와 보안
• 6.1: 쿠버네티스 이슈 트래커
• 6.2: 쿠버네티스 보안과 공개 정보
• 7: 노드 레퍼런스 정보
• 7.1: kubelet 체크포인트 API
• 7.2: 도커심 제거 및 CRI 호환 런타임 사용에 대한 기사
• 8: 네트워킹 레퍼런스
• 8.1: 서비스가 지원하는 프로토콜
• 8.2: 포트와 프로토콜
• 8.3: 가상 IP 및 서비스 프록시
• 9: 설치 도구
• 9.1: Kubeadm
• 9.1.1: Kubeadm Generated
• 10: 명령줄 도구 (kubectl)
• 10.1: kubectl 치트 시트
• 10.2: kubectl
• 10.3: JSONPath 지원
• 10.4: 도커 사용자를 위한 kubectl
• 10.5: kubectl 사용 규칙
• 11: 컴포넌트 도구
• 11.1: 기능 게이트
• 11.2: 제거된 기능 게이트
• 11.3: kube-proxy
• 12: 스케줄링
• 12.1: 스케줄러 구성
• 12.2: 스케줄링 정책
• 13: 도구

1 - 용어집

2 - API 개요

이 섹션은 쿠버네티스 API에 대한 참조 정보를 제공한다.

REST API는 쿠버네티스의 근본적인 구조이다. 모든 조작, 컴포넌트 간의 통신과 외부 사용자의 명령은 API 서버에서 처리할 수 있는 REST API 호출이다. 따라서, 쿠버네티스 플랫폼 안의 모든 것은 API 오브젝트로 취급되고, API에 상응하는 항목이 있다.

쿠버네티스 API 참조는 쿠버네티스 버전 v1.29에 대한 API가 나열되어 있다.

일반적인 배경 정보를 보려면, 쿠버네티스 API를 참고한다. 쿠버네티스 API에 대한 접근 제어는 클라이언트가 쿠버네티스 API 서버에 인증하는 방법과 요청이 승인되는 방법을 설명한다.

API 버전 규칙

JSON과 Protobuf 직렬화 스키마 모두 스키마 변경에 대해서 동일한 가이드라인을 따른다. 이후 설명에서는 이 형식 모두를 다룬다.

API 버전 규칙과 소프트웨어 버전 규칙은 간접적으로 연관된다. API와 릴리스 버전 부여에 관한 제안에는 API 버전 규칙과 소프트웨어 버전 규칙 간의 관계가 기술되어 있다.

API 버전의 차이는 수준의 안정성과 지원의 차이를 나타낸다. API 변경 문서에서 각 수준의 기준에 대한 더 많은 정보를 찾을 수 있다.

아래는 각 수준의 기준에 대한 요약이다.

• 알파(Alpha):

  • 버전 이름에 alpha가 포함된다(예: v1alpha1).
  • 빌트인 알파 API 버전은 기본적으로 활성화되지 않으며, 활성화하기 위해서는 kube-apiserver 설정에 반드시 명시해야 한다.
  • 버그가 있을 수도 있다. 이 기능을 활성화하면 버그에 노출될 수 있다.
  • 알파 API에 대한 기술 지원이 언제든 공지 없이 중단될 수 있다.
  • 다음 소프트웨어를 릴리스할 때 공지 없이 API의 호환성이 깨지는 방식으로 변경될 수 있다.
  • 버그에 대한 위험이 높고 장기간 지원되지 않으므로 단기간 테스트 용도의 클러스터에서만 사용하기를 권장한다.

• 베타(Beta):

  • 버전 이름에 beta가 포함된다(예: v2beta3).

  • 빌트인 베타 API 버전은 기본적으로 활성화되지 않으며, 활성화하기 위해서는 kube-apiserver 설정에 반드시 명시해야 한다. (예외사항 쿠버네티스 1.22 버전 이전의 베타 API들은 기본적으로 활성화되어 있다.)

  • 빌트인 베타 API 버전이 더 이상 지원되지 않기까지는 9달 또는 3번의 마이너 릴리스(둘 중 더 긴 것을 기준으로 함)가 걸린다. 그리고 지원되지 않은 시점에서 제거되기까지는 다시 9달 또는 3번의 마이너 릴리스(둘 중 더 긴 것을 기준으로 함)가 걸린다.

  • 코드가 잘 테스트 되었다. 이 기능을 활성화해도 안전하다.

  • 구체적인 내용이 바뀔 수는 있지만, 전반적인 기능에 대한 기술 지원이 중단되지 않는다.

  • 오브젝트에 대한 스키마나 문법이 다음 베타 또는 안정화 API 버전에서 호환되지 않는 방식으로 바뀔 수도 있다. 이런 경우, 다음 버전으로 이관할 수 있는 가이드가 제공된다. 다음 베타 또는 안정화 API 버전을 적용하는 것은 API 오브젝트의 편집 또는 재생성이 필요할 수도 있으며, 그렇게 쉬운 일만은 아닐 것이다. 이 기능에 의존하고 있는 애플리케이션은 다운타임이 필요할 수도 있다.

  • 이 소프트웨어는 프로덕션 용도로 권장하지 않는다. 이후 여러 버전에서 호환되지 않는 변경 사항이 적용될 수 있다. 베타 API 버전이 더 이상 지원되지 않는 경우, 후속 베타 또는 안정화 API 버전으로 전환하기 위해서는 베타 API 버전을 사용해야 한다.

  참고: 베타 기능을 사용해보고 피드백을 제공하자. 기능이 베타 수준을 벗어난 이후에는 실질적으로 더 많은 변경이 어렵다.

• 안정화(Stable):

  • 버전 이름이 vX이고 X 는 정수다.
  • 안정화된 API 버전은 이후의 모든 쿠버네티스 메이저 버전에서 사용 가능하며, 현재로써 쿠버네티스 메이저 버전에서 안정화된 API를 제거하려는 계획은 없다.

API 그룹

API 그룹은 쿠버네티스 API를 더 쉽게 확장할 수 있도록 해 준다. API 그룹은 REST 경로와 직렬화된 오브젝트의 apiVersion 필드에 명시된다.

쿠버네티스에는 다음과 같은 다양한 API 그룹이 있다.

• 핵심 (또는 레거시 라고 불리는) 그룹은 REST 경로 /api/v1에 있다. 핵심 그룹은 apiVersion 필드의 일부로 명시되지 않는다. 예를 들어, apiVersion: v1 과 같다.
• 이름이 있는 그룹은 REST 경로 /apis/$GROUP_NAME/$VERSION에 있으며 apiVersion: $GROUP_NAME/$VERSION을 사용한다(예를 들어, apiVersion: batch/v1). 지원되는 API 그룹 전체의 목록은 쿠버네티스 API 참조 문서에서 확인할 수 있다.

API 그룹 활성화 또는 비활성화

특정 리소스 및 API 그룹은 기본적으로 활성화된다. API 서버에서 --runtime-config 를 설정하여 활성화 또는 비활성화할 수 있다. --runtime-config 플래그는 API 서버의 런타임 구성을 설명하는 쉼표로 구분된 <key>=<value> 쌍을 허용한다. 만약 =<value> 부분을 생략하면, =true 가 명시된 것처럼 취급한다. 예를 들면, 다음과 같다.

• batch/v1 을 비활성화하려면, --runtime-config=batch/v1=false 로 설정
• batch/v2alpha1 을 활성화하려면, --runtime-config=batch/v2alpha1 으로 설정
• 예를 들어 storage.k8s.io/v1beta1/csistoragecapacities와 같이 특정 버전의 API를 활성화하려면, --runtime-config=storage.k8s.io/v1beta1/csistoragecapacities와 같이 설정

지속성

쿠버네티스는 etcd에 기록하여 API 리소스 측면에서 직렬화된 상태를 저장한다.

다음 내용

• API 규칙에 대해 자세히 알아보기
• 애그리게이터(aggregator)에 대한 디자인 문서 읽기

2.1 - 클라이언트 라이브러리

이 페이지는 다양한 프로그래밍 언어에서 쿠버네티스 API를 사용하기 위한 클라이언트 라이브러리에 대한 개요를 포함하고 있다.

쿠버네티스 REST API를 사용해 애플리케이션을 작성하기 위해 API 호출 또는 요청/응답 타입을 직접 구현할 필요는 없다. 사용하고 있는 프로그래밍 언어를 위한 클라이언트 라이브러리를 사용하면 된다.

클라이언트 라이브러리는 대체로 인증과 같은 공통의 태스크를 처리한다. 대부분의 클라이언트 라이브러리들은 API 클라이언트가 쿠버네티스 클러스터 내부에서 동작하는 경우 인증 또는 kubeconfig 파일 포맷을 통해 자격증명과 API 서버 주소를 읽을 수 있게 쿠버네티스 서비스 어카운트를 발견하고 사용할 수 있다.

공식적으로 지원되는 쿠버네티스 클라이언트 라이브러리

다음의 클라이언트 라이브러리들은 쿠버네티스 SIG API Machinery에서 공식적으로 관리된다.

커뮤니티에 의해 관리되는 클라이언트 라이브러리

다음의 쿠버네티스 API 클라이언트 라이브러리들은 쿠버네티스 팀이 아닌 각각의 저자들이 제공하고 관리한다.

2.2 - 쿠버네티스 API 헬스(health) 엔드포인트

쿠버네티스 API 서버는 현재 상태를 나타내는 API 엔드포인트를 제공한다. 이 페이지에서는 API 엔드포인트들에 대해 설명하고 이를 사용하는 방법을 다룬다.

헬스를 위한 API 엔드포인트

쿠버네티스 API 서버는 현재 상태를 나타내는 세 가지 API 엔드포인트(healthz, livez 와 readyz)를 제공한다. healthz 엔드포인트는 사용 중단(deprecated)됐으며 (쿠버네티스 v1.16 버전 이후), 대신 보다 구체적인 livez 와 readyz 엔드포인트를 사용해야 한다. livez 엔드포인트는 --livez-grace-period 플래그 옵션을 사용하여 시작 대기 시간을 지정할 수 있다. /readyz 엔드포인트는 --shutdown-delay-duration 플래그 옵션을 사용하여 정상적(graceful)으로 셧다운할 수 있다. API 서버의 healthz/livez/readyz 를 사용하는 머신은 HTTP 상태 코드에 의존해야 한다. 상태 코드 200은 호출된 엔드포인트에 따라 API 서버의 healthy/live/ready 상태를 나타낸다. 아래 표시된 더 자세한 옵션은 운영자가 클러스터를 디버깅하거나 특정 API 서버의 상태를 이해하는 데 사용할 수 있다.

다음의 예시는 헬스 API 엔드포인트와 상호 작용할 수 있는 방법을 보여준다.

모든 엔드포인트에 대해, verbose 파라미터를 사용하여 검사 항목과 상태를 출력할 수 있다. 이는 운영자가 머신 사용을 위한 것이 아닌, API 서버의 현재 상태를 디버깅하는데 유용하다.

curl -k https://localhost:6443/livez?verbose

인증을 사용하는 원격 호스트에서 사용할 경우에는 다음과 같이 수행한다.

kubectl get --raw='/readyz?verbose'

출력은 다음과 같다.

[+]ping ok
[+]log ok
[+]etcd ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
[+]poststarthook/generic-apiserver-start-informers ok
[+]poststarthook/start-apiextensions-informers ok
[+]poststarthook/start-apiextensions-controllers ok
[+]poststarthook/crd-informer-synced ok
[+]poststarthook/bootstrap-controller ok
[+]poststarthook/rbac/bootstrap-roles ok
[+]poststarthook/scheduling/bootstrap-system-priority-classes ok
[+]poststarthook/start-cluster-authentication-info-controller ok
[+]poststarthook/start-kube-aggregator-informers ok
[+]poststarthook/apiservice-registration-controller ok
[+]poststarthook/apiservice-status-available-controller ok
[+]poststarthook/kube-apiserver-autoregistration ok
[+]autoregister-completion ok
[+]poststarthook/apiservice-openapi-controller ok
healthz check passed

또한 쿠버네티스 API 서버는 특정 체크를 제외할 수 있다. 쿼리 파라미터는 다음 예와 같이 조합될 수 있다.

curl -k 'https://localhost:6443/readyz?verbose&exclude=etcd'

출력에서 etcd 체크가 제외된 것을 보여준다.

[+]ping ok
[+]log ok
[+]etcd excluded: ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
[+]poststarthook/generic-apiserver-start-informers ok
[+]poststarthook/start-apiextensions-informers ok
[+]poststarthook/start-apiextensions-controllers ok
[+]poststarthook/crd-informer-synced ok
[+]poststarthook/bootstrap-controller ok
[+]poststarthook/rbac/bootstrap-roles ok
[+]poststarthook/scheduling/bootstrap-system-priority-classes ok
[+]poststarthook/start-cluster-authentication-info-controller ok
[+]poststarthook/start-kube-aggregator-informers ok
[+]poststarthook/apiservice-registration-controller ok
[+]poststarthook/apiservice-status-available-controller ok
[+]poststarthook/kube-apiserver-autoregistration ok
[+]autoregister-completion ok
[+]poststarthook/apiservice-openapi-controller ok
[+]shutdown ok
healthz check passed

개별 헬스 체크

각 개별 헬스 체크는 HTTP 엔드포인트를 노출하며 개별적으로 체크할 수 있다. 개별 체크를 위한 스키마는 /livez/<healthcheck-name> 이고, 여기서 livez 와 readyz 는 API 서버의 활성 상태 또는 준비 상태인지를 확인할 때 사용한다. <healthcheck-name> 경로 위에서 설명한 verbose 플래그를 사용해서 찾을 수 있고, [+] 와 ok 사이의 경로를 사용한다. 이러한 개별 헬스 체크는 머신에서 사용되서는 안되며, 운영자가 시스템의 현재 상태를 디버깅하는데 유용하다.

curl -k https://localhost:6443/livez/etcd

3 - API 접근 제어

쿠버네티스가 API 접근을 구현 및 제어하는 방법에 대한 자세한 내용은 쿠버네티스 API에 대한 접근 제어를 참고한다.

참조 문헌

• 인증
  • 부트스트랩 토큰 인증
• 승인 컨트롤러
  • 동적 승인 제어
• 인가
  • 역할 기반 접근 제어
  • 속성 기반 접근 제어
  • 노드 인가
  • 웹훅 인가
• 인증서 서명 요청
  • CSR 승인과 인증서 서명을 포함함
• 서비스 어카운트
  • 개발자 가이드
  • 관리
• kubelet 인증과 인가
  • kubelet TLS 부트스트래핑을 포함함

3.1 - 부트스트랩 토큰을 사용한 인증

부트스트랩 토큰은 새 클러스터를 만들거나 새 노드를 기존 클러스터에 결합할 때 사용되는 간단한 전달자 토큰이다. kubeadm을 지원하도록 구축되었지만 kubeadm 없이 클러스터를 시작하려는 사용자를 위해 다른 컨텍스트에서 사용할 수 있다. 또한 RBAC 정책을 통해 Kubelet TLS 부트스트래핑 시스템과 함께 동작하도록 구축되었다.

부트스트랩 토큰 개요

부트스트랩 토큰은 kube-system 네임스페이스에 있는 특정 유형(bootstrap.kubernetes.io/token)의 시크릿(Secret)으로 정의된다. API 서버의 부트스트랩 인증자가 이러한 시크릿을 읽는다. 만료된 토큰은 컨트롤러 관리자가 TokenCleaner 컨트롤러로 제거한다. 토큰은 BootstrapSigner 컨트롤러를 통해 "discovery" 프로세스에 사용되는 특정 컨피그맵(ConfigMap)에 대한 서명을 만드는 데도 사용된다.

토큰 형식

부트스트랩 토큰은 abcdef.0123456789abcdef 형식을 취한다. 더 공식적으로는 정규식 [a-z0-9]{6}\.[a-z0-9]{16} 와 일치해야 한다.

토큰의 첫 번째 부분은 "Token ID" 이며 공개 정보로 간주된다. 인증에 사용하는 시크릿의 일부를 노출하지 않고 토큰을 참조할 때 사용한다. 두 번째 부분은 "Token Secret"이며 신뢰할 수 있는 당사자와만 공유해야 한다.

부트스트랩 토큰 인증 활성화

API 서버에서 다음 플래그를 사용하여 부트스트랩 토큰 인증자를 활성화할 수 있다.

--enable-bootstrap-token-auth

활성화되면 부트스트랩 토큰을 API 서버에 대한 요청을 인증하기 위한 전달자 토큰 자격 증명으로 사용할 수 있다.

Authorization: Bearer 07401b.f395accd246ae52d

토큰은 사용자 이름 system:bootstrap:<token id> 로 인증되며 system:bootstrappers 그룹의 구성원이다. 토큰의 시크릿에 추가 그룹을 지정할 수 있다.

만료된 토큰은 컨트롤러 관리자에서 tokencleaner 컨트롤러를 활성화하여 자동으로 삭제할 수 있다.

--controllers=*,tokencleaner

부트스트랩 토큰 시크릿 형식

각각의 유효한 토큰은 kube-system 네임스페이스의 시크릿에 의해 지원된다. 전체 디자인 문서는 여기에서 찾을 수 있다.

시크릿은 다음과 같다.

apiVersion: v1
kind: Secret
metadata:
  # Name MUST be of form "bootstrap-token-<token id>"
  name: bootstrap-token-07401b
  namespace: kube-system

# Type MUST be 'bootstrap.kubernetes.io/token'
type: bootstrap.kubernetes.io/token
stringData:
  # Human readable description. Optional.
  description: "The default bootstrap token generated by 'kubeadm init'."

  # Token ID and secret. Required.
  token-id: 07401b
  token-secret: f395accd246ae52d

  # Expiration. Optional.
  expiration: 2017-03-10T03:22:11Z

  # Allowed usages.
  usage-bootstrap-authentication: "true"
  usage-bootstrap-signing: "true"

  # Extra groups to authenticate the token as. Must start with "system:bootstrappers:"
  auth-extra-groups: system:bootstrappers:worker,system:bootstrappers:ingress

시크릿 유형은 bootstrap.kubernetes.io/token 이어야 하고 이름은 bootstrap-token-<token id>여야 한다. 반드시 kube-system 네임스페이스에도 존재해야 한다.

usage-bootstrap-* 멤버는 이 시크릿의 용도를 나타낸다. 활성화하려면 값을 true 로 설정해야 한다.

• usage-bootstrap-authentication 은 토큰을 API 서버에 베어러 토큰으로 인증하는데 사용할 수 있음을 나타낸다.
• usage-bootstrap-signing 은 토큰을 사용하여 아래에 설명된 cluster-info 컨피그맵에 서명할 수 있음을 나타낸다.

expiration 필드는 토큰의 만료를 제어한다. 만료된 토큰은 인증에 사용될 때 거부되고 컨피그맵서명 중에 무시된다. 만료된 값은 RFC3339를 사용하여 절대 UTC 시간으로 인코딩된다. 만료된 토큰을 자동으로 삭제하려면 tokencleaner 컨트롤러를 활성화한다.

kubeadm을 사용한 토큰 관리

kubeadm 툴을 사용하여 실행중인 클러스터에서 토큰을 관리할 수 있다. 자세한 내용은 kubeadm token docs 에서 찾을 수 있다.

컨피그맵 서명

토큰은 인증 외에도 컨피그맵에 서명하는데 사용할 수 있다. 이것은 클라이언트가 API 서버를 신뢰하기 전에 클러스터 부트스트랩 프로세스의 초기에 사용된다. 서명된 컨피그맵은 공유 토큰으로 인증할 수 있다.

컨트롤러 관리자에서 bootstrapsigner 컨트롤러를 활성화하여 컨피그맵서명을 활성화 한다.

--controllers=*,bootstrapsigner

서명된 컨피그맵은 kube-public 네임스페이스에 있는 cluster-info 이다. 일반적인 흐름은 클라이언트가 인증되지 않고 TLS 오류를 무시하는 동안 컨피그맵을 읽는 것이다. 그런 다음 컨피그맵에 포함된 서명을 확인하여 컨피그맵의 페이로드를 확인한다.

컨피그맵은 다음과 같을 수 있다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-info
  namespace: kube-public
data:
  jws-kubeconfig-07401b: eyJhbGciOiJIUzI1NiIsImtpZCI6IjA3NDAxYiJ9..tYEfbo6zDNo40MQE07aZcQX2m3EB2rO3NuXtxVMYm9U
  kubeconfig: |
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: <really long certificate data>
        server: https://10.138.0.2:6443
      name: ""
    contexts: []
    current-context: ""
    kind: Config
    preferences: {}
    users: []    

컨피그맵의 kubeconfig 멤버는 클러스터 정보만 입력된 구성 파일이다. 여기서 전달되는 핵심은 certificate-authority-data 이다.
이는 향후 확대될 수 있다.

서명은 "detached" 모드를 사용하는 JWS 서명이다. 서명을 검증하려면 사용자는 JWS 규칙(뒤로 오는 = 를 삭제하는 동안 인코딩된 base64)에 따라 kubeconfig 페이로드를 인코딩해야 한다. 그런 다음 인코딩된 페이로드는 두 개의 점 사이에 삽입하여 전체 JWS를 형성하는 데 사용된다. 전체 토큰(예:07401b.f395accd246ae52d)을 공유 시크릿으로 사용하여 HS256 방식(HMAC-SHA256)을 사용함으로 JWS를 확인할 수 있다. 사용자는 반드시 HS256이 사용되고 있는지 확인해야 한다.

자세한 내용은 kubeadm implementation details 섹션을 참조하면 된다.

3.2 - 서비스 어카운트 관리하기

서비스어카운트(ServiceAccount) 는 파드에서 실행되는 프로세스에 대한 식별자를 제공한다.

파드 내부의 프로세스는, 자신에게 부여된 서비스 어카운트의 식별자를 사용하여 클러스터의 API 서버에 인증할 수 있다.

서비스 어카운트에 대한 소개는, 서비스 어카운트 구성하기를 참고한다.

이 가이드는 서비스어카운트와 관련된 개념 중 일부를 설명하며, 서비스어카운트를 나타내는 토큰을 얻거나 취소하는 방법에 대해서도 설명한다.

시작하기 전에

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

• Killercoda
• Play with Kubernetes

아래 내용들을 따라하기 위해서는 examplens라는 네임스페이스가 필요하다. 없을 경우 다음과 같이 네임스페이스를 생성한다.

kubectl create namespace examplens

사용자 어카운트와 서비스 어카운트 비교

쿠버네티스는 여러 가지 이유로 사용자 어카운트와 서비스 어카운트의 개념을 구분한다.

• 사용자 어카운트는 사람을 위한 것이지만, 서비스 어카운트는 쿠버네티스의 경우 파드의 일부 컨테이너에서 실행되는 애플리케이션 프로세스를 위한 것이다.
• 사용자 어카운트는 전역적으로 고려되기 때문에, 클러스터의 모든 네임스페이스에 걸쳐 이름이 고유해야 한다. 어떤 네임스페이스를 확인하든지 간에, 특정 사용자명은 해당 유저만을 나타낸다. 쿠버네티스에서 서비스 어카운트는 네임스페이스별로 구분된다. 두 개의 서로 다른 네임스페이스는 동일한 이름의 서비스어카운트를 각자 가질 수 있다.
• 일반적으로 클러스터의 사용자 어카운트는 기업 데이터베이스로부터 동기화될 수 있으며, 여기서 새로운 사용자 어카운트를 생성하려면 특별한 권한이 필요하며 복잡한 비즈니스 프로세스에 연결된다. 반면에 서비스 어카운트를 생성하는 경우는, 클러스터 사용자가 최소 권한 원칙에 따라 특정 작업을 위한 서비스 어카운트를 만들 수 있도록 보다 가볍게 만들어졌다. 실 사용자를 온보딩하는 단계와 서비스어카운트를 생성하는 단계를 분리하는 것은, 워크로드가 최소 권한 원칙을 따르기 쉬워지게 한다.
• 사람과 서비스 어카운트에 대한 감사 고려 사항은 다를 수 있다. 이 둘을 따로 관리함으로써 더욱 쉽게 감사를 수행할 수 있다.
• 복잡한 시스템의 설정들은 그 시스템의 구성요소에 대한 다양한 서비스 어카운트 정의를 포함할 수 있다. 서비스 어카운트는 많은 제약없이 만들 수 있고 네임스페이스에 할당된 이름을 가질 수 있기 때문에 이러한 설정은 이식성이 좋다.

바인딩된 서비스 어카운트 토큰 볼륨 메커니즘

기본적으로, 쿠버네티스 컨트롤 플레인(구체적으로 말하자면 서비스어카운트 어드미션 컨트롤러)은 프로젝티드 볼륨을 파드에 추가하며, 이 볼륨은 쿠버네티스 API에 접근할 수 있는 토큰을 포함한다.

다음은 실행된 파드에서 해당 토큰이 어떻게 보이는지에 대한 예시이다.

...
  - name: kube-api-access-<random-suffix>
    projected:
      sources:
        - serviceAccountToken:
            path: token # 애플리케이션이 알고 있는 경로와 일치해야 한다.
        - configMap:
            items:
              - key: ca.crt
                path: ca.crt
            name: kube-root-ca.crt
        - downwardAPI:
            items:
              - fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.namespace
                path: namespace

위의 매니페스트는 세 가지 정보로 구성된 프로젝티드 볼륨을 정의한다. 이 경우, 각 정보는 해당 볼륨 내의 단일 경로를 나타내기도 한다. 세 가지 정보는 다음과 같다.

1. 서비스어카운트토큰(serviceAccountToken) 정보는 kubelet이 kube-apiserver로부터 취득한 토큰을 포함한다. kubelet은 TokenRequest API를 통해 일정 시간 동안 사용할 수 있는 토큰을 발급 받는다. 이렇게 취득한 토큰은 파드가 삭제되거나 지정된 수명 주기 이후에 만료된다(기본값은 1시간이다). 이 토큰은 특정한 파드에 바인딩되며 kube-apiserver를 그 대상으로 한다. 이 메커니즘은 시크릿을 기반으로 볼륨을 추가하던 이전 메커니즘을 대체한 것이다. 해당 시크릿은 파드의 서비스어카운트를 나타냈었는데, 이는 토큰과는 달리 만료가 되지 않는 것이었다.
2. 컨피그맵(ConfigMap) 정보는 인증 및 인가에 관한 번들을 포함한다. 파드들은 이러한 인증서를 사용하여 해당 클러스터의 kube-apiserver(미들박스나 실수로 잘못 구성된 피어가 아닌) 에 대한 연결을 확인할 수 있다.
3. DownwardAPI 정보는 파드가 포함된 네임스페이스를 검색하고, 해당 정보를 파드 내부에서 실행 중인 애플리케이션에서 사용할 수 있도록 한다.

이러한 볼륨을 마운트한 컨테이너는 위의 정보들에 접근할 수 있다.

서비스어카운트에 대해 수동으로 시크릿 관리하기

쿠버네티스 v1.22 이전의 버전들은 쿠버네티스 API에 접근하기 위한 자격 증명들을 자동으로 생성했다. 이러한 옛 메커니즘들은, 실행 중인 파드에 마운트 될 수 있는 토큰 시크릿을 만드는 것에 기반을 두었다.

쿠버네티스 v1.29을 포함한 최신 버전에서는, API 자격 증명들은 TokenRequest API를 사용하여 직접 얻을 수 있으며, 프로젝티드 볼륨을 사용하여 파드에 마운트할 수 있다. 이 방법으로 취득한 토큰은 시간 제한이 있으며, 마운트 되었던 파드가 삭제되는 경우 자동으로 만료된다.

예를 들어 평생 만료되지 않는 토큰이 필요한 경우, 서비스 어카운트 토큰을 유지하기 위한 시크릿을 수동으로 생성할 수 있다.

한 번 시크릿을 수동으로 생성하여 서비스어카운트에 연결했다면, 쿠버네티스 컨트롤 플레인은 자동으로 해당 시크릿에 토큰을 채운다.

컨트롤 플레인의 세부 사항들

토큰 컨트롤러

토큰 컨트롤러는 kube-controller-manager 의 일부로써 실행되며, 비동기적으로 동작한다.

• 서비스어카운트에 대한 삭제를 감시하고, 해당하는 모든 서비스어카운트 토큰 시크릿을 같이 삭제한다.
• 서비스어카운트 토큰 시크릿에 대한 추가를 감시하고, 참조된 서비스어카운트가 존재하는지 확인하며, 필요한 경우 시크릿에 토큰을 추가한다.
• 시크릿에 대한 삭제를 감시하고, 필요한 경우 해당 서비스어카운트에서 참조 중인 항목들을 제거한다.

서비스 어카운트 개인키 파일은 --service-account-private-key-file 플래그를 사용하여 kube-controller-manager 의 토큰 컨트롤러에 전달해야 한다. 개인키는 생성된 서비스 어카운트 토큰에 서명하는 데 사용될 것이다. 마찬가지로 --service-account-key-file 플래그를 사용하여 해당 공개키를 kube-apiserver 에 전달해야 한다. 공개키는 인증 과정에서 토큰을 검증하는 데 사용될 것이다.

서비스어카운트 어드미션 컨트롤러

파드 수정은 어드미션 컨트롤러라는 플러그인을 통해 구현된다. 이것은 API 서버의 일부이며, 파드가 생성될 때 파드를 수정하기 위해 동기적으로 동작한다. 이 플러그인이 활성 상태(대부분의 배포에서 기본값)인 경우, 어드미션 컨트롤러는 파드의 생성 시점에 다음 작업들을 수행한다.

1. 파드에 .spce.serviceAccountName 항목이 지정되지 않았다면, 어드미션 컨트롤러는 실행하려는 파드의 서비스어카운트 이름을 default로 설정한다.
2. 어드미션 컨트롤러는 실행되는 파드가 참조하는 서비스어카운트가 존재하는지 확인한다. 만약 해당하는 이름의 서비스어카운트가 존재하지 않는 경우, 어드미션 컨트롤러는 파드를 실행시키지 않는다. 이는 default 서비스어카운트에 대해서도 동일하게 적용된다.
3. 서비스어카운트의 automountServiceAccountToken 또는 파드의 automountServiceAccountToken 중 어느 것도 false 로 설정되어 있지 않다면,
   • 어드미션 컨트롤러는 실행하려는 파드에 API에 접근할 수 있는 토큰을 포함하는 볼륨 을 추가한다.
   • 어드미션 컨트롤러는 파드의 각 컨테이너에 volumeMount를 추가한다. 이미 /var/run/secrets/kubernetes.io/serviceaccount 경로에 볼륨이 마운트 되어있는 컨테이너에 대해서는 추가하지 않는다. 리눅스 컨테이너의 경우, 해당 볼륨은 /var/run/secrets/kubernetes.io/serviceaccount 위치에 마운트되며, 윈도우 노드 역시 동일한 경로에 마운트된다.
4. 파드의 spec에 imagePullSecrets 이 없는 경우, 어드미션 컨트롤러는 ServiceAccount의 imagePullSecrets을 복사하여 추가된다.

TokenRequest API

서비스어카운트의 하위 리소스인 TokenRequest를 사용하여 일정 시간 동안 해당 서비스어카운트에서 사용할 수 있는 토큰을 가져올 수 있다. 컨테이너 내에서 사용하기 위한 API 토큰을 얻기 위해 이 요청을 직접 호출할 필요는 없는데, kubelet이 프로젝티드 볼륨 을 사용하여 이를 설정하기 때문이다.

kubectl에서 TokenRequest API를 사용하고 싶다면, 서비스어카운트를 위한 API 토큰을 수동으로 생성하기를 확인한다.

쿠버네티스 컨트롤 플레인(구체적으로는 서비스어카운트 어드미션 컨트롤러)은 파드에 프로젝티드 볼륨을 추가하고, kubelet은 컨테이너가 올바른 서비스어카운트로 인증할 수 있도록 해당 볼륨이 토큰을 포함하는고 있는지 확인한다.

(이 메커니즘은 시크릿을 기반으로 볼륨을 추가하던 이전 메커니즘을 대체한 것이다. 해당 시크릿은 파드의 서비스어카운트를 나타냈었는데, 이는 만료가 되지 않는 것이었다.)

아래는 실행 중인 파드에서 어떻게 보이는지에 대한 예시이다.

...
  - name: kube-api-access-<random-suffix>
    projected:
      defaultMode: 420 # 8진수 0644에 대한 10진수 값
      sources:
        - serviceAccountToken:
            expirationSeconds: 3607
            path: token
        - configMap:
            items:
              - key: ca.crt
                path: ca.crt
            name: kube-root-ca.crt
        - downwardAPI:
            items:
              - fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.namespace
                path: namespace

위의 매니페스트는 세 가지 정보로 구성된 프로젝티드 볼륨을 정의한다.

1. 서비스어카운트토큰(serviceAccountToken) 정보는 kubelet이 kube-apiserver로부터 취득한 토큰을 포함한다. kubelet은 TokenRequest API를 통해 일정 시간 동안 사용할 수 있는 토큰을 발급 받는다. 이렇게 취득한 토큰은 파드가 삭제되거나 지정된 수명 주기 이후에 만료된다(기본값은 1시간이다). 이 토큰은 특정한 파드에 바인딩되며 kube-apiserver를 그 대상으로 한다.
2. 컨피그맵(ConfigMap) 정보는 인증 및 인가에 관한 번들을 포함한다. 파드들은 이러한 인증서를 사용하여 해당 클러스터의 kube-apiserver(미들박스나 실수로 잘못 구성된 피어가 아닌) 에 대한 연결을 확인할 수 있다.
3. DownwardAPI 정보는 파드가 포함된 네임스페이스를 검색하고, 해당 정보를 파드 내부에서 실행 중인 애플리케이션에서 사용할 수 있도록 한다.

이러한 볼륨을 마운트한 컨테이너는 위의 정보들에 접근할 수 있다.

추가적인 API 토큰 생성하기

서비스어카운트를 위한 만료되지 않는 API 토큰을 생성하려면, 해당 서비스어카운트를 참조하는 어노테이션을 갖는 kubernetes.io/service-account-token 타입의 시크릿을 생성한다. 그러면 컨트롤 플레인은 장기적으로 사용 가능한 토큰을 발급하여 시크릿을 갱신할 것이다.

아래는 시크릿을 위한 예제 매니페스트이다.

secret/serviceaccount/mysecretname.yaml

apiVersion: v1
kind: Secret
type: kubernetes.io/service-account-token
metadata:
  name: mysecretname
  annotations:
    kubernetes.io/service-account.name: myserviceaccount

이 예제에 기반한 시크릿을 생성하려면, 아래의 명령어를 실행한다.

kubectl -n examplens create -f https://k8s.io/examples/secret/serviceaccount/mysecretname.yaml

시크릿에 대한 자세한 사항을 확인하려면, 아래의 명령어를 실행한다.

kubectl -n examplens describe secret mysecretname

결과는 다음과 같다.

Name:           mysecretname
Namespace:      examplens
Labels:         <none>
Annotations:    kubernetes.io/service-account.name=myserviceaccount
                kubernetes.io/service-account.uid=8a85c4c4-8483-11e9-bc42-526af7764f64

Type:   kubernetes.io/service-account-token

Data
====
ca.crt:         1362 bytes
namespace:      9 bytes
token:          ...

만약 examplens 네임스페이스에 새로운 파드를 실행한다면, 해당 파드는 방금 생성한 myserviceaccount 서비스 어카운트 토큰 시크릿을 사용할 수 있다.

서비스어카운트 토큰 시크릿 삭제/무효화

만약 제거하려는 토큰을 포함하는 시크릿의 이름을 알고 있다면, 아래 명령어를 실행한다.

kubectl delete secret name-of-secret

그게 아니라면, 먼저 시크릿을 확인한다.

# 아래 명령어는 'examplens' 네임스페이스가 존재한다고 가정한다.
kubectl -n examplens get serviceaccount/example-automated-thing -o yaml

결과는 다음과 같다.

apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"ServiceAccount","metadata":{"annotations":{},"name":"example-automated-thing","namespace":"examplens"}}      
  creationTimestamp: "2019-07-21T07:07:07Z"
  name: example-automated-thing
  namespace: examplens
  resourceVersion: "777"
  selfLink: /api/v1/namespaces/examplens/serviceaccounts/example-automated-thing
  uid: f23fd170-66f2-4697-b049-e1e266b7f835
secrets:
  - name: example-automated-thing-token-zyxwv

이제 시크릿의 이름을 알았으니, 삭제한다.

kubectl -n examplens delete secret/example-automated-thing-token-zyxwv

컨트롤 플레인은 서비스어카운트에 시크릿이 누락되었음을 감지하고, 새로운 것으로 대체한다.

kubectl -n examplens get serviceaccount/example-automated-thing -o yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"ServiceAccount","metadata":{"annotations":{},"name":"example-automated-thing","namespace":"examplens"}}      
  creationTimestamp: "2019-07-21T07:07:07Z"
  name: example-automated-thing
  namespace: examplens
  resourceVersion: "1026"
  selfLink: /api/v1/namespaces/examplens/serviceaccounts/example-automated-thing
  uid: f23fd170-66f2-4697-b049-e1e266b7f835
secrets:
  - name: example-automated-thing-token-4rdrh

정리하기

예제를 위해 examplens 네임스페이스를 생성했었다면, 아래의 명령어로 제거할 수 있다.

kubectl delete namespace examplens

컨트롤 플레인의 세부 사항들

서비스어카운트 컨트롤러

서비스어카운트 컨트롤러는 네임스페이스 내의 서비스어카운트들을 관리하며, 활성화된 모든 네임스페이스에 "default"라는 이름의 서비스어카운트가 존재하도록 한다.

토큰 컨트롤러

토큰 컨트롤러는 kube-controller-manager의 일부로써 실행되며, 비동기적으로 동작한다.

• 서비스어카운트에 대한 생성을 감시하고, 해당 서비스어카운트 토큰 시크릿을 생성하여 API에 대한 접근을 허용한다.
• 서비스어카운트에 대한 삭제를 감시하고, 해당하는 모든 서비스어카운트 토큰 시크릿을 같이 삭제한다.
• 서비스어카운트 토큰 시크릿에 대한 추가를 감시하고, 참조된 서비스어카운트가 존재하는지 확인하며, 필요한 경우 시크릿에 토큰을 추가한다.
• 시크릿에 대한 삭제를 감시하고, 필요한 경우 해당 서비스어카운트에서 참조 중인 항목들을 제거한다.

서비스 어카운트 개인키 파일은 --service-account-private-key-file 플래그를 사용하여 kube-controller-manager 의 토큰 컨트롤러에 전달해야 한다. 개인키는 생성된 서비스 어카운트 토큰에 서명하는 데 사용될 것이다. 마찬가지로 --service-account-key-file 플래그를 사용하여 해당 공개키를 kube-apiserver 에 전달해야 한다. 공개키는 인증 과정에서 토큰을 검증하는 데 사용될 것이다.

다음 내용

• 자세한 내용은 프로젝티드 볼륨을 확인한다.

3.3 - 인가 개요

지원되는 인가 모듈을 사용하여 정책을 만드는 방법을 포함한 쿠버네티스 인가에 대해 자세히 알아보자.

쿠버네티스에서는 사용자의 요청이 인가(접근 권한을 부여) 받기 전에 사용자가 인증(로그인)되어야 한다. 인증에 대한 자세한 내용은 쿠버네티스 API 접근 제어하기를 참고한다.

쿠버네티스는 REST API 요청에 공통적인 속성을 요구한다. 이는 쿠버네티스 인가가 쿠버네티스 API 이외에 다른 API를 처리할 수 있는 기존 조직 전체 또는 클라우드 제공자 전체의 접근 제어 시스템과 연동된다는 것을 의미한다.

요청 허용 또는 거부 결정

쿠버네티스는 API 서버를 이용하여 API 요청을 인가한다. 모든 정책과 비교하여 모든 요청 속성을 평가하고 요청을 허용하거나 거부한다. 계속 진행하려면 API 요청의 모든 부분이 일부 정책에 의해 반드시 허용되어야 한다. 이는 기본적으로 승인이 거부된다는 것을 의미한다.

(쿠버네티스는 API 서버를 사용하지만, 특정 오브젝트의 특정 필드에 의존하는 접근 제어 및 정책은 어드미션 컨트롤러에 의해 처리된다.)

여러 개의 인가 모듈이 구성되면 각 모듈이 순서대로 확인된다. 어느 인가 모듈이 요청을 승인하거나 거부할 경우, 그 결정은 즉시 반환되며 다른 인가 모듈이 참고되지 않는다. 모든 모듈에서 요청에 대한 평가가 없으면 요청이 거부된다. 요청 거부는 HTTP 상태 코드 403을 반환한다.

요청 속성 검토

쿠버네티스는 다음 API 요청 속성만 검토한다.

• user - 인증 중에 제공된 user 문자열.
• group - 인증된 사용자가 속한 그룹 이름 목록.
• extra - 인증 계층에서 제공하는 문자열 값에 대한 임의의 문자열 키 맵.
• API - 요청이 API 리소스에 대한 것인지 여부.
• Request path - /api 또는 /healthz와 같이 다양한 리소스가 아닌 엔드포인트의 경로.
• API request verb - get, list, create, update, patch, watch, delete, deletecollection과 같은 리소스 요청에 사용하는 API 동사. 리소스 API 엔드포인트의 요청 동사를 결정하려면 요청 동사 결정을 참고한다.
• HTTP request verb - get, post, put, delete처럼 소문자 HTTP 메서드는 리소스가 아닌 요청에 사용한다.
• Resource - 접근 중인 리소스의 ID 또는 이름(리소스 요청만 해당) -- get, update, patch, delete 동사를 사용하는 리소스 요청의 경우 리소스 이름을 지정해야 한다.
• Subresource - 접근 중인 하위 리소스(리소스 요청만 해당).
• Namespace - 접근 중인 오브젝트의 네임스페이스(네임스페이스에 할당된 리소스 요청만 해당)
• API group - 접근 중인 API 그룹(리소스 요청에만 해당). 빈 문자열은 핵심(core) API 그룹을 지정한다.

요청 동사 결정

리소스가 아닌 요청 /api/v1/... 또는 /apis/<group>/<version>/... 이외에 다른 엔드포인트에 대한 요청은 "리소스가 아닌 요청"으로 간주되며, 요청의 소문자 HTTP 메서드를 동사로 사용한다. 예를 들어, /api 또는 /healthz와 같은 엔드포인트에 대한 GET 요청은 get을 동사로 사용할 것이다.

리소스 요청 리소스 API 엔드포인트에 대한 요청 동사를 결정하려면 사용된 HTTP 동사와 해당 요청이 개별 리소스 또는 리소스 모음에 적용되는지 여부를 검토한다.

쿠버네티스는 종종 전문 동사를 사용하여 부가적인 권한 인가를 확인한다. 예를 들면,

• RBAC
  • rbac.authorization.k8s.io API 그룹의 roles 및 clusterroles 리소스에 대한 bind 동사.
• 인증
  • 핵심 API 그룹의 users, groups, serviceaccounts와 authentication.k8s.io API 그룹의 userextras 동사.

인가 모드

쿠버네티스 API 서버는 몇 가지 인가 모드 중 하나를 사용하여 요청을 승인할 수 있다.

• Node - 실행되도록 스케줄된 파드에 따라 kubelet에게 권한을 부여하는 특수 목적 인가 모드. Node 인가 모드 사용에 대한 자세한 내용은 Node 인가를 참조한다.
• ABAC - 속성 기반 접근 제어 (ABAC, Attribute-based access control)는 속성과 결합한 정책의 사용을 통해 사용자에게 접근 권한을 부여하는 접근 제어 패러다임을 말한다. 이 정책은 모든 유형의 속성(사용자 속성, 리소스 속성, 오브젝트, 환경 속성 등)을 사용할 수 있다. ABAC 모드 사용에 대한 자세한 내용은 ABAC 모드를 참조한다.
• RBAC - 역할 기반 접근 제어(RBAC, Role-based access control)는 기업 내 개별 사용자의 역할을 기반으로 컴퓨터나 네트워크 리소스에 대한 접근을 규제하는 방식이다. 이 맥락에서 접근은 개별 사용자가 파일을 보거나 만들거나 수정하는 것과 같은 특정 작업을 수행할 수 있는 능력이다. RBAC 모드 사용에 대한 자세한 내용은 RBAC 모드를 참조한다.
  • 지정된 RBAC(역할 기반 접근 제어)이 인가 결정을 위해 rbac.authorization.k8s.io API 그룹을 사용하면, 관리자가 쿠버네티스 API를 통해 권한 정책을 동적으로 구성할 수 있다.
  • RBAC을 활성화하려면 --authorization-mode=RBAC로 API 서버를 시작한다.
• Webhook - WebHook은 HTTP 콜백이다(어떤 일이 일어날 때 발생하는 HTTP POST와 HTTP POST를 통한 간단한 이벤트 알림). WebHook을 구현하는 웹 애플리케이션은 특정한 일이 발생할 때 URL에 메시지를 POST 할 것이다. Webhook 모드 사용에 대한 자세한 내용은 Webhook 모드를 참조한다.

API 접근 확인

kubectl은 API 인증 계층을 신속하게 쿼리하기 위한 auth can-i 하위 명령어를 제공한다. 이 명령은 현재 사용자가 지정된 작업을 수행할 수 있는지 여부를 알아내기 위해 SelfSubjectAccessReview API를 사용하며, 사용되는 인가 모드에 관계없이 작동한다.

kubectl auth can-i create deployments --namespace dev

다음과 유사하게 출력된다.

yes

kubectl auth can-i create deployments --namespace prod

다음과 유사하게 출력된다.

no

관리자는 이를 사용자 가장(impersonation)과 병행하여 다른 사용자가 수행할 수 있는 작업을 결정할 수 있다.

kubectl auth can-i list secrets --namespace dev --as dave

다음과 유사하게 출력된다.

no

유사하게, dev 네임스페이스의 dev-sa 서비스어카운트가 target 네임스페이스의 파드 목록을 볼 수 있는지 확인하려면 다음을 실행한다.

kubectl auth can-i list pods \
	--namespace target \
	--as system:serviceaccount:dev:dev-sa

다음과 유사하게 출력된다.

yes

SelfSubjectAccessReview는 authorization.k8s.io API 그룹의 일부로서 API 서버 인가를 외부 서비스에 노출시킨다. 이 그룹의 기타 리소스에는 다음이 포함된다.

• SubjectAccessReview - 현재 사용자뿐만 아니라 모든 사용자에 대한 접근 검토. API 서버에 인가 결정을 위임하는 데 유용하다. 예를 들어, kubelet 및 확장(extension) API 서버는 자신의 API에 대한 사용자 접근을 결정하기 위해 해당 리소스를 사용한다.
• LocalSubjectAccessReview - SubjectAccessReview와 비슷하지만 특정 네임스페이스로 제한된다.
• SelfSubjectRulesReview - 사용자가 네임스페이스 안에서 수행할 수 있는 작업 집합을 반환하는 검토. 사용자가 자신의 접근을 빠르게 요약해서 보거나 UI가 작업을 숨기거나 표시하는 데 유용하다.

이러한 API는 반환된 오브젝트의 응답 "status" 필드가 쿼리의 결과인 일반 쿠버네티스 리소스를 생성하여 쿼리할 수 있다.

kubectl create -f - -o yaml << EOF
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
spec:
  resourceAttributes:
    group: apps
    resource: deployments
    verb: create
    namespace: dev
EOF

생성된 SelfSubjectAccessReview 는 다음과 같다.

apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
metadata:
  creationTimestamp: null
spec:
  resourceAttributes:
    group: apps
    resource: deployments
    namespace: dev
    verb: create
status:
  allowed: true
  denied: false

인가 모듈에 플래그 사용

정책에 포함된 인가 모듈을 나타내기 위해 정책에 플래그를 포함시켜야 한다.

다음 플래그를 사용할 수 있다.

• --authorization-mode=ABAC 속성 기반 접근 제어(ABAC) 모드를 사용하면 로컬 파일을 사용하여 정책을 구성할 수 있다.
• --authorization-mode=RBAC 역할 기반 접근 제어(RBAC) 모드를 사용하면 쿠버네티스 API를 사용하여 정책을 만들고 저장할 수 있다.
• --authorization-mode=Webhook WebHook은 원격 REST 엔드포인트를 사용하여 인가를 관리할 수 있는 HTTP 콜백 모드다.
• --authorization-mode=Node 노드 인가는 kubelet이 생성한 API 요청을 특별히 인가시키는 특수 목적 인가 모드다.
• --authorization-mode=AlwaysDeny 이 플래그는 모든 요청을 차단한다. 이 플래그는 테스트에만 사용한다.
• --authorization-mode=AlwaysAllow 이 플래그는 모든 요청을 허용한다. API 요청에 대한 인가가 필요하지 않은 경우에만 이 플래그를 사용한다.

하나 이상의 인가 모듈을 선택할 수 있다. 모듈이 순서대로 확인되기 때문에 우선 순위가 더 높은 모듈이 요청을 허용하거나 거부할 수 있다.

워크로드 생성 및 수정을 통한 권한 확대

네임스페이스에서 파드를 직접, 또는 오퍼레이터와 같은 컨트롤러를 통해 생성/수정할 수 있는 사용자는 해당 네임스페이스 안에서 자신의 권한을 확대할 수 있다.

권한 확대 경로

• 네임스페이스 내의 임의의 시크릿을 마운트
  • 다른 워크로드를 위한 시크릿으로의 접근에 사용될 수 있음
  • 더 권한이 많은 서비스 어카운트의 서비스 어카운트 토큰 획득에 사용될 수 있음
• 네임스페이스 내의 임의의 서비스 어카운트를 사용
  • 다른 워크로드인것처럼 사칭하여 쿠버네티스 API 액션을 수행할 수 있음
  • 서비스 어카운트가 갖고 있는 '권한이 필요한 액션'을 수행할 수 있음
• 네임스페이스 내의 다른 워크로드를 위한 컨피그맵을 마운트
  • 다른 워크로드를 위한 정보(예: DB 호스트 이름) 획득에 사용될 수 있음
• 네임스페이스 내의 다른 워크로드를 위한 볼륨을 마운트
  • 다른 워크로드를 위한 정보의 획득 및 수정에 사용될 수 있음

다음 내용

• 인증에 대한 자세한 내용은 쿠버네티스 API 접근 제어하기에서 인증 을 참조한다.
• 어드미션 제어에 대한 자세한 내용은 어드미션 컨트롤러 사용하기를 참조한다.

3.4 - Kubelet 인증/인가

개요

kubelet의 HTTPS 엔드포인트는 다양한 민감도의 데이터에 대한 접근을 제공하는 API를 노출하며, 노드와 컨테이너 내에서 다양한 수준의 권한으로 작업을 수행할 수 있도록 허용한다.

이 문서는 kubelet의 HTTPS 엔드포인트에 대한 접근을 인증하고 인가하는 방법을 설명한다.

Kubelet 인증

기본적으로, 다른 구성의 인증 방법에 의해 거부되지 않은 kubelet의 HTTPS 엔드포인트에 대한 요청은 익명의 요청으로 처리되며, system:anonymous의 사용자 이름과 system:unauthenticated 의 그룹이 부여된다.

익명의 접근을 비활성화하고 인증되지 않은 요청에 401 Unauthorized 응답을 보내려면 아래를 참고한다.

• --anonymous-auth=false 플래그로 kubelet을 시작

kubelet의 HTTPS 엔드포인트에 대한 X509 클라이언트 인증서 인증을 활성화하려면 아래를 참고한다.

• --client-ca-file 플래그로 kubelet을 시작하면 클라이언트 인증서를 확인할 수 있는 CA 번들을 제공
• --kubelet-client-certificate 및 --kubelet-client-key 플래그로 apiserver를 시작
• 자세한 내용은 apiserver 인증 문서를 참고

API bearer 토큰(서비스 계정 토큰 포함)을 kubelet의 HTTPS 엔드포인트 인증에 사용하려면 아래를 참고한다.

• API 서버에서 authentication.k8s.io/v1beta1 API 그룹이 사용 가능한지 확인
• --authentication-token-webhook 및 --kubeconfig 플래그로 kubelet을 시작
• kubelet은 구성된 API 서버의 TokenReview API를 호출하여 bearer 토큰에서 사용자 정보를 결정

Kubelet 승인

성공적으로 인증된 모든 요청(익명 요청 포함)이 승인된다. 기본 인가 모드는 모든 요청을 허용하는 AlwaysAllow 이다.

kubelet API에 대한 접근을 세분화하는 데는 다양한 이유가 있다.

• 익명 인증을 사용할 수 있지만, 익명 사용자의 kubelet API 호출 기능은 제한되어야 함
• bearer 토큰 인증을 사용할 수 있지만, 임의의 API 사용자(API 계정)의 kubelet API 호출 기능은 제한되어야 함
• 클라이언트 인증을 사용할 수 있지만, 구성된 CA에서 서명한 일부 클라이언트 인증서만 kubelet API를 사용하도록 허용해야 함

kubelet API에 대한 접근을 세분화하려면 API 서버에 권한을 위임한다.

• authorization.k8s.io/v1beta1 API 그룹이 API 서버에서 사용 가능한지 확인
• --authorization-mode=Webhook 및 --kubeconfig 플래그로 kubelet을 시작
• kubelet은 구성된 API 서버의 SubjectAccessReview API를 호출하여 각각의 요청이 승인되었는지 여부를 확인

kubelet은 API 요청을 apiserver와 동일한 요청 속성 접근 방식을 사용하여 승인한다.

동사는 들어오는 요청의 HTTP 동사로부터 결정된다.

리소스 및 하위 리소스는 들어오는 요청의 경로로부터 결정된다.

네임스페이스와 API 그룹 속성은 항상 빈 문자열이며, 리소스 이름은 항상 kubelet의 Node API 오브젝트 이름이다.

이 모드로 실행할 때, --kubelet-client-certificate 및 --kubelet-client-key 플래그로 식별된 사용자에게 다음 속성에 대한 권한이 있는지 확인한다.

• verb=*, resource=nodes, subresource=proxy
• verb=*, resource=nodes, subresource=stats
• verb=*, resource=nodes, subresource=log
• verb=*, resource=nodes, subresource=spec
• verb=*, resource=nodes, subresource=metrics

4 - 잘 알려진 레이블, 어노테이션, 테인트(Taint)

쿠버네티스는 모든 레이블과 어노테이션을 kubernetes.io와 k8s.io 네임스페이스 아래에 정의해 놓았다.

이 문서는 각 값에 대한 레퍼런스를 제공하며, 값을 할당하기 위한 협력 포인트도 제공한다.

API 오브젝트에서 사용되는 레이블, 어노테이션, 테인트

app.kubernetes.io/component

예시: app.kubernetes.io/component: "database"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

아키텍처 내의 컴포넌트.

추천하는 레이블을 확인한다.

app.kubernetes.io/created-by (사용 중단됨)

예시: app.kubernetes.io/created-by: "controller-manager"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

리소스를 생성한 컨트롤러/사용자.

app.kubernetes.io/instance

예시: app.kubernetes.io/instance: "mysql-abcxzy"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

애플리케이션 인스턴스를 식별하기 위한 고유한 이름. 고유하지 않은 이름을 할당하려면, app.kubernetes.io/name를 사용한다.

추천하는 레이블을 확인한다.

app.kubernetes.io/managed-by

예시: app.kubernetes.io/managed-by: "helm"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

애플리케이션의 작업을 관리하기 위해 사용되는 도구.

추천하는 레이블을 확인한다.

app.kubernetes.io/name

예시: app.kubernetes.io/name: "mysql"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

애플리케이션의 이름.

추천하는 레이블을 확인한다.

app.kubernetes.io/part-of

예시: app.kubernetes.io/part-of: "wordpress"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

해당 애플리케이션이 속한 상위 레벨의 애플리케이션 이름.

추천하는 레이블을 확인한다.

app.kubernetes.io/version

예시: app.kubernetes.io/version: "5.7.21"

적용 대상: 모든 오브젝트 (일반적으로 워크로드 리소스에서 사용됨)

애플리케이션의 현재 버전.

일반적으로 다음과 같은 형태의 값들을 포함한다.

• 시맨틱 버전
• 리비전 해시 깃 소스 코드

추천하는 레이블을 확인한다.

cluster-autoscaler.kubernetes.io/safe-to-evict

예시: cluster-autoscaler.kubernetes.io/safe-to-evict: "true"

적용 대상: 파드

이 어노테이션이 "true"로 설정된 경우, 파드 축출을 막는 다른 규칙이 있는 경우에도 클러스터 오토스케일러가 파드를 축출할 수 있다. 클러스터 오토스케일러는 명시적으로 이 어노테이션이 "false"로 설정된 파드를 절대 축출하지 않는다. 따라서, 계속해서 실행을 유지하고자 하는 중요한 파드에 설정할 수 있다. 이 어노테이션이 설정되지 않은 경우, 클러스터 오토스케일러는 파드 수준(Pod-level) 동작을 따른다.

kubernetes.io/arch

예시: kubernetes.io/arch=amd64

적용 대상: 노드

Go에 의해 정의된 runtime.GOARCH 값을 kubelet이 읽어서 이 레이블의 값으로 채운다. arm 노드와 x86 노드를 혼합하여 사용하는 경우 유용할 수 있다.

kubernetes.io/os

예시: kubernetes.io/os=linux

적용 대상: 노드

Go에 의해 정의된 runtime.GOOS 값을 kubelet이 읽어서 이 레이블의 값으로 채운다. 클러스터에서 여러 운영체제를 혼합하여 사용(예: 리눅스 및 윈도우 노드)하는 경우 유용할 수 있다.

kubernetes.io/metadata.name

예시: kubernetes.io/metadata.name=mynamespace

적용 대상: 네임스페이스

(컨트롤 플레인의 일부인) 쿠버네티스 API 서버가 이 레이블을 모든 네임스페이스에 설정한다. 레이블의 값은 네임스페이스의 이름으로 적용된다. 이 레이블의 값을 변경할 수는 없다.

레이블 셀렉터를 이용하여 특정 네임스페이스를 지정하고 싶다면 이 레이블이 유용할 수 있다.

kubernetes.io/limit-ranger

예시: kubernetes.io/limit-ranger: "LimitRanger plugin set: cpu, memory request for container nginx; cpu, memory limit for container nginx"

적용 대상: 파드

쿠버네티스는 기본적으로 어떠한 리소스 한도도 설정하지 않는다. 명시적으로 한도를 설정하지 않을 경우, 컨테이너는 CPU와 메모리를 무제한으로 사용하게 된다. 네임스페이스에 리밋레인지를 생성함으로써 리소스에 대한 요청이나 한도 기본값을 파드에 설정할 수 있다. 리밋레인지를 정의한 뒤에 배포된 파드들은 이러한 한도가 적용된다. kubernetes.io/limit-ranger 어노테이션은 파드에 대해 리소스 기본값이 성공적으로 적용되었다고 기록한다. 자세한 내용은 리밋레인지를 확인한다.

beta.kubernetes.io/arch (사용 중단됨)

이 레이블은 사용 중단되었다. 대신 kubernetes.io/arch 을 사용한다.

beta.kubernetes.io/os (사용 중단됨)

이 레이블은 사용 중단되었다. 대신 kubernetes.io/os 을 사용한다.

kubernetes.io/hostname

예시: kubernetes.io/hostname=ip-172-20-114-199.ec2.internal

적용 대상: 노드

kubelet이 호스트네임을 읽어서 이 레이블의 값으로 채운다. kubelet 에 --hostname-override 플래그를 전달하여 실제 호스트네임과 다른 값으로 설정할 수도 있다.

이 레이블은 토폴로지 계층의 일부로도 사용된다. topology.kubernetes.io/zone에서 세부 사항을 확인한다.

kubernetes.io/change-cause

예시: kubernetes.io/change-cause=kubectl edit --record deployment foo

적용 대상: 모든 오브젝트

이 어노테이션은 어떤 오브젝트가 왜 변경되었는지 그 이유를 담는다.

어떤 오브젝트를 변경할 수도 있는 kubectl 명령에 --record 플래그를 사용하면 이 레이블이 추가된다.

kubernetes.io/description

예시: kubernetes.io/description: "Description of K8s object."

적용 대상: 모든 오브젝트

이 어노테이션은 주어진 오브젝트의 특정 상태를 표현하는데 사용한다.

kubernetes.io/enforce-mountable-secrets

예시: kubernetes.io/enforce-mountable-secrets: "true"

적용 대상: 서비스어카운트(ServiceAccount)

이 어노테이션의 값은 true로 설정되어야만 작동한다. 이 어노테이션은, 해당 서비스어카운트로 동작중인 파드가 그 서비스어카운트의 secrets 항목에 명시된 Secret API 오브젝트만을 참조한다는 뜻이다.

node.kubernetes.io/exclude-from-external-load-balancer

예시: node.kubernetes.io/exclude-from-external-load-balancer

적용 대상: 노드

쿠버네티스는 클러스터에 ServiceNodeExclusion 기능 게이트를 자동으로 활성화한다. 해당 기능 게이트가 클러스터에 활성화되어 있으면, 백엔드 서버들로부터 특정 워커 노드를 제외시키도록 레이블을 추가할 수 있다. 다음 명령어는 백엔드 목록에서 워커 노드를 제외시키는 명령어이다. kubectl label nodes <node-name> node.kubernetes.io/exclude-from-external-load-balancers=true

controller.kubernetes.io/pod-deletion-cost

예시: controller.kubernetes.io/pod-deletion-cost=10

적용 대상: 파드

이 어노테이션은 레플리카셋(ReplicaSet) 다운스케일 순서를 조정할 수 있는 요소인 파드 삭제 비용을 설정하기 위해 사용한다. 명시된 값은 int32 타입으로 파싱된다.

cluster-autoscaler.kubernetes.io/enable-ds-eviction

예시: cluster-autoscaler.kubernetes.io/enable-ds-eviction: "true"

적용 대상: Pod

이 어노테이션은 클러스터 오토스케일러가 데몬셋 파드를 축출할 것인지 여부를 제어한다. 이 어노테이션은 데몬셋 매니페스트 내 데몬셋 파드에 명시되어야 한다. 이 어노테이션이 "true"로 설정된 경우, 파드 축출을 막는 다른 규칙이 있는 경우에도 클러스터 오토스케일러가 파드를 축출할 수 있다. 클러스터 오토스케일러가 데몬셋 파드를 축출하는 것을 허용하지 않기 위해서는, 중요한 데몬셋 파드에 이 어노테이션을 "false"로 설정한다. 이 어노테이션이 설정되지 않은 경우, 클러스터 오토스케일러는 전체 동작을 따른다. 즉, 해당 구성에 따라서 데몬셋을 축출한다.

kubernetes.io/ingress-bandwidth

예시: kubernetes.io/ingress-bandwidth: 10M

적용 대상: 파드

파드에 QoS(quality-of-service)를 적용함으로써 가용한 대역폭을 효과적으로 제한할 수 있다. 인그레스 트래픽(파드로 향하는)은 효과적으로 데이터를 처리하기 위해 대기 중인 패킷을 큐로 관리한다. 파드의 대역폭을 제한하기 위해서는, 오브젝트를 정의하는 JSON 파일을 작성하고 kubernetes.io/ingress-bandwidth 어노테이션을 통해 데이터 트래픽의 속도를 명시한다. 인그레스 속도를 명시할 때 사용되는 단위는 초당 비트(수량)이다. 예를 들어, 10M은 초당 10 메가비트를 의미한다.

kubernetes.io/egress-bandwidth

예시: kubernetes.io/egress-bandwidth: 10M

적용 대상: 파드

이그레스 트래픽(파드로부터의)은 설정된 속도를 초과하는 패킷을 삭제하는 정책에 의해 처리되며, 파드에 거는 제한은 다른 파드의 대역폭에 영향을 주지 않는다. 파드의 대역폭을 제한하기 위해서는, 오브젝트를 정의하는 JSON 파일을 작성하고 kubernetes.io/egress-bandwidth 어노테이션을 통해 데이터 트래픽의 속도를 명시한다. 이그레스 속도를 명시할 때 사용되는 단위는 초당 비트(수량)이다. 예를 들어, 10M은 초당 10 메가비트를 의미한다.

beta.kubernetes.io/instance-type (사용 중단됨)

node.kubernetes.io/instance-type

예시: node.kubernetes.io/instance-type=m3.medium

적용 대상: 노드

클라우드 제공자에 의해 정의된 인스턴스 타입의 값을 kubelet이 읽어서 이 레이블의 값으로 채운다. 클라우드 제공자를 사용하는 경우에만 이 레이블이 설정된다. 특정 워크로드를 특정 인스턴스 타입에 할당하고 싶다면 이 레이블이 유용할 수 있다. 하지만 일반적으로는 자원 기반 스케줄링을 수행하는 쿠버네티스 스케줄러를 이용하게 된다. 인스턴스 타입 보다는 특성을 기준으로 스케줄링을 고려해야 한다(예: g2.2xlarge 를 요구하기보다는, GPU가 필요하다고 요구한다).

failure-domain.beta.kubernetes.io/region (사용 중단됨)

topology.kubernetes.io/region을 확인한다.

failure-domain.beta.kubernetes.io/zone (사용 중단됨)

topology.kubernetes.io/zone을 확인한다.

statefulset.kubernetes.io/pod-name

예시:

statefulset.kubernetes.io/pod-name=mystatefulset-7

스테이트풀셋(StatefulSet) 컨트롤러가 파드를 위한 스테이트풀셋을 생성하면, 컨트롤 플레인이 파드에 이 레이블을 설정한다. 생성되는 파드의 이름을 이 레이블의 값으로 설정한다.

스테이트풀셋 문서의 파드 이름 레이블에서 상세 사항을 확인한다.

scheduler.alpha.kubernetes.io/node-selector

예시: scheduler.alpha.kubernetes.io/node-selector: "name-of-node-selector"

적용 대상: 네임스페이스

파드-노드 셀렉터(PodNodeSelector)는 이 어노테이션의 키를 사용하여 네임스페이스의 파드들에 노드 셀렉터를 할당한다.

topology.kubernetes.io/region

예시:

topology.kubernetes.io/region=us-east-1

topology.kubernetes.io/zone을 확인한다.

topology.kubernetes.io/zone

예시:

topology.kubernetes.io/zone=us-east-1c

적용 대상: 노드, 퍼시스턴트볼륨(PersistentVolume)

노드의 경우: 클라우드 제공자가 제공하는 값을 이용하여 kubelet 또는 외부 cloud-controller-manager가 이 어노테이션의 값을 설정한다. 클라우드 제공자를 사용하는 경우에만 이 레이블이 설정된다. 하지만, 토폴로지 내에서 의미가 있는 경우에만 이 레이블을 노드에 설정해야 한다.

퍼시스턴트볼륨의 경우: 토폴로지 어웨어 볼륨 프로비저너가 자동으로 퍼시스턴트볼륨에 노드 어피니티 제약을 설정한다.

영역(zone)은 논리적 고장 도메인을 나타낸다. 가용성 향상을 위해 일반적으로 쿠버네티스 클러스터는 여러 영역에 걸쳐 구성된다. 영역에 대한 정확한 정의는 사업자 별 인프라 구현에 따라 다르지만, 일반적으로 영역은 '영역 내 매우 낮은 네트워크 지연시간, 영역 내 네트워크 트래픽 비용 없음, 다른 영역의 고장에 독립적임' 등의 공통적인 특성을 갖는다. 예를 들어, 같은 영역 내의 노드는 하나의 네트워크 스위치를 공유하여 활용할 수 있으며, 반대로 다른 영역에 있는 노드는 하나의 네트워크 스위치를 공유해서는 안 된다.

지역(region)은 하나 이상의 영역으로 구성된 더 큰 도메인을 나타낸다. 쿠버네티스 클러스터가 여러 지역에 걸쳐 있는 경우는 드물다. 영역이나 지역에 대한 정확한 정의는 사업자 별 인프라 구현에 따라 다르지만, 일반적으로 지역은 '지역 내 네트워크 지연시간보다 지역 간 네트워크 지연시간이 큼, 지역 간 네트워크 트래픽은 비용이 발생함, 다른 영역/지역의 고장에 독립적임' 등의 공통적인 특성을 갖는다. 예를 들어, 같은 지역 내의 노드는 전력 인프라(예: UPS 또는 발전기)를 공유하여 활용할 수 있으며, 반대로 다른 지역에 있는 노드는 일반적으로 전력 인프라를 공유하지 않는다.

쿠버네티스는 영역과 지역의 구조에 대해 다음과 같이 가정한다.

1. 지역과 영역은 계층적이다. 영역은 지역의 엄격한 부분집합(strict subset)이며, 하나의 영역이 두 개의 지역에 속할 수는 없다.
2. 영역 이름은 모든 지역에 걸쳐서 유일하다. 예를 들어, "africa-east-1" 라는 지역은 "africa-east-1a" 와 "africa-east-1b" 라는 영역으로 구성될 수 있다.

토폴로지 레이블이 변경되는 일은 없다고 가정할 수 있다. 일반적으로 레이블의 값은 변경될 수 있지만, 특정 노드가 삭제 후 재생성되지 않고서는 다른 영역으로 이동할 수 없기 때문이다.

쿠버네티스는 이 정보를 다양한 방식으로 활용할 수 있다. 예를 들어, 단일 영역 클러스터에서는 스케줄러가 자동으로 레플리카셋의 파드를 여러 노드에 퍼뜨린다(노드 고장의 영향을 줄이기 위해 - kubernetes.io/hostname 참고). 복수 영역 클러스터에서는, 여러 영역에 퍼뜨린다(영역 고장의 영향을 줄이기 위해). 이는 SelectorSpreadPriority 를 통해 실현된다.

SelectorSpreadPriority 는 최선 노력(best effort) 배치 방법이다. 클러스터가 위치한 영역들의 특성이 서로 다르다면(예: 노드 숫자가 다름, 노드 타입이 다름, 파드 자원 요구사항이 다름), 파드 숫자를 영역별로 다르게 하여 배치할 수 있다. 필요하다면, 영역들의 특성(노드 숫자/타입)을 일치시켜 불균형 배치의 가능성을 줄일 수 있다.

스케줄러도 (VolumeZonePredicate 표시자를 이용하여) '파드가 요청하는 볼륨'이 위치하는 영역과 같은 영역에 파드를 배치한다. 여러 영역에서 볼륨에 접근할 수는 없다.

PersistentVolumeLabel이 퍼시스턴트볼륨의 자동 레이블링을 지원하지 않는다면, 레이블을 수동으로 추가하거나 PersistentVolumeLabel이 동작하도록 변경할 수 있다. PersistentVolumeLabel이 설정되어 있으면, 스케줄러는 파드가 다른 영역에 있는 볼륨에 마운트하는 것을 막는다. 만약 사용 중인 인프라에 이러한 제약이 없다면, 볼륨에 영역 레이블을 추가할 필요가 전혀 없다.

volume.beta.kubernetes.io/storage-provisioner (사용 중단됨)

예시: volume.beta.kubernetes.io/storage-provisioner: k8s.io/minikube-hostpath

적용 대상: 퍼시스턴트볼륨클레임(PersistentVolumeClaim)

이 어노테이션은 사용 중단되었다.

volume.beta.kubernetes.io/mount-options (사용 중단)

예시 : volume.beta.kubernetes.io/mount-options: "ro,soft"

적용 대상: 퍼시스턴트볼륨

쿠버네티스 관리자는, 노드에 퍼시스턴트볼륨이 마운트될 경우 추가적인 마운트 옵션을 명세할 수 있다.

이 어노테이션은 사용 중단되었다.

volume.kubernetes.io/storage-provisioner

적용 대상: 퍼시스턴트볼륨클레임

이 어노테이션은 동적 프로비저닝이 요구되는 PVC에 추가될 예정이다.

node.kubernetes.io/windows-build

예시: node.kubernetes.io/windows-build=10.0.17763

적용 대상: 노드

kubelet이 Microsoft 윈도우에서 실행되고 있다면, 사용 중인 Windows Server 버전을 기록하기 위해 kubelet이 노드에 이 레이블을 추가한다.

이 레이블의 값은 "MajorVersion.MinorVersion.BuildNumber"의 형태를 갖는다.

service.kubernetes.io/headless

예시: service.kubernetes.io/headless=""

적용 대상: 서비스

서비스가 헤드리스(headless)이면, 컨트롤 플레인이 엔드포인트(Endpoints) 오브젝트에 이 레이블을 추가한다.

kubernetes.io/service-name

예시: kubernetes.io/service-name="my-website"

적용 대상: 엔드포인트슬라이스(EndpointSlices)

쿠버네티스는 이 레이블을 사용하여 엔드포인트슬라이스와 서비스를 결합한다.

이 레이블은 엔드포인트슬라이스가 지원하는 서비스의 이름을 기록한다. 모든 엔드포인트슬라이스는 이 레이블을 자신과 연결된 서비스의 이름으로 설정해야 한다.

kubernetes.io/service-account.name

예시: kubernetes.io/service-account.name: "sa-name"

적용 대상: 시크릿(Secret)

이 어노테이션에는 토큰(kubernetes.io/service-account-token 타입의 시크릿에 저장되는)이 나타내는 서비스어카운트의 이름을 기록한다.

kubernetes.io/service-account.uid

예시: kubernetes.io/service-account.uid: da68f9c6-9d26-11e7-b84e-002dc52800da

적용 대상: 시크릿

이 어노테이션에는 토큰(kubernetes.io/service-account-token 타입의 시크릿에 저장되는)이 나타내는 서비스어카운트의 고유 ID를 기록한다.

kubernetes.io/legacy-token-last-used

예시: kubernetes.io/legacy-token-last-used: 2022-10-24

적용 대상: 시크릿

컨트롤 플레인은 kubernetes.io/service-account-token 타입을 갖는 시크릿에 대해서만 이 레이블을 추가한다. 이 레이블의 값은, 클라이언트가 서비스어카운트 토큰을 사용하여 인증한 요청을 컨트롤 플레인이 마지막으로 확인한 날짜(ISO 8601 형식, UTC 시간대)를 기록한다.

클러스터가 해당 기능을 얻기 전에 기존의 토큰을 마지막으로 사용한 경우(쿠버네티스 v1.26에 추가됨), 이 레이블은 설정되지 않는다.

endpointslice.kubernetes.io/managed-by

예시: endpointslice.kubernetes.io/managed-by="controller"

적용 대상: 엔드포인트슬라이스

이 레이블은 엔드포인트슬라이스(EndpointSlice)를 어떤 컨트롤러나 엔티티가 관리하는지를 나타내기 위해 사용된다. 이 레이블을 사용함으로써 한 클러스터 내에서 여러 엔드포인트슬라이스 오브젝트가 각각 다른 컨트롤러나 엔티티에 의해 관리될 수 있다.

endpointslice.kubernetes.io/skip-mirror

예시: endpointslice.kubernetes.io/skip-mirror="true"

적용 대상: 엔드포인트(Endpoints)

특정 자원에 이 레이블을 "true" 로 설정하여, EndpointSliceMirroring 컨트롤러가 엔드포인트슬라이스를 이용하여 해당 자원을 미러링하지 않도록 지시할 수 있다.

service.kubernetes.io/service-proxy-name

예시: service.kubernetes.io/service-proxy-name="foo-bar"

적용 대상: 서비스

kube-proxy 에는 커스텀 프록시를 위한 이와 같은 레이블이 있으며, 이 레이블은 서비스 컨트롤을 커스텀 프록시에 위임한다.

experimental.windows.kubernetes.io/isolation-type (사용 중단)

예시: experimental.windows.kubernetes.io/isolation-type: "hyperv"

적용 대상: 파드

Hyper-V 격리(isolation)를 사용하여 윈도우 컨테이너를 실행하려면 이 어노테이션을 사용한다. Hyper-V 격리 기능을 활성화하고 Hyper-V 격리가 적용된 컨테이너를 생성하기 위해, kubelet은 기능 게이트 HyperVContainer=true 로 설정하여 실행되어야 하며, 파드에는 experimental.windows.kubernetes.io/isolation-type=hyperv 어노테이션이 설정되어 있어야 한다.

ingressclass.kubernetes.io/is-default-class

예시: ingressclass.kubernetes.io/is-default-class: "true"

적용 대상: 인그레스클래스(IngressClass)

하나의 인그레스클래스 리소스에 이 어노테이션이 "true"로 설정된 경우, 클래스가 명시되지 않은 새로운 인그레스(Ingress) 리소스는 해당 기본 클래스로 할당될 것이다.

kubernetes.io/ingress.class (사용 중단됨)

storageclass.kubernetes.io/is-default-class

예시: storageclass.kubernetes.io/is-default-class=true

적용 대상: 스토리지클래스(StorageClass)

하나의 스토리지클래스(StorageClass) 리소스에 이 어노테이션이 "true"로 설정된 경우, 클래스가 명시되지 않은 새로운 퍼시스턴트볼륨클레임 리소스는 해당 기본 클래스로 할당될 것이다.

alpha.kubernetes.io/provided-node-ip

예시: alpha.kubernetes.io/provided-node-ip: "10.0.0.1"

적용 대상: 노드

kubelet이 노드에 할당된 IPv4 주소를 명시하기 위해 이 어노테이션을 사용할 수 있다.

kubelet이 --cloud-provider 플래그를 사용하여 어떤 값을 갖게 되었다면 (외부 또는 레거시 트리 내(in-tree) 클라우드 공급자 모두 포함), kubelet은 이 어노테이션을 노드에 설정하여 명령줄 플래그(--node-ip)를 통해 설정된 IP 주소를 명시한다. cloud-controller-manager는 클라우드 제공자에게 이 IP 주소가 유효한지를 검증한다.

batch.kubernetes.io/job-completion-index

예시: batch.kubernetes.io/job-completion-index: "3"

적용 대상: 파드

kube-controller-manager의 잡(Job) 컨트롤러는 Indexed 완료 모드로 생성된 파드에 이 어노테이션을 추가한다.

kubectl.kubernetes.io/default-container

예시: kubectl.kubernetes.io/default-container: "front-end-app"

파드의 기본 컨테이너로 사용할 컨테이너 이름을 지정하는 어노테이션이다. 예를 들어, kubectl logs 또는 kubectl exec 명령을 사용할 때 -c 또는 --container 플래그를 지정하지 않으면, 이 어노테이션으로 명시된 기본 컨테이너를 대상으로 실행될 것이다.

endpoints.kubernetes.io/over-capacity

예시: endpoints.kubernetes.io/over-capacity:truncated

적용 대상: 엔드포인트(Endpoints)

컨트롤 플레인은, 연결된 서비스에 1000개 이상의 엔드포인트가 있는 경우, 이 어노테이션을 엔드포인트 오브젝트에 추가한다. 이 어노테이션은 엔드포인트의 용량이 초과되었거나 엔드포인트의 수가 1000개로 잘렸음을 나타낸다.

백엔드 엔드포인트의 수가 1000개 미만이면, 컨트롤 플레인은 이 어노테이션을 제거한다.

batch.kubernetes.io/job-tracking (사용 중단)

예시: batch.kubernetes.io/job-tracking: ""

적용 대상: 잡

잡에 이 어노테이션이 있는 경우, 컨트롤 플레인이 파이널라이저(finalizer)를 이용하여 잡 상태를 추적하고 있음을 나타낸다. 컨트롤 플레인은 이 어노테이션을 사용하여, 아직 기능이 개발 중인 동안 파이널라이저를 사용하여 잡을 추적하도록 안전하게 전환한다. 이 어노테이션을 수동으로 추가하거나 제거해서는 안 된다.

scheduler.alpha.kubernetes.io/defaultTolerations

예시: scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Equal", "value": "value1", "effect": "NoSchedule", "key": "dedicated-node"}]'

적용 대상: 네임스페이스

이 어노테이션은 PodTolerationRestriction 어드미션 컨트롤러가 활성화되어 있어야 한다. 어노테이션의 키는 네임스페이스에 톨러레이션(toleration)을 할당하는 것을 허용하며, 해당 네임스페이스에 생성되는 모든 파드들은 이 톨러레이션이 부여된다.

scheduler.alpha.kubernetes.io/preferAvoidPods (사용 중단)

적용 대상: 노드

이 어노테이션을 사용하려면 NodePreferAvoidPods 스케줄링 플러그인이 활성화되어 있어야 한다. 해당 플러그인은 쿠버네티스 1.22에서 사용 중단되었다. 대신 테인트와 톨러레이션을 사용한다.

이 이후로 나오는 테인트는 모두 '적용 대상: 노드' 이다.

node.kubernetes.io/not-ready

예시: node.kubernetes.io/not-ready:NoExecute

노드 컨트롤러는 노드의 헬스를 모니터링하여 노드가 사용 가능한 상태인지를 감지하고 그에 따라 이 테인트를 추가하거나 제거한다.

node.kubernetes.io/unreachable

예시: node.kubernetes.io/unreachable:NoExecute

노드 컨트롤러는 노드 컨디션이 Ready에서 Unknown으로 변경된 노드에 이 테인트를 추가한다.

node.kubernetes.io/unschedulable

예시: node.kubernetes.io/unschedulable:NoSchedule

경쟁 상태(race condition) 발생을 막기 위해, 생성 중인 노드에 이 테인트가 추가된다.

node.kubernetes.io/memory-pressure

예시: node.kubernetes.io/memory-pressure:NoSchedule

kubelet은 노드의 memory.available와 allocatableMemory.available을 관측하여 메모리 압박을 감지한다. 그 뒤, 관측한 값을 kubelet에 설정된 문턱값(threshold)과 비교하여 노드 컨디션과 테인트의 추가/삭제 여부를 결정한다.

node.kubernetes.io/disk-pressure

예시: node.kubernetes.io/disk-pressure:NoSchedule

kubelet은 노드의 imagefs.available, imagefs.inodesFree, nodefs.available, nodefs.inodesFree(리눅스에 대해서만)를 관측하여 디스크 압박을 감지한다. 그 뒤, 관측한 값을 kubelet에 설정된 문턱값(threshold)과 비교하여 노드 컨디션과 테인트의 추가/삭제 여부를 결정한다.

node.kubernetes.io/network-unavailable

예시: node.kubernetes.io/network-unavailable:NoSchedule

사용 중인 클라우드 공급자가 추가 네트워크 환경설정을 필요로 한다고 명시하면, kubelet이 이 테인트를 설정한다. 클라우드 상의 네트워크 경로가 올바르게 구성되어야, 클라우드 공급자가 이 테인트를 제거할 것이다.

node.kubernetes.io/pid-pressure

예시: node.kubernetes.io/pid-pressure:NoSchedule

kubelet은 '/proc/sys/kernel/pid_max의 크기의 D-값'과 노드에서 쿠버네티스가 사용 중인 PID를 확인하여, pid.available 지표라고 불리는 '사용 가능한 PID 수'를 가져온다. 그 뒤, 관측한 지표를 kubelet에 설정된 문턱값(threshold)과 비교하여 노드 컨디션과 테인트의 추가/삭제 여부를 결정한다.

node.kubernetes.io/out-of-service

예시: node.kubernetes.io/out-of-service:NoExecute

사용자는 노드에 테인트를 수동으로 추가함으로써 서비스 중이 아니라고 표시할 수 있다. 만약 NodeOutOfServiceVolumeDetach 기능 게이트가 kube-controller-manager에 활성화되어 있으며 노드가 이 테인트로 인해 서비스 중이 아니라고 표시되어있을 경우, 노드에서 실행되던 매칭되는 톨러레이션이 없는 파드들은 강제로 삭제됨과 동시에 볼륨이 분리된다. 이는 서비스 중이 아닌 노드의 파드들이 다른 노드에서 빠르게 복구될 수 있도록 해준다.

node.cloudprovider.kubernetes.io/uninitialized

예시: node.cloudprovider.kubernetes.io/uninitialized:NoSchedule

kubelet이 "외부" 클라우드 공급자에 의해 실행되었다면 노드가 '사용 불가능'한 상태라고 표시하기 위해 이 테인트가 추가되며, 추후 cloud-controller-manager가 이 노드를 초기화하고 이 테인트를 제거한다.

node.cloudprovider.kubernetes.io/shutdown

예시: node.cloudprovider.kubernetes.io/shutdown:NoSchedule

노드의 상태가 클라우드 공급자가 정의한 'shutdown' 상태이면, 이에 따라 노드에 node.cloudprovider.kubernetes.io/shutdown 테인트가 NoSchedule 값으로 설정된다.

pod-security.kubernetes.io/enforce

예시: pod-security.kubernetes.io/enforce: baseline

적용 대상: 네임스페이스

값은 반드시 파드 보안 표준 레벨과 상응하는 privileged, baseline, 또는 restricted 중 하나여야 한다. 특히 enforce 레이블은 표시된 수준에 정의된 요구 사항을 충족하지 않는 레이블 네임스페이스에 모든 파드의 생성을 금지한다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

pod-security.kubernetes.io/enforce-version

예시: pod-security.kubernetes.io/enforce-version: 1.29

적용 대상: 네임스페이스

값은 반드시 latest이거나 v<MAJOR>.<MINOR> 형식의 유효한 쿠버네티스 버전이어야 한다. 설정된 파드의 유효성을 검사할 때 적용할 파드 보안 표준 정책의 버전이 결정된다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

pod-security.kubernetes.io/audit

예시: pod-security.kubernetes.io/audit: baseline

적용 대상: 네임스페이스

값은 반드시 파드 보안 표준 레벨과 상응하는 privileged, baseline, 또는 restricted 중 하나여야 한다. 특히 audit 레이블은 표시된 수준에 정의된 요구 사항을 충족하지 않는 레이블 네임스페이스에 파드를 생성하는 것을 방지하지 않지만, 해당 파드에 audit 어노테이션을 추가한다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

pod-security.kubernetes.io/audit-version

예시: pod-security.kubernetes.io/audit-version: 1.29

적용 대상: 네임스페이스

값은 반드시 latest이거나 v<MAJOR>.<MINOR> 형식의 유효한 쿠버네티스 버전이어야 한다. 설정된 파드의 유효성을 검사할 때 적용할 파드 보안 표준 정책의 버전이 결정된다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

pod-security.kubernetes.io/warn

예시: pod-security.kubernetes.io/warn: baseline

적용 대상: 네임스페이스

값은 반드시 파드 보안 표준 레벨과 상응하는 privileged, baseline, 또는 restricted 중 하나여야 한다. 특히 warn 레이블은 해당 레이블이 달린 네임스페이스에, 표시된 레벨에 명시된 요구 사항을 충족하지 않는 파드를 생성하는 것을 방지하지는 않지만, 그러한 파드가 생성되면 사용자에게 경고를 반환한다. 디플로이먼트, 잡, 스테이트풀셋 등과 같은 파드 템플릿을 포함하는 객체를 만들거나 업데이트할 때에도 경고가 표시된다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

pod-security.kubernetes.io/warn-version

예시: pod-security.kubernetes.io/warn-version: 1.29

적용 대상: 네임스페이스

값은 반드시 latest이거나 v<MAJOR>.<MINOR> 형식의 유효한 쿠버네티스 버전이어야 한다. 설정된 파드의 유효성을 검사할 때 적용할 파드 보안 표준 정책의 버전이 결정된다. 디플로이먼트, 잡, 스테이트풀셋 등과 같은 파드 템플릿을 포함하는 객체를 만들거나 업데이트할 때에도 경고가 표시된다.

더 많은 정보는 네임스페이스에서 파드 보안 적용을 참고한다.

kubernetes.io/psp (사용 중단됨)

예시: kubernetes.io/psp: restricted

적용 대상: 파드

이 어노테이션은 파드시큐리티폴리시(PodSecurityPolicy)PodSecurityPolicies를 사용하는 경우에만 관련이 있다. 쿠버네티스 v1.29은 파드시큐리티폴리시 API를 지원하지 않는다.

파드시큐리티폴리시 어드미션 컨트롤러가 파드를 승인했을 때, 어드미션 컨트롤러는 파드가 이 어노테이션을 갖도록 수정했다. 이 어노테이션 값은 유효성 검사에서 사용된 파드시큐리티폴리시의 이름이었다.

seccomp.security.alpha.kubernetes.io/pod (사용 중단됨)

이 어노테이션은 쿠버네티스 v1.19부터 사용 중단되었으며 향후 릴리스에서는 작동하지 않을 것이다. 대신 해당 파드 또는 컨테이너의 securityContext.seccompProfile 필드를 사용한다. 파드의 보안 설정을 지정하려면, 파드 스펙에 securityContext 필드를 추가한다. 파드의 .spec 내의 securityContext 필드는 파드 수준 보안 속성을 정의한다. 파드의 보안 컨텍스트를 설정하면, 해당 설정이 파드 내의 모든 컨테이너에 적용된다.

container.seccomp.security.alpha.kubernetes.io/[이름]

이 어노테이션은 쿠버네티스 v1.19부터 사용 중단되었으며 향후 릴리스에서는 작동하지 않을 것이다. 대신 해당 파드 또는 컨테이너의 securityContext.seccompProfile 필드를 사용한다. seccomp를 이용하여 컨테이너의 syscall 제한하기 튜토리얼에서 seccomp 프로파일을 파드 또는 파드 내 컨테이너에 적용하는 단계를 확인한다. 튜토리얼에서는 쿠버네티스에 seccomp를 설정하기 위해 사용할 수 있는 방법을 소개하며, 이는 파드의 .spec 내에 securityContext 를 설정함으로써 가능하다.

snapshot.storage.kubernetes.io/allowVolumeModeChange

예시: snapshot.storage.kubernetes.io/allowVolumeModeChange: "true"

적용 대상: VolumeSnapshotContent

값은 true 혹은 false만을 받는다. 퍼시스턴트볼륨클레임이 볼륨스냅샷(VolumeSnapshot)으로부터 생성될 경우, 사용자가 소스 볼륨의 모드를 수정할 수 있는지 여부를 결정한다.

자세한 사항은 스냅샷의 볼륨 모드 변환하기와 쿠버네티스 CSI 개발자용 문서를 참조한다.

Audit을 위한 어노테이션들

• authorization.k8s.io/decision
• authorization.k8s.io/reason
• insecure-sha1.invalid-cert.kubernetes.io/$hostname
• missing-san.invalid-cert.kubernetes.io/$hostname
• pod-security.kubernetes.io/audit-violations
• pod-security.kubernetes.io/enforce-policy
• pod-security.kubernetes.io/exempt

자세한 사항은 Audit 어노테이션 페이지를 참고한다.

kubeadm

kubeadm.alpha.kubernetes.io/cri-socket

예시: kubeadm.alpha.kubernetes.io/cri-socket: unix:///run/containerd/container.sock

적용 대상: 노드

kubeadm init/join시 주어지는 CRI 소켓 정보를 유지하기 위해 사용하는 어노테이션. kubeadm은 노드 오브젝트를 이 정보를 주석 처리한다. 이상적으로는 KubeletConfiguration의 항목이어야 하기 때문에, 어노테이션은 "alpha" 상태로 남아있다.

kubeadm.kubernetes.io/etcd.advertise-client-urls

예시: kubeadm.kubernetes.io/etcd.advertise-client-urls: https://172.17.0.18:2379

적용 대상: 파드

etcd 클라이언트들이 접근할 수 있는 URL 목록을 추적하기 위해, 로컬에서 관리되는 etcd 파드에 배치되는 어노테이션. 주로 etcd 클러스터의 헬스 체크에 사용한다.

kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint

예시: kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint: https://172.17.0.18:6443

적용 대상: 파드

외부로 노출시킬 API 서버의 엔드포인트를 추적하기 위해, 로컬에서 관리되는 kube-apiserver 파드에 배치되는 어노테이션.

kubeadm.kubernetes.io/component-config.hash

예시: kubeadm.kubernetes.io/component-config.hash: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae

적용 대상: 컨피그맵(ConfigMap)

컴포넌트 설정을 관리하는 컨피그맵에 배치되는 어노테이션. 사용자가 특정 컴포넌트에 대해서 kubeadm 기본값과 다른 설정값을 적용했는지 판단하기 위한 해시(SHA-256)를 가지고 있다.

node-role.kubernetes.io/control-plane

적용 대상: 노드

kubeadm이 관리하는 컨트롤 플레인 노드에 적용되는 레이블.

node-role.kubernetes.io/control-plane

예시: node-role.kubernetes.io/control-plane:NoSchedule

적용 대상: 노드

중요한 워크로드만 스케줄링할 수 있도록 컨트롤 플레인 노드에 적용시키는 테인트.

node-role.kubernetes.io/master (사용 중단)

적용 대상: Node

예시: node-role.kubernetes.io/master:NoSchedule

이전 버전에서 kubeadm이 컨트롤 플레인에 중요한 워크로드만 스케줄링하기 위해 적용했던 테인트. node-role.kubernetes.io/control-plane로 대체되었다. kubeadm은 더 이상 해당 테인트를 설정하거나 사용하지 않는다.

5 - 노드 메트릭 데이터

kubelet은 노드, 볼륨, 파드, 컨테이너 수준의 통계를 수집하며, 이 통계를 요약 API(Summary API)에 기록한다.

통계 요약 API에 대한 요청을 쿠버네티스 API 서버를 통해 프록시하여 전송할 수 있다.

다음은 minikube라는 이름의 노드에 대한 요약 API 요청 예시이다.

kubectl get --raw "/api/v1/nodes/minikube/proxy/stats/summary"

다음은 curl을 이용하여 동일한 API 호출을 하는 명령어다.

# 먼저 "kubectl proxy"를 실행해야 한다.
# 8080 부분을 "kubectl proxy" 명령이 할당해 준 포트로 치환한다.
curl http://localhost:8080/api/v1/nodes/minikube/proxy/stats/summary

요약 메트릭 API 소스

기본적으로, 쿠버네티스는 kubelet 내부에서 실행되는 내장 cAdvisor를 사용하여 노드 요약 메트릭 데이터를 가져온다.

CRI를 통해 요약 API 데이터 가져오기

클러스터에 PodAndContainerStatsFromCRI 기능 게이트를 활성화하고, 컨테이너 런타임 인터페이스(CRI)를 통한 통계 정보 접근을 지원하는 컨테이너 런타임을 사용하는 경우, kubelet은 cAdvisor가 아닌 CRI를 사용하여 파드 및 컨테이너 수준의 메트릭 데이터를 가져온다.

다음 내용

클러스터 트러블슈팅하기 태스크 페이지에서 이러한 데이터에 의존하는 메트릭 파이프라인을 사용하는 방법에 대해 다룬다.

6 - 쿠버네티스 이슈와 보안

6.1 - 쿠버네티스 이슈 트래커

보안 문제를 보고하려면 쿠버네티스 보안 공개 프로세스를 따른다.

쿠버네티스 코드 작업 및 공개 이슈는 깃허브 이슈를 사용하여 추적된다.

• [잘 알려진 CVE에 대한] 공식 리스트(/docs/reference/issues-security/official-cve-feed/) 보안 대응 위원회(Security Response Committee) 가 발표한 (보안 취약점)
• CVE-연관된 깃허브 이슈들

보안에 관련된 공지사항은 kubernetes-security-announce@googlegroups.com 메일 리스트로 전송된다.

6.2 - 쿠버네티스 보안과 공개 정보

이 페이지는 쿠버네티스 보안 및 공개 정보를 설명한다.

보안 공지

보안 및 주요 API 공지에 대한 이메일을 위해서는 kubernetes-security-announce) 그룹에 가입한다.

취약점 보고

우리는 쿠버네티스 오픈소스 커뮤니티에 취약점을 보고하는 보안 연구원들과 사용자들에게 매우 감사하고 있다. 모든 보고서는 커뮤니티 자원 봉사자들에 의해 철저히 조사된다.

보고서를 작성하려면, 쿠버네티스 버그 현상금 프로그램에 취약점을 제출한다. 이를 통해 표준화된 응답시간으로 취약점을 분류하고 처리할 수 있다.

또한, 보안 세부 내용과 모든 쿠버네티스 버그 보고서로 부터 예상되는 세부사항을 security@kubernetes.io로 이메일을 보낸다.

보안 대응 위원회(Security Response Committee) 구성원의 GPG 키를 사용하여 이 목록으로 이메일을 암호화할 수 있다. GPG를 사용한 암호화는 공개할 필요가 없다.

언제 취약점을 보고해야 하는가?

• 쿠버네티스에서 잠재적인 보안 취약점을 발견했다고 생각하는 경우
• 취약성이 쿠버네티스에 어떤 영향을 미치는지 확신할 수 없는 경우
• 쿠버네티스가 의존하는 다른 프로젝트에서 취약점을 발견한 경우
  • 자체 취약성 보고 및 공개 프로세스가 있는 프로젝트의 경우 직접 보고한다.

언제 취약점을 보고하지 말아야 하는가?

• 보안을 위해 쿠버네티스 구성요소를 조정하는데 도움이 필요한 경우
• 보안 관련 업데이트를 적용하는 데 도움이 필요한 경우
• 보안 관련 문제가 아닌 경우

보안 취약점 대응

각 보고서는 보안 대응 위원회 위원들에 의해 작업일 3일 이내에 인정되고 분석된다. 이렇게 하면 보안 릴리스 프로세스가 시작된다.

보안 대응 위원회와 공유하는 모든 취약성 정보는 쿠버네티스 프로젝트 내에 있으며, 문제를 해결할 필요가 없는 한 다른 프로젝트에 전파되지 않는다.

보안 문제가 심사에서 확인된 수정, 릴리스 계획으로 이동함에 따라 리포터를 계속 업데이트할 것이다.

공개 시기

공개 날짜는 쿠버네티스 보안 대응 위원회와 버그 제출자가 협상한다. 사용자 완화가 가능해지면 가능한 빨리 버그를 완전히 공개하는 것이 좋다. 버그 또는 픽스가 아직 완전히 이해되지 않았거나 솔루션이 제대로 테스트되지 않았거나 벤더 협력을 위해 공개를 지연시키는 것이 합리적이다. 공개 기간은 즉시(특히 이미 공개적으로 알려진 경우)부터 몇 주까지다. 간단한 완화 기능이 있는 취약점의 경우 보고 날짜부터 공개 날짜까지는 7일 정도 소요될 것으로 예상된다. 쿠버네티스 보안 대응 위원회는 공개 날짜를 설정할 때 최종 결정권을 갖는다.

7 - 노드 레퍼런스 정보

이 섹션에서는 노드에 관한 다음의 레퍼런스 주제를 다룬다.

• kubelet의 체크포인트 API
• 도커심 제거 및 CRI 호환 런타임 사용에 대한 글 목록

다음과 같은 다른 쿠버네티스 문서에서도 노드 레퍼런스 상세에 대해 읽어볼 수 있다.

• 노드 메트릭 데이터.

7.1 - kubelet 체크포인트 API

컨테이너 체크포인트는 실행 중인 컨테이너의 스테이트풀(stateful) 복사본을 생성하는 기능이다. 컨테이너의 스테이트풀 복사본이 있으면, 디버깅 또는 다른 목적을 위해 이를 다른 컴퓨터로 이동할 수 있다.

체크포인트 컨테이너 데이터를 복원할 수 있는 컴퓨터로 이동하면, 복원된 컨테이너는 체크포인트된 지점과 정확히 동일한 지점에서 계속 실행된다. 적절한 도구가 있다면, 저장된 데이터를 검사해 볼 수도 있다.

컨테이너 체크포인트 생성 시에는 유의해야 할 보안 사항이 있다. 일반적으로 각 체크포인트는 체크포인트된 컨테이너의 모든 프로세스의 메모리 페이지를 포함한다. 이는 곧 메모리에 있던 모든 데이터가 로컬 디스크에 저장되어 열람이 가능함을 의미한다. 이 아카이브(archive)에는 모든 개인 데이터와 암호화 키가 포함된다. 따라서, 내부 CRI 구현체(노드의 컨테이너 런타임)는 체크포인트 아카이브를 생성 시 root 사용자만 액세스 가능하도록 처리해야 한다. 그럼에도 여전히 주의가 필요한데, 체크포인트 아카이브를 다른 시스템으로 전송하게 되면 해당 시스템의 체크포인트 아카이브 소유자가 모든 메모리 페이지를 읽을 수 있기 때문이다.

운영

POST 특정 컨테이너의 체크포인트 생성

지정된 파드의 특정 컨테이너를 체크포인트하도록 kubelet에 지시한다.

kubelet 체크포인트 인터페이스로의 접근이 어떻게 제어되는지에 대한 자세한 내용은 Kubelet 인증/인가 레퍼런스 를 참고한다.

kubelet은 내부 CRI 구현체에 체크포인트를 요청한다. 체크포인트 요청 시, kubelet은 체크포인트 아카이브의 이름을 checkpoint-<podFullName>-<containerName>-<timestamp>.tar로 지정하고 루트 디렉토리(--root-dir 로 지정 가능) 아래의 checkpoints 디렉토리에 체크포인트 아카이브를 저장하도록 요청한다. 기본값은 /var/lib/kubelet/checkpoints이다.

체크포인트 아카이브는 tar 형식이며 tar 유틸리티를 사용하여 조회해 볼 수 있다. 아카이브의 내용은 내부 CRI 구현체(노드의 컨테이너 런타임)에 따라 다르다.

HTTP 요청

POST /checkpoint/{namespace}/{pod}/{container}

파라미터

• namespace (경로 내 파라미터): 문자열(string), 필수

  네임스페이스(Namespace)

• pod (경로 내 파라미터): 문자열(string), 필수

  파드(Pod)

• container (경로 내 파라미터): 문자열(string), 필수

  컨테이너(Container)

• timeout (쿼리 파라미터): 정수(integer)

  체크포인트 생성이 완료될 때까지 대기할 시간제한(초)이다. 시간 제한이 0 또는 지정되지 않은 경우 기본 CRI 시간 제한 값이 사용될 것이다. 체크포인트 생성 시간은 컨테이너가 사용하고 있는 메모리에 따라 다르다. 컨테이너가 사용하는 메모리가 많을수록 해당 체크포인트를 생성하는 데 더 많은 시간이 필요하다.

응답

200: OK

401: Unauthorized

404: Not Found (ContainerCheckpoint 기능 게이트가 비활성화된 경우)

404: Not Found (명시한 namespace, pod 또는 container를 찾을 수 없는 경우)

500: Internal Server Error (CRI 구현체가 체크포인트를 수행하는 중에 오류가 발생한 경우 (자세한 내용은 오류 메시지를 확인한다.))

500: Internal Server Error (CRI 구현체가 체크포인트 CRI API를 구현하지 않은 경우 (자세한 내용은 오류 메시지를 확인한다.))

7.2 - 도커심 제거 및 CRI 호환 런타임 사용에 대한 기사

이 문서는 쿠버네티스의 도커심 사용 중단(deprecation) 및 제거, 또는 해당 제거를 고려한 CRI 호환 컨테이너 런타임 사용에 관한 기사 및 기타 페이지 목록을 제공한다.

쿠버네티스 프로젝트

• 쿠버네티스 블로그: 도커심 제거 FAQ (originally published 2020/12/02)

• 쿠버네티스 블로그: 업데이트: 도커심 제거 FAQ (updated published 2022/02/17)

• 쿠버네티스 블로그: 도커심에서 움직이는 쿠버네티스: 약속과 다음 단계 (published 2022/01/07)

• 쿠버네티스 블로그: 도커심 제거가 다가오고 있다. 준비됐는가? (published 2021/11/12)

• 쿠버네티스 문서: 도커심에서 마이그레이션하기

• 쿠버네티스 문서: 컨테이너 런타임

• 쿠버네티스 개선 제안 이슈: KEP-2221: kubelet에서 도커심 제거하기

• 쿠버네티스 개선 제안 이슈: kubelet에서 도커심 제거하기 (k/enhancements#2221)

GitHub 이슈를 통해 피드백을 제공할 수 있다. 도커심 제거 피드백 및 이슈. (k/kubernetes/#106917)

외부 소스

• 아마존 웹 서비스 EKS 문서: 아마존 EKS 도커심 지원 종료

• CNCF 컨퍼런스 영상: 도커에서 containerd 런타임으로 마이그레이션하며 얻은 교훈 (Ana Caylin, at KubeCon Europe 2019)

• 도커닷컴 블로그: 개발자가 도커, 도커 엔진 및 쿠버네티스 v1.20에 관해 알아야 할 사항 (published 2020/12/04)

• "구글 오픈소스" 유튜브 채널: 구글과 함께 쿠버네티스 배우기 - 도커심에서 containerd로 마이그레이션하기

• Azure의 Microsoft 앱 블로그: 도커심 지원 중단 및 AKS (published 2022/01/21)

• Mirantis 블로그: 도커심의 미래는 cri-dockerd (published 2021/04/21)

• Mirantis: Mirantis/cri-dockerd Git 리포지터리 (깃허브)

• Tripwire: 곧 다가올 도커심의 지원 중단이 당신의 쿠버네티스에 미칠 영향 (published 2021/07/01)

8 - 네트워킹 레퍼런스

이 섹션에서는 쿠버네티스 네트워킹의 레퍼런스 상세를 제공한다.

8.1 - 서비스가 지원하는 프로토콜

서비스를 구성하여, 쿠버네티스가 지원하는 네트워크 프로토콜 중 하나를 선택할 수 있다.

쿠버네티스는 서비스에 대해 다음의 프로토콜을 지원한다.

• SCTP
• TCP (기본값)
• UDP

서비스를 정의할 때, 서비스가 사용할 애플리케이션 프로토콜을 지정할 수도 있다.

이 문서에서는 몇 가지 특수 사례에 대해 설명하며, 이들 모두는 일반적으로 전송 프로토콜(transport protocol)로 TCP를 사용한다.

• HTTP 및 HTTPS
• PROXY 프로토콜
• 로드밸런서에서의 TLS 터미네이션

지원하는 프로토콜

서비스 포트의 protocol에 대해 다음 3개의 값이 유효하다.

SCTP

SCTP 트래픽을 지원하는 네트워크 플러그인을 사용하는 경우, 대부분의 서비스에 SCTP를 사용할 수 있다. type: LoadBalancer 서비스의 경우 SCTP 지원 여부는 이 기능을 제공하는 클라우드 공급자에 따라 다르다. (대부분 지원하지 않음)

SCTP는 윈도우 노드에서는 지원되지 않는다.

멀티홈(multihomed) SCTP 연결 지원

멀티홈 SCTP 연결 지원을 위해서는 CNI 플러그인이 파드에 복수개의 인터페이스 및 IP 주소를 할당하는 기능을 지원해야 한다.

멀티홈 SCTP 연결에서의 NAT는 상응하는 커널 모듈 내의 특수한 로직을 필요로 한다.

TCP

모든 종류의 서비스에 TCP를 사용할 수 있으며, 이는 기본 네트워크 프로토콜이다.

UDP

대부분의 서비스에 UDP를 사용할 수 있다. type: LoadBalancer 서비스의 경우, UDP 지원 여부는 이 기능을 제공하는 클라우드 공급자에 따라 다르다.

특수 케이스

HTTP

클라우드 공급자가 이를 지원하는 경우, LoadBalancer 모드의 서비스를 사용하여, 쿠버네티스 클러스터 외부에, HTTP / HTTPS 리버스 프록싱을 통해 해당 서비스의 백엔드 엔드포인트로 트래픽을 전달하는 로드밸런서를 구성할 수 있다.

일반적으로, 트래픽을 HTTP 수준에서 제어하려면 해당 서비스의 프로토콜을 TCP로 지정하고 로드밸런서를 구성하는 어노테이션(보통 클라우드 공급자마다 다름)을 추가한다. 이 구성은 워크로드로의 HTTPS (HTTP over TLS) 지원 및 평문 HTTP 리버스 프록시도 포함할 수 있다.

특정 연결의 애플리케이션 프로토콜을 http 또는 https로 추가적으로 명시하고 싶을 수도 있다. 로드밸런서에서 워크로드로 가는 세션이 HTTP without TLS이면 http를 사용하고, 로드밸런서에서 워크로드로 가는 세션이 TLS 암호화를 사용하면 https를 사용한다.

PROXY 프로토콜

클라우드 공급자가 지원하는 경우에, type: LoadBalancer로 설정된 서비스를 사용하여, 쿠버네티스 외부에 존재하면서 연결들을 PROXY 프로토콜로 감싸 전달하는 로드밸런서를 구성할 수 있다.

이러한 로드 밸런서는 들어오는 연결을 설명하는 초기 일련의 옥텟(octets)을 전송하며, 이는 다음의 예시(PROXY 프로토콜 v1)와 유사하다.

PROXY TCP4 192.0.2.202 10.0.42.7 12345 7\r\n

프록시 프로토콜 프리앰블(preamble) 뒤에 오는 데이터는 클라이언트가 전송한 원본 데이터이다. 양쪽 중 한쪽에서 연결을 닫으면, 로드밸런서도 연결 종료를 트리거하며 남아있는 데이터를 수신 가능한 쪽으로 보낸다.

일반적으로는, 프로토콜을 TCP로 설정한 서비스를 정의한다. 또한, 클라우드 공급자별로 상이한 어노테이션을 설정하여 로드밸런서가 각 인커밍 연결을 PROXY 프로토콜로 감싸도록 구성할 수도 있다.

TLS

클라우드 공급자가 지원하는 경우에, type: LoadBalancer로 설정된 서비스를 사용하여, 쿠버네티스 외부에 존재하는 리버스 프록시를 구축할 수 있으며, 이 때 클라이언트로부터 로드밸런서까지의 연결은 TLS 암호화되고 로드밸런서는 TLS 서버 피어가 된다. 로드밸런서로부터 워크로드까지의 연결은 TLS일 수도 있으며, 평문일 수도 있다. 사용 가능한 정확한 옵션의 범위는 클라우드 공급자 또는 커스텀 서비스 구현에 따라 다를 수 있다.

일반적으로는, 프로토콜을 TCP로 설정하고 어노테이션(보통 클라우드 공급자별로 상이함)을 설정하여 로드밸런서가 TLS 서버로 작동하도록 구성한다. 클라우드 공급자별로 상이한 메커니즘을 사용하여 TLS 아이덴티티(서버, 그리고 경우에 따라 워크로드로 연결하는 클라이언트도 가능)를 구성할 수도 있다.

8.2 - 포트와 프로토콜

물리적 네트워크 방화벽이 있는 온프레미스 데이터 센터 또는 퍼블릭 클라우드의 가상 네트워크와 같이 네트워크 경계가 엄격한 환경에서 쿠버네티스를 실행할 때, 쿠버네티스 구성 요소에서 사용하는 포트와 프로토콜을 알고 있는 것이 유용하다.

컨트롤 플레인

etcd 포트가 컨트롤 플레인 섹션에 포함되어 있지만, 외부 또는 사용자 지정 포트에서 자체 etcd 클러스터를 호스팅할 수도 있다.

워커 노드

† 노드포트(NodePort) 서비스의 기본 포트 범위.

모든 기본 포트 번호를 재정의할 수 있다. 사용자 지정 포트를 사용하는 경우 여기에 언급된 기본값 대신 해당 포트를 열어야 한다.

종종 발생하는 한 가지 일반적인 예는 API 서버 포트를 443으로 변경하는 경우이다. 또는, API 서버의 기본 포트를 그대로 유지하고, 443 포트에서 수신 대기하는 로드 밸런서 뒤에 API 서버를 두고, 로드 밸런서에서 API 서버로 가는 요청을 API 서버의 기본 포트로 라우팅할 수도 있다.

8.3 - 가상 IP 및 서비스 프록시

쿠버네티스 클러스터의 모든 노드는 kube-proxy를 실행한다(kube-proxy를 대체하는 구성요소를 직접 배포한 경우가 아니라면).

kube-proxy는 ExternalName 외의 type의 서비스를 위한 가상 IP 메커니즘의 구현을 담당한다.

항상 발생하는 질문은, 왜 쿠버네티스가 인바운드 트래픽을 백엔드로 전달하기 위해 프록시에 의존하는가 하는 점이다. 다른 접근법이 있는가? 예를 들어, 여러 A 값 (또는 IPv6의 경우 AAAA)을 가진 DNS 레코드를 구성하고, 라운드-로빈 이름 확인 방식을 취할 수 있는가?

There are a few reasons for using proxying for Services:

• 레코드 TTL을 고려하지 않고, 만료된 이름 검색 결과를 캐싱하는 DNS 구현에 대한 오래된 역사가 있다.
• 일부 앱은 DNS 검색을 한 번만 수행하고 결과를 무기한으로 캐시한다.
• 앱과 라이브러리가 적절히 재-확인을 했다고 하더라도, DNS 레코드의 TTL이 낮거나 0이면 DNS에 부하가 높아 관리하기가 어려워질 수 있다.

본 페이지의 뒷 부분에서 다양한 kube-proxy 구현이 동작하는 방식에 대해 읽을 수 있다. 우선 알아두어야 할 것은, kube-proxy를 구동할 때, 커널 수준의 규칙이 수정(예를 들어, iptables 규칙이 생성될 수 있음)될 수 있고, 이는 때로는 리부트 전까지 정리되지 않을 수도 있다. 그래서, kube-proxy는 컴퓨터에서 저수준의, 특권을 가진(privileged) 네트워킹 프록시 서비스가 구동됨으로써 발생하는 결과를 이해하고 있는 관리자에 의해서만 구동되어야 한다. 비록 kube-proxy 실행 파일이 cleanup 기능을 지원하기는 하지만, 이 기능은 공식적인 기능이 아니기 때문에 구현된 그대로만 사용할 수 있다.

예를 들어, 3개의 레플리카로 실행되는 스테이트리스 이미지-처리 백엔드를 생각해보자. 이러한 레플리카는 대체 가능하다. 즉, 프론트엔드는 그것들이 사용하는 백엔드를 신경쓰지 않는다. 백엔드 세트를 구성하는 실제 파드는 변경될 수 있지만, 프론트엔드 클라이언트는 이를 인식할 필요가 없으며, 백엔드 세트 자체를 추적해야 할 필요도 없다.

프록시 모드들

kube-proxy는 여러 모드 중 하나로 기동될 수 있으며, 이는 환경 설정에 따라 결정됨에 유의한다.

• kube-proxy의 구성은 컨피그맵(ConfigMap)을 통해 이루어진다. 그리고 해당 kube-proxy를 위한 컨피그맵은 실효성있게 거의 대부분의 kube-proxy의 플래그의 행위를 더 이상 사용하지 않도록 한다.
• kube-proxy를 위한 해당 컨피그맵은 기동 중 구성의 재적용(live reloading)은 지원하지 않는다.
• kube-proxy를 위한 컨피그맵 파라미터는 기동 시에 검증이나 확인을 하지 않는다. 예를 들어, 운영 체계가 iptables 명령을 허용하지 않을 경우, 표준 커널 kube-proxy 구현체는 작동하지 않을 것이다.

iptables 프록시 모드

이 모드에서는, kube-proxy는 쿠버네티스 컨트롤 플레인의 서비스, 엔드포인트슬라이스 오브젝트의 추가와 제거를 감시한다. 각 서비스에 대해, 서비스의 clusterIP 및 port에 대한 트래픽을 캡처하고 해당 트래픽을 서비스의 백엔드 세트 중 하나로 리다이렉트(redirect)하는 iptables 규칙을 설치한다. 각 엔드포인트 오브젝트에 대해, 백엔드 파드를 선택하는 iptables 규칙을 설치한다.

기본적으로, iptables 모드의 kube-proxy는 백엔드를 임의로 선택한다.

트래픽을 처리하기 위해 iptables를 사용하면 시스템 오버헤드가 줄어드는데, 유저스페이스와 커널 스페이스 사이를 전환할 필요없이 리눅스 넷필터(netfilter)가 트래픽을 처리하기 때문이다. 이 접근 방식은 더 신뢰할 수 있기도 하다.

kube-proxy가 iptables 모드에서 실행 중이고 선택된 첫 번째 파드가 응답하지 않으면, 연결이 실패한다. 이는 이전의 userspace 모드와 다르다. 이전의 userspace 시나리오에서는, kube-proxy는 첫 번째 파드에 대한 연결이 실패했음을 감지하고 다른 백엔드 파드로 자동으로 재시도한다.

파드 준비성 프로브(readiness probe)를 사용하여 백엔드 파드가 제대로 작동하는지 확인할 수 있으므로, iptables 모드의 kube-proxy는 정상으로 테스트된 백엔드만 볼 수 있다. 이렇게 하면 트래픽이 kube-proxy를 통해 실패한 것으로 알려진 파드로 전송되는 것을 막을 수 있다.

예시

다시 한번, 위에서 설명한 이미지 처리 애플리케이션을 고려한다. 백엔드 서비스가 생성되면, 쿠버네티스 컨트롤 플레인은 가상 IP 주소(예 : 10.0.0.1)를 할당한다. 서비스 포트를 1234라고 가정하자. 클러스터의 모든 kube-proxy 인스턴스는 새 서비스의 생성을 관찰할 수 있다.

프록시가 새로운 서비스를 발견하면, 가상 IP 주소에서 서비스-별 규칙으로 리다이렉션되는 일련의 iptables 규칙을 설치한다. 서비스-별 규칙은 트래픽을 (목적지 NAT를 사용하여) 백엔드로 리다이렉션하는 엔드포인트-별 규칙에 연결한다.

클라이언트가 서비스의 가상 IP 주소에 연결하면 iptables 규칙이 시작한다. (세션 어피니티(Affinity)에 따라 또는 무작위로) 백엔드가 선택되고, 패킷의 클라이언트 IP 주소를 덮어쓰지 않고 백엔드로 리다이렉션된다.

트래픽이 노드-포트 또는 로드 밸런서를 통해 들어오는 경우에도, 이와 동일한 기본 흐름이 실행되지만, 클라이언트 IP는 변경된다.

IPVS 프록시 모드

ipvs 모드에서, kube-proxy는 쿠버네티스 서비스와 엔드포인트슬라이스를 감시하고, netlink 인터페이스를 호출하여 그에 따라 IPVS 규칙을 생성하고 IPVS 규칙을 쿠버네티스 서비스 및 엔드포인트슬라이스와 주기적으로 동기화한다. 이 제어 루프는 IPVS 상태가 원하는 상태와 일치하도록 보장한다. 서비스에 접근하면, IPVS는 트래픽을 백엔드 파드 중 하나로 보낸다.

IPVS 프록시 모드는 iptables 모드와 유사한 넷필터 후크 기능을 기반으로 하지만, 해시 테이블을 기본 데이터 구조로 사용하고 커널 스페이스에서 동작한다. 이는 IPVS 모드의 kube-proxy는 iptables 모드의 kube-proxy보다 지연 시간이 짧은 트래픽을 리다이렉션하고, 프록시 규칙을 동기화할 때 성능이 훨씬 향상됨을 의미한다. 다른 프록시 모드와 비교했을 때, IPVS 모드는 높은 네트워크 트래픽 처리량도 지원한다.

IPVS는 트래픽을 백엔드 파드로 밸런싱하기 위한 추가 옵션을 제공하며, 그 목록은 다음과 같다.

• rr: 라운드-로빈
• lc: 최소 연결 (가장 적은 수의 열려있는 연결)
• dh: 목적지 해싱
• sh: 소스 해싱
• sed: 최단 예상 지연 (shortest expected delay)
• nq: 큐 미사용 (never queue)

세션 어피니티

이러한 프록시 모델에서, 클라이언트가 쿠버네티스/서비스/파드에 대해 전혀 모르더라도 서비스의 IP:포트로 향하는 트래픽은 적절한 백엔드로 프록시된다.

특정 클라이언트의 연결이 매번 동일한 파드로 전달되도록 하려면, 서비스의 .spec.sessionAffinity를 ClientIP로 설정하여 클라이언트의 IP 주소를 기반으로 세션 어피니티를 선택할 수 있다. (기본값은 None)

세션 고정(Session stickiness) 타임아웃

서비스의 .spec.sessionAffinityConfig.clientIP.timeoutSeconds를 적절히 설정하여 최대 세션 고정 시간을 설정할 수도 있다. (기본값은 10800으로, 이는 3시간에 해당됨)

서비스에 IP 주소 할당

고정된 목적지로 실제로 라우팅되는 파드 IP 주소와 달리, 서비스 IP는 실제로는 단일 호스트에서 응답하지 않는다. 대신에, kube-proxy는 패킷 처리 로직(예: 리눅스의 iptables)을 사용하여, 필요에 따라 투명하게 리다이렉션되는 가상 IP 주소를 정의한다.

클라이언트가 VIP에 연결하면, 트래픽이 자동으로 적절한 엔드포인트로 전송된다. 환경 변수와 서비스 용 DNS는 실제로는 서비스의 가상 IP 주소 (및 포트)로 채워진다.

충돌 방지하기

쿠버네티스의 주요 철학 중 하나는, 사용자가 잘못한 것이 없는 경우에는 실패할 수 있는 상황에 노출되어서는 안된다는 것이다. 서비스 리소스 설계 시, 다른 사람의 포트 선택과 충돌할 경우에 대비해 자신의 포트 번호를 선택하지 않아도 된다. 만약 그러한 일이 발생한다면 그것은 격리 실패이다.

서비스에 대한 포트 번호를 사용자가 선택할 수 있도록 하려면, 두 개의 서비스가 충돌하지 않도록 해야 한다. 쿠버네티스는 API 서버에 설정되어 있는 service-cluster-ip-range CIDR 범위에서 각 서비스에 고유한 IP 주소를 할당하여 이를 달성한다.

각 서비스가 고유한 IP를 받도록 하기 위해, 각 서비스를 만들기 전에 내부 할당기가 etcd에서 글로벌 할당 맵을 원자적으로(atomically) 업데이트한다. 서비스가 IP 주소 할당을 가져오려면 레지스트리에 맵 오브젝트가 있어야 하는데, 그렇지 않으면 IP 주소를 할당할 수 없다는 메시지와 함께 생성에 실패한다.

컨트롤 플레인에서, 백그라운드 컨트롤러는 해당 맵을 생성해야 한다(인-메모리 잠금을 사용하는 이전 버전의 쿠버네티스에서의 마이그레이션 지원을 위해 필요함). 쿠버네티스는 또한 컨트롤러를 사용하여 유효하지 않은 할당(예: 관리자 개입에 의한)을 체크하고 더 이상 어떠한 서비스도 사용하지 않는 할당된 IP 주소를 정리한다.

서비스 가상 IP 주소의 IP 주소 범위

쿠버네티스는 min(max(16, cidrSize / 16), 256) 공식을 사용하여 얻어진 service-cluster-ip-range의 크기에 기반하여 ClusterIP 범위를 두 대역으로 나누며, 여기서 이 공식은 16 이상 256 이하이며, 그 사이에 계단 함수가 있음 으로 설명할 수 있다.

쿠버네티스는 서비스에 대한 동적 IP 할당 시 상위 대역에서 우선적으로 선택하며, 이는 곧 만약 사용자가 type: ClusterIP 서비스에 특정 IP 주소를 할당하고 싶다면 하위 대역에서 골라야 함을 의미한다. 이렇게 함으로써 할당 시 충돌의 위험을 줄일 수 있다.

만약 ServiceIPStaticSubrange 기능 게이트를 비활성화하면 쿠버네티스는 type: ClusterIP 서비스에 대해 수동 및 동적 할당 IP 주소를 위한 하나의 공유되는 풀을 사용한다.

트래픽 폴리시

.spec.internalTrafficPolicy 및 .spec.externalTrafficPolicy 필드를 설정하여 쿠버네티스가 트래픽을 어떻게 정상(healthy, “ready”) 백엔드로 라우팅할지를 제어할 수 있다.

내부 트래픽 폴리시

spec.internalTrafficPolicy 필드를 설정하여 내부 소스에서 오는 트래픽이 어떻게 라우트될지를 제어할 수 있다. 이 필드는 Cluster 또는 Local로 설정할 수 있다. 필드를 Cluster로 설정하면 내부 트래픽을 준비 상태의 모든 엔드포인트로 라우트하며, Local로 설정하면 준비 상태의 노드-로컬 엔드포인트로만 라우트한다. 만약 트래픽 정책이 Local로 설정되어 있는데 노드-로컬 엔드포인트가 하나도 없는 경우, kube-proxy는 트래픽을 드롭시킨다.

외부 트래픽 폴리시

spec.externalTrafficPolicy 필드를 설정하여 외부 소스에서 오는 트래픽이 어떻게 라우트될지를 제어할 수 있다. 이 필드는 Cluster 또는 Local로 설정할 수 있다. 필드를 Cluster로 설정하면 외부 트래픽을 준비 상태의 모든 엔드포인트로 라우트하며, Local로 설정하면 준비 상태의 노드-로컬 엔드포인트로만 라우트한다. 만약 트래픽 정책이 Local로 설정되어 있는데 노드-로컬 엔드포인트가 하나도 없는 경우, kube-proxy는 연관된 서비스로의 트래픽을 포워드하지 않는다.

종료 중인 엔드포인트로 가는 트래픽

kube-proxy에 대해 ProxyTerminatingEndpoints 기능 게이트가 활성화되어 있고 트래픽 폴리시가 Local이면, 해당 노드의 kube-proxy는 서비스에 대한 엔드포인트를 선택할 때 좀 더 복잡한 알고리즘을 사용한다. 이 기능이 활성화되어 있으면, kube-proxy는 노드가 로컬 엔드포인트를 갖고 있는지, 그리고 모든 로컬 엔드포인트가 '종료 중'으로 표시되어 있는지 여부를 확인한다. 만약 로컬 엔드포인트가 존재하고 모든 로컬 엔드포인트가 종료 중이면, kube-proxy는 종료 중인 해당 엔드포인트로 트래픽을 전달한다. 이외의 경우, kube-proxy는 종료 중이 아닌 엔드포인트로 트래픽을 전달하는 편을 선호한다.

종료 중인 엔드포인트에 대한 이러한 포워딩 정책 덕분에, externalTrafficPolicy: Local을 사용하는 경우에 NodePort 및 LoadBalancer 서비스가 연결들을 자비롭게(gracefully) 종료시킬 수 있다.

디플로이먼트가 롤링 업데이트될 때, 로드밸런서 뒤에 있는 노드가 해당 디플로이먼트의 레플리카를 N개에서 0개 갖도록 변경될 수 있다. 일부 경우에, 외부 로드 밸런서가 헬스 체크 프로브 사이의 기간에 레플리카 0개를 갖는 노드로 트래픽을 전송할 수 있다. 종료 중인 엔드포인트로의 트래픽 라우팅 기능을 통해 파드를 스케일 다운 중인 노드가 해당 종료 중인 파드로의 트래픽을 자비롭게 수신 및 드레인할 수 있다. 파드 종료가 완료되면, 외부 로드 밸런서는 이미 노드의 헬스 체크가 실패했음을 확인하고 해당 노드를 백엔드 풀에서 완전히 제거했을 것이다.

다음 내용

서비스에 대해 더 알아보려면, 서비스와 애플리케이션 연결을 읽어 본다.

또한,

• 서비스에 대해 읽어 본다.
• 서비스 API에 대한 API 레퍼런스를 읽어 본다.

9 - 설치 도구

9.1 - Kubeadm

Kubeadm은 쿠버네티스 클러스터 생성을 위한 "빠른 경로"의 모범 사례로 kubeadm init 및 kubeadm join 을 제공하도록 만들어진 도구이다.

kubeadm은 실행 가능한 최소 클러스터를 시작하고 실행하는 데 필요한 작업을 수행한다. 설계 상, 시스템 프로비저닝이 아닌 부트스트랩(bootstrapping)만 다룬다. 마찬가지로, 쿠버네티스 대시보드, 모니터링 솔루션 및 클라우드별 애드온과 같은 다양한 있으면 좋은(nice-to-have) 애드온을 설치하는 것은 범위에 포함되지 않는다.

대신, 우리는 더 높은 수준의 맞춤형 도구가 kubeadm 위에 구축될 것으로 기대하며, 이상적으로는, 모든 배포의 기반으로 kubeadm을 사용하면 규격을 따르는 클러스터를 더 쉽게 생성할 수 있다.

설치 방법

kubeadm을 설치하려면, 설치 가이드를 참고한다.

다음 내용

• kubeadm init: 쿠버네티스 컨트롤 플레인 노드를 부트스트랩한다.
• kubeadm join: 쿠버네티스 워커(worker) 노드를 부트스트랩하고 클러스터에 조인시킨다.
• kubeadm upgrade: 쿠버네티스 클러스터를 새로운 버전으로 업그레이드한다.
• kubeadm config: kubeadm v1.7.x 이하의 버전을 사용하여 클러스터를 초기화한 경우, kubeadm upgrade 를 위해 사용자의 클러스터를 구성한다.
• kubeadm token: kubeadm join 을 위한 토큰을 관리한다.
• kubeadm reset: kubeadm init 또는 kubeadm join 에 의한 호스트의 모든 변경 사항을 되돌린다.
• kubeadm certs: 쿠버네티스 인증서를 관리한다.
• kubeadm kubeconfig: kubeconfig 파일을 관리한다.
• kubeadm version: kubeadm 버전을 출력한다.
• kubeadm alpha: 커뮤니티에서 피드백을 수집하기 위해서 기능 미리 보기를 제공한다.

9.1.1 - Kubeadm Generated

10 - 명령줄 도구 (kubectl)

쿠버네티스는 다음을 제공한다: 쿠버네티스 API를 사용하여 쿠버네티스 클러스터의 컨트롤 플레인과 통신하기 위한 커맨드라인 툴

이 툴의 이름은 kubectl이다.

구성을 위해, kubectl 은 config 파일을 $HOME/.kube 에서 찾는다. KUBECONFIG 환경 변수를 설정하거나 --kubeconfig 플래그를 설정하여 다른 kubeconfig 파일을 지정할 수 있다.

이 개요는 kubectl 구문을 다루고, 커맨드 동작을 설명하며, 일반적인 예제를 제공한다. 지원되는 모든 플래그 및 하위 명령을 포함한 각 명령에 대한 자세한 내용은 kubectl 참조 문서를 참고한다.

설치 방법에 대해서는 kubectl 설치를 참고하고, 빠른 가이드는 치트 시트를 참고한다. docker 명령줄 도구에 익숙하다면, 도커 사용자를 위한 kubectl에서 대응되는 쿠버네티스 명령어를 볼 수 있다.

구문

터미널 창에서 kubectl 명령을 실행하려면 다음의 구문을 사용한다.

kubectl [command] [TYPE] [NAME] [flags]

다음은 command, TYPE, NAME 과 flags 에 대한 설명이다.

• command: 하나 이상의 리소스에서 수행하려는 동작을 지정한다. 예: create, get, describe, delete

• TYPE: 리소스 타입을 지정한다. 리소스 타입은 대소문자를 구분하지 않으며 단수형, 복수형 또는 약어 형식을 지정할 수 있다. 예를 들어, 다음의 명령은 동일한 출력 결과를 생성한다.

  kubectl get pod pod1
  kubectl get pods pod1
  kubectl get po pod1
  

• NAME: 리소스 이름을 지정한다. 이름은 대소문자를 구분한다. 이름을 생략하면, 모든 리소스에 대한 세부 사항이 표시된다. 예: kubectl get pods

  여러 리소스에 대한 작업을 수행할 때, 타입 및 이름별로 각 리소스를 지정하거나 하나 이상의 파일을 지정할 수 있다.

  • 타입 및 이름으로 리소스를 지정하려면 다음을 참고한다.

    • 리소스가 모두 동일한 타입인 경우 리소스를 그룹화하려면 다음을 사용한다. TYPE1 name1 name2 name<#>
      예: kubectl get pod example-pod1 example-pod2

    • 여러 리소스 타입을 개별적으로 지정하려면 다음을 사용한다. TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>
      예: kubectl get pod/example-pod1 replicationcontroller/example-rc1

  • 하나 이상의 파일로 리소스를 지정하려면 다음을 사용한다. -f file1 -f file2 -f file<#>

    • YAML이 특히 구성 파일에 대해 더 사용자 친화적이므로, JSON 대신 YAML을 사용한다.
      예: kubectl get -f ./pod.yaml

• flags: 선택적 플래그를 지정한다. 예를 들어, -s 또는 --server 플래그를 사용하여 쿠버네티스 API 서버의 주소와 포트를 지정할 수 있다.
  

도움이 필요하다면, 터미널 창에서 kubectl help 를 실행한다.

클러스터 내 인증과 네임스페이스 오버라이드

기본적으로 kubectl은 먼저 자신이 파드 안에서 실행되고 있는지, 즉 클러스터 안에 있는지를 판별한다. 이를 위해 KUBERNETES_SERVICE_HOST와 KUBERNETES_SERVICE_PORT 환경 변수, 그리고 서비스 어카운트 토큰 파일이 /var/run/secrets/kubernetes.io/serviceaccount/token 경로에 있는지를 확인한다. 세 가지가 모두 감지되면, 클러스터 내 인증이 적용된다.

하위 호환성을 위해, 클러스터 내 인증 시에 POD_NAMESPACE 환경 변수가 설정되어 있으면, 서비스 어카운트 토큰의 기본 네임스페이스 설정을 오버라이드한다. 기본 네임스페이스 설정에 의존하는 모든 매니페스트와 도구가 영향을 받을 것이다.

POD_NAMESPACE 환경 변수

POD_NAMESPACE 환경 변수가 설정되어 있으면, 네임스페이스에 속하는 자원에 대한 CLI 작업은 환경 변수에 설정된 네임스페이스를 기본값으로 사용한다. 예를 들어, 환경 변수가 seattle로 설정되어 있으면, kubectl get pods 명령은 seattle 네임스페이스에 있는 파드 목록을 반환한다. 이는 파드가 네임스페이스에 속하는 자원이며, 명령어에 네임스페이스를 특정하지 않았기 때문이다. kubectl api-resources 명령을 실행하고 결과를 확인하여 특정 자원이 네임스페이스에 속하는 자원인지 판별한다.

명시적으로 --namespace <value> 인자를 사용하면 위와 같은 동작을 오버라이드한다.

kubectl이 서비스어카운트 토큰을 관리하는 방법

만약

• 쿠버네티스 서비스 어카운트 토큰 파일이 /var/run/secrets/kubernetes.io/serviceaccount/token 경로에 마운트되어 있고,
• KUBERNETES_SERVICE_HOST 환경 변수가 설정되어 있고,
• KUBERNETES_SERVICE_PORT 환경 변수가 설정되어 있고,
• kubectl 명령에 네임스페이스를 명시하지 않으면

kubectl은 자신이 클러스터 내부에서 실행되고 있다고 가정한다. kubectl은 해당 서비스어카운트의 네임스페이스(파드의 네임스페이스와 동일하다)를 인식하고 해당 네임스페이스에 대해 동작한다. 이는 클러스터 외부에서 실행되었을 때와는 다른데, kubectl이 클러스터 외부에서 실행되었으며 네임스페이스가 명시되지 않은 경우 kubectl 명령어는 클라이언트 구성에서 현재 컨텍스트(current context)에 설정된 네임스페이스에 대해 동작한다. kubectl이 동작하는 기본 네임스페이스를 변경하려면 아래의 명령어를 실행한다.

kubectl config set-context --current --namespace=<namespace-name>

명령어

다음 표에는 모든 kubectl 작업에 대한 간단한 설명과 일반적인 구문이 포함되어 있다.

명령 동작에 대한 자세한 내용을 배우려면 kubectl 참조 문서를 참고한다.

리소스 타입

다음 표에는 지원되는 모든 리소스 타입과 해당 약어가 나열되어 있다.

(이 출력은 kubectl api-resources 에서 확인할 수 있으며, 쿠버네티스 1.25.0 에서의 출력을 기준으로 한다.)

출력 옵션

특정 명령의 출력을 서식화하거나 정렬하는 방법에 대한 정보는 다음 섹션을 참고한다. 다양한 출력 옵션을 지원하는 명령에 대한 자세한 내용은 kubectl 참조 문서를 참고한다.

출력 서식화

모든 kubectl 명령의 기본 출력 형식은 사람이 읽을 수 있는 일반 텍스트 형식이다. 특정 형식으로 터미널 창에 세부 정보를 출력하려면, 지원되는 kubectl 명령에 -o 또는 --output 플래그를 추가할 수 있다.

구문

kubectl [command] [TYPE] [NAME] -o <output_format>

kubectl 명령에 따라, 다음과 같은 출력 형식이 지원된다.

예제

이 예제에서, 다음의 명령은 단일 파드에 대한 세부 정보를 YAML 형식의 오브젝트로 출력한다.

kubectl get pod web-pod-13je7 -o yaml

기억하기: 각 명령이 지원하는 출력 형식에 대한 자세한 내용은 kubectl 참조 문서를 참고한다.

사용자 정의 열

사용자 정의 열을 정의하고 원하는 세부 정보만 테이블에 출력하려면, custom-columns 옵션을 사용할 수 있다. 사용자 정의 열을 인라인으로 정의하거나 템플릿 파일을 사용하도록 선택할 수 있다. -o custom-columns=<spec> 또는 -o custom-columns-file=<filename>

예제

인라인:

kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

템플릿 파일:

kubectl get pods <pod-name> -o custom-columns-file=template.txt

template.txt 파일에 포함된 내용은 다음과 같다.

NAME          RSRC
metadata.name metadata.resourceVersion

두 명령 중 하나를 실행한 결과는 다음과 비슷하다.

NAME           RSRC
submit-queue   610995

서버측 열

kubectl 는 서버에서 오브젝트에 대한 특정 열 정보 수신을 지원한다. 이는 클라이언트가 출력할 수 있도록, 주어진 리소스에 대해 서버가 해당 리소스와 관련된 열과 행을 반환한다는 것을 의미한다. 이는 서버가 출력의 세부 사항을 캡슐화하도록 하여, 동일한 클러스터에 대해 사용된 클라이언트에서 사람이 읽을 수 있는 일관된 출력을 허용한다.

이 기능은 기본적으로 활성화되어 있다. 사용하지 않으려면, kubectl get 명령에 --server-print=false 플래그를 추가한다.

예제

파드 상태에 대한 정보를 출력하려면, 다음과 같은 명령을 사용한다.

kubectl get pods <pod-name> --server-print=false

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

NAME       AGE
pod-name   1m

오브젝트 목록 정렬

터미널 창에서 정렬된 목록으로 오브젝트를 출력하기 위해, 지원되는 kubectl 명령에 --sort-by 플래그를 추가할 수 있다. --sort-by 플래그와 함께 숫자나 문자열 필드를 지정하여 오브젝트를 정렬한다. 필드를 지정하려면, jsonpath 표현식을 사용한다.

구문

kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

예제

이름별로 정렬된 파드 목록을 출력하려면, 다음을 실행한다.

kubectl get pods --sort-by=.metadata.name

예제: 일반적인 작업

다음 예제 세트를 사용하여 일반적으로 사용되는 kubectl 조작 실행에 익숙해진다.

kubectl apply - 파일 또는 표준입력에서 리소스를 적용하거나 업데이트한다.

# example-service.yaml의 정의를 사용하여 서비스를 생성한다.
kubectl apply -f example-service.yaml

# example-controller.yaml의 정의를 사용하여 레플리케이션 컨트롤러를 생성한다.
kubectl apply -f example-controller.yaml

# <directory> 디렉터리 내의 .yaml, .yml 또는 .json 파일에 정의된 오브젝트를 생성한다.
kubectl apply -f <directory>

kubectl get - 하나 이상의 리소스를 나열한다.

# 모든 파드를 일반 텍스트 출력 형식으로 나열한다.
kubectl get pods

# 모든 파드를 일반 텍스트 출력 형식으로 나열하고 추가 정보(예: 노드 이름)를 포함한다.
kubectl get pods -o wide

# 지정된 이름의 레플리케이션 컨트롤러를 일반 텍스트 출력 형식으로 나열한다. 팁: 'replicationcontroller' 리소스 타입을 'rc'로 짧게 바꿔쓸 수 있다.
kubectl get replicationcontroller <rc-name>

# 모든 레플리케이션 컨트롤러와 서비스를 일반 텍스트 출력 형식으로 함께 나열한다.
kubectl get rc,services

# 모든 데몬 셋을 일반 텍스트 출력 형식으로 나열한다.
kubectl get ds

# 노드 server01에서 실행 중인 모든 파드를 나열한다.
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe - 초기화되지 않은 리소스를 포함하여 하나 이상의 리소스의 기본 상태를 디폴트로 표시한다.

# 노드 이름이 <node-name>인 노드의 세부 사항을 표시한다.
kubectl describe nodes <node-name>

# 파드 이름이 <pod-name> 인 파드의 세부 정보를 표시한다.
kubectl describe pods/<pod-name>

# 이름이 <rc-name>인 레플리케이션 컨트롤러가 관리하는 모든 파드의 세부 정보를 표시한다.
# 기억하기: 레플리케이션 컨트롤러에서 생성된 모든 파드에는 레플리케이션 컨트롤러 이름이 접두사로 붙는다.
kubectl describe pods <rc-name>

# 모든 파드의 정보를 출력한다.
kubectl describe pods

kubectl delete - 파일, 표준입력 또는 레이블 선택기, 이름, 리소스 선택기나 리소스를 지정하여 리소스를 삭제한다.

# pod.yaml 파일에 지정된 타입과 이름을 사용하여 파드를 삭제한다.
kubectl delete -f pod.yaml

# '<label-key>=<label-value>' 레이블이 있는 모든 파드와 서비스를 삭제한다.
kubectl delete pods,services -l <label-key>=<label-value>

# 초기화되지 않은 파드를 포함한 모든 파드를 삭제한다.
kubectl delete pods --all

kubectl exec - 파드의 컨테이너에 대해 명령을 실행한다.

# 파드 <pod-name>에서 'date'를 실행한 결과를 얻는다. 기본적으로, 첫 번째 컨테이너에서 출력된다.
kubectl exec <pod-name> -- date

# 파드 <pod-name>의 <container-name> 컨테이너에서 'date'를 실행하여 출력 결과를 얻는다.
kubectl exec <pod-name> -c <container-name> -- date

# 파드 <pod-name>에서 대화식 TTY를 연결해 /bin/bash를 실행한다. 기본적으로, 첫 번째 컨테이너에서 출력된다.
kubectl exec -ti <pod-name> -- /bin/bash

kubectl logs - 파드의 컨테이너에 대한 로그를 출력한다.

# 파드 <pod-name>에서 로그의 스냅샷을 반환한다.
kubectl logs <pod-name>

# 파드 <pod-name>에서 로그 스트리밍을 시작한다. 이것은 리눅스 명령 'tail -f'와 비슷하다.
kubectl logs -f <pod-name>

kubectl diff - 제안된 클러스터 업데이트의 차이점을 본다.

# "pod.json"에 포함된 리소스의 차이점을 출력한다.
kubectl diff -f pod.json

# 표준입력에서 파일을 읽어 차이점을 출력한다.
cat service.yaml | kubectl diff -f -

예제: 플러그인 작성 및 사용

kubectl 플러그인 작성과 사용에 익숙해지려면 다음의 예제 세트를 사용한다.

# 어떤 언어로든 간단한 플러그인을 만들고 "kubectl-" 접두사로
# 시작하도록 실행 파일의 이름을 지정한다.
cat ./kubectl-hello

#!/bin/sh

# 이 플러그인은 "hello world"라는 단어를 출력한다
echo "hello world"

작성한 플러그인을 실행 가능하게 한다

chmod a+x ./kubectl-hello

# 그리고 PATH의 위치로 옮긴다
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin

# 이제 kubectl 플러그인을 만들고 "설치했다".
# kubectl에서 플러그인을 일반 명령처럼 호출하여 플러그인을 사용할 수 있다
kubectl hello

hello world

# 플러그인을 배치한 $PATH의 폴더에서 플러그인을 삭제하여,
# 플러그인을 "제거"할 수 있다
sudo rm /usr/local/bin/kubectl-hello

kubectl 에 사용할 수 있는 모든 플러그인을 보려면, kubectl plugin list 하위 명령을 사용한다.

kubectl plugin list

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

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

kubectl plugin list 는 또한 실행 가능하지 않거나, 다른 플러그인에 의해 차단된 플러그인에 대해 경고한다. 예를 들면 다음과 같다.

sudo chmod -x /usr/local/bin/kubectl-foo # 실행 권한 제거
kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar

error: one plugin warning was found

플러그인은 기존 kubectl 명령 위에 보다 복잡한 기능을 구축하는 수단으로 생각할 수 있다.

cat ./kubectl-whoami

다음 몇 가지 예는 이미 kubectl-whoami 에 다음 내용이 있다고 가정한다.

#!/bin/bash

# 이 플러그인은 현재 선택된 컨텍스트를 기반으로 현재 사용자에 대한
# 정보를 출력하기 위해 'kubectl config' 명령을 사용한다.
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

위의 플러그인을 실행하면 KUBECONFIG 파일에서 현재의 컨텍스트에 대한 사용자가 포함된 출력이 제공된다.

# 파일을 실행 가능하게 한다
sudo chmod +x ./kubectl-whoami

# 그리고 PATH로 옮긴다
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

다음 내용

• kubectl 레퍼런스 문서를 읽는다.
  • kubectl 명령어 레퍼런스
  • 명령줄 인자 레퍼런스
• kubectl 사용 규칙에 대해 알아본다.
• kubectl의 JSONPath 지원에 대해 알아본다.
• 플러그인으로 kubectl 확장에 대해 알아본다.
  • 플러그인에 대해 좀 더 알아보려면, 예시 CLI 플러그인을 살펴본다.

10.1 - kubectl 치트 시트

이 페이지는 일반적으로 사용하는 kubectl 커맨드와 플래그에 대한 목록을 포함한다.

Kubectl 자동 완성

BASH

source <(kubectl completion bash) # bash-completion 패키지를 먼저 설치한 후, bash의 자동 완성을 현재 셸에 설정한다
echo "source <(kubectl completion bash)" >> ~/.bashrc # 자동 완성을 bash 셸에 영구적으로 추가한다

또한, kubectl의 의미로 사용되는 약칭을 사용할 수 있다.

alias k=kubectl
complete -o default -F __start_kubectl k

ZSH

source <(kubectl completion zsh)  # 현재 셸에 zsh의 자동 완성 설정
echo '[[ $commands[kubectl] ]] && source <(kubectl completion zsh)' >> ~/.zshrc # 자동 완성을 zsh 셸에 영구적으로 추가한다.

--all-namespaces 에 대한 노트

--all-namespaces를 붙여야 하는 상황이 자주 발생하므로, --all-namespaces의 축약형을 알아 두는 것이 좋다.

kubectl -A

Kubectl 컨텍스트와 설정

kubectl이 통신하고 설정 정보를 수정하는 쿠버네티스 클러스터를 지정한다. 설정 파일에 대한 자세한 정보는 kubeconfig를 이용한 클러스터 간 인증 문서를 참고한다.

kubectl config view # 병합된 kubeconfig 설정을 표시한다.

# 동시에 여러 kubeconfig 파일을 사용하고 병합된 구성을 확인한다
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2

kubectl config view

# e2e 사용자의 암호를 확인한다
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'

kubectl config view -o jsonpath='{.users[].name}'     # 첫 번째 사용자 출력
kubectl config view -o jsonpath='{.users[*].name}'    # 사용자 리스트 조회
kubectl config get-contexts                           # 컨텍스트 리스트 출력
kubectl config current-context                        # 현재 컨텍스트 출력
kubectl config use-context my-cluster-name            # my-cluster-name를 기본 컨텍스트로 설정

kubectl config set-cluster my-cluster-name            # kubeconfig에 클러스터 엔트리를 설정

# kubeconfig에 이 클라이언트가 발생시킨 요청에 사용할 프록시 서버의 URL을 구성한다.
kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url

# 기본 인증을 지원하는 새로운 사용자를 kubeconf에 추가한다
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword

# 해당 컨텍스트에서 모든 후속 kubectl 커맨드에 대한 네임스페이스를 영구적으로 저장한다
kubectl config set-context --current --namespace=ggckad-s2

# 특정 사용자와 네임스페이스를 사용하는 컨텍스트 설정
kubectl config set-context gce --user=cluster-admin --namespace=foo \
  && kubectl config use-context gce

kubectl config unset users.foo                       # foo 사용자 삭제

# 컨텍스트/네임스페이스를 설정/조회하는 단축 명령 (bash 및 bash 호환 셸에서만 동작함, 네임스페이스 설정을 위해 kn 을 사용하기 전에 현재 컨텍스트가 설정되어야 함)
alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'

Kubectl apply

apply는 쿠버네티스 리소스를 정의하는 파일을 통해 애플리케이션을 관리한다. kubectl apply를 실행하여 클러스터에 리소스를 생성하고 업데이트한다. 이것은 프로덕션 환경에서 쿠버네티스 애플리케이션을 관리할 때 권장된다. Kubectl Book을 참고한다.

오브젝트 생성

쿠버네티스 매니페스트는 JSON이나 YAML로 정의된다. 파일 확장자는 .yaml , .yml, .json 이 사용된다.

kubectl apply -f ./my-manifest.yaml            # 리소스(들) 생성
kubectl apply -f ./my1.yaml -f ./my2.yaml      # 여러 파일로 부터 생성
kubectl apply -f ./dir                         # dir 내 모든 매니페스트 파일에서 리소스(들) 생성
kubectl apply -f https://git.io/vPieo          # url로부터 리소스(들) 생성
kubectl create deployment nginx --image=nginx  # nginx 단일 인스턴스를 시작

# "Hello World"를 출력하는 잡(Job) 생성
kubectl create job hello --image=busybox:1.28 -- echo "Hello World"

# 매분마다 "Hello World"를 출력하는 크론잡(CronJob) 생성
kubectl create cronjob hello --image=busybox:1.28   --schedule="*/1 * * * *" -- echo "Hello World"

kubectl explain pods                           # 파드 매니페스트 문서를 조회

# stdin으로 다수의 YAML 오브젝트 생성
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep
spec:
  containers:
  - name: busybox
    image: busybox:1.28
    args:
    - sleep
    - "1000000"
---
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep-less
spec:
  containers:
  - name: busybox
    image: busybox:1.28
    args:
    - sleep
    - "1000"
EOF

# 여러 개의 키로 시크릿 생성
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  password: $(echo -n "s33msi4" | base64 -w0)
  username: $(echo -n "jane" | base64 -w0)
EOF

리소스 조회 및 찾기

# 기본 출력을 위한 Get 커맨드
kubectl get services                          # 네임스페이스 내 모든 서비스의 목록 조회
kubectl get pods --all-namespaces             # 모든 네임스페이스 내 모든 파드의 목록 조회
kubectl get pods -o wide                      # 해당하는 네임스페이스 내 모든 파드의 상세 목록 조회
kubectl get deployment my-dep                 # 특정 디플로이먼트의 목록 조회
kubectl get pods                              # 네임스페이스 내 모든 파드의 목록 조회
kubectl get pod my-pod -o yaml                # 파드의 YAML 조회

# 상세 출력을 위한 Describe 커맨드
kubectl describe nodes my-node
kubectl describe pods my-pod

# Name으로 정렬된 서비스의 목록 조회
kubectl get services --sort-by=.metadata.name

# 재시작 횟수로 정렬된 파드의 목록 조회
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# PersistentVolumes을 용량별로 정렬해서 조회
kubectl get pv --sort-by=.spec.capacity.storage

# app=cassandra 레이블을 가진 모든 파드의 레이블 버전 조회
kubectl get pods --selector=app=cassandra -o \
  jsonpath='{.items[*].metadata.labels.version}'

# 예를 들어 'ca.crt'와 같이 점이 있는 키값을 검색한다
kubectl get configmap myconfig \
  -o jsonpath='{.data.ca\.crt}'

# 밑줄(`_`) 대신 대시(`-`)를 사용하여 base64 인코딩된 값을 조회
kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}'

# 모든 워커 노드 조회 (셀렉터를 사용하여 'node-role.kubernetes.io/control-plane'
# 으로 명명된 라벨의 결과를 제외)
kubectl get node --selector='!node-role.kubernetes.io/control-plane'

# 네임스페이스의 모든 실행 중인 파드를 조회
kubectl get pods --field-selector=status.phase=Running

# 모든 노드의 외부IP를 조회
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

# 특정 RC에 속해있는 파드 이름의 목록 조회
# "jq" 커맨드는 jsonpath를 사용하는 매우 복잡한 변환에 유용하다. https://stedolan.github.io/jq/ 에서 확인할 수 있다.
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})

# 모든 파드(또는 레이블을 지원하는 다른 쿠버네티스 오브젝트)의 레이블 조회
kubectl get pods --show-labels

# 어떤 노드가 준비됐는지 확인
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
 && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"

# 외부 도구 없이 디코딩된 시크릿 출력
kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'

# 파드에 의해 현재 사용되고 있는 모든 시크릿 목록 조회
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq

# 모든 파드의 초기화 컨테이너(initContainer)의 컨테이너ID 목록 조회
# 초기화 컨테이너(initContainer)를 제거하지 않고 정지된 모든 컨테이너를 정리할 때 유용하다.
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3

# 타임스탬프로 정렬된 이벤트 목록 조회
kubectl get events --sort-by=.metadata.creationTimestamp

# 모든 Warning 타입 이벤트 조회
kubectl events --types=Warning

# 매니페스트가 적용된 경우 클러스터의 현재 상태와 클러스터의 상태를 비교한다.
kubectl diff -f ./my-manifest.yaml

# 노드에 대해 반환된 모든 키의 마침표로 구분된 트리를 생성한다.
# 복잡한 중첩 JSON 구조 내에서 키를 찾을 때 유용하다.
kubectl get nodes -o json | jq -c 'paths|join(".")'

# 파드 등에 대해 반환된 모든 키의 마침표로 구분된 트리를 생성한다.
kubectl get pods -o json | jq -c 'paths|join(".")'

# 모든 파드에 대해 ENV를 생성한다(각 파드에 기본 컨테이너가 있고, 기본 네임스페이스가 있고, `env` 명령어가 동작한다고 가정).
# `env` 뿐만 아니라 다른 지원되는 명령어를 모든 파드에 실행할 때에도 참고할 수 있다.
for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done

# 디플로이먼트의 status 서브리소스를 조회한다.
kubectl get deployment nginx-deployment --subresource=status

리소스 업데이트

kubectl set image deployment/frontend www=image:v2               # "frontend" 디플로이먼트의 "www" 컨테이너 이미지를 업데이트하는 롤링 업데이트
kubectl rollout history deployment/frontend                      # 현 리비전을 포함한 디플로이먼트의 이력을 체크
kubectl rollout undo deployment/frontend                         # 이전 디플로이먼트로 롤백
kubectl rollout undo deployment/frontend --to-revision=2         # 특정 리비전으로 롤백
kubectl rollout status -w deployment/frontend                    # 완료될 때까지 "frontend" 디플로이먼트의 롤링 업데이트 상태를 감시
kubectl rollout restart deployment/frontend                      # "frontend" 디플로이먼트의 롤링 재시작


cat pod.json | kubectl replace -f -                              # stdin으로 전달된 JSON을 기반으로 파드 교체

# 리소스를 강제 교체, 삭제 후 재생성함. 이것은 서비스를 중단시킴.
kubectl replace --force -f ./pod.json

# 복제된 nginx를 위한 서비스를 생성한다. 80 포트로 서비스하고, 컨테이너는 8000 포트로 연결한다.
kubectl expose rc nginx --port=80 --target-port=8000

# 단일-컨테이너 파드의 이미지 버전(태그)을 v4로 업데이트
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

kubectl label pods my-pod new-label=awesome                      # 레이블 추가
kubectl label pods my-pod new-label-                             # 레이블 제거
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq       # 어노테이션 추가
kubectl autoscale deployment foo --min=2 --max=10                # 디플로이먼트 "foo" 오토스케일

리소스 패치

# 노드를 부분적으로 업데이트
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# 컨테이너의 이미지를 업데이트. 병합(merge) 키이므로, spec.containers[*].name이 필요
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# 위치 배열을 이용한 json 패치를 사용하여, 컨테이너의 이미지를 업데이트
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# 위치 배열을 이용한 json 패치를 사용하여 livenessProbe 디플로이먼트 비활성화
kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# 위치 배열에 새 요소 추가
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

# 디플로이먼트의 scale 서브리소스를 패치하여 레플리카 수 업데이트
kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'

리소스 편집

선호하는 편집기로 모든 API 리소스를 편집할 수 있다.

kubectl edit svc/docker-registry                      # docker-registry라는 서비스 편집
KUBE_EDITOR="nano" kubectl edit svc/docker-registry   # 다른 편집기 사용

리소스 스케일링

kubectl scale --replicas=3 rs/foo                                 # 'foo'라는 레플리카셋을 3으로 스케일
kubectl scale --replicas=3 -f foo.yaml                            # "foo.yaml"에 지정된 리소스의 크기를 3으로 스케일
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql  # mysql이라는 디플로이먼트의 현재 크기가 2인 경우, mysql을 3으로 스케일
kubectl scale --replicas=5 rc/foo rc/bar rc/baz                   # 여러 개의 레플리케이션 컨트롤러 스케일

리소스 삭제

kubectl delete -f ./pod.json                                      # pod.json에 지정된 유형 및 이름을 사용하여 파드 삭제
kubectl delete pod unwanted --now                                 # 유예 시간 없이 즉시 파드 삭제
kubectl delete pod,service baz foo                                # "baz", "foo"와 동일한 이름을 가진 파드와 서비스 삭제
kubectl delete pods,services -l name=myLabel                      # name=myLabel 라벨을 가진 파드와 서비스 삭제
kubectl -n my-ns delete pod,svc --all                             # my-ns 네임스페이스 내 모든 파드와 서비스 삭제
# awk pattern1 또는 pattern2에 매칭되는 모든 파드 삭제
kubectl get pods  -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs  kubectl delete -n mynamespace pod

실행 중인 파드와 상호 작용

kubectl logs my-pod                                 # 파드 로그 덤프 (stdout)
kubectl logs -l name=myLabel                        # name이 myLabel인 파드 로그 덤프 (stdout)
kubectl logs my-pod --previous                      # 컨테이너의 이전 인스턴스 생성에 대한 파드 로그 덤프 (stdout)
kubectl logs my-pod -c my-container                 # 파드 로그 덤프 (stdout, 멀티-컨테이너 경우)
kubectl logs -l name=myLabel -c my-container        # name이 myLabel인 파드 로그 덤프 (stdout)
kubectl logs my-pod -c my-container --previous      # 컨테이너의 이전 인스턴스 생성에 대한 파드 로그 덤프 (stdout, 멀티-컨테이너 경우)
kubectl logs -f my-pod                              # 실시간 스트림 파드 로그(stdout)
kubectl logs -f my-pod -c my-container              # 실시간 스트림 파드 로그(stdout, 멀티-컨테이너 경우)
kubectl logs -f -l name=myLabel --all-containers    # name이 myLabel인 모든 파드의 로그 스트리밍 (stdout)
kubectl run -i --tty busybox --image=busybox:1.28 -- sh  # 대화형 셸로 파드를 실행
kubectl run nginx --image=nginx -n mynamespace      # mynamespace 네임스페이스에서 nginx 파드 1개 실행
kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
                                                    # nginx 파드에 대한 spec을 생성하고, pod.yaml이라는 파일에 해당 내용을 기록한다.
kubectl attach my-pod -i                            # 실행 중인 컨테이너에 연결
kubectl port-forward my-pod 5000:6000               # 로컬 머신의 5000번 포트를 리스닝하고, my-pod의 6000번 포트로 전달
kubectl exec my-pod -- ls /                         # 기존 파드에서 명령 실행(한 개 컨테이너 경우)
kubectl exec --stdin --tty my-pod -- /bin/sh        # 실행 중인 파드로 대화형 셸 액세스(1 컨테이너 경우)
kubectl exec my-pod -c my-container -- ls /         # 기존 파드에서 명령 실행(멀티-컨테이너 경우)
kubectl top pod POD_NAME --containers               # 특정 파드와 해당 컨테이너에 대한 메트릭 표시
kubectl top pod POD_NAME --sort-by=cpu              # 지정한 파드에 대한 메트릭을 표시하고 'cpu' 또는 'memory'별로 정렬

컨테이너로/컨테이너에서 파일과 디렉터리 복사

kubectl cp /tmp/foo_dir my-pod:/tmp/bar_dir            # 로컬 디렉토리 /tmp/foo_dir 를 현재 네임스페이스의 my-pod 파드 안의 /tmp/bar_dir 로 복사
kubectl cp /tmp/foo my-pod:/tmp/bar -c my-container    # 로컬 파일 /tmp/foo 를 my-pod 파드의 my-container 컨테이너 안의 /tmp/bar 로 복사
kubectl cp /tmp/foo my-namespace/my-pod:/tmp/bar       # 로컬 파일 /tmp/foo 를 my-namespace 네임스페이스의 my-pod 파드 안의 /tmp/bar 로 복사
kubectl cp my-namespace/my-pod:/tmp/foo /tmp/bar       # my-namespace 네임스페이스의 my-pod 파드 안의 파일 /tmp/foo 를 로컬의 /tmp/bar 로 복사

tar cf - /tmp/foo | kubectl exec -i -n my-namespace my-pod -- tar xf - -C /tmp/bar           # 로컬 파일 /tmp/foo 를 my-namespace 네임스페이스의 my-pod 파드 안의 /tmp/bar 로 복사
kubectl exec -n my-namespace my-pod -- tar cf - /tmp/foo | tar xf - -C /tmp/bar    # my-namespace 네임스페이스의 my-pod 파드 안의 파일 /tmp/foo 를 로컬의 /tmp/bar 로 복사

디플로이먼트, 서비스와 상호 작용

kubectl logs deploy/my-deployment                         # 디플로이먼트에 대한 파드 로그 덤프 (단일-컨테이너 경우)
kubectl logs deploy/my-deployment -c my-container         # 디플로이먼트에 대한 파드 로그 덤프 (멀티-컨테이너 경우)

kubectl port-forward svc/my-service 5000                  # 로컬 머신의 5000번 포트를 리스닝하고, my-service의 동일한(5000번) 포트로 전달
kubectl port-forward svc/my-service 5000:my-service-port  # 로컬 머신의 5000번 포트를 리스닝하고, my-service의 <my-service-port> 라는 이름을 가진 포트로 전달

kubectl port-forward deploy/my-deployment 5000:6000       # 로컬 머신의 5000번 포트를 리스닝하고, <my-deployment> 에 의해 생성된 파드의 6000번 포트로 전달
kubectl exec deploy/my-deployment -- ls                   # <my-deployment> 에 의해 생성된 첫번째 파드의 첫번째 컨테이너에 명령어 실행 (단일- 또는 다중-컨테이너 경우)

노드, 클러스터와 상호 작용

kubectl cordon my-node                                                # my-node를 스케줄링할 수 없도록 표기
kubectl drain my-node                                                 # 유지 보수를 위해서 my-node를 준비 상태로 비움
kubectl uncordon my-node                                              # my-node를 스케줄링할 수 있도록 표기
kubectl top node my-node                                              # 주어진 노드에 대한 메트릭 표시
kubectl cluster-info                                                  # 마스터 및 서비스의 주소 표시
kubectl cluster-info dump                                             # 현재 클러스터 상태를 stdout으로 덤프
kubectl cluster-info dump --output-directory=/path/to/cluster-state   # 현재 클러스터 상태를 /path/to/cluster-state으로 덤프

# 현재 노드에 존재하고 있는 테인트(taint)들을 확인
kubectl get nodes -o='custom-columns=NodeName:.metadata.name,TaintKey:.spec.taints[*].key,TaintValue:.spec.taints[*].value,TaintEffect:.spec.taints[*].effect'

# 이미 존재하고 있는 key와 effect를 갖는 테인트의 경우, 지정한 값으로 대체
kubectl taint nodes foo dedicated=special-user:NoSchedule

리소스 타입

단축명, API 그룹과 함께 지원되는 모든 리소스 유형들, 그것들의 네임스페이스와 종류(Kind)를 나열:

kubectl api-resources

API 리소스를 탐색하기 위한 다른 작업:

kubectl api-resources --namespaced=true      # 네임스페이스를 가지는 모든 리소스
kubectl api-resources --namespaced=false     # 네임스페이스를 가지지 않는 모든 리소스
kubectl api-resources -o name                # 모든 리소스의 단순한 (리소스 이름만) 출력
kubectl api-resources -o wide                # 모든 리소스의 확장된 ("wide"로 알려진) 출력
kubectl api-resources --verbs=list,get       # "list"와 "get"의 요청 동사를 지원하는 모든 리소스 출력
kubectl api-resources --api-group=extensions # "extensions" API 그룹의 모든 리소스

출력 형식 지정

특정 형식으로 터미널 창에 세부 사항을 출력하려면, 지원되는 kubectl 명령에 -o (또는 --output) 플래그를 추가한다.

-o=custom-columns 의 사용 예시:

# 클러스터에서 실행 중인 모든 이미지
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'

# `default` 네임스페이스의 모든 이미지를 파드별로 그룹지어 출력
kubectl get pods --namespace default --output=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image"

 # "registry.k8s.io/coredns:1.6.2" 를 제외한 모든 이미지
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="registry.k8s.io/coredns:1.6.2")].image'

# 이름에 관계없이 메타데이터 아래의 모든 필드
kubectl get pods -A -o=custom-columns='DATA:metadata.*'

더 많은 예제는 kubectl 참조 문서를 참고한다.

Kubectl 출력 로그 상세 레벨(verbosity)과 디버깅

Kubectl 로그 상세 레벨(verbosity)은 -v 또는--v 플래그와 로그 레벨을 나타내는 정수로 제어된다. 일반적인 쿠버네티스 로깅 규칙과 관련 로그 레벨이 여기에 설명되어 있다.

다음 내용

• kubectl 개요를 읽고 JsonPath에 대해 배워보자.

• kubectl 옵션을 참고한다.

• 재사용 스크립트에서 kubectl 사용 방법을 이해하기 위해 kubectl 사용 규칙을 참고한다.

• 더 많은 커뮤니티 kubectl 치트시트를 확인한다.

10.2 - kubectl

시놉시스

kubectl은 쿠버네티스 클러스터 관리자를 제어한다.

자세한 정보는 kubectl 개요를 확인한다.

kubectl [flags]

옵션

환경 변수

tr>

더 보기

• kubectl annotate - 리소스에 대한 어노테이션 업데이트
• kubectl api-resources - 서버에서 지원되는 API 리소스 출력
• kubectl api-versions - "그룹/버전" 형식으로 서버에서 지원되는 API 버전을 출력
• kubectl apply - 파일명 또는 표준 입력으로 리소스에 구성 적용
• kubectl attach - 실행 중인 컨테이너에 연결
• kubectl auth - 권한 검사
• kubectl autoscale - 디플로이먼트(Deployment), 레플리카셋(ReplicaSet) 또는 레플리케이션컨트롤러(ReplicationController) 자동 스케일링
• kubectl certificate - 인증서 리소스 수정
• kubectl cluster-info - 클러스터 정보 표시
• kubectl completion - 지정된 셸(bash 또는 zsh)에 대한 셸 완성 코드 출력
• kubectl config - kubeconfig 파일 수정
• kubectl cordon - 노드를 unschedulable로 표시
• kubectl cp - 컨테이너 간에 파일과 디렉터리 복사
• kubectl create - 파일 또는 표준 입력에서 리소스를 생성
• kubectl debug - 워크로드와 노드의 문제 해결을 위한 디버깅 세션 생성
• kubectl delete - 파일명, 표준 입력, 리소스 및 이름, 또는 리소스 및 레이블 셀렉터로 리소스 삭제
• kubectl describe - 특정 리소스 또는 리소스 그룹의 세부 정보를 표시
• kubectl diff - 적용 예정 버전과 라이브 버전 비교
• kubectl drain - 유지 보수 준비 중 노드 드레인
• kubectl edit - 서버에서 리소스 편집
• kubectl events - 이벤트 목록 나열
• kubectl exec - 컨테이너에서 커맨드 실행
• kubectl explain - 리소스의 문서
• kubectl expose - 레플리케이션 컨트롤러, 서비스, 디플로이먼트 또는 파드를 가져와서 새로운 쿠버네티스 서비스로 노출
• kubectl get - 하나 이상의 리소스 표시
• kubectl kustomize - 디렉터리 또는 원격 URL에서 kustomization 대상을 빌드
• kubectl label - 리소스의 레이블 업데이트
• kubectl logs - 파드의 컨테이너에 대한 로그 출력
• kubectl options - 모든 커맨드에서 상속된 플래그 목록을 출력
• kubectl patch - 리소스 필드를 업데이트
• kubectl plugin - 플러그인과 상호 작용하기 위한 유틸리티를 제공
• kubectl port-forward - 하나 이상의 로컬 포트를 파드로 전달
• kubectl proxy - 쿠버네티스 API 서버에 대한 프록시 실행
• kubectl replace - 파일명 또는 표준 입력으로 리소스 교체
• kubectl rollout - 리소스 롤아웃 관리
• kubectl run - 클러스터에서 특정 이미지 실행
• kubectl scale - 디플로이먼트, 레플리카셋 또는 레플리케이션 컨트롤러의 새 크기 설정
• kubectl set - 오브젝트에 특정 기능 설정
• kubectl taint - 하나 이상의 노드에서 테인트(taint) 업데이트
• kubectl top - 리소스(CPU/메모리/스토리지) 사용량을 표시
• kubectl uncordon - 노드를 schedulable로 표시
• kubectl version - 클라이언트 및 서버 버전 정보 출력
• kubectl wait - 실험적(experimental) 기능: 하나 이상의 리소스에 대해서 특정 조건이 만족될 때까지 대기(wait)

10.3 - JSONPath 지원

Kubectl은 JSONPath 템플릿을 지원한다.

JSONPath 템플릿은 중괄호 {}로 둘러싸인 JSONPath 표현식으로 구성된다. Kubectl은 JSONPath 표현식을 사용하여 JSON 오브젝트의 특정 필드를 필터링하고 출력 형식을 지정한다. 원본 JSONPath 템플릿 구문 외에도 다음과 같은 기능과 구문이 유효하다.

1. 큰따옴표를 사용하여 JSONPath 표현식 내부의 텍스트를 인용한다.
2. 목록을 반복하려면 range, end 오퍼레이터를 사용한다.
3. 목록에서 뒤로 이동하려면 negative slice 인덱스를 사용한다. negative 인덱스는 목록을 "순환(wrap around)" 하지 않으며, -index + listLength >= 0 인 한 유효하다.

JSON 입력 시 다음과 같다.

{
  "kind": "List",
  "items":[
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.1"},
      "status":{
        "capacity":{"cpu":"4"},
        "addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}]
      }
    },
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.2"},
      "status":{
        "capacity":{"cpu":"8"},
        "addresses":[
          {"type": "LegacyHostIP", "address":"127.0.0.2"},
          {"type": "another", "address":"127.0.0.3"}
        ]
      }
    }
  ],
  "users":[
    {
      "name": "myself",
      "user": {}
    },
    {
      "name": "e2e",
      "user": {"username": "admin", "password": "secret"}
    }
  ]
}

kubectl 및 JSONPath 표현식을 사용하는 예는 다음과 같다.

kubectl get pods -o json
kubectl get pods -o=jsonpath='{@}'
kubectl get pods -o=jsonpath='{.items[0]}'
kubectl get pods -o=jsonpath='{.items[0].metadata.name}'
kubectl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}"
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'

kubectl get pods -o=jsonpath="{range .items[*]}{.metadata.name}{'\t'}{.status.startTime}{'\n'}{end}"
kubectl get pods -o=jsonpath="{range .items[*]}{.metadata.name}{\"\t\"}{.status.startTime}{\"\n\"}{end}"

# kubectl은 JSONPath 출력에 대한 정규 표현식을 지원하지 않는다.
# 다음 커맨드는 작동하지 않는다.
kubectl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}'

# 다음 커맨드는 원하는 결과를 얻는다.
kubectl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).spec.containers[].image'

10.4 - 도커 사용자를 위한 kubectl

당신은 쿠버네티스 커맨드 라인 도구인 kubectl을 사용하여 API 서버와 상호 작용할 수 있다. 만약 도커 커맨드 라인 도구에 익숙하다면 kubectl을 사용하는 것은 간단하다. 다음 섹션에서는 도커의 하위 명령을 보여주고 kubectl과 같은 명령어를 설명한다.

docker run

nginx 디플로이먼트(Deployment)를 실행하고 해당 디플로이먼트를 노출시키려면, kubectl create deployment을 참고한다. docker:

docker run -d --restart=always -e DOMAIN=cluster --name nginx-app -p 80:80 nginx

55c103fa129692154a7652490236fee9be47d70a8dd562281ae7d2f9a339a6db

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   9 seconds ago       Up 9 seconds        0.0.0.0:80->80/tcp   nginx-app

kubectl:

# nginx 실행하는 파드를 시작한다
kubectl create deployment --image=nginx nginx-app

deployment.apps/nginx-app created

# nginx-app 에 env를 추가한다
kubectl set env deployment/nginx-app  DOMAIN=cluster

deployment.apps/nginx-app env updated

# 서비스를 통해 포트를 노출
kubectl expose deployment nginx-app --port=80 --name=nginx-http

service "nginx-http" exposed

kubectl을 사용하면, N개의 파드가 nginx를 실행하도록 디플로이먼트를 생성할 수 있다. 여기서 N은 스펙에 명시된 레플리카 수이며, 기본값은 1이다. 또한 파드의 레이블과 셀럭터를 사용하여 서비스를 생성할 수 있다. 자세한 내용은 클러스터 내 애플리케이션에 접근하기 위해 서비스 사용하기를 참고한다.

기본적으로 이미지는 docker run -d ... 와 비슷하게 백그라운드로 실행된다. 포그라운드로 실행하려면 kubectl run을 이용하여 파드를 생성한다.

kubectl run [-i] [--tty] --attach <name> --image=<image>

docker run ... 과 달리 --attach 를 지정하면 표준 입력(stdin), 표준 출력(stdout) 및 표준 오류(stderr)가 붙는다. 연결된(attached) 스트림을 제어할 수 없다(docker -a ...). 해당 컨테이너에서 분리(detach)하려면 이스케이프 시퀀스(escape sequence) Ctrl+P를 입력한 다음 Ctrl+Q를 입력한다.

docker ps

현재 실행 중인 목록을 보기 위해서는 kubectl get을 참고한다.

docker:

docker ps -a

CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS                     PORTS                NAMES
14636241935f        ubuntu:16.04        "echo test"              5 seconds ago        Exited (0) 5 seconds ago                        cocky_fermi
55c103fa1296        nginx               "nginx -g 'daemon of…"   About a minute ago   Up About a minute          0.0.0.0:80->80/tcp   nginx-app

kubectl:

kubectl get po

NAME                        READY     STATUS      RESTARTS   AGE
nginx-app-8df569cb7-4gd89   1/1       Running     0          3m
ubuntu                      0/1       Completed   0          20s

docker attach

이미 실행 중인 컨테이너에 연결하려면 kubectl attach를 참고한다.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   5 minutes ago       Up 5 minutes        0.0.0.0:80->80/tcp   nginx-app

docker attach 55c103fa1296
...

kubectl:

kubectl get pods

NAME              READY     STATUS    RESTARTS   AGE
nginx-app-5jyvm   1/1       Running   0          10m

kubectl attach -it nginx-app-5jyvm
...

컨테이너에서 분리하려면 이스케이프 시퀀스 Ctrl+P를 입력한 다음 Ctrl+Q를 입력한다.

docker exec

컨테이너에서 커맨드를 실행하려면 kubectl exec를 참고한다.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   6 minutes ago       Up 6 minutes        0.0.0.0:80->80/tcp   nginx-app

docker exec 55c103fa1296 cat /etc/hostname

55c103fa1296

kubectl:

kubectl get po

NAME              READY     STATUS    RESTARTS   AGE
nginx-app-5jyvm   1/1       Running   0          10m

kubectl exec nginx-app-5jyvm -- cat /etc/hostname

nginx-app-5jyvm

대화형 커맨드를 사용한다.

docker:

docker exec -ti 55c103fa1296 /bin/sh
# exit

kubectl:

kubectl exec -ti nginx-app-5jyvm -- /bin/sh
# exit

자세한 내용은 실행 중인 컨테이너의 셸 얻기를 참고한다.

docker logs

실행 중인 프로세스의 표준 입력(stdout)/표준 오류(stderr)를 수행하려면 kubectl logs를 참고한다.

docker:

docker logs -f a9e

192.168.9.1 - - [14/Jul/2015:01:04:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.35.0" "-"
192.168.9.1 - - [14/Jul/2015:01:04:03 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.35.0" "-"

kubectl:

kubectl logs -f nginx-app-zibvs

10.240.63.110 - - [14/Jul/2015:01:09:01 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"
10.240.63.110 - - [14/Jul/2015:01:09:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"

파드와 컨테이너에는 근소한 차이가 있다. 기본적으로 파드는 프로세스가 종료되어도 종료되지 않는다. 대신 파드가 프로세스를 다시 시작한다. 이는 도커의 실행 옵션인 --restart=always와 유사하지만, 한 가지 큰 차이점이 있다. 도커에서는 프로세스의 각 호출에 대한 출력이 연결되지만, 쿠버네티스의 경우 각 호출은 별개다. 쿠버네티스에서 이전 실행의 출력 내용을 보려면 다음을 수행한다.

kubectl logs --previous nginx-app-zibvs

10.240.63.110 - - [14/Jul/2015:01:09:01 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"
10.240.63.110 - - [14/Jul/2015:01:09:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"

자세한 정보는 로깅 아키텍처를 참고한다.

docker stop 과 docker rm

실행 중인 프로세스를 중지하고 삭제하려면 kubectl delete을 참고한다.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS              PORTS                         NAMES
a9ec34d98787        nginx               "nginx -g 'daemon of"  22 hours ago        Up 22 hours         0.0.0.0:80->80/tcp, 443/tcp   nginx-app

docker stop a9ec34d98787

a9ec34d98787

docker rm a9ec34d98787

a9ec34d98787

kubectl:

kubectl get deployment nginx-app

NAME         READY   UP-TO-DATE   AVAILABLE   AGE
nginx-app    1/1     1            1           2m

kubectl get po -l app=nginx-app

NAME                         READY     STATUS    RESTARTS   AGE
nginx-app-2883164633-aklf7   1/1       Running   0          2m

kubectl delete deployment nginx-app

deployment "nginx-app" deleted

kubectl get po -l app=nginx-app
# 아무것도 반환하지 않는다

docker login

kubectl은 docker login와 직접적인 유사점은 없다. 프라이빗 레지스트리와 함께 쿠버네티스를 사용하려면 프라이빗 레지스트리 사용을 참고한다.

docker version

클라이언트와 서버의 버전을 가져오려면 kubectl version을 참고한다.

docker:

docker version

Client version: 1.7.0
Client API version: 1.19
Go version (client): go1.4.2
Git commit (client): 0baf609
OS/Arch (client): linux/amd64
Server version: 1.7.0
Server API version: 1.19
Go version (server): go1.4.2
Git commit (server): 0baf609
OS/Arch (server): linux/amd64

kubectl:

kubectl version

Client Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}

docker info

환경 및 설정에 대한 자세한 정보는 kubectl cluster-info를 참고한다.

docker:

docker info

Containers: 40
Images: 168
Storage Driver: aufs
 Root Dir: /usr/local/google/docker/aufs
 Backing Filesystem: extfs
 Dirs: 248
 Dirperm1 Supported: false
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.13.0-53-generic
Operating System: Ubuntu 14.04.2 LTS
CPUs: 12
Total Memory: 31.32 GiB
Name: k8s-is-fun.mtv.corp.google.com
ID: ADUV:GCYR:B3VJ:HMPO:LNPQ:KD5S:YKFQ:76VN:IANZ:7TFV:ZBF4:BYJO
WARNING: No swap limit support

kubectl:

kubectl cluster-info

Kubernetes master is running at https://203.0.113.141
KubeDNS is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/kube-dns/proxy
kubernetes-dashboard is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/kubernetes-dashboard/proxy
Grafana is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-grafana/proxy
Heapster is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-heapster/proxy
InfluxDB is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-influxdb/proxy

10.5 - kubectl 사용 규칙

kubectl에 대한 권장 사용 규칙.

재사용 가능한 스크립트에서 kubectl 사용

스크립트의 안정적인 출력을 위해서

• -o name, -o json, -o yaml, -o go-template 혹은 -o jsonpath와 같은 머신 지향(machine-oriented) 출력 양식 중 하나를 요청한다.
• 예를 들어 jobs.v1.batch/myjob과 같이 전체 버전을 사용한다. 이를 통해 kubectl이 시간이 지남에 따라 변경될 수 있는 기본 버전을 사용하지 않도록 한다.
• 문맥, 설정 또는 기타 암묵적 상태에 의존하지 않는다.

서브리소스

• kubectl의 get, patch, edit 및 replace와 같은 명령어에서 서브리소스를 지원하는 모든 리소스에 대해 --subresource 알파 플래그를 사용하여 서브리소스를 조회하고 업데이트할 수 있다. 현재, status와 scale 서브리소스만 지원된다.
• 서브리소스에 대한 API 계약은 전체 리소스와 동일하다. status 서브리소스를 새 값으로 업데이트해도, 컨트롤러에서 서브리소스를 잠재적으로 다른 값으로 조정할 수 있다는 점을 염두에 두어야 한다.

모범 사례

kubectl run

kubectl run으로 infrastructure as code를 충족시키기 위해서

• 버전이 명시된 태그로 이미지를 태그하고 그 태그를 새로운 버전으로 이동하지 않는다. 예를 들어, :latest가 아닌 :v1234, v1.2.3, r03062016-1-4를 사용한다(자세한 정보는 구성 모범 사례를 참고한다).
• 많은 파라미터가 적용된 이미지를 위한 스크립트를 작성한다.
• 필요하지만 kubectl run 플래그를 통해 표현할 수 없는 기능은 구성 파일을 소스 코드 버전 관리 시스템에 넣어서 전환한다.

--dry-run 플래그를 사용하여 실제로 제출하지 않고 클러스터로 보낼 오브젝트를 미리 볼 수 있다.

kubectl apply

• kubectl apply를 사용해서 리소스를 생성하거나 업데이트 할 수 있다. kubectl apply를 사용하여 리소스를 업데이트하는 방법에 대한 자세한 정보는 Kubectl 책을 참고한다.

11 - 컴포넌트 도구

11.1 - 기능 게이트

이 페이지에는 관리자가 다른 쿠버네티스 컴포넌트에서 지정할 수 있는 다양한 기능 게이트에 대한 개요가 포함되어 있다.

기능의 단계(stage)에 대한 설명은 기능 단계를 참고한다.

개요

기능 게이트는 쿠버네티스 기능을 설명하는 일련의 키=값 쌍이다. 각 쿠버네티스 컴포넌트에서 --feature-gates 커맨드 라인 플래그를 사용하여 이러한 기능을 켜거나 끌 수 있다.

각 쿠버네티스 컴포넌트를 사용하면 해당 컴포넌트와 관련된 기능 게이트 집합을 활성화 또는 비활성화할 수 있다. 모든 컴포넌트에 대한 전체 기능 게이트 집합을 보려면 -h 플래그를 사용한다. kubelet과 같은 컴포넌트의 기능 게이트를 설정하려면, 기능 쌍 목록에 지정된 --feature-gates 플래그를 사용한다.

--feature-gates=...,GracefulNodeShutdown=true

다음 표는 다른 쿠버네티스 컴포넌트에서 설정할 수 있는 기능 게이트를 요약한 것이다.

• "도입" 열에는 기능이 소개되거나 릴리스 단계가 변경될 때의 쿠버네티스 릴리스가 포함된다.
• "종료" 열이 비어 있지 않으면, 여전히 기능 게이트를 사용할 수 있는 마지막 쿠버네티스 릴리스가 포함된다.
• 기능이 알파 또는 베타 상태인 경우, 알파/베타 기능 게이트 테이블에서 나열된 기능을 찾을 수 있다.
• 기능이 안정된 경우 해당 기능에 대한 모든 단계를 승급(graduated)/사용 중단(deprecated) 기능 게이트 테이블에 나열할 수 있다.
• 승급/사용 중단 기능 게이트 테이블에는 사용 중단된 기능과 철회(withdrawn) 기능의 목록도 있다.

알파 또는 베타 기능을 위한 기능 게이트