이제 나도 클라우드 네이티브 전문가: 쿠버네티스 구축부터 운영 완전 정복

우리가 쿠버네티스와 통신하는 거의 모든 작업은 쿠버네티스 API를 통해 이루어진다고 여러 번 강조드렸습니다. 마치 우리가 스마트폰의 다양한 기능을 앱을 통해 사용하듯이, 쿠버네티스의 강력한 기능들 역시 잘 정의된 API를 통해 노출됩니다. 그런데 쿠버네티스는 정말 많은 기능을 제공하고, 지금도 끊임없이 새로운 기능들이 추가되고 발전하고 있습니다. 이렇게 방대하고 변화무쌍한 기능들을 뒤죽박죽으로 제공한다면 어떻게 될까요? 아마 사용자들은 큰 혼란을 겪을 것이고, 시스템의 안정성도 보장하기 어려울 겁니다.

쿠버네티스는 이러한 문제를 해결하기 위해 매우 체계적인 방법으로 API를 관리하는데, 그것이 바로 API 그룹(API Groups) 과 API 버전 관리(API Versioning) 입니다. 이 두 가지 개념 덕분에 쿠버네티스는 엄청난 확장성을 가지면서도 안정성을 유지할 수 있는 것이죠.

쿠버네티스가 처음 등장했을 때는 지금처럼 API 그룹이 다양하지 않았습니다. 대부분의 핵심 기능들이 하나의 큰 API 묶음 안에 있었죠. 하지만 쿠버네티스가 점점 더 많은 기능을 포용하고, 다양한 영역으로 확장되면서 기존 방식으로는 한계에 부딪히기 시작했습니다. 예를 들어, 애플리케이션 배포 관련 기능, 네트워크 관련 기능, 스토리지 관련 기능 등이 모두 한 곳에 섞여 있다면 새로운 기능을 추가하거나 기존 기능을 변경할 때 서로 영향을 줄 가능성이 커지고, 전체 시스템의 복잡도도 걷잡을 수 없이 증가하게 됩니다.

이러한 문제를 해결하고 쿠버네티스 API의 확장성과 안정성을 동시에 확보하기 위해 도입된 것이 바로 API 그룹과 버전 관리입니다.

API 버전 관리 (API Versioning) 는 각 API 그룹 내에서 기능의 성숙도나 변경 사항을 관리하기 위한 방법입니다. 모든 소프트웨어가 그렇듯, 쿠버네티스의 API도 처음부터 완벽할 수는 없습니다. 새로운 기능은 실험적인 단계를 거쳐 점차 안정화되고, 때로는 기존 기능이 더 나은 방식으로 개선되기도 합니다. API 버전 관리는 이러한 변화의 과정을 체계적으로 관리하여 사용자에게 예측 가능성과 안정성을 제공합니다.

쿠버네티스 API 버전은 일반적으로 다음과 같은 단계를 따릅니다:

• 알파 (Alpha) 버전 (예: v1alpha1, v2alpha1):
  • 이름에서 알 수 있듯이, 매우 초기 단계의 실험적인 버전입니다.
  • 언제든지 이전 버전과 호환되지 않는 방식으로 변경되거나 심지어 기능 자체가 삭제될 수도 있습니다.
  • 기본적으로 클러스터에서 비활성화되어 있을 수 있으며, 사용하려면 명시적으로 활성화해야 하는 경우도 있습니다.
  • 버그가 있을 가능성이 높으므로, 프로덕션 환경에서는 절대로 사용해서는 안 되며, 테스트나 기능 평가 목적으로만 사용해야 합니다.
• 베타 (Beta) 버전 (예: v1beta1, v1beta2):
  • 알파 버전보다는 충분한 테스트를 거쳐 어느 정도 안정화된 버전입니다.
  • 기능 자체는 안정적이라고 간주되지만, 정식 버전(GA)으로 가기 전에 API의 세부 명세(스키마)가 약간 변경될 가능성은 여전히 남아 있습니다. 하지만 큰 틀에서의 호환성은 유지하려고 노력합니다.
  • 많은 사용자들이 베타 버전을 사용하며 피드백을 주고, 이를 통해 기능이 더욱 다듬어집니다. 프로덕션 환경에서 사용을 고려할 수 있지만, 변경 가능성을 염두에 두고 주의 깊게 검토해야 합니다.
