쿠버네티스 오브젝트

이 페이지는 쿠버네티스 오브젝트가 쿠버네티스 API에서 어떻게 표현되는지와 이를 .yaml 형식으로 작성하는 방법을 설명한다.

쿠버네티스 오브젝트 이해하기

쿠버네티스 오브젝트는 쿠버네티스 시스템의 영속성을 가진 엔티티이다. 쿠버네티스는 이러한 엔티티를 사용하여 클러스터의 상태를 나타낸다. 구체적으로, 다음을 설명할 수 있다.

• 어떤 컨테이너화된 애플리케이션이 실행 중인지 (그리고 어떤 노드에서 실행되는지)
• 해당 애플리케이션에서 사용 가능한 리소스
• 재시작 정책, 업그레이드, 내결함성과 같은 애플리케이션의 동작 방식에 대한 정책

쿠버네티스 오브젝트는 "의도의 기록"이다. 오브젝트를 생성하면, 쿠버네티스 시스템은 오브젝트가 존재하도록 지속적으로 동작한다. 오브젝트를 생성한다는 것은 곧 쿠버네티스 시스템에 클러스터의 워크로드가 어떤 모습이어야 하는지를 알려주는 것이며, 이것이 클러스터의 의도한 상태(desired state) 이다.

쿠버네티스 오브젝트를 생성, 수정 또는 삭제하려면 쿠버네티스 API를 사용해야 한다. kubectl 명령줄 인터페이스를 사용하면, 예를 들어, CLI가 필요한 쿠버네티스 API 호출을 대신 수행한다. 또한 클라이언트 라이브러리 중 하나를 이용해 직접 작성한 프로그램에서 쿠버네티스 API를 호출할 수 있다.

오브젝트 명세(spec)과 상태(status)

대부분의 쿠버네티스 오브젝트에는 오브젝트 구성을 정의하는 spec 와 status 두 가지 중첩 필드가 있다. spec을 가진 오브젝트의 경우, 오브젝트를 생성할 때 이를 설정해야 하며, 리소스에 원하는 특성에 대한 설명을 제공해야 한다. 이를 의도한 상태 라고 한다.

status는 쿠버네티스 시스템과 그 컴포넌트가 제공하고 업데이트하는 오브젝트의 현재 상태 를 설명한다. 쿠버네티스 컨트롤 플레인 은 모든 오브젝트의 실제 상태가 사용자가 제공한 원하는 상태와 일치하도록 지속적이고 능동적으로 관리한다.

예를 들어, 쿠버네티스에서 디플로이먼트(Deployment)는 클러스터에서 실행 중인 애플리케이션을 나타낼 수 있는 오브젝트이다. 디플로이먼트를 생성할 때, 디플로이먼트 spec을 설정하여 애플리케이션 복제본 세 개를 실행하도록 지정할 수 있다. 쿠버네티스 시스템은 디플로이먼트 명세를 읽고 원하는 애플리케이션 인스턴스 세 개를 시작하며, 명세에 맞게 상태를 업데이트 한다. 인스턴스 중 하나라도 실패하면 (상태 변경), 쿠버네티스 시스템은 명세와 상태 차이에 대응하여 수정 작업을 수행한다. 이 경우에는 대체 인스턴스를 시작한다.

오브젝트 명세, 상태, 그리고 메타데이터에 대한 자세한 내용은 쿠버네티스 API 컨벤션을 참고한다.

쿠버네티스 오브젝트 설명

쿠버네티스에서 오브젝트를 생성할 때는 원하는 상태를 설명하는 오브젝트 명세와 오브젝트에 대한 기본 정보 (예: 이름)을 제공해야 한다. 쿠버네티스 API를 사용하여 오브젝트를 생성할 때 (직접 또는 kubectl을 통해), 해당 API 요청은 요청 본문에 해당 정보를 JSON 형식으로 포함해야 한다. 대부분의 경우, kubectl에 매니페스트 라는 파일로 정보를 제공한다. 관례적으로, 매니페스트는 YAML 형식이다 (JSON 형식을 사용할 수도 있다). kubectl과 같은 도구는 HTTP를 통해 API 요청을 할 때 매니페스트의 정보를 JSON이나 다른 지원되는 직렬화 형식으로 변환한다.

다음은 쿠버네티스 배포에 필요한 필드와 오브젝트 명세를 보여주는 매니페스트 예시이다.

application/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # tells deployment to run 2 pods matching the template
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

