[kubespray] Ansible Playbook & Role 분석

Kubespray Ansible Playbook & Role 분석

• Kubespray로 Kubernetes 클러스터를 배포할 때 내부적으로 어떤 과정이 진행되는지 분석해본다.
• 총 14개의 PLAY와 559개의 TASK가 순차적으로 실행되며, 크게 4단계로 구분할 수 있다.

---

전체 설치 흐름 요약

Kubespray 설치 과정은 다음 4단계로 진행된다.

단계	목적	주요 작업
1단계	사전 준비 및 검증	Ansible 버전 확인, inventory 검증, bastion 설정, 노드 부트스트랩, fact 수집
2단계	etcd 클러스터 구축	etcd 사전 준비, worker 노드 추가, etcd 설치 및 클러스터 구성
3단계	Kubernetes 코어 설치	노드 컴포넌트 설치, control-plane 구성, kubeadm init/join, CNI 설치
4단계	부가 서비스 설치	Calico RR, Windows 패치, 애드온(CoreDNS, metrics-server), DNS 설정 정리

---

1단계: 사전 준비 및 검증

클러스터 배포 전 환경을 검증하고 노드를 준비하는 단계다.

주요 PLAY 목록

PLAY	설명
Check Ansible version	Kubespray가 지원하는 Ansible 버전인지 확인 (2.17.3 <= version < 2.18.0)
Inventory setup and validation	inventory 설정 검증: kube_control_plane, etcd 그룹 존재 여부, etcd 노드 수(홀수 권장), Pod/Service CIDR 유효성
Install bastion ssh config	Bastion(점프 호스트) 환경 지원. 미사용 시 skip
Bootstrap hosts for Ansible	모든 노드를 Ansible 실행 가능 상태로 준비: Python 설치, sudo 권한, 기본 패키지
Gather facts	Ansible fact 수집. 이후 조건 분기(예: when: ansible_os_family == "Debian")에 사용

핵심 Role

• dynamic_groups: 그룹 매칭 및 정의
• validate_inventory: inventory 정합성 검증
• bootstrap_os: OS별 초기화 (패키지 설치, hostname 설정)
• network_facts: 네트워크 정보 수집 (IP, fallback 설정)
• kubernetes/preinstall: swap 비활성화, 디렉터리 생성, sysctl 설정, NetworkManager 설정

---

2단계: etcd 클러스터 구축

Kubernetes의 상태 저장소인 etcd를 설치하고 클러스터를 구성하는 단계다.

주요 PLAY 목록

PLAY	설명
Prepare for etcd install	etcd user 생성, 디렉터리 생성, 방화벽/포트, 인증서 경로 준비
Add worker nodes to etcd play	kube_node + etcd 겸용 노드를 etcd PLAY에 추가
Install etcd	etcd binary 설치, TLS 인증서 생성, systemd 등록, 클러스터 구성

핵심 Role

• adduser: etcd 전용 사용자/그룹 생성
• etcd: 인증서 생성 및 검증, etcd 바이너리 설치, 클러스터 구성
• etcdctl_etcdutl: etcdctl, etcdutl 바이너리 설치 및 wrapper 스크립트 생성

etcd 인증서 처리 흐름

1. 첫 번째 etcd 노드에서 인증서 존재 여부 확인
2. 인증서 없으면 gen_certs 플래그 설정
3. openssl config 작성 후 인증서 생성 스크립트 실행
4. CA 인증서를 신뢰 저장소에 추가
5. 다른 노드에 동기화 필요 시 sync_certs 플래그 설정

---

3단계: Kubernetes 코어 설치

kubelet, kubectl, control-plane 컴포넌트를 설치하고 클러스터를 초기화하는 단계다.

주요 PLAY 목록

PLAY	설명
Install Kubernetes nodes	모든 노드에 공통 K8s 컴포넌트 설치 (kubelet). 클러스터 join은 아직 안 함
Install the control plane	control-plane 노드 구성: kubeadm init, 인증서, 토큰 생성
Invoke kubeadm and install a CNI	kubeadm join 실행, CNI 플러그인 설치

핵심 Role

• container-engine: containerd, runc, crictl, nerdctl 설치 및 설정
• download: 바이너리 및 컨테이너 이미지 다운로드
• kubernetes/node: kubelet 설치, cgroup driver 설정, br_netfilter 활성화
• kubernetes/control-plane: kubeadm init/join, kubectl 설치, 인증서 갱신 cron 설정
• kubernetes/client: kubeconfig 복사, API 서버 대기
• kubernetes-apps/cluster_roles: ClusterRole, PriorityClass 생성
• kubernetes/kubeadm: worker 노드 join, kube-proxy 설정
• network_plugin/cni: CNI 플러그인 복사
• network_plugin/flannel: Flannel 매니페스트 생성 및 배포

kubeadm 초기화 흐름

1. 첫 번째 control-plane 노드에서 kubeadm init 실행
2. join 토큰 생성 (24시간 만료)
3. 다른 control-plane 노드 join
4. 인증서 업로드 및 키 파싱
5. API 서버 대기 후 taint 제거 (필요시)

---

4단계: 부가 서비스 및 최적화

애드온 설치 및 최종 설정을 정리하는 단계다.

주요 PLAY 목록

PLAY	설명
Install Calico Route Reflector	Calico BGP 미사용 환경이면 skip
Patch Kubernetes for Windows	Linux-only 환경이면 skip
Install Kubernetes apps	기본 애드온 설치: CoreDNS, metrics-server
Apply resolv.conf changes	클러스터 DNS 안정화 후 노드 DNS 설정 최종 정리

핵심 Role

• kubernetes-apps/ansible: CoreDNS 배포
• kubernetes-apps/helm: Helm 바이너리 설치 및 completion 설정
• kubernetes-apps/metrics_server: metrics-server 매니페스트 생성 및 배포
• win_nodes/kubernetes_patch: kube-proxy daemonset에 nodeSelector 패치
• kubernetes/preinstall: (재실행) resolv.conf 최종 정리

---

TASK 통계

# 전체 TASK 수
cat kubespray_install.log | grep -E 'TASK' | wc -l
559

# PLAY 목록 확인
cat kubespray_install.log | grep -E 'PLAY'