• 안정 (Stable) / 일반 공급 (GA, General Availability) 버전 (예: v1, v2):
  • 충분한 테스트와 검증을 거쳐 공식적으로 안정화된 버전입니다.
  • 한 번 안정 버전으로 출시되면, 장기간에 걸쳐 하위 호환성을 유지하도록 노력합니다. 즉, 이전 방식으로 작성된 설정 파일이 새로운 쿠버네티스 버전에서도 문제없이 동작하도록 보장하려고 합니다. (물론, 아주 예외적인 경우나 보안상의 이유로 변경이 있을 수는 있지만, 매우 신중하게 이루어집니다.)
  • 프로덕션 환경에서는 안정 버전을 사용하는 것이 강력히 권장됩니다.

이러한 API 그룹화와 체계적인 버전 관리를 통해, 쿠버네티스는 새로운 기능을 빠르게 도입하고 실험하면서도, 기존 사용자들에게는 안정적인 환경을 제공하는 두 마리 토끼를 모두 잡을 수 있게 됩니다. 이것이 바로 쿠버네티스가 복잡하고 거대한 시스템임에도 불구하고 지속적으로 발전하며 신뢰를 얻을 수 있는 핵심 비결 중 하나입니다.

이제 우리가 YAML 매니페스트 파일을 작성할 때 가장 먼저 마주하게 되는 apiVersion 필드가 왜 중요한지, 그리고 무엇을 의미하는지 좀 더 자세히 살펴보겠습니다. 이 apiVersion 필드는 우리가 정의하려는 쿠버네티스 오브젝트가 어떤 API 그룹의 어떤 버전을 사용하는지를 쿠버네티스 API 서버에게 알려주는 역할을 합니다. 마치 우리가 편지를 보낼 때 정확한 주소를 적어야 제대로 전달되듯이, apiVersion을 올바르게 지정해야 쿠버네티스가 우리가 원하는 작업을 정확히 이해하고 처리할 수 있습니다.

apiVersion 필드의 형식은 일반적으로 다음과 같습니다:

• GROUP/VERSION: 대부분의 API는 이러한 형식을 따릅니다. 예를 들어, 디플로이먼트를 정의할 때는 apps/v1, 크론잡을 정의할 때는 batch/v1 과 같이 API 그룹명과 버전명을 슬래시(/)로 구분하여 적습니다.
• VERSION: 아주 특별한 경우, 즉 코어(Core) API 그룹에 속하는 리소스들은 역사적인 이유로 그룹명이 생략되고 버전명만 적습니다. 예를 들어, 파드(Pod), 서비스(Service), 네임스페이스(Namespace) 등 쿠버네티스의 가장 기본적인 핵심 리소스들은 v1 이라고만 표기합니다. 이 v1은 현재 안정(Stable) 버전을 의미하며, 내부적으로는 core라는 그룹에 속하지만 편의상 생략하는 것입니다.

몇 가지 주요 API 그룹과 그 예시를 통해 apiVersion이 실제로 어떻게 사용되는지 살펴보겠습니다:

표에서 보시다시피, 각 리소스(kind)는 특정 apiVersion에 속해 있습니다. 우리가 YAML 파일에 kind: Deployment 라고 적었다면, 그에 맞는 apiVersion: apps/v1 (현재 안정 버전 기준)을 정확히 명시해주어야 합니다. 만약 apiVersion을 잘못 적거나 해당 클러스터 버전에서 지원하지 않는 apiVersion을 사용하면, kubectl apply 명령을 실행했을 때 “error: unable to recognize “your-file.yaml”: no matches for kind “Deployment” in version “wrong/v1″” 와 같은 오류 메시지를 만나게 될 것입니다.

특히 쿠버네티스 클러스터 버전을 업그레이드할 때는 주의가 필요합니다. 이전 버전에서 잘 사용하던 API 버전이 새로운 클러스터 버전에서는 지원 중단(deprecated)되거나 삭제될 수도 있기 때문입니다. 예를 들어, 과거에는 Deployment가 extensions/v1beta1 이라는 apiVersion을 사용했지만, 지금은 apps/v1으로 완전히 이전되었습니다. 따라서 클러스터 업그레이드 전에는 반드시 릴리스 노트를 확인하여 사용 중인 API 버전들이 여전히 유효한지, 변경이 필요하다면 어떻게 마이그레이션해야 하는지를 숙지해야 합니다. 이것은 안정적인 클러스터 운영을 위한 매우 중요한 실무 지식입니다.

