---
title: 03. kubespray 배포 가이드
date: 2026-06-29
type: guide
domain: k8s
tags: [etcd, kubespray, kubernetes, deployment]
---


## kubespray 개요

kubespray는 Ansible 기반의 프로덕션급 Kubernetes 클러스터 배포 도구입니다.

```
kubespray (Ansible Playbook)
    └── cluster.yml
        ├── 부트스트랩 (python, pip 설치)
        ├── etcd 클러스터 구성 (3-node)
        ├── kube-apiserver, kube-scheduler, kube-controller-manager
        ├── kubelet, kube-proxy
        └── CNI (Calico)
```

## kubespray Clone 및 환경 구성

```bash
cd /home/jinsoo/Documents/k8s-etcd-lab

# kubespray clone
git clone https://github.com/kubernetes-sigs/kubespray.git /tmp/kubespray-src

# 인벤토리 복사
cp -rfp /tmp/kubespray-src/inventory/sample kubespray/inventory/k8s-etcd-lab

# Python 가상환경 활성화 후 의존성 설치
source .venv/bin/activate
pip install -r /tmp/kubespray-src/requirements.txt

# ansible 연결 테스트
ansible all -i kubespray/inventory/k8s-etcd-lab/hosts.yaml \
    -m ping \
    --private-key ~/.ssh/k8s-lab \
    -u ubuntu
```

## 인벤토리 구조

`kubespray/inventory/k8s-etcd-lab/hosts.yaml` 파일을 사용합니다.

```yaml
# 3개 노드 모두 control-plane + etcd + worker 역할
all:
  hosts:
    k8s-ctrl1:
      ansible_host: 203.0.113.11
    k8s-ctrl2:
      ansible_host: 203.0.113.12
    k8s-ctrl3:
      ansible_host: 203.0.113.13
  children:
    kube_control_plane:
      hosts: [k8s-ctrl1, k8s-ctrl2, k8s-ctrl3]
    etcd:
      hosts: [k8s-ctrl1, k8s-ctrl2, k8s-ctrl3]
    kube_node:
      hosts: [k8s-ctrl1, k8s-ctrl2, k8s-ctrl3]
```

## 주요 설정값 (group_vars)

### k8s-cluster.yml 핵심 설정

| 항목 | 값 | 이유 |
|------|----|------|
| `kube_version` | v1.31.x | 최신 stable |
| `container_manager` | containerd | 표준 |
| `network_plugin` | calico | 안정적, eBPF 지원 |
| `kube_proxy_mode` | iptables | 기본값, 실험 용이 |
| `etcd_deployment_type` | host | VM 자체에 etcd 바이너리 직접 설치 (컨테이너 아님 → 직접 조작 용이) |

> `etcd_deployment_type: host` 설정 이유:
> etcd를 컨테이너로 올리면 실험 시 `etcdctl` 접근이 번거롭습니다.
> host 바이너리로 설치하면 `systemctl stop etcd` 등으로 직접 제어 가능합니다.

## 클러스터 배포 실행

```bash
cd /tmp/kubespray-src
source /home/jinsoo/Documents/k8s-etcd-lab/.venv/bin/activate

# 전체 클러스터 배포 (약 20~30분 소요)
ansible-playbook \
    -i /home/jinsoo/Documents/k8s-etcd-lab/kubespray/inventory/k8s-etcd-lab/hosts.yaml \
    --private-key ~/.ssh/k8s-lab \
    -u ubuntu \
    -b \
    cluster.yml

# 특정 태그만 실행 (재배포 시 빠름)
ansible-playbook ... --tags "etcd"
ansible-playbook ... --tags "master"
```

## 배포 후 검증

```bash
# kubeconfig 가져오기
ssh -i ~/.ssh/k8s-lab ubuntu@203.0.113.11 \
    "sudo cat /etc/kubernetes/admin.conf" > ~/.kube/k8s-etcd-lab.conf

export KUBECONFIG=~/.kube/k8s-etcd-lab.conf

# 노드 상태 확인
kubectl get nodes -o wide

# 예상 출력
# NAME         STATUS   ROLES                  AGE   VERSION
# k8s-ctrl1    Ready    control-plane,master   5m    v1.31.x
# k8s-ctrl2    Ready    control-plane,master   5m    v1.31.x
# k8s-ctrl3    Ready    control-plane,master   5m    v1.31.x

# etcd 클러스터 상태 확인
ssh -i ~/.ssh/k8s-lab ubuntu@203.0.113.11 \
    "sudo ETCDCTL_API=3 etcdctl \
        --endpoints=https://127.0.0.1:2379 \
        --cacert=/etc/ssl/etcd/ssl/ca.pem \
        --cert=/etc/ssl/etcd/ssl/member-k8s-ctrl1.pem \
        --key=/etc/ssl/etcd/ssl/member-k8s-ctrl1-key.pem \
        member list -w table"

# 예상 출력
# +------------------+---------+-----------+----------------------------+----------------------------+------------+
# |        ID        | STATUS  |   NAME    |         PEER ADDRS         |        CLIENT ADDRS        | IS LEARNER |
# +------------------+---------+-----------+----------------------------+----------------------------+------------+
# | xxxxxxxxxxxxxxx1 | started | k8s-ctrl1 | https://203.0.113.11:2380 | https://203.0.113.11:2379 |      false |
# | xxxxxxxxxxxxxxx2 | started | k8s-ctrl2 | https://203.0.113.12:2380 | https://203.0.113.12:2379 |      false |
# | xxxxxxxxxxxxxxx3 | started | k8s-ctrl3 | https://203.0.113.13:2380 | https://203.0.113.13:2379 |      false |

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

## etcd 인증서 경로 (kubespray host 방식)

```
/etc/ssl/etcd/ssl/
├── ca.pem                         # CA 인증서
├── member-k8s-ctrl1.pem           # ctrl1 멤버 인증서
├── member-k8s-ctrl1-key.pem       # ctrl1 멤버 키
├── member-k8s-ctrl2.pem
├── member-k8s-ctrl2-key.pem
└── member-k8s-ctrl3.pem
```

## etcdctl alias 설정 (ctrl1 기준)

SSH 접속 후 다음을 ~/.bashrc에 추가하면 편리합니다.

```bash
# ctrl1에 SSH 접속 후
cat >> ~/.bashrc <<'EOF'
alias etcdctl='sudo ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/ssl/etcd/ssl/ca.pem \
  --cert=/etc/ssl/etcd/ssl/member-k8s-ctrl1.pem \
  --key=/etc/ssl/etcd/ssl/member-k8s-ctrl1-key.pem'
EOF
source ~/.bashrc

# 이후 간편 사용
etcdctl member list
etcdctl endpoint health
etcdctl endpoint status
```