주요 Role별 TASK 분포

Role	주요 기능
download	바이너리/이미지 다운로드 (가장 많은 TASK)
kubernetes/preinstall	시스템 사전 설정
container-engine	컨테이너 런타임 설치
etcd	etcd 클러스터 구성
kubernetes/control-plane	control-plane 초기화

---

설치 흐름도

---

Kubespray Ansible PLAY & TASK 전체 상세 분석

Kubespray 설치 로그에서 추출한 모든 PLAY와 TASK를 정리했다. 총 14개 PLAY, 559개 TASK가 순차 실행된다.

---

PLAY 전체 목록 (14개)

순번	PLAY 이름	단계	설명
1	Check Ansible version	1단계	Kubespray가 지원하는 Ansible 버전인지 확인 (2.17.3 <= version < 2.18.0)
2	Inventory setup and validation	1단계	inventory 설정 정합성 검증. kube_control_plane, etcd 그룹 존재 여부, etcd 노드 수(홀수 권장), Pod CIDR / Service CIDR 유효성, Kubernetes 버전 지원 여부 확인
3	Install bastion ssh config	1단계	Bastion(점프 호스트) 환경 지원. SSH 프록시 설정. bastion 미사용 시 대부분 skip
4	Bootstrap hosts for Ansible	1단계	모든 노드를 Ansible 실행 가능한 상태로 준비. Python 설치, sudo 권한 확보, 기본 패키지 설치, /usr/bin/python 보장
5	Gather facts	1단계	Ansible fact 수집. 이후 TASK들이 when: ansible_os_family == "Debian" 같은 조건 분기에서 사용
6	Prepare for etcd install	2단계	etcd 설치 전 사전 준비. etcd user 생성, 디렉터리 생성, 방화벽/포트 설정, 인증서 경로 준비
7	Add worker nodes to the etcd play if needed	2단계	worker + etcd 겸용 노드 지원. kube_node와 etcd 둘 다 포함된 노드를 etcd PLAY에 추가
8	Install etcd	2단계	etcd 설치 실행. etcd binary 설치, TLS 인증서 생성, systemd 등록, 클러스터 구성
9	Install Kubernetes nodes	3단계	모든 노드에 공통 K8s 컴포넌트 설치. kubelet, container runtime 등. 아직 클러스터 join은 안 함
10	Install the control plane	3단계	kube_control_plane 그룹 대상 control-plane 노드 구성. kubeadm init, API server, scheduler, controller-manager 설정
11	Invoke kubeadm and install a CNI	3단계	kubeadm init/join 실행, 네트워크 플러그인(CNI) 설치. worker 노드 join 포함
12	Install Calico Route Reflector	4단계	Calico BGP Route Reflector 설정. Calico BGP 미사용 환경이면 skip
13	Patch Kubernetes for Windows	4단계	Windows 노드 지원 패치. Linux-only 환경이면 skip
14	Install Kubernetes apps	4단계	기본 애드온 설치. CoreDNS, metrics-server, Helm 등
15	Apply resolv.conf changes now that cluster DNS is up	4단계	CoreDNS 설치 후 노드의 DNS 설정 최종 정리. bootstrap 단계에선 임시 resolv.conf 사용했다가 클러스터 DNS 안정화 후 되돌림

---

TASK 전체 목록 (559개)

1단계: 사전 준비 및 검증

PLAY 1: Check Ansible version

순번	Role	TASK 이름	설명
1	-	Check 2.17.3 <= Ansible version < 2.18.0	Ansible 버전 범위 검증
2	-	Check that python netaddr is installed	Python netaddr 모듈 설치 확인
3	-	Check that jinja is not too old (install via pip)	Jinja2 버전 확인

PLAY 2: Inventory setup and validation

순번	Role	TASK 이름	설명
4	dynamic_groups	Match needed groups by their old names or definition	그룹 매칭 및 정의
5	validate_inventory	Stop if removed tags are used	제거된 태그 사용 시 중지
6	validate_inventory	Stop if kube_control_plane group is empty	control-plane 그룹 비어있으면 중지
7	validate_inventory	Stop if etcd group is empty in external etcd mode	외부 etcd 모드에서 etcd 그룹 비어있으면 중지
8	validate_inventory	Stop if unsupported version of Kubernetes	지원하지 않는 K8s 버전이면 중지
9	validate_inventory	Stop if known booleans are set as strings	boolean 값이 문자열로 설정되면 중지
10	validate_inventory	Stop if even number of etcd hosts	etcd 호스트가 짝수면 중지 (홀수 권장)
11	validate_inventory	Guarantee that enough network address space is available for all pods	Pod용 네트워크 주소 공간 충분한지 확인
12	validate_inventory	Check that kube_service_addresses is a network range	Service CIDR이 네트워크 범위인지 확인
13	validate_inventory	Check that kube_pods_subnet is a network range	Pod CIDR이 네트워크 범위인지 확인
14	validate_inventory	Check that kube_pods_subnet does not collide with kube_service_addresses	Pod CIDR과 Service CIDR 충돌 확인
15	validate_inventory	Check that ipv4 IP range is enough for the nodes	IPv4 범위가 노드에 충분한지 확인
16	validate_inventory	Stop if unsupported options selected	지원하지 않는 옵션 선택 시 중지
17	validate_inventory	Ensure minimum containerd version	containerd 최소 버전 확인

PLAY 3: Install bastion ssh config (bastion 미사용 시 skip)

PLAY 4: Bootstrap hosts for Ansible

순번	Role	TASK 이름	설명
18	bootstrap_os	Fetch /etc/os-release	OS 릴리즈 정보 가져오기
19	bootstrap_os	Include tasks	OS별 태스크 포함
20	bootstrap_os	Gather host facts to get ansible_distribution_version	배포판 버전 정보 수집
21	bootstrap_os	Add proxy to yum.conf or dnf.conf if http_proxy is defined	프록시 설정 추가 (RedHat 계열)
22	bootstrap_os	Check presence of fastestmirror.conf	fastestmirror 설정 확인
23	system_packages	Gather OS information	OS 정보 수집
24	system_packages	Remove legacy docker repo file	레거시 docker repo 파일 제거
25	system_packages	Manage packages	패키지 관리
26	bootstrap_os	Create remote_tmp for it is used by another module	remote_tmp 디렉터리 생성
27	bootstrap_os	Gather facts	fact 수집
28	bootstrap_os	Assign inventory name to unconfigured hostnames	hostname 미설정 시 inventory 이름 할당
29	bootstrap_os	Ensure bash_completion.d folder exists	bash_completion.d 폴더 생성

