guidek8s 2026-06-29etcdkubespraykubernetesdeployment

03. kubespray 배포 가이드

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 및 환경 구성

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 파일을 사용합니다.

# 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 등으로 직접 제어 가능합니다.

클러스터 배포 실행

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"

배포 후 검증

# kubeconfig 가져오기
ssh -i ~/.ssh/k8s-lab [email protected] \
    "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 [email protected] \
    "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에 추가하면 편리합니다.

# 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

Files

Raw Markdown (index.md)