---
title: "경량 쿠버네티스를 위한 K3s 설치 및 관리 가이드"
description: "K3s는 경량 쿠버네티스 배포판으로, 사전 hosts 파일 설정 후 마스터와 워커 노드에 설치 스크립트를 사용해 간단히 배포할 수 있다. 마스터 노드는 VXLAN 기반 Flannel 네트워크와 토큰 기반 인증을 설정하고, 워커 노드는 마스터 토큰을 이용해 클러스터에 참여한다. 설치 후 kubectl으로 노드와 파드 상태를 확인하고, 필요 시 제공된 제거 스크립트나 수동 절차로 완전히 삭제할 수 있다."
date: "2025-09-25"
last_modified: "2026-05-20T23:53:00.000Z"
type: "Post"
tags:
  - "install"
  - "troubleshooting"
  - "network"
categories:
  - "📗 Docs"
series:
  - "k8s"
canonical_url: "https://blog.pieroot.xyz/k3s-setup-guide"
markdown_url: "https://blog.pieroot.xyz/k3s-setup-guide.md"
---

# 경량 쿠버네티스를 위한 K3s 설치 및 관리 가이드

K3s는 경량 쿠버네티스 배포판으로, 사전 hosts 파일 설정 후 마스터와 워커 노드에 설치 스크립트를 사용해 간단히 배포할 수 있다. 마스터 노드는 VXLAN 기반 Flannel 네트워크와 토큰 기반 인증을 설정하고, 워커 노드는 마스터 토큰을 이용해 클러스터에 참여한다. 설치 후 kubectl으로 노드와 파드 상태를 확인하고, 필요 시 제공된 제거 스크립트나 수동 절차로 완전히 삭제할 수 있다.

이번에는 k3s를 설치해보겠습니다. k3s는 경량화된 쿠버네티스 배포판으로, 리소스 요구사항이 적고 설치가 간단하면서도 쿠버네티스의 기능을 대부분 제공합니다.