PLAY 5: Gather facts

순번	Role	TASK 이름	설명
30	network_facts	Gather ansible_default_ipv4	기본 IPv4 정보 수집
31	network_facts	Set fallback_ip	fallback IP 설정
32	network_facts	Gather ansible_default_ipv6	기본 IPv6 정보 수집
33	network_facts	Set fallback_ip6	fallback IPv6 설정
34	network_facts	Set main access ip	메인 접근 IP 설정 (IPv4/IPv6 스택 옵션 기반)
35	network_facts	Set main ip	메인 IP 설정
36	network_facts	Set main access ips (mixed ips for dualstack)	듀얼스택용 혼합 IP 설정
37	network_facts	Set main ips (mixed ips for dualstack)	듀얼스택용 메인 IP 설정
38	-	Gather minimal facts	최소 fact 수집
39	-	Gather necessary facts (network)	네트워크 fact 수집
40	-	Gather necessary facts (hardware)	하드웨어 fact 수집
41	adduser	User | Create User Group	사용자 그룹 생성
42	adduser	User | Create User	사용자 생성
43	kubernetes/preinstall	Check if /etc/fstab exists	/etc/fstab 존재 확인
44	kubernetes/preinstall	Remove swapfile from /etc/fstab	fstab에서 swap 항목 제거
45	kubernetes/preinstall	Mask swap.target (persist swapoff)	swap.target 마스킹으로 swap 영구 비활성화
46	kubernetes/preinstall	Disable swap	swap 비활성화
47	kubernetes/preinstall	Check resolvconf	resolvconf 확인
48	kubernetes/preinstall	Check existence of /etc/resolvconf/resolv.conf.d	resolvconf 디렉터리 존재 확인
49	kubernetes/preinstall	Check status of /etc/resolv.conf	resolv.conf 상태 확인
50	kubernetes/preinstall	Fetch resolv.conf	resolv.conf 가져오기
51	kubernetes/preinstall	NetworkManager | Check if host has NetworkManager	NetworkManager 존재 확인
52	kubernetes/preinstall	Check systemd-resolved	systemd-resolved 확인
53	kubernetes/preinstall	Set default dns if remove_default_searchdomains is false	기본 DNS 설정
54	kubernetes/preinstall	Set dns facts	DNS fact 설정
55	kubernetes/preinstall	Check if kubelet is configured	kubelet 설정 여부 확인
56	kubernetes/preinstall	Check if early DNS configuration stage	초기 DNS 설정 단계 확인
57	kubernetes/preinstall	Target resolv.conf files	resolv.conf 파일 대상 지정
58	kubernetes/preinstall	Check if /etc/dhclient.conf exists	dhclient.conf 존재 확인
59	kubernetes/preinstall	Check if /etc/dhcp/dhclient.conf exists	dhcp/dhclient.conf 존재 확인
60	kubernetes/preinstall	Target dhclient hook file for Red Hat family	RedHat용 dhclient hook 파일 지정
61	kubernetes/preinstall	Check /usr readonly	/usr 읽기전용 확인
62	kubernetes/preinstall	Stop if non systemd OS type	systemd 아닌 OS면 중지
63	kubernetes/preinstall	Stop if the os does not support	지원하지 않는 OS면 중지
64	kubernetes/preinstall	Stop if memory is too small for control plane nodes	control-plane 노드 메모리 부족하면 중지
65	kubernetes/preinstall	Stop if memory is too small for nodes	노드 메모리 부족하면 중지
66	kubernetes/preinstall	Stop if cgroups are not enabled on nodes	cgroups 미활성화면 중지
67	kubernetes/preinstall	Stop if ip var does not match local ips	IP 변수가 로컬 IP와 불일치하면 중지
68	kubernetes/preinstall	Stop if access_ip is not pingable	access_ip에 ping 불가면 중지
69	kubernetes/preinstall	Stop if bad hostname	잘못된 hostname이면 중지
70	kubernetes/preinstall	Stop if /etc/resolv.conf has no configured nameservers	nameserver 미설정이면 중지
71	kubernetes/preinstall	Create kubernetes directories	kubernetes 디렉터리 생성
72	kubernetes/preinstall	Create other directories of root owner	root 소유 기타 디렉터리 생성
73	kubernetes/preinstall	Check if kubernetes kubeadm compat cert dir exists	kubeadm 호환 인증서 디렉터리 존재 확인
74	kubernetes/preinstall	Create kubernetes kubeadm compat cert dir	kubeadm 호환 인증서 디렉터리 생성 (issue 1498)
75	kubernetes/preinstall	Create cni directories	CNI 디렉터리 생성
76	kubernetes/preinstall	NetworkManager | Ensure NetworkManager conf.d dir	NetworkManager conf.d 디렉터리 확인
77	kubernetes/preinstall	NetworkManager | Prevent NetworkManager from managing K8S interfaces	NetworkManager가 K8s 인터페이스 관리 방지 (kube-ipvs0/nodelocaldns)
78	kubernetes/preinstall	NetworkManager | Add nameservers to NM configuration	NetworkManager에 nameserver 추가
79	kubernetes/preinstall	Set default dns if remove_default_searchdomains is false	기본 DNS 설정
80	kubernetes/preinstall	NetworkManager | Add DNS search to NM configuration	NetworkManager에 DNS search 추가
81	kubernetes/preinstall	NetworkManager | Add DNS options to NM configuration	NetworkManager에 DNS 옵션 추가
82	kubernetes/preinstall	Confirm selinux deployed	SELinux 배포 확인
83	kubernetes/preinstall	Set selinux policy	SELinux 정책 설정
84	kubernetes/preinstall	Clean previously used sysctl file locations	이전 sysctl 파일 위치 정리
85	kubernetes/preinstall	Stat sysctl file configuration	sysctl 파일 설정 상태 확인
86	kubernetes/preinstall	Change sysctl file path to link source if linked	심볼릭 링크면 소스 경로로 변경
87	kubernetes/preinstall	Make sure sysctl file path folder exists	sysctl 파일 경로 폴더 존재 확인
88	kubernetes/preinstall	Enable ip forwarding	IP 포워딩 활성화
89	kubernetes/preinstall	Check if we need to set fs.may_detach_mounts	fs.may_detach_mounts 설정 필요 여부 확인
90	kubernetes/preinstall	Ensure kubelet expected parameters are set	kubelet 예상 파라미터 설정 확인
91	kubernetes/preinstall	Disable fapolicyd service	fapolicyd 서비스 비활성화
92	kubernetes/preinstall	Check if we are running inside a Azure VM	Azure VM 내부 실행 여부 확인