위와 같은 매니페스트 파일을 사용하여 디플로이먼트를 생성하는 한 가지 방법은 kubectl 명령줄 인터페이스에서 kubectl apply 명령을 사용하여 .yaml 파일을 인수로 전달하는 것이다. 예를 들면 다음과 같다.

kubectl apply -f https://k8s.io/examples/application/deployment.yaml

출력은 다음과 유사하다.

deployment.apps/nginx-deployment created

필수 필드

생성하려는 쿠버네티스 오브젝트의 매니페스트 (YAML 또는 JSON 파일)에서 다음 필드에 대한 값을 설정해야 한다.

• apiVersion - 이 오브젝트를 생성하는 데 사용하는 쿠버네티스 API 버전
• kind - 생성하려는 오브젝트 종류
• metadata - name 문자열, UID 및 선택적인 namespace을 포함하여 오브젝트를 고유하게 식별하는 데 도움이 되는 데이터
• spec - 오브젝트에 대해 원하는 상태

오브젝트 spec의 정확한 형식은 모든 쿠버네티스 오브젝트마다 다르며, 해당 오브젝트에 고유한 중첩 필드를 포함한다. 쿠버네티스 API 래퍼런스를 통해 쿠버네티스를 사용하여 생성할 수 있는 모든 오브젝트 명세 형식을 찾을 수 있다.

예를 들어, 파드 API 레퍼런스의 spec 필드를 참조한다. 각 파드에 대해, .spec 필드는 파드와 원하는 상태 (예: 해당 파드 내 각 컨테이너의 컨테이너 이미지 이름)을 지정한다. 오브젝트 명세의 또 다른 예로는 스테이트풀셋(StatefulSet) API의 spec 필드가 있다. 스테이트풀셋을 위해, .spec 필드는 스테이트풀셋과 원하는 상태를 지정한다. 스테이트풀셋의 .spec 내에는 파드 오브젝트에 대한 템플릿이 있다. 이 템플릿은 스테이트풀셋 컨트롤러가 스테이트풀셋 명세를 충족하기 위해 생성할 파드를 설명한다. 다양한 유형의 오브젝트는 서로 다른 .status을 가진다. 다시 말하자면, API 래퍼런스 페이지에서는 해당 .status 필드의 구조와 각 유형의 오브젝트에 대한 내용을 자세히 설명한다.

서버 측 필드 유효성 검사

쿠버네티스 v1.25부터, API 서버는 오브젝트에서 인식되지 않거나 중복된 필드를 감지하는 서버 측 필드 유효성 검사 를 제공한다. 서버 측에서 kubectl --validate 의 모든 기능을 제공한다.

kubectl 도구는 --validate 플래그를 사용하여 필드 유효성 검사 수준을 설정한다. ignore, warn, 또는 strict 값을 사용할 수 있으며, true (strict와 동일) 와 false (ignore와 동일) 값도 사용할 수 있다. kubectl 의 기본 유효성 검사 설정은 --validate=true이다.

Strict

엄격한 필드 검증, 검증 실패 시 오류 발생

Warn

필드 검증이 수행되지만, 오류는 요청 실패가 아닌 경고로 표시된다.

Ignore

서버 측 필드 검증이 수행되지 않는다.

kubectl이 필드 검증을 지원하려는 API 서버에 연결할 수 없는 경우, 클라이언트 측 검증을 사용한다. 쿠버네티스 1.27 이상 버전은 항상 필드 검증을 제공하지만, 이전 쿠버네티스 릴리즈에서는 그렇지 않을 수 있다. 클러스터가 v1.27 보다 이전 버전인 경우, 쿠버네티스 버전에 대한 문서를 확인한다.

다음 내용

쿠버네티스를 처음 접한다면, 다음 내용을 자세히 참고한다.

• 쿠버네티스의 가장 중요한 기본 오브젝트인 파드.
• 디플로이먼트 오브젝트.
• 쿠버네티스 컨트롤러.
• kubectl 과 kubectl 명령어.

쿠버네티스 오브젝트 관리는 kubectl 를 사용하여 오브젝트를 관리하는 방법에 대해 설명한다. 아직 설치되어 있지 않다면, kubectl 설치하기가 필요할 수 있다.

전반적으로 쿠버네티스 API 대해 알아보려면 다음을 방문한다.

• 쿠버네티스 API 개요

쿠버네티스의 오브젝트에 대해 더 깊이 이해하려면, 이 섹션의 다른 페이지를 읽어본다.