5.3.3 K3s 환경 확인 및 kubectl 설정

이전 단계에서 K3s 설치 스크립트를 성공적으로 실행하고, systemctl status k3s 명령을 통해 K3s 서비스가 활발하게 실행 중임을 확인했습니다. 이는 우리 로컬 시스템 안에 쿠버네티스의 심장이 뛰기 시작했다는 신호입니다. 하지만 심장이 뛰는 것만으로는 충분하지 않죠. 우리는 이제 이 심장, 즉 K3s 클러스터와 실제로 대화하고 명령을 내릴 수 있는 소통 채널을 구축해야 합니다.

Rancher Desktop을 사용할 때는 이 과정이 대부분 자동으로 처리되었지만, K3s를 직접 설치한 경우에는 우리가 직접 kubectl 명령줄 도구가 새로 설치된 K3s 클러스터를 인식하고 통신할 수 있도록 설정해주는 작업이 필요합니다. 이 과정은 쿠버네티스 클라이언트가 어떻게 클러스터에 연결되는지에 대한 기본적인 이해를 돕는 매우 중요한 단계이므로, 조금 더 집중해서 따라와 주시기 바랍니다. 또한, 설정이 완료된 후에는 클러스터가 정말로 건강하게 작동하는지 최종적으로 점검하는 확인 작업도 함께 진행합니다.

5.3.3.1 Kubeconfig 파일 위치