---

Container Engine 설치

순번	Role	TASK 이름	설명
93	container-engine/validate-container-engine	Validate-container-engine | check if fedora coreos	Fedora CoreOS 확인
94	container-engine/validate-container-engine	Validate-container-engine | set is_ostree	is_ostree 설정
95	container-engine/validate-container-engine	Ensure kubelet systemd unit exists	kubelet systemd unit 존재 확인
96	container-engine/validate-container-engine	Populate service facts	서비스 fact 수집
97	container-engine/validate-container-engine	Check if containerd is installed	containerd 설치 여부 확인
98	container-engine/validate-container-engine	Check if docker is installed	docker 설치 여부 확인
99	container-engine/validate-container-engine	Check if crio is installed	crio 설치 여부 확인
100	container-engine/containerd-common	Containerd-common | check if fedora coreos	Fedora CoreOS 확인
101	container-engine/containerd-common	Containerd-common | set is_ostree	is_ostree 설정
102	container-engine/runc	Runc | check if fedora coreos	Fedora CoreOS 확인
103	container-engine/runc	Runc | set is_ostree	is_ostree 설정
104	container-engine/runc	Runc | Uninstall runc package managed by package manager	패키지 관리자로 설치된 runc 제거
105	container-engine/runc	Runc | Download runc binary	runc 바이너리 다운로드
106	container-engine/runc	Prep_download | Set a few facts	다운로드 준비 fact 설정
107	container-engine/runc	Download_file | Set pathname of cached file	캐시 파일 경로 설정
108	container-engine/runc	Download_file | Create dest directory on node	노드에 대상 디렉터리 생성
109	container-engine/runc	Download_file | Download item	파일 다운로드
110	container-engine/runc	Download_file | Extract file archives	파일 아카이브 추출
111	container-engine/runc	Copy runc binary from download dir	다운로드 디렉터리에서 runc 바이너리 복사
112	container-engine/runc	Runc | Remove orphaned binary	고아 바이너리 제거
113	container-engine/crictl	Install crictl	crictl 설치
114	container-engine/crictl	Crictl | Download crictl	crictl 다운로드
115	container-engine/crictl	Prep_download | Set a few facts	다운로드 준비 fact 설정
116	container-engine/crictl	Download_file | Set pathname of cached file	캐시 파일 경로 설정
117	container-engine/crictl	Download_file | Create dest directory on node	노드에 대상 디렉터리 생성
118	container-engine/crictl	Download_file | Download item	파일 다운로드
119	container-engine/crictl	Download_file | Extract file archives	파일 아카이브 추출
120	container-engine/crictl	Extract_file | Unpacking archive	아카이브 압축 해제
121	container-engine/crictl	Install crictl config	crictl 설정 설치
122	container-engine/crictl	Copy crictl binary from download dir	다운로드 디렉터리에서 crictl 바이너리 복사
123	container-engine/nerdctl	Nerdctl | Download nerdctl	nerdctl 다운로드
124	container-engine/nerdctl	Prep_download | Set a few facts	다운로드 준비 fact 설정
125	container-engine/nerdctl	Download_file | Set pathname of cached file	캐시 파일 경로 설정
126	container-engine/nerdctl	Download_file | Create dest directory on node	노드에 대상 디렉터리 생성
127	container-engine/nerdctl	Download_file | Download item	파일 다운로드
128	container-engine/nerdctl	Download_file | Extract file archives	파일 아카이브 추출
129	container-engine/nerdctl	Extract_file | Unpacking archive	아카이브 압축 해제
130	container-engine/nerdctl	Nerdctl | Copy nerdctl binary from download dir	다운로드 디렉터리에서 nerdctl 바이너리 복사
131	container-engine/nerdctl	Nerdctl | Create configuration dir	nerdctl 설정 디렉터리 생성
132	container-engine/nerdctl	Nerdctl | Install nerdctl configuration	nerdctl 설정 설치
133	container-engine/containerd	Containerd | Download containerd	containerd 다운로드
134	container-engine/containerd	Prep_download | Set a few facts	다운로드 준비 fact 설정
135	container-engine/containerd	Download_file | Set pathname of cached file	캐시 파일 경로 설정
136	container-engine/containerd	Download_file | Create dest directory on node	노드에 대상 디렉터리 생성
137	container-engine/containerd	Download_file | Download item	파일 다운로드
138	container-engine/containerd	Download_file | Extract file archives	파일 아카이브 추출
139	container-engine/containerd	Containerd | Unpack containerd archive	containerd 아카이브 압축 해제
140	container-engine/containerd	Containerd | Generate systemd service for containerd	containerd용 systemd 서비스 생성
141	container-engine/containerd	Containerd | Ensure containerd directories exist	containerd 디렉터리 존재 확인
142	container-engine/containerd	Containerd | Generate default base_runtime_spec	기본 base_runtime_spec 생성
143	container-engine/containerd	Containerd | Store generated default base_runtime_spec	생성된 base_runtime_spec 저장
144	container-engine/containerd	Containerd | Write base_runtime_specs	base_runtime_specs 작성
145	container-engine/containerd	Containerd | Copy containerd config file	containerd 설정 파일 복사
146	container-engine/containerd	Containerd | Create registry directories	레지스트리 디렉터리 생성
147	container-engine/containerd	Containerd | Write hosts.toml file	hosts.toml 파일 작성
148	container-engine/containerd	Containerd | Ensure containerd is started and enabled	containerd 시작 및 활성화 확인

---