이론적으로 API 그룹과 버전에 대해 배우는 것도 중요하지만, 실제로 내가 사용하고 있는 쿠버네티스 클러스터가 어떤 API들을 지원하는지 직접 확인해 보는 것은 더욱 중요합니다. 마치 새로운 도시에 도착해서 지도를 펼쳐보는 것처럼, kubectl 명령어를 사용하면 현재 클러스터의 ‘API 지도’를 탐험할 수 있습니다.

여기 두 가지 유용한 kubectl 명령어가 있습니다:

이 명령어는 현재 여러분이 접속한 쿠버네티스 클러스터에서 활성화되어 있는 모든 API 그룹과 버전의 목록을 보여줍니다.

터미널에서 다음 명령을 실행해 보세요

그러면 다음과 유사한 출력(클러스터 버전이나 설치된 기능에 따라 다를 수 있음)을 보실 수 있습니다:

이 목록에 나타난 apiVersion들만이 여러분의 YAML 매니페스트 파일에 유효하게 사용될 수 있는 것들입니다. 만약 특정 기능의 알파나 베타 버전을 사용하고 싶다면, 이 목록에 해당 버전이 포함되어 있는지 먼저 확인해야 합니다.

:이 명령어는 클러스터에서 사용 가능한 모든 API 리소스 종류에 대한 더욱 상세한 정보를 제공합니다. 각 리소스의 전체 이름, 짧은 이름(shortname), 소속된 API 그룹, 네임스페이스 사용 여부, 그리고 YAML 파일의 kind 필드에 사용하는 실제 이름을 알려줍니다.

터미널에서 다음 명령을 실행해 보세요.

출력은 다음과 같은 테이블 형태로 나타납니다 (일부만 발췌):

이 표를 통해 우리는 다음과 같은 유용한 정보들을 얻을 수 있습니다:

• NAME: kubectl get 명령어 등에서 사용할 수 있는 리소스의 복수형 이름입니다 (예: pods).
• SHORTNAMES: 타이핑을 줄여주는 짧은 이름입니다 (예: pods 대신 po).
• APIGROUP: 해당 리소스가 속한 API 그룹입니다. 비어 있다면 코어 그룹을 의미합니다.
• NAMESPACED: true이면 해당 리소스는 특정 네임스페이스 안에 생성되어야 하고, false이면 클러스터 전체에 적용되는 리소스(예: Node, Namespace 자체)임을 나타냅니다.
• KIND: YAML 매니페스트 파일의 kind 필드에 정확히 이 이름을 사용해야 합니다.

이 kubectl api-resources 명령어는 YAML 파일을 작성할 때 어떤 kind를 사용해야 하고, 그 kind가 어떤 APIGROUP에 속하는지, 그리고 네임스페이스를 사용하는지 등을 확인하는 데 매우 유용합니다. 예를 들어, Deployment라는 KIND를 사용하고 싶다면, 이 표에서 deployments 행을 찾아 APIGROUP이 apps이고 NAMESPACED가 true임을 알 수 있습니다. 따라서 apiVersion은 apps/v1 (또는 kubectl api-versions에서 확인된 apps 그룹의 다른 유효한 버전)을 사용하고, metadata.namespace를 지정할 수 있다는 것을 유추할 수 있습니다.

조금 더 자세한 정보를 보고 싶다면 -o wide 옵션을 추가하거나, 특정 API 그룹에 속한 리소스만 보고 싶다면 –api-group=<그룹명> 옵션을 사용할 수도 있습니다. 예를 들어, apps 그룹의 리소스만 보려면 kubectl api-resources –api-group=apps와 같이 실행하면 됩니다.

이처럼 kubectl api-versions와 kubectl api-resources 명령어는 우리가 쿠버네티스 클러스터와 ‘대화’하기 전에, 클러스터가 어떤 ‘언어'(API)를 이해하고 어떤 ‘주제'(리소스)에 대해 이야기할 수 있는지를 미리 파악할 수 있게 해주는 강력한 도구입니다.

결론적으로, 쿠버네티스의 API 그룹과 버전 관리 체계는 복잡하고 다양한 기능들을 질서정연하게 제공하고, 지속적인 발전을 가능하게 하는 핵심적인 메커니즘입니다. 우리가 YAML 매니페스트를 작성할 때 apiVersion과 kind를 정확히 명시하는 것은 이 체계를 따르는 첫걸음이며, kubectl 명령어를 통해 현재 클러스터의 API 상태를 확인하는 습관은 쿠버네티스를 더욱 효과적으로 사용하고 예기치 않은 문제를 방지하는 데 큰 도움이 될 것입니다.