우리가 kubectl이라는 도구를 사용하여 쿠버네티스 클러스터와 상호작용할 수 있는 것은, kubectl이 해당 클러스터에 접속하는 데 필요한 모든 정보(어디로 접속해야 하는지, 어떤 인증 정보를 사용해야 하는지 등*를 알고 있기 때문입니다. 이 중요한 접속 정보들을 담고 있는 특별한 설정 파일을 바로 Kubeconfig 파일이라고 부릅니다. 마치 우리가 특정 건물에 들어가기 위해 건물의 주소(클러스터 API 서버 주소), 출입증(사용자 인증서 또는 토큰), 그리고 어떤 사무실로 가야 할지(네임스페이스) 정보가 필요한 것처럼, Kubeconfig 파일은 kubectl에게 이러한 필수 정보들을 제공하는 ‘마스터 키’ 또는 ‘출입증 및 주소록’과 같은 역할을 합니다.

K3s는 설치 과정에서, 자신이 생성한 클러스터에 접속하기 위한 전용 Kubeconfig 파일을 자동으로 생성하여 특정 위치에 저장해 둡니다. K3s 설치 스크립트를 사용하여 서버 모드로 설치했을 경우, 이 Kubeconfig 파일이 생성되는 기본 위치는 바로 다음과 같습니다.

클립보드에 복사

이 k3s.yaml 파일 안에는 새로 생성된 로컬 K3s 클러스터의 API 서버 주소(보통 https://127.0.0.1:6443), 클러스터에 접근하기 위한 클라이언트 인증서와 키 정보 등이 YAML 형식으로 기록되어 있습니다.

중요한 점은 이 파일이 시스템 디렉토리(/etc) 아래에 생성되기 때문에, 기본적으로는 오직 관리자(root) 사용자만이 읽기 권한을 가지고 있다는 것입니다. 일반 사용자 계정으로는 이 파일에 직접 접근하거나 내용을 보려고 하면 ‘Permission denied'(권한 거부) 오류가 발생할 가능성이 높습니다. 이는 다음 단계에서 kubectl 접근 권한을 설정할 때 우리가 고려해야 할 중요한 사항입니다.

우선, 터미널에서 sudo cat /etc/rancher/k3s/k3s.yaml 명령어를 사용하여 (관리자 권한으로 파일 내용을 확인) 이 파일이 실제로 존재하는지, 그리고 어떤 내용으로 구성되어 있는지 한번 살펴보는 것도 좋습니다.

5.3.3.2 kubectl 접근 권한 설정

이제 K3s 클러스터 접속 정보가 담긴 k3s.yaml 파일의 위치를 알았으니, 다음 과제는 kubectl 명령어가 이 파일을 사용하여 K3s 클러스터와 통신하도록 설정하는 것입니다. kubectl은 기본적으로 현재 사용자의 홈 디렉토리 아래에 있는 ~/.kube/config 파일을 자신의 기본 설정 파일로 사용하려고 시도합니다. 따라서 /etc/rancher/k3s/k3s.yaml 에 있는 K3s 클러스터 정보를 kubectl이 인식하도록 만들어 주어야 합니다. 또한, 앞서 언급했듯이 /etc/rancher/k3s/k3s.yaml 파일의 접근 권한 문제도 해결해야 합니다.

kubectl이 특정 Kubeconfig 파일을 사용하도록 설정하는 방법은 여러 가지가 있지만, 여기서는 가장 일반적이고 실용적인 방법들을 중심으로 설명하겠습니다.

방법 1: –kubeconfig 플래그 직접 사용 (매번 지정)

가장 간단한 방법은 kubectl 명령어를 실행할 때마다 –kubeconfig 플래그를 사용하여 Kubeconfig 파일의 경로를 명시적으로 지정하는 것입니다. 하지만 이 방법은 /etc/rancher/k3s/k3s.yaml 파일에 대한 읽기 권한이 필요하므로, sudo를 함께 사용해야 할 가능성이 높습니다.

클립보드에 복사

이 방식은 매번 긴 플래그를 입력해야 하고 sudo를 사용해야 하는 번거로움 때문에, 일상적인 사용에는 다소 불편할 수 있습니다. 하지만 임시로 특정 클러스터에 명령을 내리거나 스크립트 내에서 명시적으로 지정할 때는 유용할 수 있습니다.

방법 2: KUBECONFIG 환경 변수 설정 (세션 또는 프로필 기반)

또 다른 방법은 KUBECONFIG라는 환경 변수에 사용할 Kubeconfig 파일의 경로를 설정하는 것입니다. kubectl은 이 환경 변수가 설정되어 있으면, 기본 경로(~/.kube/config) 대신 이 환경 변수에 지정된 경로의 파일을 사용합니다.

이 방법 역시 파일 접근 권한 문제가 있으므로, 가장 쉬운 해결책은 K3s Kubeconfig 파일을 일반 사용자가 접근 가능한 위치로 복사하고 권한을 변경한 뒤, 그 복사본의 경로를 환경 변수에 설정하는 것입니다.

  1. Kubeconfig 파일 복사 및 권한 변경:
    클립보드에 복사
    $(id -u)는 현재 사용자의 User ID, $(id -g)는 현재 사용자의 Group ID를 자동으로 가져오는 셸 명령어입니다. chmod 600은 파일 소유자에게만 읽기(4)와 쓰기(2) 권한을 부여하고 다른 모든 사용자의 접근을 막는 설정입니다.
  2. KUBECONFIG 환경 변수 설정:
    클립보드에 복사
    이제 이 터미널 세션에서는 kubectl 명령어가 ~/.kube/k3s.yaml 파일을 기본으로 사용하게 됩니다. 예를 들어 kubectl get nodes 명령을 sudo 없이 실행할 수 있습니다.이 환경 변수 설정은 현재 터미널 세션에만 유효합니다. 터미널을 닫거나 새 터미널을 열면 다시 설정해야 합니다. 만약 항상 이 설정을 유지하고 싶다면, ~/.bashrc (Bash 셸 사용 시) 또는 ~/.zshrc (Zsh 셸 사용 시) 같은 셸 시작 파일의 맨 아래에 export KUBECONFIG=~/.kube/k3s.yaml 라인을 추가하고 셸을 다시 시작하면 됩니다.

방법 3 (권장): 기본 Kubeconfig 파일(~/.kube/config)에 병합 (영구적 설정)

가장 일반적으로 권장되는 방법은, K3s 클러스터 정보를 여러분의 기본 ~/.kube/config 파일에 병합(merge)하는 것입니다. 이렇게 하면 kubectl이 다른 설정 없이도 K3s 클러스터를 인식하고, 필요하다면 여러 클러스터 정보(예: 로컬 K3s, 원격 개발 클러스터 등)를 하나의 파일 안에서 관리하며 컨텍스트를 전환해가며 사용할 수 있습니다.

이 작업 역시 K3s Kubeconfig 파일의 권한 문제가 있으므로, 방법 2의 1단계(파일 복사 및 권한 변경)를 먼저 수행해야 합니다. ~/.kube/k3s.yaml 파일이 준비되었다고 가정하고 다음 단계를 진행합니다.

  1. (중요!) 기존 ~/.kube/config 파일 백업: 만약 기존에 다른 클러스터 정보가 ~/.kube/config 파일에 있었다면, 병합 과정에서 실수가 발생할 경우를 대비해 반드시 백업해 둡니다.
    클립보드에 복사
    이는 현재 시간을 포함한 백업 파일을 생성합니다. 만약 ~/.kube/config 파일이 아예 없다면 이 단계는 건너뛰어도 됩니다.
  2. Kubeconfig 파일 내용 병합: kubectl config view 명령어를 사용하여 여러 Kubeconfig 파일의 내용을 하나로 합칠 수 있습니다. –flatten 옵션은 모든 정보를 인라인으로 펼쳐서 단일 파일로 만들어 줍니다.
    클립보드에 복사
    만약 기존 ~/.kube/config 파일이 없었다면, 단순히 복사한 k3s.yaml 파일을 config라는 이름으로 바꾸거나 복사해도 됩니다: cp ~/.kube/k3s.yaml ~/.kube/config
  3. 현재 컨텍스트 확인 및 설정 (선택적): 병합 후, kubectl이 어떤 클러스터를 기본 대상으로 사용할지 확인하고 필요하면 변경할 수 있습니다.
    • 사용 가능한 모든 컨텍스트 목록 보기:
      클립보드에 복사
      출력 목록에서 CURRENT 열에 * 표시가 있는 것이 현재 기본 컨텍스트입니다. K3s에서 생성된 컨텍스트는 보통 default 또는 k3s-local과 같은 이름을 가질 수 있습니다.
    • 기본 컨텍스트 변경 (예: 컨텍스트 이름이 k3s-local이라고 가정):
      클립보드에 복사

이제 kubectl은 별도의 플래그나 환경 변수 설정 없이도 여러분의 기본 ~/.kube/config 파일을 통해 K3s 클러스터와 통신할 준비가 되었습니다. 이 방법 3이 여러 클러스터를 관리해야 할 가능성이 있는 실제 개발 및 운영 환경에서 가장 표준적으로 사용되는 방식입니다.

이 책에서는 이후의 실습 편의를 위해 방법 3을 사용하여 ~/.kube/config 파일에 K3s 설정을 병합하고 기본 컨텍스트로 설정하는 것을 권장합니다.

5.3.3.3 클러스터 정보 및 노드 상태 확인

이제 마지막으로 우리가 직접 설치한 K3s 클러스터가 정말로 건강하게 작동하고 있는지, 그리고 kubectl 설정이 올바르게 되었는지 최종 점검을 해보겠습니다. 이는 5.2.3절에서 Rancher Desktop 환경을 확인할 때 사용했던 명령어들과 동일합니다.

  1. 클러스터 정보 확인 (kubectl cluster-info): 터미널에서 다음 명령어를 실행하여 클러스터의 핵심 컴포넌트 정보를 조회합니다.
    클립보드에 복사
  2. 노드 상태 확인 (kubectl get nodes): 다음 명령어를 실행하여 클러스터를 구성하는 노드의 상태를 확인합니다.
    클립보드에 복사
    직접 설치한 K3s 단일 노드 환경에서는 보통 다음과 유사한 출력을 기대할 수 있습니다. (NAME은 여러분의 시스템 호스트 이름일 가능성이 높습니다.)
    클립보드에 복사
    여기서 가장 중요한 것은 역시 STATUS 열이 Ready로 표시되는 것입니다. 이는 K3s 노드가 건강하며 애플리케이션 파드를 실행할 준비가 되었음을 나타냅니다. ROLES 열에서는 해당 노드가 컨트롤 플레인과 마스터 역할을 겸하고 있음을 보여줄 수 있습니다.

만약 이 두 명령어(kubectl cluster-info, kubectl get nodes)가 모두 오류 없이 성공적으로 실행되고, 특히 kubectl get nodes 결과에서 노드 상태가 Ready로 확인되었다면, 마침내 모든 과정이 성공적으로 완료된 것입니다! 여러분은 이제 openSUSE 시스템 위에 K3s를 직접 설치하고, kubectl을 통해 완벽하게 제어할 수 있는 로컬 쿠버네티스 클러스터를 성공적으로 구축했습니다.

이 과정은 Rancher Desktop을 사용할 때보다 조금 더 많은 단계를 거쳤지만, Kubeconfig 파일의 역할과 kubectl 설정 방식에 대한 더 깊은 이해를 얻는 귀중한 경험이 되었을 것입니다. 이제 이 강력하고 가벼운 K3s 클러스터 위에서 클라우드 네이티브 애플리케이션의 세계를 탐험할 준비가 되었습니다. 다음 장에서는 이 클러스터 위에 우리의 첫 번째 애플리케이션을 배포하는 실습을 진행해 보겠습니다.