Download Role (바이너리 및 컨테이너 이미지 다운로드)

순번	Role	TASK 이름	설명
149	download	Prep_download | Set a few facts	다운로드 준비 fact 설정
150	download	Prep_download | Register docker images info	docker 이미지 정보 등록
151	download	Prep_download | Create staging directory on remote node	원격 노드에 스테이징 디렉터리 생성
152	download	Download | Get kubeadm binary and list of required images	kubeadm 바이너리 및 필요 이미지 목록 가져오기
153	download	Prep_kubeadm_images | Download kubeadm binary	kubeadm 바이너리 다운로드
154-162	download	Prep_download / Download_file 시리즈	파일 다운로드 반복 작업
163	download	Prep_kubeadm_images | Copy kubeadm binary from download dir to system path	kubeadm 바이너리를 시스템 경로로 복사
164	download	Prep_kubeadm_images | Create kubeadm config	kubeadm 설정 생성
165	download	Prep_kubeadm_images | Generate list of required images	필요 이미지 목록 생성
166	download	Prep_kubeadm_images | Parse list of images	이미지 목록 파싱
167	download	Prep_kubeadm_images | Convert list of images to dict for later use	이미지 목록을 dict로 변환
168	download	Download | Download files / images	파일/이미지 다운로드
169-250	download	반복되는 다운로드 TASK들	kubectl, kubelet, calicoctl, CNI plugins, cni, helm 등 다운로드

다운로드 대상 바이너리:

• kubeadm, kubectl, kubelet
• CNI plugins
• calicoctl (Calico 사용 시)
• etcdctl, etcdutl
• helm
• cri-tools (crictl)

다운로드 대상 컨테이너 이미지 (기본 구성 기준):

순번	이미지	설명
1	kube-apiserver	API 서버
2	kube-controller-manager	컨트롤러 매니저
3	kube-scheduler	스케줄러
4	kube-proxy	kube-proxy
5	pause	인프라 컨테이너
6	coredns	클러스터 DNS
7	flannel (또는 calico)	CNI 플러그인
8	metrics-server	메트릭 서버
9	dns-node-cache	노드 로컬 DNS 캐시
10	nginx-ingress-controller	Ingress 컨트롤러 (선택)
11	etcd	etcd (컨테이너 모드 시)

---

2단계: etcd 클러스터 구축

PLAY 6: Prepare for etcd install

순번	Role	TASK 이름	설명
251	-	Gathering Facts	fact 수집
252	-	Check if nodes needs etcd client certs (depends on network_plugin)	네트워크 플러그인에 따른 etcd 클라이언트 인증서 필요 여부 확인
253	adduser	User | Create User Group	etcd 사용자 그룹 생성
254	adduser	User | Create User	etcd 사용자 생성

PLAY 7: Add worker nodes to the etcd play if needed

순번	Role	TASK 이름	설명
255	adduser	User | Create User Group	사용자 그룹 생성
256	adduser	User | Create User	사용자 생성

PLAY 8: Install etcd

순번	Role	TASK 이름	설명
257	etcd	Check etcd certs	etcd 인증서 확인
258	etcd	Check_certs | Register certs that have already been generated on first etcd node	첫 번째 etcd 노드에서 이미 생성된 인증서 등록
259	etcd	Check_certs | Set default value for 'sync_certs', 'gen_certs' and 'etcd_secret_changed' to false	sync_certs, gen_certs, etcd_secret_changed 기본값 false 설정
260	etcd	Check certs | Register ca and etcd admin/member certs on etcd hosts	etcd 호스트에 CA 및 admin/member 인증서 등록
261	etcd	Check certs | Register ca and etcd node certs on kubernetes hosts	kubernetes 호스트에 CA 및 노드 인증서 등록
262	etcd	Check_certs | Set 'gen_certs' to true if expected certificates are not on the first etcd node(1/2)	첫 번째 etcd 노드에 예상 인증서 없으면 gen_certs=true (1/2)
263	etcd	Check_certs | Set 'gen_certs' to true if expected certificates are not on the first etcd node(2/2)	첫 번째 etcd 노드에 예상 인증서 없으면 gen_certs=true (2/2)
264	etcd	Checkcerts | Set 'gen*_certs' groups to track which nodes needs to have certs generated on first etcd node	인증서 생성 필요 노드 추적용 그룹 설정
265	etcd	Check_certs | Set 'etcd_member_requires_sync' to true if ca or member/admin cert and key don't exist on etcd member or checksum doesn't match	CA 또는 member/admin 인증서가 없거나 체크섬 불일치하면 동기화 필요
266	etcd	Check_certs | Set 'sync_certs' to true	sync_certs=true 설정
267	etcd	Generate etcd certs	etcd 인증서 생성
268	etcd	Gen_certs | create etcd cert dir	etcd 인증서 디렉터리 생성
269	etcd	Gen_certs | create etcd script dir (on k8s-ctr1)	etcd 스크립트 디렉터리 생성 (첫 번째 control-plane)
270	etcd	Gen_certs | write openssl config	openssl 설정 작성
271	etcd	Gen_certs | copy certs generation script	인증서 생성 스크립트 복사
272	etcd	Gen_certs | run cert generation script for etcd and kube control plane nodes	etcd 및 control-plane 노드용 인증서 생성 스크립트 실행
273	etcd	Gen_certs | run cert generation script for all clients	모든 클라이언트용 인증서 생성 스크립트 실행
274	etcd	Gen_certs | check certificate permissions	인증서 권한 확인
275	etcd	Trust etcd CA	etcd CA 신뢰 설정
276	etcd	Gen_certs | target ca-certificate store file	CA 인증서 저장소 파일 대상 지정
277	etcd	Gen_certs | add CA to trusted CA dir	신뢰 CA 디렉터리에 CA 추가
278	etcd	Gen_certs | update ca-certificates (RedHat)	ca-certificates 업데이트 (RedHat)
279	etcd	Trust etcd CA on nodes if needed	필요시 노드에서 etcd CA 신뢰 설정
280	etcd	Gen_certs | target ca-certificate store file	CA 인증서 저장소 파일 대상 지정
281	etcd	Gen_certs | add CA to trusted CA dir	신뢰 CA 디렉터리에 CA 추가
282	etcd	Gen_certs | Get etcd certificate serials	etcd 인증서 시리얼 가져오기
283	etcd	Set etcd_client_cert_serial	etcd_client_cert_serial 설정
284	etcdctl_etcdutl	Download etcd binary	etcd 바이너리 다운로드
285-292	etcdctl_etcdutl	Prep_download / Download_file 시리즈	다운로드 관련 작업
293	etcdctl_etcdutl	Extract_file | Unpacking archive	아카이브 압축 해제
294	etcdctl_etcdutl	Copy etcd binary	etcd 바이너리 복사
295	etcdctl_etcdutl	Copy etcdctl and etcdutl binary from download dir	etcdctl, etcdutl 바이너리 복사
296	etcdctl_etcdutl	Create etcdctl wrapper script	etcdctl 래퍼 스크립트 생성
297	etcd	Install etcd	etcd 설치
298	etcd	Get currently-deployed etcd version	현재 배포된 etcd 버전 가져오기
299	etcd	Restart etcd if necessary	필요시 etcd 재시작
300	etcd	Install | Copy etcd binary from download dir	다운로드 디렉터리에서 etcd 바이너리 복사
301	etcd	Configure etcd	etcd 설정
302	etcd	Configure | Check if etcd cluster is healthy	etcd 클러스터 건강 상태 확인
303	etcd	Configure | Refresh etcd config	etcd 설정 새로고침
304	etcd	Refresh config | Create etcd config file	etcd 설정 파일 생성
305	etcd	Configure | Copy etcd.service systemd file	etcd.service systemd 파일 복사
306	etcd	Configure | reload systemd	systemd 리로드
307	etcd	Configure | Ensure etcd is running	etcd 실행 중인지 확인
308	etcd	Configure | Wait for etcd cluster to be healthy	etcd 클러스터 건강해질 때까지 대기
309	etcd	Configure | Check if member is in etcd cluster	멤버가 etcd 클러스터에 있는지 확인
310	etcd	Refresh etcd config	etcd 설정 새로고침
311	etcd	Refresh config | Create etcd config file	etcd 설정 파일 생성
312	etcd	Refresh etcd config again for idempotency	멱등성을 위해 etcd 설정 다시 새로고침
313	etcd	Refresh config | Create etcd config file	etcd 설정 파일 생성