![image](https://blog.pieroot.xyz/api/image-proxy?id=a680c4a2-2198-4c9c-891d-cce26a0d7ec2&kind=s3&pageId=278067c0-15d0-80f1-ad04-f6a8fac7355d&source=block&blockId=2e4067c0-15d0-8018-8a15-fe24c29baa98)

![K3s 경량 Kubernetes 클러스터 아키텍처](https://blog.pieroot.xyz/api/image-proxy?id=e547ee93-aefa-43e8-926f-fb0db1423552&kind=s3&pageId=278067c0-15d0-80f1-ad04-f6a8fac7355d&source=block&blockId=5407d9b2-8772-4bee-9141-3d56b08434d8)

### 사전 설정

![K3s 설치 전 사전 설정 및 설치 흐름](https://blog.pieroot.xyz/api/image-proxy?id=1eb1996f-8e91-430e-a3f0-c827822e5736&kind=s3&pageId=278067c0-15d0-80f1-ad04-f6a8fac7355d&source=block&blockId=349139d3-bc73-408d-93c7-c4cd7211a29a)

#### 각 노드의 hosts 파일 수정

K3s 클러스터를 구성하기 전, 모든 노드에서 마스터 노드의 IP 주소를 [k3s.test.com](http://k3s.test.com/) 도메인으로 인식할 수 있도록 hosts 파일을 수정해야 합니다. 아래 단계를 따라 각 노드에서 수정해 주세요.

#### 1. 마스터 노드 IP 확인

```bash
# 마스터 노드에서 실행
ip addr show | grep inet
```

출력된 결과에서 마스터 노드의 IP 주소를 확인합니다. 예: 192.168.1.100

#### 2. hosts 파일 수정

모든 노드(마스터 및 워커 노드)에서 다음 명령어를 사용하여 hosts 파일을 수정합니다:

```bash
# 관리자 권한으로 hosts 파일 열기
sudo nano /etc/hosts

# 아래 줄을 추가 (마스터 노드 IP 주소를 실제 IP로 변경)
192.168.1.100 k3s.test.com
```

nano 대신 vi나 vim 등 다른 텍스트 편집기를 사용해도 됩니다.

#### 3. hosts 파일 적용 확인

```bash
# 설정이 적용되었는지 확인
ping k3s.test.com
```

이제 모든 노드에서 [k3s.test.com](http://k3s.test.com/) 도메인을 통해 마스터 노드와 통신할 수 있습니다. 이 설정이 완료된 후 K3s 설치 작업을 진행하세요.

### K3s 설치

```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - --flannel-backend none --token <CHANGE_K3S_TOKEN>
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --flannel-backend none" K3S_TOKEN=<CHANGE_K3S_TOKEN> sh -s -
curl -sfL https://get.k3s.io | K3S_TOKEN=<CHANGE_K3S_TOKEN> sh -s - server --flannel-backend none
# server is assumed below because there is no K3S_URL
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--flannel-backend none --token <CHANGE_K3S_TOKEN>" sh -s - 
curl -sfL https://get.k3s.io | sh -s - --flannel-backend none --token <CHANGE_K3S_TOKEN>
```

이제 우리가 사용할 K3s 설치 방법에 대해 구체적으로 설명하겠습니다.

### 우리의 K3s 설치 구성

- K3S\_URL**:** [k3s.test.com](http://k3s.test.com/)

- **네트워크 백엔드:** vxlan (Flannel VXLAN 모드)

#### 마스터 노드 설치 명령어

```bash
# 마스터 노드 설치
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" K3S_URL="https://k3s.test.com" K3S_KUBECONFIG_MODE="644" sh -s - --flannel-backend=vxlan
```

이 명령어는 다음 옵션을 사용합니다:

- **INSTALL\_K3S\_EXEC="server"**: 이 노드를 마스터(서버) 노드로 설정

- **K3S\_URL="https://k3s.test.com"**: 클러스터 API 서버의 URL 설정

- **K3S\_KUBECONFIG\_MODE="644"**: kubeconfig 파일의 권한을 644로 설정하여 일반 사용자도 접근 가능

- **--flannel-backend=vxlan**: Flannel 네트워크 백엔드로 vxlan 사용

#### 워커 노드 설치 명령어

```bash
# 워커 노드 설치 (마스터 노드에서 토큰 값 가져온 후)
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="agent --server https://k3s.test.com:6443 --token <토큰값>" sh -s - --flannel-backend=vxlan
```

워커 노드 설치 시 필요한 토큰은 마스터 노드의 `/var/lib/rancher/k3s/server/node-token` 파일에서 확인할 수 있습니다.

#### 설치 확인

설치 완료 후 클러스터 상태를 확인하려면:

```bash
# 노드 상태 확인
kubectl get nodes

# 시스템 파드 확인
kubectl get pods -n kube-system
```

### K3s 제거하는 방법

![K3s 제거 및 정리 절차](https://blog.pieroot.xyz/api/image-proxy?id=7341a951-7da5-451b-b7f4-2d409f0e5c67&kind=s3&pageId=278067c0-15d0-80f1-ad04-f6a8fac7355d&source=block&blockId=d9801b84-bbec-4391-8073-d47abd039a9b)

K3s를 설치했던 방식에 따라 제거 방법이 다릅니다. 아래는 주요 제거 방법입니다.

#### 스크립트를 이용한 제거

K3s는 설치 시 자동으로 제거 스크립트도 제공합니다.

- **서버(마스터) 노드 제거:**

```bash
/usr/local/bin/k3s-uninstall.sh
```

- **에이전트(워커) 노드 제거:**

```bash
/usr/local/bin/k3s-agent-uninstall.sh
```

#### 수동으로 정리하기

스크립트가 제대로 작동하지 않을 경우, 다음 단계를 통해 수동으로 정리할 수 있습니다:

- **서비스 중지:**

```bash
systemctl stop k3s
# 에이전트 노드의 경우
systemctl stop k3s-agent
```

- **프로세스 확인 및 종료:**

```bash
ps aux | grep k3s
# 관련 프로세스 종료
kill -9 <PID>
```

- **파일 시스템 정리:**

```bash
# 구성 파일 제거
rm -rf /etc/rancher /etc/kubernetes

# 데이터 제거 (주의: 모든 워크로드 데이터가 삭제됨)
rm -rf /var/lib/rancher /var/lib/kubelet /var/lib/cni

# 로그 제거
rm -rf /var/log/pods /var/log/containers
```

- **네트워크 인터페이스 정리:**

```bash
# Flannel 인터페이스 제거
ip link delete flannel.1
ip link delete cni0
```

#### 제거 후 확인

모든 K3s 관련 프로세스가 종료되었는지 확인합니다.

```bash
ps aux | grep k3s
systemctl status k3s
# 또는 에이전트 노드의 경우
systemctl status k3s-agent
```

이렇게 K3s를 완전히 제거하면, 시스템이 초기 상태로 돌아가며 필요한 경우 다시 설치할 수 있습니다.

### 정리

이 문서에서는 K3s의 설치 방법과 구성, 그리고 제거 방법에 대해 자세히 알아보았습니다. K3s는 경량화된 쿠버네티스 배포판으로, 간단한 설치 과정과 효율적인 리소스 사용으로 다양한 환경에서 활용할 수 있습니다.

### **핵심 정리**

✅ **사전 설정**: 모든 노드의 hosts 파일을 수정하여 마스터 노드([k3s.test.com](http://k3s.test.com/))와 통신 가능하도록 구성

✅ **마스터 노드 설치**: VXLAN 네트워크 백엔드를 사용하여 서버 모드로 설치, kubeconfig 권한 설정

✅ **워커 노드 설치**: 마스터 노드의 토큰을 사용하여 에이전트 모드로 클러스터에 참여

✅ **네트워크 구성**: Flannel VXLAN 백엔드를 통한 오버레이 네트워크 구성

✅ **제거 방법**: 자동 제거 스크립트 제공, 필요시 수동으로 서비스, 파일, 네트워크 인터페이스 정리

✅ **확인 사항**: kubectl 명령어로 노드 상태 및 시스템 파드 확인, 제거 후 프로세스 종료 검증