---

3단계: Kubernetes 코어 설치

PLAY 9: Install Kubernetes nodes

순번	Role	TASK 이름	설명
314	kubernetes/node	Set kubelet_cgroup_driver_detected fact for containerd	containerd용 kubelet cgroup driver fact 설정
315	kubernetes/node	Set kubelet_cgroup_driver	kubelet cgroup driver 설정
316	kubernetes/node	Ensure /var/lib/cni exists	/var/lib/cni 존재 확인
317	kubernetes/node	Install | Copy kubelet binary from download dir	다운로드 디렉터리에서 kubelet 바이너리 복사
318	kubernetes/node	Ensure nodePort range is reserved	nodePort 범위 예약 확인
319	kubernetes/node	Verify if br_netfilter module exists	br_netfilter 모듈 존재 확인
320	kubernetes/node	Verify br_netfilter module path exists	br_netfilter 모듈 경로 존재 확인
321	kubernetes/node	Enable br_netfilter module	br_netfilter 모듈 활성화
322	kubernetes/node	Persist br_netfilter module	br_netfilter 모듈 영구 설정
323	kubernetes/node	Check if bridge-nf-call-iptables key exists	bridge-nf-call-iptables 키 존재 확인
324	kubernetes/node	Enable bridge-nf-call tables	bridge-nf-call 테이블 활성화
325	kubernetes/node	Set kubelet api version to v1beta1	kubelet API 버전 v1beta1 설정
326	kubernetes/node	Write kubelet environment config file (kubeadm)	kubelet 환경 설정 파일 작성 (kubeadm)
327	kubernetes/node	Write kubelet config file	kubelet 설정 파일 작성
328	kubernetes/node	Write kubelet systemd init file	kubelet systemd init 파일 작성
329	kubernetes/node	Enable kubelet	kubelet 활성화

PLAY 10: Install the control plane

순번	Role	TASK 이름	설명
330	kubernetes/control-plane	Pre-upgrade | Delete control plane manifests if etcd secrets changed	etcd 시크릿 변경 시 control-plane 매니페스트 삭제
331	kubernetes/control-plane	Create kube-scheduler config	kube-scheduler 설정 생성
332	kubernetes/control-plane	Install | Copy kubectl binary from download dir	다운로드 디렉터리에서 kubectl 바이너리 복사
333	kubernetes/control-plane	Install kubectl bash completion	kubectl bash completion 설치
334	kubernetes/control-plane	Set kubectl bash completion file permissions	kubectl bash completion 파일 권한 설정
335	kubernetes/control-plane	Check which kube-control nodes are already members of the cluster	이미 클러스터 멤버인 kube-control 노드 확인
336	kubernetes/control-plane	Set fact first_kube_control_plane	first_kube_control_plane fact 설정
337	kubernetes/control-plane	Kubeadm | Check if kubeadm has already run	kubeadm 이미 실행됐는지 확인
338	kubernetes/control-plane	Kubeadm | aggregate all SANs	모든 SAN 집계
339	kubernetes/control-plane	Kubeadm | Create kubeadm config	kubeadm 설정 생성
340	kubernetes/control-plane	Kubeadm | Initialize first control plane node (1st try)	첫 번째 control-plane 노드 초기화 (1차 시도)
341	kubernetes/control-plane	Create kubeadm token for joining nodes with 24h expiration (default)	노드 join용 kubeadm 토큰 생성 (24시간 만료)
342	kubernetes/control-plane	Set kubeadm_token	kubeadm_token 설정
343	kubernetes/control-plane	Kubeadm | Join other control plane nodes	다른 control-plane 노드 join
344	kubernetes/control-plane	Set kubeadm_discovery_address	kubeadm_discovery_address 설정
345	kubernetes/control-plane	Upload certificates so they are fresh and not expired	인증서 업로드 (만료되지 않도록)
346	kubernetes/control-plane	Parse certificate key if not set	설정되지 않은 경우 인증서 키 파싱
347	kubernetes/control-plane	Wait for k8s apiserver	k8s apiserver 대기
348	kubernetes/control-plane	Check already run	이미 실행됐는지 확인
349	kubernetes/control-plane	Kubeadm | Remove taint for control plane node with node role	노드 역할 있는 control-plane 노드의 taint 제거
350	kubernetes/control-plane	Include kubeadm secondary server apiserver fixes	kubeadm 보조 서버 apiserver 수정 포함
351	kubernetes/control-plane	Update server field in component kubeconfigs	컴포넌트 kubeconfig의 server 필드 업데이트
352	kubernetes/control-plane	Include kubelet client cert rotation fixes	kubelet 클라이언트 인증서 rotation 수정 포함
353	kubernetes/control-plane	Fixup kubelet client cert rotation 1/2	kubelet 클라이언트 인증서 rotation 수정 1/2
354	kubernetes/control-plane	Fixup kubelet client cert rotation 2/2	kubelet 클라이언트 인증서 rotation 수정 2/2
355	kubernetes/control-plane	Install script to renew K8S control plane certificates	K8s control-plane 인증서 갱신 스크립트 설치
356	kubernetes/control-plane	Renew K8S control plane certificates monthly 1/2	K8s control-plane 인증서 월간 갱신 1/2
357	kubernetes/control-plane	Renew K8S control plane certificates monthly 2/2	K8s control-plane 인증서 월간 갱신 2/2

PLAY 11: Invoke kubeadm and install a CNI

순번	Role	TASK 이름	설명
358	kubernetes/client	Set external kube-apiserver endpoint	외부 kube-apiserver 엔드포인트 설정
359	kubernetes/client	Create kube config dir for current/ansible become user home	현재/ansible become 사용자 홈에 kube config 디렉터리 생성
360	kubernetes/client	Copy admin kubeconfig to current/ansible become user home	admin kubeconfig를 사용자 홈에 복사
361	kubernetes/client	Wait for k8s apiserver	k8s apiserver 대기
362	kubernetes-apps/cluster_roles	Kubernetes Apps | Wait for kube-apiserver	kube-apiserver 대기
363	kubernetes-apps/cluster_roles	Kubernetes Apps | Add ClusterRoleBinding to admit nodes	노드 승인용 ClusterRoleBinding 추가
364	kubernetes-apps/cluster_roles	Apply workaround to allow all nodes with cert O=system:nodes to register	O=system:nodes 인증서를 가진 모든 노드 등록 허용 워크어라운드 적용
365	kubernetes-apps/cluster_roles	Kubernetes Apps | Remove old webhook ClusterRole	이전 webhook ClusterRole 제거
366	kubernetes-apps/cluster_roles	Kubernetes Apps | Remove old webhook ClusterRoleBinding	이전 webhook ClusterRoleBinding 제거
367	kubernetes-apps/cluster_roles	PriorityClass | Copy k8s-cluster-critical-pc.yml file	k8s-cluster-critical PriorityClass 파일 복사
368	kubernetes-apps/cluster_roles	PriorityClass | Create k8s-cluster-critical	k8s-cluster-critical PriorityClass 생성
369	kubernetes/kubeadm	Set kubeadm_discovery_address	kubeadm_discovery_address 설정
370	kubernetes/kubeadm	Check if kubelet.conf exists	kubelet.conf 존재 확인
371	kubernetes/kubeadm	Check if kubeadm CA cert is accessible	kubeadm CA 인증서 접근 가능 확인
372	kubernetes/kubeadm	Fetch CA certificate from control plane node	control-plane 노드에서 CA 인증서 가져오기
373	kubernetes/kubeadm	Check if discovery kubeconfig exists	discovery kubeconfig 존재 확인
374	kubernetes/kubeadm	Get current resourceVersion of kube-proxy configmap	kube-proxy configmap의 현재 resourceVersion 가져오기
375	kubernetes/kubeadm	Update server field in kube-proxy kubeconfig	kube-proxy kubeconfig의 server 필드 업데이트
376	kubernetes/kubeadm	Get new resourceVersion of kube-proxy configmap	kube-proxy configmap의 새 resourceVersion 가져오기
377	kubernetes/kubeadm	Set ca.crt file permission	ca.crt 파일 권한 설정
378	kubernetes/kubeadm	Restart all kube-proxy pods to ensure that they load the new configmap	새 configmap 로드를 위해 모든 kube-proxy pod 재시작
379	kubernetes/node-label	Kubernetes Apps | Wait for kube-apiserver	kube-apiserver 대기
380	kubernetes/node-label	Set role node label to empty list	role 노드 레이블을 빈 리스트로 설정
381	kubernetes/node-label	Set inventory node label to empty list	inventory 노드 레이블을 빈 리스트로 설정
382	kubernetes/node-label	debug	디버그
383	kubernetes/node-label	debug	디버그
384	kubernetes/node-taint	Set role and inventory node taint to empty list	role 및 inventory 노드 taint를 빈 리스트로 설정
385	kubernetes/node-taint	debug	디버그
386	kubernetes/node-taint	debug	디버그
387	network_plugin/cni	CNI | make sure /opt/cni/bin exists	/opt/cni/bin 존재 확인
388	network_plugin/cni	CNI | Copy cni plugins	CNI 플러그인 복사
389	network_plugin/cni	CNI | make sure /opt/cni/bin exists	/opt/cni/bin 존재 확인
390	network_plugin/cni	CNI | Copy cni plugins	CNI 플러그인 복사
391	network_plugin/flannel	Flannel | Create Flannel manifests	Flannel 매니페스트 생성
392	network_plugin/flannel	Flannel | Start Resources	Flannel 리소스 시작
393	network_plugin/flannel	Flannel | Wait for flannel subnet.env file presence	flannel subnet.env 파일 존재 대기

---

4단계: 부가 서비스 및 최적화

PLAY 12: Install Calico Route Reflector (Calico BGP 미사용 시 skip)

PLAY 13: Patch Kubernetes for Windows

순번	Role	TASK 이름	설명
394	win_nodes/kubernetes_patch	Ensure that user manifests directory exists	사용자 매니페스트 디렉터리 존재 확인
395	win_nodes/kubernetes_patch	Check current nodeselector for kube-proxy daemonset	kube-proxy daemonset의 현재 nodeselector 확인
396	win_nodes/kubernetes_patch	Apply nodeselector patch for kube-proxy daemonset	kube-proxy daemonset에 nodeselector 패치 적용
397	win_nodes/kubernetes_patch	debug	디버그
398	win_nodes/kubernetes_patch	debug	디버그

PLAY 14: Install Kubernetes apps

순번	Role	TASK 이름	설명
399	kubernetes-apps/ansible	Kubernetes Apps | Wait for kube-apiserver	kube-apiserver 대기
400	kubernetes-apps/ansible	Kubernetes Apps | CoreDNS	CoreDNS 설치
401	kubernetes-apps/helm	Helm | Gather os specific variables	OS별 변수 수집
402	kubernetes-apps/helm	Helm | Install PyYaml	PyYaml 설치
403	kubernetes-apps/helm	Helm | Download helm	helm 다운로드
404-411	kubernetes-apps/helm	Prep_download / Download_file 시리즈	helm 다운로드 관련 작업
412	kubernetes-apps/helm	Extract_file | Unpacking archive	아카이브 압축 해제
413	kubernetes-apps/helm	Helm | Copy helm binary from download dir	다운로드 디렉터리에서 helm 바이너리 복사
414	kubernetes-apps/helm	Helm | Get helm completion	helm completion 가져오기
415	kubernetes-apps/helm	Helm | Install helm completion	helm completion 설치
416	kubernetes-apps/metrics_server	Metrics Server | Delete addon dir	애드온 디렉터리 삭제
417	kubernetes-apps/metrics_server	Metrics Server | Create addon dir	애드온 디렉터리 생성
418	kubernetes-apps/metrics_server	Metrics Server | Templates list	템플릿 목록
419	kubernetes-apps/metrics_server	Metrics Server | Create manifests	매니페스트 생성
420	kubernetes-apps/metrics_server	Metrics Server | Apply manifests	매니페스트 적용

PLAY 15: Apply resolv.conf changes now that cluster DNS is up

순번	Role	TASK 이름	설명
421	adduser	User | Create User Group	사용자 그룹 생성
422	adduser	User | Create User	사용자 생성
423	kubernetes/preinstall	Check resolvconf	resolvconf 확인
424	kubernetes/preinstall	Check existence of /etc/resolvconf/resolv.conf.d	resolvconf 디렉터리 존재 확인
425	kubernetes/preinstall	Check status of /etc/resolv.conf	resolv.conf 상태 확인
426	kubernetes/preinstall	Fetch resolv.conf	resolv.conf 가져오기
427	kubernetes/preinstall	NetworkManager | Check if host has NetworkManager	NetworkManager 존재 확인
428	kubernetes/preinstall	Check systemd-resolved	systemd-resolved 확인
429	kubernetes/preinstall	Set default dns if remove_default_searchdomains is false	기본 DNS 설정
430	kubernetes/preinstall	Set dns facts	DNS fact 설정
431	kubernetes/preinstall	Check if kubelet is configured	kubelet 설정 여부 확인
432	kubernetes/preinstall	Check if early DNS configuration stage	초기 DNS 설정 단계 확인
433	kubernetes/preinstall	Target resolv.conf files	resolv.conf 파일 대상 지정
434	kubernetes/preinstall	Check if /etc/dhclient.conf exists	dhclient.conf 존재 확인
435	kubernetes/preinstall	Check if /etc/dhcp/dhclient.conf exists	dhcp/dhclient.conf 존재 확인
436	kubernetes/preinstall	Target dhclient hook file for Red Hat family	RedHat용 dhclient hook 파일 지정
437	kubernetes/preinstall	Check /usr readonly	/usr 읽기전용 확인
438	kubernetes/preinstall	NetworkManager | Ensure NetworkManager conf.d dir	NetworkManager conf.d 디렉터리 확인
439	kubernetes/preinstall	NetworkManager | Prevent NetworkManager from managing K8S interfaces	NetworkManager가 K8s 인터페이스 관리 방지
440	kubernetes/preinstall	NetworkManager | Add nameservers to NM configuration	NetworkManager에 nameserver 추가
441	kubernetes/preinstall	Set default dns if remove_default_searchdomains is false	기본 DNS 설정
442	kubernetes/preinstall	NetworkManager | Add DNS search to NM configuration	NetworkManager에 DNS search 추가
443	kubernetes/preinstall	NetworkManager | Add DNS options to NM configuration	NetworkManager에 DNS 옵션 추가

---

Role별 TASK 수 요약

Role	TASK 수 (대략)	주요 기능
download	~150	바이너리/이미지 다운로드 (가장 많음)
kubernetes/preinstall	~50	시스템 사전 설정, swap 비활성화, sysctl
container-engine/*	~55	containerd, runc, crictl, nerdctl 설치
etcd	~55	etcd 인증서 생성, 클러스터 구성
kubernetes/control-plane	~30	kubeadm init, control-plane 구성
kubernetes/node	~15	kubelet 설치, br_netfilter 설정
kubernetes/kubeadm	~12	worker join, kube-proxy 설정
network_plugin/*	~8	CNI 플러그인 설치 (Flannel/Calico)
kubernetes-apps/*	~20	CoreDNS, metrics-server, Helm
validate_inventory	~13	inventory 검증
bootstrap_os	~12	OS 부트스트랩
adduser	~8	사용자/그룹 생성

---

정리

Kubespray는 복잡한 Kubernetes 클러스터 배포를 자동화하지만, 내부적으로는 체계적인 단계를 거친다.

1. 사전 검증으로 환경 문제를 미리 차단
2. etcd 우선 구축으로 상태 저장소 확보
3. kubeadm 기반 초기화로 표준 방식 준수
4. 애드온 자동 설치로 운영 준비 완료
5. download Role이 가장 많은 TASK 차지 - 바이너리와 컨테이너 이미지 다운로드가 핵심
6. 검증 TASK가 많음 - 설치 실패를 사전에 방지하기 위한 철저한 검증
7. 멱등성 보장 - 동일 TASK 반복 실행해도 결과 동일하도록 설계
8. 조건부 실행 - bastion, Windows, Calico 등 환경에 따라 skip 처리