renamed.log

Git 이력 관리와 Branch 작업

2026-09-10T00:00:00+09:00

Version Control과 Git 기본 작업 흐름에서 Working Tree, Staging Area와 Local Repository의 관계를 살펴봤다. 이 글에서는 저장된 Commit을 조회하고 비교하는 방법부터 변경 복구, Branch 통합까지 다룬다.

SourceTree를 사용해도 Git의 상태와 History는 CLI를 사용할 때와 같다. GUI 조작과 명령을 함께 확인하면 버튼을 눌렀을 때 Repository에서 무엇이 바뀌는지 이해할 수 있다.

1 ) SourceTree와 Git CLI

SourceTree는 Git Repository를 시각적으로 다루는 GUI Client이다. File 상태, Commit Graph와 Branch 관계를 화면에 표시하고 선택한 작업에 해당하는 Git 명령을 실행한다.

Git 작업	SourceTree에서 확인할 영역	CLI
Repository 생성	Local Repository 생성	`git init`
File 상태 확인	File Status·Working Copy	`git status`
Stage	Stage 대상 선택	`git add`, `git restore --staged`
Commit	Commit Message 입력 영역	`git commit`
History	Commit Graph·History	`git log --graph`
Tag	Commit의 Tag 메뉴	`git tag`
Branch 전환	Branch 목록	`git switch`
통합	Merge·Rebase 메뉴	`git merge`, `git rebase`
임시 보관	Stash 메뉴	`git stash`

버튼 이름과 화면 배치는 SourceTree Version과 운영체제에 따라 달라질 수 있다. 조작 후 git status, git log와 git branch로 실제 Repository 상태를 확인하면 GUI 표시와 Git 개념을 연결할 수 있다.

2 ) Local Repository에서 Version 생성

Repository 준비

SourceTree에서는 Local Repository 생성 화면에서 작업 Directory를 선택한다. CLI에서는 같은 Directory로 이동해 git init을 실행한다.

mkdir git-history-lab
cd git-history-lab
git init --initial-branch=main

초기 상태를 확인한다.

git status

첫 번째 Commit

a.txt, b.txt, c.txt를 만들고 각각 A, B, C를 기록한다. File 작성 방식은 사용하는 Editor에 따라 달라지므로 여기서는 Git 상태 변화에 집중한다.

git-history-lab/
├── a.txt
├── b.txt
└── c.txt

새 File은 Untracked 상태이다.

git status

세 File을 다음 Commit 대상으로 Stage한다.

git add a.txt b.txt c.txt
git diff --staged
git status

SourceTree에서는 Unstaged File 목록에서 대상을 선택하여 Staged File 영역으로 옮긴다. Commit 전에는 Staged Diff를 읽어 의도한 내용만 포함됐는지 확인한다.

git commit -m "docs: add initial text files"

두 번째 Commit

a.txt를 수정하고 c.txt를 삭제하면 두 File 모두 Working Tree 변경으로 표시된다. 삭제도 Git이 추적하는 변경이다.

git status
git diff

변경을 Stage하고 두 번째 Commit을 만든다.

git add a.txt c.txt
git diff --staged
git commit -m "docs: update A and remove C"

git add .은 현재 Directory 아래의 추가, 수정과 삭제를 한꺼번에 Stage할 수 있다. 범위가 넓으므로 사용 직후 git diff --staged로 Commit 대상을 확인한다.

git add .
git diff --staged

이미 추적 중인 File의 수정과 삭제를 Stage하면서 Commit까지 수행할 때는 -a를 사용할 수 있다.

git commit -am "docs: update tracked files"

git commit -am은 Untracked File을 포함하지 않는다. 새 File은 먼저 git add로 추적 대상에 포함해야 한다.

3 ) Commit History 조회

SourceTree의 History 화면은 Commit을 Graph로 표시한다. CLI에서는 목적에 따라 git log Option을 조합한다.

# 상세 History
git log

# 한 Commit을 한 줄로 표시
git log --oneline

# Commit별 Patch 포함
git log --patch

# Branch와 Tag를 함께 표시
git log --oneline --graph --decorate --all

Commit을 선택하면 작성자, 시각, Message, Parent와 변경된 File을 확인할 수 있다. CLI에서는 git show를 사용한다.

git show 
git show --stat 
git show --name-status 

Commit 개수는 작업을 나눈 방식에 따라 크게 달라진다. 많은 Commit이 Project 품질이나 기여 수준을 자동으로 증명하지 않으므로 변경 내용과 Message, Review 결과를 함께 봐야 한다.

4 ) Tag로 Version 표시

Tag

특정 Git Object를 읽기 쉬운 이름으로 가리키는 Reference이다. Release Version을 표시할 때 주로 Commit에 연결한다.

Commit Object ID는 Git이 Content와 Metadata를 바탕으로 생성한다. 사용자가 원하는 문자열로 Object ID를 정할 수 없으므로 v1.0.0 같은 Tag를 별도로 붙인다.

Lightweight Tag

현재 Commit을 직접 가리키는 Lightweight Tag를 생성한다.

git tag v1.0.0

Annotated Tag

Annotated Tag에는 작성자, 생성 시각과 Message가 별도 Tag Object로 기록된다. Release 표시에는 Annotated Tag가 적합하다.

git tag -a v1.0.0 -m "release v1.0.0"

특정 Commit에 Tag를 붙이려면 Commit을 함께 지정한다.

git log --oneline
git tag -a v0.9.0  -m "release v0.9.0"

Tag 목록과 대상을 확인한다.

git tag --list
git show v1.0.0

Local Tag를 삭제한다.

git tag --delete v1.0.0

Tag는 기본 git push에 항상 포함되지 않는다. Remote에 특정 Tag를 올리거나 삭제하는 작업은 명시적으로 수행한다.

git push origin v1.0.0
git push origin --delete v1.0.0

SourceTree에서는 History에서 대상 Commit을 선택해 Tag를 만들 수 있다. 생성 후 Local Tag인지 Remote에도 Push된 Tag인지 구분해서 확인한다.

5 ) Version 비교

git diff는 어떤 두 상태를 비교하는지에 따라 출력 범위가 달라진다.

비교 대상	명령	확인하는 내용
Working Tree ↔ Staging Area	`git diff`	아직 Stage하지 않은 변경
Staging Area ↔ `HEAD`	`git diff --staged`	다음 Commit에 들어갈 변경
Commit ↔ Commit	`git diff`	두 Commit의 Snapshot 차이
Branch ↔ Branch	`git diff ..`	두 Branch Tip의 Snapshot 차이

git diff
git diff --staged
git diff HEAD~1 HEAD
git diff main..feature/login

SourceTree에서는 Commit 두 개를 선택하여 변경 File과 Diff를 비교할 수 있다. 다중 선택에 사용하는 보조 Key는 운영체제에 따라 다르므로 선택된 두 Commit의 ID를 화면에서 확인한다.

`HEAD`, `^`와 `~`

HEAD는 현재 Checkout한 위치를 가리킨다. Branch에 정상적으로 연결된 상태에서는 현재 Branch의 Tip Commit을 가리킨다.

표현	의미
`HEAD`	현재 Checkout한 Commit
`HEAD^`	`HEAD`의 첫 번째 Parent
`HEAD^2`	Merge Commit인 `HEAD`의 두 번째 Parent
`HEAD~2`	첫 번째 Parent를 두 번 따라간 Commit

일직선 History에서는 HEAD^와 HEAD~1이 같은 Commit을 가리킨다. Parent가 여러 개인 Merge Commit에서는 ^<번호>로 어느 Parent를 선택하는지 지정할 수 있다.

6 ) File 변경 복구

File 복구는 Staging Area만 되돌리는 작업과 Working Tree의 내용을 폐기하는 작업을 구분해야 한다.

Stage 취소

다음 명령은 File의 Staged 상태를 HEAD 기준으로 되돌린다. Working Tree의 수정 내용은 유지한다.

git restore --staged 
git status

SourceTree에서는 Staged File을 Unstaged 영역으로 옮기는 동작에 해당한다.

Working Tree 변경 폐기

다음 명령은 Working Tree의 File을 Staging Area의 내용으로 복원한다.

git diff -- 
git restore 

저장하지 않은 변경은 사라질 수 있다. 실행 전에 git diff를 확인하고 보존할 내용이 있으면 Commit이나 Stash로 저장한다.

특정 Commit의 File만 가져올 수도 있다.

git restore --source= -- 

이 명령은 Branch 전체를 해당 Commit으로 이동시키지 않고 선택한 File의 Working Tree 내용만 바꾼다.

7 ) Commit 되돌리기

reset과 revert는 결과가 비슷해 보이지만 History 처리 방식이 다르다.

명령	현재 Branch Tip	Staging Area	Working Tree	공유 Branch 사용
`reset --soft`	대상 Commit으로 이동	유지	유지	History가 달라지므로 주의
`reset --mixed`	대상 Commit으로 이동	대상 Commit 기준으로 초기화	유지	History가 달라지므로 주의
`reset --hard`	대상 Commit으로 이동	대상 Commit 기준으로 초기화	대상 Commit 기준으로 변경	저장하지 않은 변경 손실 가능
`revert`	새 Commit 추가	새 Commit 과정에 따라 반영	취소 결과 반영	기존 History를 보존하므로 적합

Soft Reset

Commit만 취소하고 변경 내용을 Staging Area와 Working Tree에 유지한다.

git reset --soft 
git status
git diff --staged

Mixed Reset

Option을 생략한 git reset은 기본적으로 Mixed Mode이다. Branch를 대상 Commit으로 옮기고 Staging Area를 초기화하지만 Working Tree 변경은 유지한다.

git reset 
git status
git diff

Hard Reset

git reset --hard

Hard Reset은 Branch, Staging Area와 추적 중인 Working Tree File을 대상 Commit 상태에 맞춘다. Commit하지 않은 변경이 사라질 수 있으므로 다음 내용을 먼저 확인한다.

git status
git diff
git diff --staged
git log --oneline --decorate -n 10

필요하면 현재 위치를 임시 Branch로 보존한 뒤 Reset한다.

git branch backup-before-reset

Revert

git revert는 취소할 Commit의 반대 변경을 적용한 새 Commit을 만든다.

git revert

기존 Commit이 History에 남으므로 이미 Remote에 공유한 Branch에서 변경을 취소할 때 사용하기 쉽다. 충돌이 발생하면 File을 수정하고 Stage한 뒤 작업을 계속하거나 중단한다.

git add 
git revert --continue

git revert --abort

8 ) Stash로 변경 임시 보관

Stash는 Commit하기 이른 Working Tree와 Staging Area의 변경을 임시로 저장하고 현재 Branch의 작업 공간을 정리할 때 사용한다.

git stash push -m "temporary work"
git status

기본 Stash에는 추적 중인 File의 Staged·Unstaged 변경이 들어간다. Untracked File은 기본 대상이 아니며 필요할 때 -u를 명시한다.

git stash push -u -m "include untracked files"

저장된 목록과 변경 내용을 확인한다.

git stash list
git stash show --patch stash@{0}

apply는 Stash를 적용한 뒤 목록에 남긴다. Stage 상태까지 복원하려면 --index를 사용할 수 있다.

git stash apply stash@{0}
git stash apply --index stash@{0}

더 이상 필요하지 않은 Stash를 삭제한다.

git stash drop stash@{0}

pop은 적용에 성공하면 해당 Stash를 목록에서 제거한다.

git stash pop stash@{0}

Stash 적용 중에도 현재 Branch의 변경과 충돌할 수 있다. 적용 후 git status와 Diff를 확인한다.

9 ) Branch와 `HEAD`

Branch

Commit을 가리키며 새 Commit이 만들어질 때 함께 이동하는 Reference이다.

Branch는 Project File을 통째로 복사한 Directory가 아니다. 여러 작업 흐름이 서로 다른 Commit을 가리키도록 분기한다.

              D──E  feature/login
             /
A──B──C───────────  main

현재 Branch와 목록을 확인한다.

git branch --show-current
git branch

Branch를 만들고 전환한다.

git branch feature/login
git switch feature/login

생성과 전환을 동시에 수행할 수 있다.

git switch -c feature/payment

기존 환경에서는 다음 checkout 명령도 계속 볼 수 있다.

git checkout feature/login
git checkout -b feature/payment

checkout은 Branch 전환과 File 복구를 모두 담당하는 오래된 범용 명령이다. 새 문서에서는 의도가 분명한 switch와 restore를 우선 사용한다.

특정 Commit을 직접 Checkout하면 HEAD가 Branch가 아닌 Commit을 가리키는 Detached HEAD 상태가 될 수 있다. 이 상태에서 만든 Commit을 보존하려면 해당 위치에서 Branch를 생성한다.

git switch -c save-detached-work

Branch 삭제

현재 Checkout한 Branch는 삭제할 수 없다. 다른 Branch로 이동한 뒤 병합이 끝난 Branch를 삭제한다.

git switch main
git branch -d feature/login

-d는 병합되지 않은 Commit이 있으면 삭제를 거절한다. -D는 이를 무시하는 강제 삭제이므로 보존할 Commit이 없는지 확인하지 않고 사용하지 않는다.

10 ) Merge

Merge는 현재 Branch에 다른 Branch의 History를 통합한다. feature/login을 main에 합치려면 결과를 받을 main으로 먼저 이동한다.

git switch main
git merge feature/login

Fast-forward Merge

Branch가 분기된 뒤 main에 새 Commit이 없다면 main Reference를 feature/login의 Tip까지 앞으로 이동할 수 있다.

병합 전

A──B  main
    \
     C──D  feature/login

병합 후

A──B──C──D  main, feature/login

Fast-forward Merge는 별도 Merge Commit을 만들지 않아도 된다.

Merge Commit

두 Branch가 각각 새 Commit을 가진 경우 Git은 공통 조상을 기준으로 변경을 통합하고 Merge Commit을 만들 수 있다.

       C──D  feature/login
      /    \
A──B──E─────M  main

특정 Commit을 git merge 대상으로 지정할 수 있지만 해당 Commit 하나의 Patch만 적용하는 작업은 아니다. Git은 지정한 Commit까지 이어지는 History를 현재 Branch와 병합한다. 하나의 Commit 변경만 적용하려는 경우에는 목적을 확인한 뒤 git cherry-pick 을 검토한다.

Merge 충돌

서로 다른 Branch가 같은 File의 같은 영역을 다르게 수정하면 Git이 결과를 자동으로 결정하지 못할 수 있다.

git status

충돌 File에는 다음과 같은 Marker가 생길 수 있다.

<<<<<<< HEAD
현재 Branch의 내용
=======
병합하는 Branch의 내용
>>>>>>> feature/login

적용할 내용을 결정하고 Marker를 제거한 뒤 File을 Stage한다.

git add 
git commit

Merge를 완료하지 않고 시작 전으로 돌아가려면 다음 명령을 사용한다.

git merge --abort

ours와 theirs는 현재 진행 중인 작업 종류와 방향에 따라 가리키는 쪽을 정확히 확인해야 한다. 이름만 보고 자동으로 한쪽 전체를 선택하지 않는다.

11 ) Rebase

Rebase는 현재 Branch의 Commit을 새로운 Base 위에 다시 적용한다.

변경 전

A──B──C  main
    \
     D──E  feature/login

변경 후

A──B──C  main
       \
        D'──E'  feature/login

feature/login을 최신 main 위로 옮긴다.

git switch feature/login
git rebase main

Rebase는 D와 E를 그대로 이동하지 않는다. 같은 변경을 새 Parent 위에 적용하여 D', E'라는 새 Commit을 만들기 때문에 Object ID가 달라진다.

충돌이 발생하면 File을 수정하고 Stage한 뒤 다음 Commit 적용을 계속한다.

git status
git add 
git rebase --continue

현재 Rebase를 중단하고 시작 전 상태로 돌아간다.

git rebase --abort

이미 여러 사람이 사용하는 Remote Branch의 Commit을 Rebase하면 기존 History와 다른 Commit ID가 만들어진다. 공유하기 전의 개인 작업 Branch에서 사용하는 범위와 팀의 History 정책을 먼저 확인한다.

12 ) Non-fast-forward Push와 Merge의 차이

Remote Branch에 Local이 가지고 있지 않은 Commit이 있으면 Push가 non-fast-forward로 거절될 수 있다.

Local main       A──B──L
                     
Remote main      A──B──R

이 오류는 Fast-forward Merge 기능의 실패가 아니다. Remote Branch를 Local Commit까지 단순 이동하면 R이 History에서 빠질 수 있으므로 Server가 Update를 거절한 것이다.

Remote 상태를 먼저 가져와 History를 확인한다.

git fetch origin
git log --oneline --graph --decorate --all

팀 정책에 따라 Remote 변경을 Merge하거나 Rebase한 뒤 충돌을 해결하고 다시 Push한다.

git merge origin/main

또는 다음과 같이 현재 Commit을 Remote Branch 위에 다시 적용할 수 있다.

git rebase origin/main

원격 Repository 연결과 Push 전체 흐름은 GitHub Remote Repository 작업 흐름에서 다룬다.

전체 정리

최종 정리

SourceTree와 CLI는 같은 Git Repository와 상태를 다루므로 GUI 작업 뒤에도 Git 명령으로 결과를 확인할 수 있다.

Tag는 Commit Object ID를 바꾸지 않고 특정 Version을 읽기 쉬운 이름으로 가리킨다.

git diff는 Working Tree, Staging Area, Commit과 Branch 중 어떤 두 상태를 비교하는지 구분해야 한다.

restore는 File, reset은 Branch와 Index, revert는 기존 Commit을 취소하는 새 Commit을 다룬다.

기본 Stash는 추적 중인 변경을 저장하며 Untracked File을 포함하려면 -u가 필요하다.

Merge는 History를 통합하고 Rebase는 현재 Branch의 Commit을 새 Base 위에 다시 적용한다.

Non-fast-forward Push 거절은 Remote에 Local이 가지지 않은 Commit이 있을 때 History 손실을 막기 위해 발생한다.

GitHub Remote Repository 작업 흐름

2026-09-10T00:00:00+09:00

Version Control과 Git 기본 작업 흐름에서 Local Repository의 구조를 정리했고 Git 이력 관리와 Branch 작업에서 Branch를 나누고 통합하는 방법을 다뤘다. 이 글에서는 Local Repository와 GitHub의 Remote Repository 사이에서 Commit과 Branch를 교환한다.

1 ) GitHub와 Git

Git은 Local에서 Commit과 Branch History를 관리하는 Version Control System이다. GitHub는 Git Repository를 Hosting하고 협업 기능을 제공하는 Service이다.

GitHub 기능	용도
Repository Hosting	Git Commit, Branch와 Tag 저장·공유
Pull Request	Branch 변경 검토와 병합
Issues	작업과 문제 추적
Actions	Build, Test와 배포 Workflow 실행
Packages	Package와 Container Image 저장
Projects	Issue와 Pull Request 기반 작업 관리
Pages	Repository Content 기반 정적 Site 배포

GitHub의 무료 범위, Storage와 Actions 사용량은 Plan에 따라 달라질 수 있으므로 사용 시점의 공식 정책을 확인한다.

Local Repository
├── Working Tree
├── Staging Area
└── Local Branch와 Commit
          │
          │ fetch·pull·push
          ▼
GitHub Remote Repository
├── Remote Branch
├── Tag
└── Pull Request·Issue·Actions

2 ) Remote Repository 인증 방식

Private Repository를 Clone하거나 Push할 때 GitHub는 사용자를 인증하고 Repository 권한을 확인한다. Remote URL 형식에 따라 HTTPS 또는 SSH 인증을 사용한다.

방식	인증 수단	특징
HTTPS	Personal Access Token과 Credential Helper	HTTPS URL을 사용하며 운영체제 Credential Store와 연동 가능
SSH	SSH Private Key와 GitHub에 등록한 Public Key	GitHub Password나 PAT를 Push마다 전달하지 않음
GitHub CLI	`gh auth login`	Browser, HTTPS 또는 SSH 인증 설정을 안내하고 GitHub API도 함께 사용

HTTPS와 Personal Access Token

GitHub의 HTTPS Git 작업에서 Account Password를 대신해 Personal Access Token을 사용할 수 있다. Token에는 필요한 Repository와 작업 범위만 부여하고 만료 기간을 설정한다.

Token 값을 다음 위치에 직접 작성하지 않는다.

Markdown과 Source Code
git remote URL
Shell Script
.gitconfig의 평문 설정
CI Log에 출력되는 명령 인자

현재 Credential Helper 설정을 확인한다.

git config --show-origin --get-all credential.helper

Git Credential Manager, macOS Keychain 같은 Helper를 사용하면 Credential을 운영체제의 Credential Store와 연결할 수 있다. 설치 방식과 Helper 이름은 운영체제와 Git 배포판에 따라 다르므로 임의로 덮어쓰기 전에 기존 설정을 확인한다.

저장된 계정을 바꿀 때는 Git 설정만 반복해서 추가하지 않는다. 현재 Helper 또는 운영체제 Credential Manager에서 기존 GitHub Credential을 제거한 뒤 다시 인증한다.

SSH 인증

SSH Remote는 다음 형식을 사용한다.

git@github.com:/.git

Local Private Key는 외부에 공개하지 않고 대응하는 Public Key만 GitHub 계정이나 조직에 등록한다. SSH Key 생성과 공개키 등록 이유는 원격 접속의 SSH Key 절에서 다룬다.

GitHub SSH 연결을 확인한다.

ssh -T git@github.com

첫 연결에서는 Host Key Fingerprint를 GitHub 공식 문서의 값과 대조한 뒤 신뢰 여부를 결정한다.

GitHub CLI 인증

GitHub CLI를 사용한다면 대화형 Login 절차를 실행할 수 있다.

gh auth login
gh auth status

필요한 경우 현재 gh 인증을 Git Credential 설정에 연결한다.

gh auth setup-git

계정을 변경할 때는 현재 인증 상태를 확인하고 Logout한다.

gh auth status
gh auth logout
gh auth login

gh 인증과 SSH Agent에 올라간 Key는 별도 상태일 수 있다. 오류가 발생하면 Remote URL이 HTTPS인지 SSH인지 먼저 확인한다.

3 ) 올바른 Remote URL

GitHub Repository의 HTTPS와 SSH URL은 형식이 다르다.

HTTPS
https://github.com//.git

SSH
git@github.com:/.git

다음 주소는 HTTPS Scheme과 SSH 구분자를 섞었으므로 올바른 GitHub Remote URL이 아니다.

https://github.com:/.git

현재 Repository의 Remote 이름과 URL을 확인한다.

git remote -v
git remote get-url origin

Remote 이름은 URL 자체가 아니다. origin은 git clone이 기본으로 등록하는 관례적인 이름이며 원하는 이름으로 바꿀 수 있다.

4 ) Clone과 Fork

Clone과 Fork는 Repository의 복사 위치와 소유 관계가 다르다.

작업	생성 위치	결과
Clone	Local Computer	Remote Repository의 Local Repository와 Working Tree 생성
Fork	GitHub 계정	원본과 별도로 관리되는 GitHub Remote Repository 생성

Clone

Repository를 현재 Directory 아래에 복제한다.

git clone \
  https://github.com//.git

Local Directory 이름을 직접 지정할 수 있다. 대상 Directory는 비어 있거나 존재하지 않아야 한다.

git clone \
  https://github.com//.git \
  

Clone이 끝나면 등록된 Remote와 Branch를 확인한다.

cd 
git remote -v
git branch --all
git log --oneline --decorate -n 5

큰 공개 Repository를 예제로 그대로 Clone하면 Network와 Disk를 많이 사용할 수 있다. Git 명령 학습에는 직접 만든 작은 Repository나 전용 실습 Repository를 사용한다.

Fork

Fork는 GitHub에서 원본 Repository를 자신의 계정이나 조직 아래에 복사하는 기능이다. 원본 Repository에 직접 Push 권한이 없어도 Fork에서 Branch를 Push하고 Pull Request를 만들 수 있다.

Fork를 Clone하면 일반적으로 자신의 Fork가 origin이 된다. 원본 Repository의 변경을 가져오려면 upstream Remote를 별도로 등록한다.

git remote add upstream \
  https://github.com//.git
git remote -v

origin
└── 자신의 GitHub Fork

upstream
└── 원본 GitHub Repository

5 ) Remote 연결과 변경

Remote 추가

기존 Local Repository에 GitHub Repository를 연결한다.

git remote add origin \
  https://github.com//.git
git remote -v

같은 이름의 Remote가 이미 있으면 remote origin already exists 오류가 발생한다. 기존 URL을 확인하고 새 Remote가 필요한지 URL 변경이 필요한지 판단한다.

git remote get-url origin

Remote URL 변경

git remote set-url origin \
  git@github.com:/.git
git remote -v

이 명령은 Local Repository의 연결 URL을 변경한다. GitHub Repository의 이름이나 소유자를 바꾸는 작업은 아니다.

Remote 이름 변경

git remote rename  
git remote -v

Remote 연결 제거

git remote remove 
git remote -v

git remote remove는 Local .git/config의 Remote 연결을 제거한다. GitHub의 Remote Repository와 그 안의 Data는 삭제하지 않는다.

6 ) Fetch와 Pull

Remote의 변경을 가져오는 명령은 Local Branch를 자동으로 바꾸는지에 따라 구분한다.

Fetch

git fetch origin

Fetch는 Remote의 새 Commit, Tag와 Branch Reference를 Local Repository로 가져온다. 현재 Working Tree와 Local Branch에는 자동으로 통합하지 않는다.

GitHub origin/main
        │ git fetch origin
        ▼
Local origin/main 갱신
        │
        └── 현재 Local main은 그대로 유지

가져온 상태와 Local Branch를 비교한다.

git log --oneline --graph --decorate --all
git diff main..origin/main

Pull

git pull origin main

Pull은 먼저 Fetch한 뒤 가져온 변경을 현재 Branch에 통합한다. 기본 통합 방식은 Git 설정과 Option에 따라 Merge 또는 Rebase가 될 수 있다.

실행 전 현재 Branch와 Working Tree 상태를 확인한다.

git branch --show-current
git status
git fetch origin
git log --oneline --graph --decorate --all

통합 방식을 명시하면 의도가 분명해진다.

# Merge 방식
git pull --no-rebase origin main

# Rebase 방식
git pull --rebase origin main

# Fast-forward만 허용
git pull --ff-only origin main

팀이 정한 History 정책과 현재 Branch의 공유 여부에 맞는 방식을 선택한다.

7 ) Local Repository를 GitHub에 Push

빈 GitHub Repository를 준비한 뒤 기존 Local Repository를 연결하는 흐름은 다음과 같다.

Local File 작성
      │ git add
      ▼
Staging Area
      │ git commit
      ▼
Local Branch
      │ git remote add
      ▼
Remote 연결
      │ git push -u
      ▼
GitHub Remote Branch

Local Repository 확인

git status
git branch --show-current
git log --oneline --decorate -n 5

아직 Commit이 없다면 File을 Stage하고 Commit한다.

git add 
git diff --staged
git commit -m "docs: add initial content"

GitHub에서 만든 빈 Repository를 origin으로 등록한다.

git remote add origin \
  https://github.com//.git
git remote -v

현재 Branch 이름을 확인한 뒤 같은 이름의 Remote Branch로 Push한다.

git branch --show-current
git push -u origin main

-u 또는 --set-upstream은 현재 Local Branch가 어느 Remote Branch를 추적할지 설정한다. 관계가 설정된 뒤에는 Remote와 Branch 인자를 생략할 수 있다.

git push
git pull --ff-only

새로운 Local Branch를 처음 Push할 때는 해당 Branch의 Upstream을 다시 설정할 수 있다.

git switch -c feature/login
git push -u origin feature/login

Local Repository의 초기 Branch가 항상 master이고 GitHub가 항상 main인 것은 아니다. 실제 이름을 확인하고 필요할 때만 Branch 이름을 변경한다.

git branch --show-current
git branch -M main

공유 중인 Branch 이름을 변경하면 Remote 설정, Pull Request와 다른 작업자의 Local Branch에 영향을 줄 수 있다.

8 ) SourceTree에서 Remote 작업

SourceTree의 Remote 작업도 같은 Git 상태를 변경한다.

SourceTree 작업	Git 동작	실행 후 확인
Clone	`git clone`	`git remote -v`
Remote 추가	`git remote add`	`git remote get-url`
Fetch	`git fetch`	`git log --all --graph`
Pull	`git pull`	`git status`, `git log`
Push	`git push`	Local·Remote Branch 관계

Push 화면에서는 대상 Remote와 Branch, Tag 포함 여부를 확인한다. GUI에 저장된 계정과 Repository를 실제로 Push할 권한이 있는 GitHub 계정이 다르면 인증 오류가 발생할 수 있다.

SourceTree에서 작업한 뒤 CLI로 다음 상태를 확인할 수 있다.

git status
git remote -v
git branch -vv
git log --oneline --graph --decorate --all

9 ) Push 실패 진단

오류 Message에서 인증, 권한, URL과 History 문제를 먼저 구분한다.

증상	우선 확인할 내용
`non-fast-forward`	Remote에 Local이 가지지 않은 Commit이 있는지 확인
HTTPS `403`	현재 계정의 Repository 쓰기 권한과 Token Scope
`Authentication failed`	PAT 만료·폐기 여부와 Credential Helper의 저장 계정
`Permission denied (publickey)`	SSH Key, SSH Agent, GitHub Public Key 등록과 SSH URL
`Repository not found`	Owner·Repository 이름, Private Repository 접근 권한
`remote origin already exists`	기존 `origin` URL과 추가하려는 URL 비교
`src refspec ... does not match any`	Local Commit 존재 여부와 Branch 이름

현재 연결 상태 확인

git remote -v
git branch --show-current
git branch -vv
git status

GitHub CLI 인증 확인

gh auth status

SSH 인증 확인

Remote가 SSH URL일 때 실행한다.

ssh -T git@github.com

Remote History 확인

Non-fast-forward 오류가 발생하면 Force Push 전에 Remote History를 가져온다.

git fetch origin
git log --oneline --graph --decorate --all

Remote 변경을 확인하지 않은 git push --force는 다른 작업자의 Commit을 Remote Branch에서 제외할 수 있다. History를 다시 써야 하는 명확한 이유와 팀 합의가 없다면 사용하지 않는다.

10 ) Credential 노출 대응

PAT, Password나 Private Key가 Source File, Commit 또는 화면 공유에 노출되면 문자열을 지우는 작업만으로 해결되지 않는다.

GitHub에서 해당 Credential을 폐기한다.
필요한 최소 권한과 만료 기간으로 새 Credential을 발급한다.
Local Credential Helper와 CI Secret을 새 값으로 갱신한다.
Repository에 Commit됐다면 Git History와 Remote Cache의 정리 범위를 확인한다.
Audit Log와 관련 Service Log에서 의심스러운 사용 기록을 확인한다.

새 Token 값을 문서의 예제에 다시 넣지 않는다.

전체 정리

최종 정리

GitHub는 Git Remote Repository를 Hosting하고 Pull Request, Issue와 자동화 기능을 제공한다.

HTTPS는 PAT와 Credential Helper를, SSH는 Local Private Key와 GitHub에 등록한 Public Key를 사용한다.

Clone은 Local Repository를 만들고 Fork는 GitHub 계정 아래에 별도 Remote Repository를 만든다.

Fetch는 Remote 상태를 가져오고 Pull은 가져온 변경을 현재 Branch에 통합한다.

git push -u는 현재 Local Branch와 Remote Branch의 Upstream 관계를 설정한다.

Push 실패 시 Force Push보다 Remote URL, 인증 계정, 권한, Branch와 Remote History를 먼저 확인한다.

노출된 Credential은 문서에서 삭제한 뒤 GitHub에서 폐기하고 새로 발급해야 한다.

Container Image Registry와 Kubernetes Image Pull

2026-09-09T00:00:00+09:00

Docker 이미지와 Union File System에서는 Image 이름, Tag와 Docker Hub Push를 다뤘다. 이 글에서는 범위를 Registry 전체로 확장하여 Image가 저장되고 배포되는 과정과 Kubernetes Worker가 Registry에서 Image를 가져오는 과정을 연결한다.

1 ) Image Registry

Image Registry

Container Image와 OCI Artifact를 이름과 Version별로 저장하고 Client의 Push와 Pull 요청에 응답하는 Service이다.

Registry는 Image File 하나를 그대로 보관하는 단순 File Server가 아니다. Image Manifest, 여러 Layer와 설정 정보를 Content Digest로 관리하고 Repository와 Tag를 통해 이를 찾을 수 있게 한다.

Image의 전체 참조 형식은 다음과 같다.

REGISTRY/NAMESPACE/REPOSITORY:TAG
REGISTRY/NAMESPACE/REPOSITORY@DIGEST

구성 요소	예시	역할
Registry	`docker.io`	Image를 제공하는 Registry 주소
Namespace	`example-user`	사용자, 조직 또는 Project 구분
Repository	`python-app`	하나의 Application Image 계열
Tag	`v1.0`	사람이 읽을 수 있는 Version 별칭
Digest	`sha256:...`	Image Content를 식별하는 불변 Hash

docker.io/library/nginx:1.29에서 docker.io는 Registry, library는 Namespace, nginx는 Repository, 1.29는 Tag이다. Tag는 다른 Image를 가리키도록 바뀔 수 있지만 Digest는 같은 Content를 계속 가리킨다.

2 ) Public Registry와 Private Registry

Registry는 접근 범위와 운영 주체에 따라 구분할 수 있다.

구분	예시	특징	확인할 사항
Public Registry Service	Docker Hub, GHCR, Quay.io	Internet에서 바로 사용하기 쉽고 공개 Image 생태계가 큼	Rate Limit, 공개 범위, 계정 보안
Cloud Registry Service	Amazon ECR, Google Artifact Registry 등	Cloud IAM, Audit와 CI/CD Service 연동	Region, 권한, Network와 비용 정책
자체 Private Registry	CNCF Distribution, Harbor	내부 Network와 보안 정책에 맞게 직접 운영	TLS, 인증, Storage, Backup, 고가용성

Private Registry가 반드시 사내 Server를 의미하는 것은 아니다. Docker Hub, GHCR와 Cloud Registry에서도 비공개 Repository를 사용할 수 있다. 반대로 자체 Registry를 실행해도 인증과 Network 접근 제어가 없다면 안전한 Private Registry라고 볼 수 없다.

Service의 무료 범위, 저장 용량과 과금 정책은 변경될 수 있으므로 Registry 선택 시 현재 공식 Plan을 확인한다.

3 ) Image 배포 흐름

Application을 Registry를 통해 배포하는 기본 흐름은 다음과 같다.

Source Code + Dockerfile
          │ docker build
          ▼
      Local Image
          │ docker tag
          ▼
Registry 주소가 포함된 Image 참조
          │ docker push
          ▼
        Registry
          │ docker pull
          ▼
Docker Host 또는 Kubernetes Worker

단계	명령	결과
Build	`docker build`	Local Image Store에 Image 생성
Tag	`docker tag`	같은 Image에 Registry용 참조 이름 추가
Push	`docker push`	Registry에 Manifest와 Layer 업로드
Pull	`docker pull`	Registry에서 Manifest와 필요한 Layer 다운로드

Application Image를 만드는 방법은 애플리케이션별 Docker 이미지 빌드에서 자세히 다룬다. 여기서는 다음 Image가 Local에 준비되어 있다고 가정한다.

docker image ls my-python-app

4 ) Docker Hub에 Image 배포

Tag와 Push

Local Image에 Docker Hub Namespace가 포함된 이름을 추가한다.

docker tag my-python-app:latest \
  /python-app:v1.0

두 이름이 같은 Image ID를 가리키는지 확인한다.

docker image ls \
  /python-app:v1.0

Registry로 Push한다.

docker push \
  /python-app:v1.0

Push가 끝나면 다른 Host 또는 Local Image를 사용하지 않는 격리된 환경에서 Pull하여 Registry 배포를 검증한다.

docker pull \
  /python-app:v1.0

latest는 자동으로 최신 Version을 찾는 기능이 아니라 이름이 latest인 Tag이다. 배포 Manifest에는 검증한 Version Tag를 사용하고 더 강한 재현성이 필요하면 Digest를 고정한다.

Public과 Private Repository

Public Repository의 Image는 일반적으로 인증 없이 Pull할 수 있다. Private Repository는 Registry가 발급한 Credential이 필요하며 Docker Hub의 제공 범위와 비용 정책은 현재 Plan을 확인해야 한다.

로그인하지 않은 상태에서 Private Image Pull이 실패하면 다음 항목을 확인한다.

Image 이름의 Namespace와 Repository가 정확한지 확인한다.
계정 또는 Token에 Repository를 읽을 권한이 있는지 확인한다.
Token이 만료되거나 폐기되지 않았는지 확인한다.
docker logout 후 올바른 계정으로 다시 로그인했는지 확인한다.

5 ) Kubernetes의 Image Pull

Kubernetes는 Registry에 Image를 Push하지 않는다. 관리자가 Deployment를 생성하면 Control Plane이 Pod 배치를 결정하고, 선택된 Worker의 kubelet이 Container Runtime을 통해 Image를 Pull한다.

관리 Client
    │ Deployment 제출
    ▼
API Server
    │
    ├── Deployment·ReplicaSet Controller가 Pod 생성
    │
    └── Scheduler가 실행할 Worker 결정
                         │
                         ▼
                    Worker kubelet
                         │ CRI 요청
                         ▼
                       containerd
                         │ Image Pull
                         ▼
                       Registry
                         │ Layer 저장
                         ▼
                    Container 실행

Public Image를 사용하는 Deployment

다음 내용을 flask-deployment.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flask-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: flask-web
  template:
    metadata:
      labels:
        app: flask-web
    spec:
      containers:
        - name: flask-container
          image: /python-app:v1.0
          ports:
            - name: http
              containerPort: 5000

Service는 세 Pod의 Port 5000으로 요청을 전달한다. 다음 내용을 flask-service.yaml로 저장한다.

apiVersion: v1
kind: Service
metadata:
  name: flask-service
spec:
  type: ClusterIP
  selector:
    app: flask-web
  ports:
    - name: http
      protocol: TCP
      port: 8080
      targetPort: 5000

Control Plane에 접근 가능한 관리 Client에서 적용한다.

kubectl apply -f flask-deployment.yaml
kubectl apply -f flask-service.yaml
kubectl rollout status deployment/flask-deployment
kubectl get pods -o wide

Ingress를 연결하기 전에 Port Forwarding으로 Service와 Pod 응답을 먼저 확인한다.

kubectl port-forward service/flask-service 8080:8080

다른 Terminal에서 요청한다.

curl http://127.0.0.1:8080

Application Log와 Pod Event를 함께 확인한다.

kubectl logs deployment/flask-deployment --all-pods=true
kubectl describe pod 
kubectl get events \
  --sort-by=.metadata.creationTimestamp

외부 Host 기반 Routing은 Kubernetes Ingress와 HTTP Routing에서 이어서 다룬다. 새 Ingress Manifest는 Legacy Annotation 대신 spec.ingressClassName을 사용한다.

Private Image와 `imagePullSecrets`

Private Repository를 사용하는 Pod는 같은 Namespace의 Registry Credential Secret을 참조한다.

spec:
  template:
    spec:
      imagePullSecrets:
        - name: regcred
      containers:
        - name: flask-container
          image: /private-python-app:v1.0

동작 관계는 다음과 같다.

Pod의 imagePullSecrets
        │
        ▼
Worker kubelet이 같은 Namespace의 Secret 확인
        │
        ▼
CRI Image Pull 요청에 Registry 인증 정보 전달
        │
        ▼
containerd가 Private Registry에서 Image Pull

Secret 생성과 안전한 Credential 관리 방법은 Kubernetes 환경 변수, Secret과 ConfigMap의 Private Registry Secret 절에서 다룬다.

ImagePullBackOff가 발생하면 Application Log보다 Pod Event를 먼저 확인한다. Container가 시작되기 전 Image Pull 단계에서 실패하면 Application Log가 존재하지 않을 수 있다.

kubectl describe pod 
kubectl get pod  \
  -o jsonpath='{.spec.containers[*].image}{"\n"}'

6 ) 자체 Registry 구성

CNCF Distribution은 OCI Distribution API를 제공하는 가벼운 Registry 구현이다. Local File System을 기본 Storage로 사용할 수 있고 필요에 따라 외부 Object Storage와 인증 구성을 연결할 수 있다.

격리된 실습용 Registry 실행

다음 구성은 localhost 또는 신뢰할 수 있는 폐쇄형 실습 Network에서 Registry API를 확인하기 위한 예제이다. 외부에 공개할 운영 구성으로 사용하지 않는다.

Registry Data를 Container 삭제와 분리하기 위해 Named Volume을 먼저 생성한다.

docker volume create registry-data

Registry Container를 실행한다.

docker run -d \
  --name registry \
  --restart=always \
  -p 5000:5000 \
  -v registry-data:/var/lib/registry \
  registry:3

설정	역할
`-p 5000:5000`	Host의 TCP `5000`을 Registry API에 연결
`--restart=always`	Docker Daemon 재시작 후 Container 재실행
`-v registry-data:/var/lib/registry`	Registry Manifest와 Layer를 Volume에 저장
`registry:3`	CNCF Distribution 3.x Image 사용

Container 상태, API 응답과 Log를 확인한다.

docker ps --filter name=registry
curl -i http://127.0.0.1:5000/v2/
docker logs registry

인증이 없는 Local Registry의 /v2/가 정상 동작하면 빈 JSON Object인 {}가 반환될 수 있다. 인증을 적용한 Registry에서는 401 Unauthorized와 인증 Challenge가 정상 상태일 수 있다.

Local Registry에 Push

Image에 Registry 주소가 포함된 Tag를 추가한다.

docker tag my-python-app:latest \
  127.0.0.1:5000/python-app:v1

Push한 뒤 Registry Catalog와 Tag를 확인한다.

docker push 127.0.0.1:5000/python-app:v1
curl http://127.0.0.1:5000/v2/_catalog
curl http://127.0.0.1:5000/v2/python-app/tags/list

Registry Container를 재시작하고 Image를 다시 Pull하여 Volume의 Data가 유지되는지 확인한다.

docker restart registry
docker pull 127.0.0.1:5000/python-app:v1
docker logs --tail 50 registry

7 ) HTTP Registry와 TLS Registry

Docker와 containerd는 Registry 통신에서 HTTPS를 기본으로 기대한다. Plain HTTP Registry는 Traffic과 Credential을 보호하지 못하므로 격리된 실습 환경에서만 제한적으로 사용한다.

환경	통신 방식	요구 사항
Local 단일 Host 실습	`http://127.0.0.1:5000`	외부 접근 차단, 실제 Credential 사용 금지
폐쇄형 다중 Node 실습	임시 HTTP 또는 내부 CA 기반 HTTPS	접근 가능한 Node 제한, 사용 목적과 위험 명시
운영 환경	신뢰 가능한 TLS 기반 HTTPS	인증, 권한, 영구 Storage, Backup, Monitoring

운영 Registry는 다음 항목을 함께 설계한다.

DNS Name과 Server 인증서의 Subject Alternative Name이 일치해야 한다.
Registry를 사용하는 모든 Client가 인증서 발급 CA를 신뢰해야 한다.
Repository별 Push와 Pull 권한을 분리한다.
Registry Metadata와 Blob Storage를 영구 저장하고 Backup한다.
Disk 사용량, 오류율, 인증 실패와 취약점 Scan 결과를 Monitoring한다.

Docker Engine의 실습용 HTTP 허용

Docker Engine으로 Remote HTTP Registry에 Push하거나 Pull해야 하는 격리된 실습 환경에서는 /etc/docker/daemon.json의 insecure-registries에 정확한 Host와 Port를 등록할 수 있다.

{
  "insecure-registries": [
    "192.168.0.100:5000"
  ]
}

기존 daemon.json에 다른 설정이 있다면 File 전체를 덮어쓰지 않고 JSON Object 안에 항목을 병합한다. 문법을 확인한 뒤 Docker를 재시작한다.

sudo systemctl restart docker
docker info

이 설정은 해당 Docker Daemon의 동작만 바꾼다. Kubernetes Worker가 containerd를 사용한다면 Docker 설정만으로 kubelet의 Image Pull이 허용되지 않는다.

8 ) Kubernetes Worker의 containerd Registry 설정

Registry 설정은 실제 Image를 Pull할 가능성이 있는 모든 Worker에 필요하다. Control Plane Node에도 Workload Scheduling을 허용했다면 해당 Node 역시 같은 설정 대상이다.

Control Plane
└── Pod를 어느 Worker에 배치할지 결정

Worker
├── kubelet이 PodSpec의 Image 참조 확인
├── containerd에 Pull 요청
└── Worker Local Storage에 Image Layer 저장

`hosts.toml` 작성

각 Worker에서 Registry Host와 Port에 해당하는 Directory를 만든다.

sudo mkdir -p \
  /etc/containerd/certs.d/192.168.0.100:5000

/etc/containerd/certs.d/192.168.0.100:5000/hosts.toml에 격리된 HTTP 실습 Registry를 등록한다.

server = "http://192.168.0.100:5000"

[host."http://192.168.0.100:5000"]
  capabilities = ["pull", "resolve"]

skip_verify는 HTTPS 인증서 검증을 건너뛰는 Option이다. Plain HTTP를 지정하는 설정에 습관적으로 추가하지 않는다. 운영 환경에서는 http:// 대신 https://를 사용하고 필요한 CA 인증서를 배포한다.

containerd 1.x의 `config_path`

/etc/containerd/config.toml이 Version 2 형식이고 containerd 1.x를 사용한다면 다음 Section을 확인한다.

version = 2

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

containerd 2.x의 `config_path`

containerd 2.x의 Version 3 설정에서는 Plugin 경로가 다르다.

version = 3

[plugins."io.containerd.cri.v1.images".registry]
  config_path = "/etc/containerd/certs.d"

기존 설정의 version과 Plugin Section을 먼저 확인하고 서로 다른 Version 예제를 한 File에 동시에 넣지 않는다.

containerd --version
sudo containerd config dump | less

config_path를 처음 활성화하도록 config.toml을 변경했다면 containerd를 재시작하고 상태와 Log를 확인한다.

sudo systemctl restart containerd
sudo systemctl status containerd --no-pager
sudo journalctl -u containerd -n 100 --no-pager

config_path가 이미 설정된 환경에서 Registry별 hosts.toml만 변경하는 경우에는 containerd가 해당 Directory의 변경을 읽으므로 일반적으로 Daemon 재시작이 필요하지 않다.

각 Worker에서 CRI 경로를 직접 검증한다.

sudo crictl pull \
  192.168.0.100:5000/python-app:v1
sudo crictl images

그다음 Control Plane에 접근 가능한 관리 Client에서 Pod를 다시 생성하거나 Deployment Rollout을 수행한다.

kubectl rollout restart deployment/flask-deployment
kubectl rollout status deployment/flask-deployment
kubectl get pods -o wide

Deprecated Registry 설정

다음과 같이 CRI Plugin 아래에 registry.mirrors와 registry.configs를 직접 작성하는 방식은 Deprecated 상태이다.

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."192.168.0.100:5000"]
  endpoint = ["http://192.168.0.100:5000"]

기존 환경을 확인할 때는 볼 수 있지만 신규 구성은 config_path와 Registry별 hosts.toml을 사용한다.

9 ) Legacy Registry Web UI

Registry API 자체는 Image 검색과 권한 관리를 위한 완성된 Web Portal을 제공하지 않는다. 과거에는 hyper/docker-registry-web Container를 --link로 Registry에 연결하는 예제가 사용되었다.

이 구성은 다음 이유로 신규 환경에 그대로 적용하지 않는다.

Docker의 Legacy Container Link에 의존한다.
오래된 별도 Image의 유지보수와 보안 상태를 추가로 검증해야 한다.
인증, 권한, 취약점 Scan과 Project 관리가 Registry와 분리된다.

단순 API 확인은 /v2/, /v2/_catalog와 /tags/list를 사용하고 관리 UI와 보안 기능이 필요하면 Harbor 같은 Registry Platform을 검토한다.

10 ) Harbor

Harbor는 OCI 호환 Registry를 기반으로 내부 Image와 Artifact를 관리하는 Open Source Registry Platform이다.

기능	역할
Project	Repository와 접근 범위를 조직 단위로 구분
RBAC	사용자와 Robot Account의 Push·Pull 권한 관리
Web UI	Repository, Artifact, Tag와 Scan 결과 확인
Vulnerability Scan	저장된 Artifact의 알려진 취약점 검사
Replication	다른 Registry와 Artifact 복제
OCI Artifact	Container Image 외 Helm Chart 등의 Artifact 저장

CNCF Distribution이 Registry API의 가벼운 기반을 제공한다면 Harbor는 조직에서 필요한 사용자 관리, 보안 검사와 운영 UI를 함께 제공한다. 그 대신 구성 요소와 운영 부담이 더 크므로 단일 개발 Host의 단순 저장소에는 Distribution이 적합할 수 있고, 여러 사용자와 Project를 관리해야 하는 환경에는 Harbor가 적합할 수 있다.

Helm Chart도 OCI Artifact로 Registry에 저장할 수 있다. Chart Package의 실제 Push와 Pull 과정은 Kubernetes Helm Chart와 Release 관리에서 이어서 다룬다.

11 ) Registry 문제 진단 순서

Image Pull 실패는 Application 실행 이전 단계의 문제이다. 다음 순서로 범위를 좁힌다.

Image 참조의 Registry, Namespace, Repository와 Tag가 정확한지 확인한다.
실행 주체가 Public Image인지 Private Image인지 확인한다.
Registry API와 TCP Port에 접근할 수 있는지 확인한다.
TLS 인증서와 Client의 CA 신뢰 상태를 확인한다.
Docker 또는 containerd 중 실제 Pull을 수행하는 Runtime 설정을 확인한다.
Kubernetes에서는 Secret의 Namespace와 imagePullSecrets 이름을 확인한다.
Pod Event, containerd Log와 Registry Log의 같은 시간대 요청을 대조한다.

# Registry Host
docker logs --since 10m registry

# Worker
sudo journalctl -u containerd --since "10 minutes ago"

# Control Plane에 접근 가능한 관리 Client
kubectl describe pod 
kubectl get events \
  --sort-by=.metadata.creationTimestamp

증상	우선 확인 대상
`ImagePullBackOff`	직전 Pull 실패 원인을 보여주는 Pod Event
`unauthorized`	Registry Credential과 Repository 권한
`manifest unknown`	Repository, Tag와 Platform Manifest
`x509: certificate signed by unknown authority`	Worker의 CA Trust와 Registry 인증서 Chain
`http: server gave HTTP response to HTTPS client`	HTTP Registry 허용 설정과 실제 Protocol
`connection refused`	Registry Process, Listen Port, Firewall와 주소

전체 정리

최종 정리

Registry는 Image Manifest와 Layer를 Repository, Tag와 Digest로 관리하고 Push와 Pull API를 제공한다.

Kubernetes에서는 Scheduler가 Worker를 선택하고 해당 Worker의 kubelet과 containerd가 Registry에서 Image를 Pull한다.

Private Image는 같은 Namespace의 imagePullSecrets와 Registry 읽기 권한이 필요하다.

Docker Engine의 Registry 설정과 Kubernetes Worker의 containerd Registry 설정은 서로 다른 대상이다.

Plain HTTP와 인증서 검증 생략은 격리된 실습에만 제한하고 운영 Registry에는 TLS, 인증, 권한과 영구 Storage를 구성한다.

containerd의 Legacy registry.mirrors 방식은 Deprecated 상태이며 신규 구성은 config_path와 hosts.toml을 사용한다.

Harbor는 OCI Registry에 Project, RBAC, Web UI, 취약점 Scan과 Replication을 결합한 Platform이다.

Version Control과 Git 기본 작업 흐름

2026-09-09T00:00:00+09:00

Container Image, Kubernetes Manifest와 Helm Chart도 Source Code와 함께 계속 변경된다. Git을 사용하면 이러한 File의 변경 이력을 기록하고, 특정 시점의 상태를 다시 확인하며, 여러 사람이 변경 내용을 교환하고 병합할 수 있다.

이 글에서 Local Repository와 Commit의 기본 구조를 익힌 뒤 Git 이력 관리와 Branch 작업에서 이력 비교, 복구와 Branch 통합을 다룬다. Remote Repository와의 작업은 GitHub Remote Repository 작업 흐름으로 이어진다.

1 ) Version Control System

Version Control System, VCS

File의 변경 내용을 시간 순서대로 기록하여 특정 Version을 확인하거나 복원하고 여러 작업자의 변경을 조정하는 System이다.

Version 관리 대상은 Source Code로 제한되지 않는다. Text로 표현할 수 있는 설정 File, 문서, Kubernetes Manifest와 Script도 관리할 수 있다. Binary File도 저장할 수 있지만 작은 변경에도 File 전체가 크게 달라질 수 있어 저장 공간과 변경 비교 측면에서 별도 관리 전략이 필요하다.

Version 관리로 해결하려는 주요 문제는 다음과 같다.

누가 언제 어떤 내용을 변경했는지 추적한다.
현재 상태와 이전 상태의 차이를 비교한다.
문제가 생긴 변경의 범위를 찾고 필요한 Version으로 복원한다.
여러 작업자가 만든 변경을 하나의 History로 병합한다.
Local 작업과 Server의 공유 상태를 분리한다.

2 ) Version Control System의 종류

Version Control System은 History를 저장하고 공유하는 구조에 따라 Local, Centralized와 Distributed 방식으로 구분할 수 있다.

구분	History 저장 위치	협업 방식	특징	대표 예시
Local VCS	한 Computer의 Local Database	File을 별도 수단으로 전달	개인 변경 추적에는 사용할 수 있지만 중앙 협업 기능이 부족	RCS
Centralized VCS	중앙 Server	Client가 Server에서 Checkout·Commit	권한과 History를 중앙에서 관리하지만 Server 의존도가 큼	CVS, Subversion, Perforce
Distributed VCS	각 Clone에 Repository History 저장	Remote Repository와 Fetch·Push	Network 연결 없이도 Local Commit과 History 조회 가능	Git, Mercurial

Local Version Control

Local VCS는 같은 Computer 안의 Database에 Revision이나 Patch를 기록한다. 수동으로 날짜별 Directory를 복사하는 것보다 변경 이력을 체계적으로 관리할 수 있지만 다른 작업자와 History를 공유하고 병합하기에는 적합하지 않다.

RCS는 대표적인 Local Version Control System이다. 특정 운영체제나 개발 도구 설치 여부만으로 항상 제공된다고 가정하지 않고 현재 환경에서 Package 존재 여부를 확인한다.

Centralized Version Control

Centralized VCS는 중앙 Server가 기준 Repository를 관리한다.

Client A ─┐
          ├── Central VCS Server
Client B ─┘

모든 사용자가 같은 중앙 History를 기준으로 작업하기 쉬운 반면 Server에 접속할 수 없으면 Update나 Commit 같은 주요 작업이 제한될 수 있다. Server 장애가 곧바로 모든 Local 작업 File의 소실을 의미하지는 않지만 중앙 Repository의 Backup과 가용성이 중요하다.

Distributed Version Control

Distributed VCS의 Clone에는 Working File만 아니라 Repository History와 Metadata가 함께 저장된다.

Developer A Local Repository
              │ fetch·push
              ▼
        Remote Repository
              ▲
              │ fetch·push
Developer B Local Repository

각 작업자는 Network가 없어도 Local Commit, Branch 생성과 History 조회를 수행할 수 있다. checkout할 때마다 Repository 전체를 다시 Backup하는 방식은 아니다. 일반적으로 clone이 Repository를 처음 가져오고, 이후 fetch가 Remote의 새로운 Object와 Reference를 전달하며, checkout 또는 switch는 가지고 있는 Object를 이용해 Working Tree의 상태를 바꾼다.

3 ) Git

Git은 File 변경을 추적하고 여러 작업자의 변경을 병합할 수 있는 Open Source Distributed Version Control System이다. Linux Kernel 개발을 지원하기 위해 2005년에 Linus Torvalds를 중심으로 처음 개발되었다.

Git의 주요 특징은 다음과 같다.

대부분의 작업을 Local Repository에서 수행할 수 있다.
Commit 단위로 변경 이력과 작성자 정보를 추적한다.
Branch를 이용해 서로 다른 작업 흐름을 분리한다.
Remote Repository를 통해 다른 작업자와 History를 교환한다.
같은 기반에서 갈라진 변경을 Merge하거나 Rebase할 수 있다.

Git은 GitHub와 같은 Service의 이름이 아니다. Git은 Local에서 실행하는 Version Control 도구이고 GitHub, GitLab과 Bitbucket은 Git Repository Hosting과 협업 기능을 제공하는 Service이다.

4 ) Git Hosting Service

Service	Git 이외의 주요 기능	자체 설치 선택지
GitHub	Pull Request, Issues, Actions, Packages, Pages와 Project 기능	GitHub Enterprise Server
GitLab	Merge Request, Issues, CI/CD, Package·Container Registry	GitLab Self-Managed
Bitbucket	Pull Request, Pipeline과 Jira 등 Atlassian 제품 연동	제공 형태와 Plan 확인 필요

Hosting Service의 무료 사용자 수, Private Repository 범위, CI 실행 시간과 Storage 한도는 변경될 수 있다. 문서에 특정 수치를 고정하지 않고 사용할 시점의 공식 Plan과 조직 정책을 확인한다.

Remote Repository와 Local Repository

Local Repository

현재 Computer의 .git Directory에 저장된 Git Object, Reference와 설정이다.

Remote Repository

다른 Repository와 History를 교환하기 위해 이름과 URL로 등록한 Repository이다.

Remote Repository가 반드시 Cloud Service에 있어야 하는 것은 아니다. 접근 가능한 Server의 Bare Repository도 Remote로 사용할 수 있다. origin은 특별한 Protocol이 아니라 git clone이 기본적으로 등록하는 Remote 이름이다.

git remote -v

5 ) Git 설치와 Version 확인

Git 공식 배포 경로나 운영체제의 Package Manager를 사용하여 설치한다. Linux 배포판에서는 일반적으로 git Package로 제공된다.

설치된 Git Version을 확인한다.

git --version

GitHub 기능을 Terminal에서 사용해야 한다면 GitHub CLI인 gh를 별도로 설치할 수 있다. gh는 Git 자체를 대체하지 않는다.

gh --version

GUI Client가 필요하면 SourceTree 같은 도구를 사용할 수 있다. GUI에서 Stage, Commit과 Push를 실행해도 내부적으로 다루는 Git Repository와 기본 개념은 같다.

6 ) 사용자 정보 설정

Git Commit에는 작성자 이름과 Email이 Metadata로 기록된다. 이 값은 Hosting Service Login 정보와 자동으로 같아지는 것이 아니므로 직접 설정을 확인한다.

모든 Local Repository의 기본값으로 사용할 이름과 Email을 설정한다.

git config --global user.name ""
git config --global user.email ""

현재 Repository에서만 다른 값을 사용하려면 --global을 제외한다.

git config user.name ""
git config user.email ""

설정 값을 확인한다.

git config user.name
git config user.email
git config --list --show-origin

범위	Option	일반적인 저장 위치	우선순위
System	`--system`	System Git 설정 File	낮음
사용자	`--global`	사용자 Git 설정 File	중간
현재 Repository	`--local` 또는 생략	`.git/config`	높음

같은 Key가 여러 범위에 있으면 더 구체적인 Repository 설정이 사용자 기본값보다 우선한다.

7 ) 초기 Branch 이름

Git이 새 Repository에 사용할 초기 Branch 이름은 Git Version, 배포판 설정과 사용자 설정에 따라 달라질 수 있다. Hosting Service가 새 Remote Repository에 선택하는 기본 Branch 이름과 Local git init의 결과도 항상 같다고 가정할 수 없다.

새 Local Repository의 초기 Branch 이름을 main으로 통일하려면 다음과 같이 설정한다.

git config --global init.defaultBranch main

특정 Repository를 만들 때 직접 지정할 수도 있다.

git init --initial-branch=main

이미 Commit이 있는 Repository의 Branch 이름을 바꾸는 작업은 Remote Branch와 협업자에게 영향을 줄 수 있으므로 단순 초기 설정과 구분한다.

8 ) Git의 세 작업 영역

Git의 기본 흐름을 이해하려면 Working Tree, Staging Area와 Local Repository를 구분해야 한다.

Working Tree
    │ git add
    ▼
Staging Area(Index)
    │ git commit
    ▼
Local Repository(.git)
    │ git push
    ▼
Remote Repository

영역	저장되는 내용	주요 확인 명령
Working Tree	사용자가 현재 편집하는 File	`git status`, `git diff`
Staging Area	다음 Commit에 넣기로 선택한 내용	`git diff --staged`
Local Repository	Commit, Tree, Blob와 Reference 등 Git Object	`git log`, `git show`
Remote Repository	다른 Repository와 교환한 Commit과 Branch Reference	`git remote -v`, `git branch -r`

Working Tree

Working Tree는 특정 Commit에서 Checkout한 File을 실제로 편집하는 공간이다. 일반 Repository에서는 .git Directory를 제외한 Project File 영역으로 볼 수 있다.

Staging Area

Staging Area는 다음 Commit에 포함할 내용을 선택하는 영역이며 Index라고도 한다. File을 단순히 다른 Directory로 이동시키는 것이 아니라 다음 Commit의 Snapshot에 포함할 내용을 Git Index에 기록한다.

Local Repository

.git Directory에는 Git Object Database, Branch와 Tag Reference, Repository 설정 등이 저장된다. .git을 삭제하면 Working File이 남아 있더라도 해당 Local Repository의 History와 설정을 잃을 수 있다.

9 ) File 상태

상태	의미	다음에 주로 사용하는 명령
Untracked	Working Tree에는 있지만 현재 Commit이 추적하지 않는 File	`git add` 또는 `.gitignore` 등록
Modified	추적 중인 File이 Index 또는 현재 Commit과 달라진 상태	`git diff`, `git add`
Staged	다음 Commit에 포함할 내용이 Index에 기록된 상태	`git diff --staged`, `git commit`
Committed	내용이 Local Repository의 Commit에 기록된 상태	`git log`, `git show`

하나의 File이 항상 한 상태만 가지는 것은 아니다. File을 Stage한 후 다시 수정하면 같은 File에 Staged 변경과 아직 Stage하지 않은 변경이 동시에 존재할 수 있다.

git status
git diff
git diff --staged

git status는 상태를 요약하고 git diff는 Working Tree와 Index의 차이, git diff --staged는 Index와 현재 Commit의 차이를 보여준다.

`.gitignore`

.gitignore는 Git이 추적하지 않을 File과 Directory Pattern을 기록한다. Build 결과, Package 설치 Directory, 가상 환경과 Local Credential처럼 Repository에 포함할 필요가 없는 항목을 제외할 때 사용한다.

# Python
.venv/
__pycache__/
*.pyc

# Node.js
node_modules/

# Java·Spring
.gradle/
build/
target/

# Local 환경과 Credential
.env
*.key

Project 구성원이 공통으로 제외할 Pattern은 Repository의 .gitignore에 기록하고 함께 Commit한다. 개인 Editor의 임시 File처럼 Project에 공유할 필요가 없는 Pattern은 Repository의 .git/info/exclude나 사용자 전역 Ignore File에서 관리할 수 있다.

.gitignore는 Untracked File에 적용된다. 이미 Commit했거나 Stage하여 Git이 추적 중인 File은 Pattern을 추가해도 자동으로 추적 대상에서 빠지지 않는다.

git status
git check-ignore -v 
git ls-files 

추적 중인 File을 Working Tree에는 남겨두고 이후 Commit 대상에서 제외하려면 먼저 변경 범위와 Repository 정책을 확인한 뒤 Index에서 제거한다.

git rm --cached 
git status
git diff --staged

git rm --cached 결과는 다음 Commit에 반영되는 변경이다. Directory 전체나 넓은 Pattern에 실행하기 전에 git status와 git diff --staged로 제거 대상을 확인한다. 이미 History에 들어간 Password나 Token은 .gitignore로 제거되지 않으므로 Credential을 폐기하고 History 정리 필요 여부를 별도로 판단해야 한다.

10 ) Local Repository 기본 실습

Repository 생성

새 실습 Directory를 만들고 이동한다.

mkdir git-basic-lab
cd git-basic-lab
git init --initial-branch=main

.git Directory와 현재 상태를 확인한다.

git status
ls -la

Untracked File 생성

README.md를 작성한 뒤 상태를 확인한다.

touch README.md
git status

README.md는 아직 Commit이 추적하지 않는 Untracked 상태이다.

Staging Area에 등록

다음 Commit에 포함할 File을 선택한다.

git add README.md
git status
git diff --staged

git add는 File을 Repository History에 즉시 기록하지 않는다. 현재 내용을 Staging Area에 올려 다음 Commit의 입력으로 만든다.

첫 Commit 생성

Editor를 열어 Commit Message를 작성한다.

git commit

짧은 실습에서는 -m으로 제목을 지정할 수 있다.

git commit -m "docs: add project README"

Commit과 Working Tree 상태를 확인한다.

git log --oneline --decorate
git status

수정 후 두 번째 Commit

README.md를 수정한 뒤 Working Tree와 현재 Commit의 차이를 확인한다.

git status
git diff

변경 내용을 Stage하고 실제로 Commit될 차이를 다시 검토한다.

git add README.md
git diff --staged
git commit -m "docs: explain project purpose"

History를 확인한다.

git log --oneline --graph --decorate

11 ) Commit

Commit은 Staging Area에 선택한 Project 상태를 가리키는 Snapshot과 다음 Metadata를 Local Repository에 기록한다.

작성자와 Committer 정보
작성 시각
Commit Message
Project File과 Directory 구조를 가리키는 Tree
이전 History를 연결하는 Parent Commit

Git은 File의 전체 복사본을 날짜별 Directory에 반복 저장하는 방식처럼 보이지 않는다. Content를 Object로 관리하고 같은 Content는 같은 Object를 재사용하며 Commit이 Project Snapshot을 가리키도록 구성한다.

Commit Message

Commit Message는 변경한 결과뿐 아니라 변경 이유를 History에 남기는 정보이다. 여러 줄 Message는 다음 구조로 작성할 수 있다.

변경 내용을 요약한 제목

변경한 이유, 고려한 제약과 필요한 추가 설명

제목과 본문 사이를 빈 줄로 구분하면 git log, Hosting Service와 여러 Git 도구가 두 영역을 구분해서 표시할 수 있다.

Commit Object ID

Commit은 Git Object ID로 식별된다. 일반적인 SHA-1 Repository에서는 40자리 16진수이고 SHA-256 형식의 Repository에서는 64자리 16진수이다. 화면에서는 식별에 필요한 앞부분만 축약하여 보여주는 경우가 많다.

git log --oneline
git rev-parse HEAD

짧은 ID는 현재 Repository에서 다른 Object와 구분될 때 편리하게 사용할 수 있지만 고정 길이의 전역 Identifier라고 가정하지 않는다.

12 ) Remote Repository와 Push

Local Commit은 git commit만으로 Remote에 전송되지 않는다. Remote Repository URL을 등록하고 Push해야 한다.

git remote add origin 
git remote -v

현재 main Branch를 origin에 Push하고 Upstream 관계를 설정한다.

git push -u origin main

Working Tree 변경
      │ git add
      ▼
Staging Area
      │ git commit
      ▼
Local main Branch
      │ git push
      ▼
Remote의 main Branch

git push는 Working Tree File을 바로 Server로 복사하는 명령이 아니다. Local Repository의 Commit과 Reference를 Remote와 교환하여 Remote Branch를 갱신한다.

Push가 거절되면 강제 Push부터 실행하지 않는다. Remote에 Local이 가지고 있지 않은 Commit이 있는지 먼저 확인한다.

git fetch origin
git log --oneline --graph --decorate --all

13 ) Container·Kubernetes 작업과 Git

Git Repository에는 Container Image Binary 자체보다 Image를 재현할 수 있는 입력을 저장한다.

저장 대상	예시
Application Source	Python, Java, Go와 JavaScript Source File
Image Build 정의	`Dockerfile`, `.dockerignore`
Package 의존성	`requirements.txt`, `package.json`, Build 설정
Kubernetes 설정	Deployment, Service, ConfigMap Manifest
배포 구성	Kustomize Base·Overlay, Helm Chart와 Values
자동화	CI/CD Workflow와 Shell Script

다음 정보는 Repository에 직접 Commit하지 않는다.

Docker Hub Personal Access Token
Private Key
실제 Password가 들어 있는 Secret Manifest
Cloud Access Key
Local 개발 환경의 Credential File

Secret을 .gitignore에 넣는 것은 실수 방지 수단일 뿐 이미 Commit된 Secret을 History에서 자동으로 제거하지 않는다. Credential이 Commit되거나 외부에 노출됐다면 값을 삭제하는 것과 별개로 해당 Credential을 폐기하고 새로 발급해야 한다.

전체 정리

최종 정리

Version Control System은 File의 변경 이력을 기록하고 특정 Version의 비교, 복원과 협업을 지원한다.

Git은 각 Clone이 Local Repository와 History를 가지는 Distributed Version Control System이다.

Git과 GitHub·GitLab·Bitbucket 같은 Hosting Service는 서로 다른 대상이다.

Git의 기본 작업 영역은 Working Tree, Staging Area와 Local Repository이다.

git add는 다음 Commit에 포함할 내용을 선택하고 git commit은 이를 Local Repository에 기록한다.

git push는 Local Commit과 Branch Reference를 Remote Repository로 전송한다.

.gitignore는 의도적으로 추적하지 않을 File을 지정하며 이미 추적 중인 File에는 자동으로 적용되지 않는다.

초기 Branch 이름과 Object ID 길이는 Version과 Repository 형식에 따라 달라질 수 있으므로 고정된 값으로 단정하지 않는다.

Container와 Kubernetes 작업에서는 재현 가능한 설정을 Git에 저장하고 Token, Password와 Private Key는 Commit하지 않는다.

Kubernetes Kustomize로 Manifest 구성 관리

2026-09-08T00:00:00+09:00

Kubernetes Application은 Deployment 하나만으로 끝나지 않고 Service, Ingress, ConfigMap과 Secret 등 여러 Manifest로 구성된다. Kustomize는 원본 YAML을 Template 문법으로 바꾸지 않고 Resource를 조합하고 공통 설정과 환경별 차이를 적용하여 최종 Manifest를 만든다.

1 ) Kustomize

Kustomize

Kubernetes Resource YAML을 Base로 유지하면서 Label, Image, Namespace와 Patch를 조합하여 환경별 Manifest를 생성하는 구성 관리 도구이다.

Kustomize가 제공하는 주요 기능은 다음과 같다.

여러 Manifest를 하나의 구성 단위로 조합한다.
여러 Resource에 공통 Label, Annotation, Namespace와 이름 Prefix를 적용한다.
Base를 재사용하고 개발·검증·운영 환경의 차이만 Overlay에 기록한다.
Strategic Merge Patch와 JSON Patch로 필요한 Field만 변경한다.
File이나 Literal을 이용하여 ConfigMap과 Secret Manifest를 생성한다.

Kustomize는 Cluster 안에서 실행되는 Controller가 아니다. Master 또는 kubeconfig가 설정된 관리 Client에서 Manifest를 Rendering하고, 결과를 API Server에 적용하는 Client 도구이다.

Base Resources + Overlay + Generator
                 │
                 ▼
        Kustomize Rendering
                 │ 최종 Kubernetes Manifest
                 ▼
             API Server
                 │
                 ▼
Deployment·Service 등 각 Controller
                 │
                 ▼
Scheduler ──▶ Worker의 kubelet ──▶ Container Runtime

2 ) kubectl 내장 기능과 독립 실행형 Kustomize

Kustomize는 kubectl에 내장된 기능과 별도 설치하는 독립 실행형 Binary로 사용할 수 있다.

구분	Rendering	적용	특징
kubectl 내장	`kubectl kustomize`	`kubectl apply -k`	별도 도구 없이 기본 기능 사용
독립 실행형	`kustomize build`	Rendering 결과를 kubectl에 전달	최신 Kustomize 기능과 편집 명령을 별도로 선택 가능

두 도구에 포함된 Kustomize Version이 다르면 지원 Field나 Rendering 결과가 달라질 수 있다. 팀과 CI에서는 어느 도구와 Version을 기준으로 하는지 고정한다.

kubectl version --client
kubectl kustomize --help
kustomize version

기본적인 Build와 배포만 필요하다면 kubectl의 -k 기능으로 시작할 수 있다. 독립 실행형의 특정 기능이나 Version 통일이 필요할 때 별도 Binary를 설치한다.

3 ) asdf를 이용한 Version 관리

asdf는 여러 언어와 CLI 도구의 Version을 .tool-versions File로 관리하는 Version Manager이다. 현재 asdf 0.16 이상은 Go로 다시 작성된 Binary이며, 0.15 이하의 Shell Script 방식과 설치 및 명령 체계가 다르다.

asdf 0.16 이상

asdf Binary를 운영체제와 Architecture에 맞게 설치하고 $ASDF_DATA_DIR/shims를 PATH 앞에 추가한다. 설치 방식은 배포판 Package Manager나 공식 Release 절차를 따른다.

Kustomize Plugin과 사용할 Version을 확인한다.

asdf plugin add kustomize
asdf list all kustomize
asdf install kustomize 
asdf set --home kustomize 
kustomize version

Project Directory에만 Version을 고정하려면 해당 Directory에서 --home 없이 asdf set kustomize 을 실행한다. 생성된 .tool-versions를 함께 관리하면 작업자와 CI가 같은 Version을 선택할 수 있다.

asdf 0.15 이하의 Legacy 방식

다음 방식은 asdf v0.14.0처럼 Bash로 구현된 Version에서 사용하던 설치 방식이다. 현재 설치 절차로 사용하지 않으며, 기존 환경을 이해하거나 Migration할 때만 참고한다.

git clone https://github.com/asdf-vm/asdf.git ~/.asdf \
  --branch v0.14.0

echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
source ~/.bashrc

asdf plugin add kustomize
asdf install kustomize 5.3.0
asdf global kustomize 5.3.0

asdf 0.16 이상에서는 asdf global과 asdf local이 제거되고 asdf set으로 대체됐다. 기존 설치를 Migration할 때는 Shell RC File의 . "$HOME/.asdf/asdf.sh" 설정도 현재 Binary와 Shim 경로 설정으로 변경해야 한다.

4 ) Base Directory와 Resource 작성

Echo Application의 공통 Resource를 다음 구조로 작성한다.

echo/
└── base/
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── kustomization.yaml

Directory를 생성하고 이동한다.

mkdir -p echo/base
cd echo/base

다음 내용을 deployment.yaml로 저장한다. nginx Container가 같은 Pod의 Echo Container에 localhost:8080으로 요청을 전달한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: echo
  template:
    metadata:
      labels:
        app.kubernetes.io/name: echo
    spec:
      containers:
        - name: nginx
          image: ghcr.io/jpubdocker/simple-nginx-proxy:v0.1.0
          env:
            - name: NGINX_PORT
              value: "80"
            - name: SERVER_NAME
              value: localhost
            - name: BACKEND_HOST
              value: localhost:8080
            - name: BACKEND_MAX_FAILS
              value: "3"
            - name: BACKEND_FAIL_TIMEOUT
              value: 10s
          ports:
            - name: http
              containerPort: 80
        - name: echo
          image: ghcr.io/jpubdocker/echo:v0.1.0

같은 Pod의 Container는 Network Namespace를 공유하므로 nginx는 Echo Container를 localhost:8080으로 호출할 수 있다.

다음 내용을 service.yaml로 저장한다.

apiVersion: v1
kind: Service
metadata:
  name: echo
spec:
  selector:
    app.kubernetes.io/name: echo
  ports:
    - name: echo
      port: 80
      targetPort: http
      protocol: TCP

다음 내용을 ingress.yaml로 저장한다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
spec:
  ingressClassName: nginx
  rules:
    - host: echo.jpub.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: echo
                port:
                  number: 80

Ingress Resource가 실제 Traffic을 처리하려면 nginx IngressClass를 담당하는 Controller가 필요하다. ingress-nginx Controller의 현재 상태와 실습 조건은 Kubernetes Ingress Resource와 HTTP Routing에서 확인할 수 있다.

5 ) kustomization.yaml로 Resource 조합

독립 실행형 Kustomize는 현재 Directory의 Resource를 검색하여 kustomization.yaml을 만들 수 있다.

kustomize create --autodetect

직접 작성한다면 다음과 같다.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml

resources의 경로는 kustomization.yaml을 기준으로 해석된다. 조합 결과를 화면에 출력한다.

kustomize build .

kubectl 내장 기능으로 같은 구성을 Rendering할 수 있다.

kubectl kustomize .

Rendering 결과를 File로 저장하지 않아도 Directory를 직접 적용하고 삭제할 수 있다.

kubectl diff -k .
kubectl apply -k .
kubectl delete -k .

독립 실행형 Kustomize 결과를 Pipe로 전달할 때는 kubectl이 표준 입력의 Manifest를 읽도록 -f -를 사용한다.

kustomize build . | kubectl apply -f -
kustomize build . | kubectl delete -f -

kustomize build . | kubectl apply -k .처럼 사용하면 앞 명령의 표준 출력은 적용 대상이 되지 않는다. -k는 표준 입력이 아니라 지정한 Kustomization Directory를 읽는 Option이다.

6 ) 공통 Label 적용

여러 Resource에 같은 Label을 반복하지 않고 labels Transformer로 추가할 수 있다. kustomization.yaml에 다음 내용을 추가한다.

labels:
  - pairs:
      app.kubernetes.io/part-of: echo-system
    includeSelectors: false

includeSelectors: false는 Resource의 Metadata와 Pod Template 등에 Label을 추가하되 기존 Selector를 바꾸지 않는다. Application을 식별하는 app.kubernetes.io/name: echo는 Deployment Selector, Pod Label과 Service Selector의 연결 조건이므로 Base Manifest에 명시적으로 유지한다.

독립 실행형 Kustomize의 편집 명령으로도 Label을 설정할 수 있다.

kustomize edit set label \
  'app.kubernetes.io/part-of:echo-system'

편집 명령이 생성하는 Field 형태는 Kustomize Version에 따라 달라질 수 있으므로 변경된 kustomization.yaml과 Build 결과를 함께 확인한다.

sed -n '1,160p' kustomization.yaml
kustomize build .

Deployment의 spec.selector는 필수이며 spec.template.metadata.labels와 일치해야 한다. 공통 Label 기능을 사용한다는 이유로 Base Deployment의 필수 Selector를 제거하지 않는다.

7 ) Base와 Overlay

Base에는 환경에 공통인 Resource를 두고 Overlay에는 개발·검증·운영 환경별 차이만 둔다.

echo/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── kustomization.yaml
└── overlays/
    └── dev/
        ├── kustomization.yaml
        ├── patch-deployment.yaml
        └── patch-ingress.yaml

echo/base에서 상위 Directory로 이동한 뒤 개발 Overlay를 생성한다.

cd ..
mkdir -p overlays/dev
cd overlays/dev
kustomize create --resources ../../base

생성되는 overlays/dev/kustomization.yaml의 기본 형태는 다음과 같다.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

Base Directory 자체도 kustomization.yaml을 가지므로 Overlay의 resources에서 하나의 구성 단위로 참조할 수 있다. Version Control에는 kustomize build 결과보다 Base, Overlay와 Patch 원본을 저장한다.

8 ) Strategic Merge 방식의 Patch

개발 환경에서 Replica를 2개로 늘리고 nginx의 실패 허용 횟수를 변경한다. 다음 내용을 patch-deployment.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: nginx
          env:
            - name: BACKEND_MAX_FAILS
              value: "5"

전체 Deployment를 복사하지 않고 변경할 Field와 병합 기준이 되는 Resource·Container 이름만 작성한다. overlays/dev/kustomization.yaml에 Patch를 추가한다.

patches:
  - path: patch-deployment.yaml
    target:
      group: apps
      version: v1
      kind: Deployment
      name: echo

patchesStrategicMerge는 기존 구성에서 볼 수 있는 Legacy Field이다. 현재 문서에서는 Strategic Merge Patch와 JSON Patch를 모두 통합해서 표현할 수 있는 patches Field를 사용한다.

9 ) JSON Patch

Ingress Host처럼 배열 안의 특정 Field를 경로로 지정할 때 JSON Patch를 사용할 수 있다. 다음 내용을 patch-ingress.yaml로 저장한다.

- op: replace
  path: /spec/rules/0/host
  value: dev-echo.jpub.local

JSON Pointer의 /spec/rules/0/host는 첫 번째 Rule의 host Field를 의미한다. 마지막에 /를 추가하면 다른 경로로 해석되므로 붙이지 않는다.

overlays/dev/kustomization.yaml의 patches에 다음 항목을 추가한다.

patches:
  - path: patch-deployment.yaml
    target:
      group: apps
      version: v1
      kind: Deployment
      name: echo
  - path: patch-ingress.yaml
    target:
      group: networking.k8s.io
      version: v1
      kind: Ingress
      name: echo

개발 Overlay의 최종 결과와 변경 사항을 확인한다.

kustomize build .
kubectl diff -k .

Build 결과에서 Deployment의 Replica가 2, BACKEND_MAX_FAILS가 5, Ingress Host가 dev-echo.jpub.local인지 확인한다.

10 ) Secret Generator

Kustomize의 secretGenerator는 File, Env File 또는 Literal을 읽어 Secret Manifest를 생성한다. 다음 내용을 secret.env로 저장한다.

API_USERNAME=echo-user
API_PASSWORD=REPLACE_WITH_SECRET

실제 Secret 값이 있는 File은 Version Control 대상에서 제외한다.

secret.env

overlays/dev/kustomization.yaml에 Generator를 추가한다.

secretGenerator:
  - name: echo-secret
    envs:
      - secret.env

생성 결과를 확인한다.

kustomize build .

생성된 이름에는 echo-secret- 형태의 Suffix가 붙는다. Secret을 참조하는 Workload가 같은 Kustomization 안에 있으면 Kustomize가 알려진 참조 Field의 이름도 함께 변환한다.

envFrom:
  - secretRef:
      name: echo-secret

Hash Suffix는 Secret 내용이 바뀌었을 때 Pod Template의 참조 이름도 바뀌게 하여 새 Rollout을 유도한다. generatorOptions.disableNameSuffixHash: true로 끌 수 있지만 자동 갱신 동작도 사라지므로 이유 없이 비활성화하지 않는다.

Secret을 Git에서 제외해도 보안이 완성되는 것은 아니다. kustomize build 결과에는 Base64로 표현된 값이 포함되며 Base64는 암호화가 아니다. Terminal 출력, CI Log, 임시 File과 Cluster 접근 권한을 함께 관리해야 한다.

11 ) Remote Resource

공개된 Git Repository나 URL의 Kustomization을 resources에서 참조할 수 있다. Remote Resource는 재사용에 편리하지만 외부 Network와 공급자의 변경에 의존한다.

resources:
  - https://example.com/application/kustomization.yaml

운영 구성에서는 움직이는 Branch나 변경 가능한 URL보다 검증한 Commit이나 Release Tag를 고정하고, 적용 전 Build 결과와 Resource 권한을 검토한다.

ingress-nginx controller-v1.8.1의 Remote Kustomization은 Kustomize의 Network Resource 예제로 사용된 적이 있지만 현재 설치 대상으로 사용하지 않는다. ingress-nginx는 2026년 3월 24일 이후 신규 Release와 보안 수정이 없는 Retirement 상태이다.

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/kustomization.yaml

위 명령은 과거 Kustomization File의 내용을 확인할 뿐 Cluster에 배포하지 않는다. 신규 환경에서는 유지보수 중인 Controller나 Gateway API 구현을 선택한다.

12 ) 개발 Overlay 적용과 확인

Master 또는 관리 Client의 echo/overlays/dev에서 최종 Manifest를 먼저 확인한다.

kubectl kustomize .
kubectl diff -k .
kubectl apply -k .

Control Plane은 Rendering된 결과만 받으며 Base와 Overlay Directory 구조를 알지 못한다. API Server에 저장된 Deployment와 Service를 각 Controller가 조정하고, Scheduler가 선택한 Worker에서 kubelet이 Pod를 실행한다.

kubectl rollout status deployment/echo
kubectl get deployment,service,ingress
kubectl get pods \
  -l app.kubernetes.io/name=echo \
  -o wide
kubectl get endpointslice \
  -l kubernetes.io/service-name=echo

문제가 있으면 적용된 Resource만 보지 말고 Rendering 결과가 예상한 Selector, Image, Host와 Secret 이름을 포함하는지 먼저 확인한다.

13 ) 실습 Resource 정리

적용에 사용한 같은 Overlay Directory에서 Resource를 삭제한다.

kubectl delete -k echo/overlays/dev

현재 Directory가 echo/overlays/dev라면 다음과 같이 실행한다.

kubectl delete -k .

Secret Generator가 만든 Secret도 같은 Kustomization의 Resource이므로 함께 삭제된다.

전체 정리

최종 정리

Kustomize는 Base Resource에 공통 설정과 환경별 Patch를 적용하여 최종 Kubernetes Manifest를 만든다.

kubectl 내장 기능은 kubectl kustomize와 kubectl apply -k로 사용하고 독립 실행형은 kustomize build로 Rendering한다.

Base에는 공통 구성을, Overlay에는 환경별 차이를 두며 Build 결과보다 Base와 Patch 원본을 Version Control에서 관리한다.

Deployment Selector와 Pod Label, Service Selector의 연결은 Kustomize를 사용해도 유지해야 한다.

patches에서 Strategic Merge Patch와 JSON Patch를 사용하여 필요한 Field만 변경할 수 있다.

secretGenerator는 Secret 이름에 Content Hash를 추가하지만 Secret 값을 암호화하지는 않는다.

Control Plane은 Rendering된 Kubernetes Resource만 처리하고 Worker의 kubelet이 최종 Pod Spec을 실행한다.

다음 글인 Kubernetes Helm Chart와 Release 관리에서는 여러 Resource를 Version이 있는 Package로 묶고 설치·Upgrade·Rollback하는 방법을 다룬다.

Kubernetes Helm Chart와 Release 관리

2026-09-08T00:00:00+09:00

Kubernetes Kustomize로 Manifest 구성 관리에서 다룬 Kustomize는 원본 Manifest를 조합하고 환경별 차이를 Overlay로 관리한다. Helm은 여러 Kubernetes Resource와 기본 설정을 Version이 있는 Chart로 묶고, Chart를 Cluster에 설치한 결과를 Release 단위로 관리한다.

1 ) Helm

Helm

Kubernetes Application을 Chart로 Packaging하고 설치, Upgrade, Rollback과 제거를 Release 단위로 관리하는 CNCF Project이다.

Helm의 주요 구성 요소는 다음과 같다.

구성 요소	역할
Helm Client	Chart를 읽고 Template을 Rendering하여 Kubernetes API Server에 적용
Chart	Kubernetes Resource Template, 기본값과 Metadata를 묶은 Package
Values	같은 Chart에서 변경할 Image, Replica, Port와 Storage 등의 입력값
Manifest	Chart와 Values를 Rendering한 최종 Kubernetes YAML
Release	특정 Namespace에 설치한 Chart Instance와 Revision History
Repository·OCI Registry	Version별 Chart Package를 배포하는 저장소

관계는 다음과 같다.

Chart Templates + Default values.yaml + 사용자 Values
                         │
                         ▼
                   Helm Rendering
                         │
                         ▼
             Kubernetes Manifest 집합
                         │ API Server에 적용
                         ▼
                    Helm Release
                         │ Revision 기록
                         ▼
Deployment·StatefulSet·Service 등의 Controller
                         │
                         ▼
              Worker의 kubelet과 Pod

Helm은 Application Container를 직접 실행하지 않는다. Helm이 Rendering한 Resource를 API Server에 저장하면 Control Plane의 각 Controller가 원하는 상태를 조정하고 Worker의 kubelet이 실제 Container를 실행한다.

2 ) Helm Version과 Kubernetes 호환성

2026년 9월 기준 Helm의 현재 Stable Major Version은 Helm 4이다. Helm 3은 지원 종료 단계에 있으므로 신규 환경에서는 Helm 4와 Cluster의 호환 범위를 먼저 확인한다.

helm version
kubectl version

Helm은 내부에 포함된 Kubernetes Client Library를 통해 API Server와 통신한다. Cluster보다 지나치게 오래된 Helm이나 Helm이 보장하지 않는 더 새로운 Kubernetes Cluster를 조합하면 API 호환 문제가 생길 수 있다.

Helm 3.13.3을 고정하는 다음 명령은 당시 환경을 재현하기 위한 Legacy 예제이다.

asdf plugin add helm
asdf install helm 3.13.3
asdf global helm 3.13.3

asdf 0.16 이상에서는 asdf global 대신 asdf set을 사용한다. 실제 Version은 Cluster와 Helm의 공식 Version Skew를 확인한 뒤 선택한다.

asdf plugin add helm
asdf list all helm
asdf install helm 
asdf set --home helm 
helm version

3 ) Debian·Ubuntu에서 Helm 설치

Helm의 Debian·Ubuntu Package Repository를 이용하려면 먼저 필요한 Package를 설치한다.

sudo apt-get install curl gpg apt-transport-https --yes

Repository Signing Key를 내려받아 Fingerprint를 확인하고 Keyring으로 변환한다. Fingerprint 값은 실행 전에 Helm 공식 설치 문서의 현재 값과 다시 대조한다.

HELM_APT_KEY_ID='DDF78C3E6EBB2D2CC223C95C62BA89D07698DBC6'

curl -fsSL \
  https://packages.buildkite.com/helm-linux/helm-debian/gpgkey \
  -o /tmp/helm.gpg

if [ "$(gpg --show-keys --with-colons /tmp/helm.gpg | awk -F: '$1 == "fpr" {print $10}' | head -n 1)" != "${HELM_APT_KEY_ID}" ]
then
  echo 'ERROR: unexpected Helm APT signing key'
  exit 1
fi

확인한 Key를 등록하고 Repository를 추가한다.

gpg --dearmor < /tmp/helm.gpg | \
  sudo tee /usr/share/keyrings/helm.gpg > /dev/null

echo 'deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main' | \
  sudo tee /etc/apt/sources.list.d/helm-stable-debian.list

sudo apt-get update
sudo apt-get install helm
helm version

Package Repository에서 최신 Major Version이 설치될 수 있으므로 운영 Cluster에 적용하기 전에 helm version과 Kubernetes Version 지원 범위를 확인한다.

4 ) Chart, Repository와 OCI Registry

전통적인 Helm Repository는 index.yaml과 Chart Package를 HTTP Server에서 제공한다. OCI Registry는 Container Image와 유사한 방식으로 Chart Artifact를 저장한다.

배포 위치	검색·사용 방식
Helm Repository	`helm repo add`, `helm repo update`, `helm search repo`
Artifact Hub	Browser 또는 `helm search hub`로 여러 공급자의 Chart 검색
OCI Registry	`oci:////`를 직접 참조

등록된 Repository를 확인한다.

helm repo list

Bitnami Repository를 등록하고 Index를 갱신한다.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm search repo bitnami/nginx
helm search repo bitnami/mariadb --versions

Artifact Hub 전체에서 Chart를 찾을 수 있다.

helm search hub nginx
helm search hub mariadb

과거 Helm의 기본 Chart 모음이었던 stable과 incubator Repository는 2020년 11월부터 읽기 전용 Archive이며 신규 Chart 선택지로 사용하지 않는다. 현재 Chart는 Artifact Hub에서 공급자, 최근 Release, Source Repository와 보안 정보를 확인한 뒤 선택한다.

OCI Registry에 사용자 Chart 배포

OCI Registry는 Container Image뿐 아니라 Helm Chart Package도 저장할 수 있다. Chart Directory를 직접 Push하지 않고 helm package로 만든 .tgz File을 업로드한다.

Registry의 Image 참조 구조, Public·Private Registry와 인증 방식은 Container Image Registry와 Kubernetes Image Pull에서 다룬다.

Chart Directory
      │ helm lint
      ▼
검증된 Chart
      │ helm package
      ▼
Chart Archive(.tgz)
      │ helm push
      ▼
OCI Registry
      │ helm pull·helm install
      ▼
Helm Client

샘플 Chart를 생성한다. 기존 echo Directory가 있다면 덮어쓰지 말고 내용을 먼저 확인한다.

helm create echo
helm lint ./echo
helm template echo-preview ./echo

Chart.yaml의 name과 version을 확인한 뒤 Package를 생성한다.

helm show chart ./echo
helm package ./echo

기본 생성값을 사용했다면 현재 Directory에 echo-0.1.0.tgz가 만들어진다. 실제 File 이름은 Chart.yaml의 Version에 따라 달라진다.

Docker Hub 같은 OCI Registry에 로그인한다. Password 또는 Personal Access Token은 명령 인자에 작성하지 않고 Prompt에 입력한다.

helm registry login registry-1.docker.io \
  -u 

Package를 Registry Namespace로 Push한다.

helm push echo-0.1.0.tgz \
  oci://registry-1.docker.io/

helm push의 대상 경로에는 Chart 이름과 Tag를 붙이지 않는다. Helm이 Chart.yaml의 name을 OCI Repository 이름으로, version을 Tag로 사용하므로 위 명령의 결과 참조는 다음 형태가 된다.

registry-1.docker.io//echo:0.1.0

OCI Chart 참조는 oci:// Prefix를 사용하며 helm show, helm pull과 helm install에서 Chart Version을 명시할 수 있다.

helm show chart \
  oci://registry-1.docker.io//echo \
  --version 0.1.0

helm pull \
  oci://registry-1.docker.io//echo \
  --version 0.1.0

Cluster에 설치하기 전 Rendering 결과를 확인한다.

helm template echo-oci-preview \
  oci://registry-1.docker.io//echo \
  --version 0.1.0

검증이 끝난 Chart를 별도 Namespace에 설치하고 Helm Release와 Kubernetes Resource를 함께 확인한다.

helm install echo-oci \
  oci://registry-1.docker.io//echo \
  --version 0.1.0 \
  --namespace helm-lab \
  --create-namespace

helm status echo-oci --namespace helm-lab
kubectl get pods,services --namespace helm-lab

Chart를 Registry에 Push하는 과정은 Cluster를 변경하지 않는다. helm install을 실행해야 Helm Client가 Chart를 Pull하고 Manifest를 Rendering하여 API Server에 제출한다. 그 이후에는 Controller와 Worker의 kubelet이 Resource를 조정한다.

설치한 Chart가 Service를 생성했다면 외부 공개 설정을 추가하기 전에 Port Forwarding으로 응답을 확인한다.

kubectl port-forward \
  --namespace helm-lab \
  service/echo-oci 8080:80

Chart의 실제 Service 이름과 Port는 다음 명령으로 확인한 뒤 예제 값을 바꾼다.

kubectl get service --namespace helm-lab
kubectl describe service echo-oci --namespace helm-lab

Pod가 시작되지 않으면 Release 상태만 보지 않고 Event와 Container Log를 확인한다.

kubectl get events \
  --namespace helm-lab \
  --sort-by=.metadata.creationTimestamp
kubectl logs \
  --namespace helm-lab \
  deployment/echo-oci \
  --all-pods=true

Resource 이름과 Workload Kind는 Chart Template에 따라 다를 수 있다. helm get manifest echo-oci --namespace helm-lab으로 실제 생성된 Resource를 확인하고 Log 명령의 대상을 선택한다.

실습이 끝나면 Release와 Registry Login Session을 정리한다.

helm uninstall echo-oci --namespace helm-lab
helm registry logout registry-1.docker.io

5 ) Chart 설치 전 확인

외부 Chart를 바로 설치하지 않고 Metadata, 기본 Values와 Rendering 결과를 먼저 확인한다.

helm show chart bitnami/nginx
helm show values bitnami/nginx
helm template my-nginx bitnami/nginx
helm install my-nginx bitnami/nginx --dry-run

명령	확인 대상
`helm show chart`	Chart 이름, Version, Dependency와 Metadata
`helm show values`	변경 가능한 기본 설정
`helm template`	Cluster에 연결하지 않고 생성되는 Manifest
`helm install --dry-run`	Release 이름과 Values를 적용한 설치 결과

Rendering 결과에서 다음 항목을 확인한다.

사용할 Container Image Registry와 Tag
생성되는 RBAC Resource와 ServiceAccount 권한
Service Type과 외부 공개 여부
PVC, StorageClass와 요청 용량
Secret에 들어갈 값과 생성 방식
Namespace와 Cluster Scope Resource

Chart Version을 생략하면 Repository 갱신 시 다른 Version이 선택될 수 있다. 재현 가능한 설치에는 검증한 Chart Version을 명시한다.

helm install my-nginx bitnami/nginx \
  --version 

6 ) Bitnami Chart의 현재 배포 상태

Bitnami는 2025년부터 Public Container와 Chart 배포 정책을 변경했다. Chart Source는 공개되어 있어도 Chart가 참조하는 Versioned Image가 기존 docker.io/bitnami Registry에 없을 수 있으며, 이 경우 설치된 Pod는 ImagePullBackOff 상태가 된다.

따라서 다음 명령이 성공적으로 Chart를 Rendering했다는 사실만으로 Container Image도 Pull할 수 있다고 판단하지 않는다.

helm show chart bitnami/mariadb
helm show values bitnami/mariadb
helm template my-mariadb bitnami/mariadb

Chart가 사용하는 Image를 Rendering 결과에서 확인한다.

helm template my-mariadb bitnami/mariadb | \
  grep -E '^[[:space:]]*image:'

설치 후 Pod가 시작되지 않으면 Event와 Image를 확인한다.

kubectl get pods
kubectl describe pod 
kubectl get pod  \
  -o jsonpath='{.spec.containers[*].image}{"\n"}'

bitnamilegacy Registry는 이전 Image를 보관하는 Migration 용도이며 신규 수정과 보안 Update가 제공되지 않는다. 단순히 Repository 이름을 Legacy로 바꿔 운영 문제를 해결했다고 판단하지 않는다.

7 ) nginx Chart Release 관리

검증한 Chart Version과 Image를 사용할 수 있을 때 nginx Chart를 설치한다.

helm install my-nginx bitnami/nginx \
  --version  \
  --namespace helm-lab \
  --create-namespace

Helm Release와 Kubernetes Resource를 함께 확인한다.

helm list --namespace helm-lab
helm status my-nginx --namespace helm-lab
kubectl get deployments,pods,services \
  --namespace helm-lab

Helm은 Release 상태를 기록하지만 Pod가 Ready인지 대신 보장하지 않는다. helm status와 함께 Deployment Rollout, Pod Event와 Container Log를 확인한다.

kubectl rollout status deployment/my-nginx \
  --namespace helm-lab
kubectl get events \
  --namespace helm-lab \
  --sort-by=.metadata.creationTimestamp

실습이 끝나면 Release를 제거한다.

helm uninstall my-nginx --namespace helm-lab

Release를 제거해도 Chart가 생성한 PVC가 보존 정책에 따라 남을 수 있으므로 Namespace의 Resource를 확인한다.

8 ) MariaDB Chart와 PVC Pending 진단

MariaDB 같은 Stateful Application은 기본 Values에서 Persistence가 활성화되어 있을 수 있다. Cluster에 Default StorageClass나 조건에 맞는 PV가 없으면 PVC가 Pending 상태로 남고 MariaDB Pod도 정상 시작하지 못한다.

설치 전에 Storage 설정을 확인한다.

helm show values bitnami/mariadb | \
  grep -A 20 'persistence:'
kubectl get storageclasses
kubectl get persistentvolumes

검증한 Chart와 Image를 사용할 수 있는 환경에서 MariaDB를 설치한다.

helm install my-mariadb bitnami/mariadb \
  --version  \
  --namespace helm-lab \
  --create-namespace

설치 상태를 Resource 계층별로 확인한다.

helm status my-mariadb --namespace helm-lab
kubectl get statefulsets,pods \
  --namespace helm-lab
kubectl get persistentvolumeclaims \
  --namespace helm-lab
kubectl get persistentvolumes

PVC가 Pending이면 Pod Log보다 PVC Event와 StorageClass를 먼저 확인한다.

kubectl describe persistentvolumeclaim \
  --namespace helm-lab \
  
kubectl get storageclasses
kubectl get events \
  --namespace helm-lab \
  --sort-by=.metadata.creationTimestamp

PV, PVC와 StorageClass의 연결은 Kubernetes Volume과 Persistent Storage에서 자세히 설명한다.

9 ) Persistence를 사용하지 않는 임시 실습

Storage 구성이 없는 격리 실습에서는 Persistence를 끄고 emptyDir를 사용하도록 Chart 값을 변경할 수 있다.

helm install my-mariadb bitnami/mariadb \
  --version  \
  --namespace helm-lab \
  --set primary.persistence.enabled=false \
  --set-string auth.rootPassword=''

--set에 입력한 Password는 Shell History와 Process 정보에 노출될 수 있다. 위 명령은 Option 구조를 설명하기 위한 임시 실습이며 실제 Credential은 별도 Secret이나 보호된 Values 전달 방식을 사용한다.

Persistence를 끄면 Pod가 교체될 때 Database Data를 잃을 수 있으므로 운영 Database 구성으로 사용하지 않는다.

kubectl get pods --namespace helm-lab
kubectl exec -it \
  --namespace helm-lab \
  statefulset/my-mariadb -- bash

실습 Release를 제거한다.

helm uninstall my-mariadb --namespace helm-lab

10 ) Node Local PV와 PVC 준비

직접 구축한 Cluster에서 Dynamic Provisioner가 없다면 특정 Worker의 Directory를 사용하는 정적 PV를 만들 수 있다. 이 방식은 Node 장애 시 다른 Worker로 자동 이동하는 공유 Storage가 아니므로 실습 범위로 제한한다.

먼저 MariaDB Pod를 배치할 Worker 이름을 확인한다.

kubectl get nodes

다음 명령은 선택한 worker1에서 실행한다. UID와 GID 1001은 Bitnami MariaDB Image 계열에서 사용하는 값이므로 실제 선택한 Image의 실행 사용자를 먼저 확인한다.

sudo mkdir -p /data/mariadb
sudo chown 1001:1001 /data/mariadb
sudo chmod 0750 /data/mariadb

모든 사용자에게 쓰기 권한을 주는 chmod 777은 사용하지 않는다. 다음 내용을 mariadb-pv.yaml로 저장한다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: mariadb-local-pv
spec:
  storageClassName: manual
  persistentVolumeReclaimPolicy: Retain
  capacity:
    storage: 1Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  local:
    path: /data/mariadb
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - worker1
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mariadb-pvc
  namespace: helm-lab
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

hostPath도 Node Directory를 직접 사용하지만 PV와 Pod의 Node 관계를 자동으로 표현하지 않는다. 이 예제는 local Volume과 nodeAffinity를 사용해 PV가 worker1에 종속됨을 Scheduler가 알 수 있게 한다.

Master 또는 관리 Client에서 PV와 PVC를 생성한다.

kubectl create namespace helm-lab \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f mariadb-pv.yaml
kubectl get persistentvolume
kubectl get persistentvolumeclaim \
  --namespace helm-lab

11 ) 기존 PVC와 Secret을 MariaDB Chart에 연결

MariaDB Credential을 별도 Secret으로 준비하고 Chart에는 Secret 이름만 전달한다. 현재 Bitnami MariaDB Chart를 기준으로 Secret Key 요구 사항은 선택한 Chart Version의 README와 values.yaml에서 다시 확인한다.

다음 내용을 mariadb-auth-secret.yaml로 저장한다.

apiVersion: v1
kind: Secret
metadata:
  name: mariadb-auth
  namespace: helm-lab
type: Opaque
stringData:
  mariadb-root-password: REPLACE_WITH_ROOT_PASSWORD
  mariadb-password: REPLACE_WITH_USER_PASSWORD
  mariadb-replication-password: REPLACE_WITH_REPLICATION_PASSWORD

실제 Password가 채워진 File은 공개 Repository에 Commit하지 않는다. Secret을 적용한다.

kubectl apply -f mariadb-auth-secret.yaml

다음 내용을 mariadb-values.yaml로 저장한다.

architecture: standalone

auth:
  existingSecret: mariadb-auth
  database: testdb
  username: dbuser

primary:
  persistence:
    enabled: true
    existingClaim: mariadb-pvc
  nodeSelector:
    kubernetes.io/hostname: worker1

PVC와 Pod 모두 worker1에 고정되는지 Rendering 결과를 확인한다.

helm template my-mariadb bitnami/mariadb \
  --version  \
  --namespace helm-lab \
  --values mariadb-values.yaml

Chart와 Image를 검증한 환경에서 설치한다.

helm install my-mariadb bitnami/mariadb \
  --version  \
  --namespace helm-lab \
  --values mariadb-values.yaml

Pod가 선택한 Worker에서 실행되고 PVC가 연결됐는지 확인한다.

kubectl get pod \
  --namespace helm-lab \
  -o wide
kubectl get persistentvolume
kubectl get persistentvolumeclaim \
  --namespace helm-lab
kubectl describe pod \
  --namespace helm-lab \
  

12 ) 사용자 Helm Chart 구조

helm create는 기본 Chart Directory를 자동으로 생성한다.

helm create custom-mariadb

기본 Sample을 목적에 맞게 정리하면 다음 구조가 된다.

custom-mariadb/
├── Chart.yaml
├── values.yaml
├── .helmignore
└── templates/
    ├── secret.yaml
    ├── service.yaml
    ├── statefulset.yaml
    └── pvc.yaml

File	역할
`Chart.yaml`	Chart 이름, Type, Chart Version과 Application Version 정의
`values.yaml`	Template에서 사용할 기본값 정의
`templates/`	Rendering할 Kubernetes Resource Template 저장
`.helmignore`	Chart Package에서 제외할 File Pattern 정의

Helm은 templates/ 아래의 Template을 Rendering하므로 Directory 이름을 정확하게 사용해야 한다.

13 ) Chart Metadata와 Values

다음 내용을 custom-mariadb/Chart.yaml로 저장한다.

apiVersion: v2
name: custom-mariadb
description: A custom MariaDB Helm chart
type: application
version: 0.1.0
appVersion: "11.4"

version은 Chart Package Version이고 appVersion은 Chart가 배포하는 Application Version을 설명하는 값이다. 둘은 같은 의미가 아니다.

다음 내용을 custom-mariadb/values.yaml로 저장한다.

replicaCount: 1

image:
  repository: mariadb
  tag: "11.4"
  pullPolicy: IfNotPresent

mariadb:
  existingSecret: ""
  rootPassword: REPLACE_WITH_ROOT_PASSWORD
  database: appdb
  user: appuser
  password: REPLACE_WITH_USER_PASSWORD

persistence:
  enabled: true
  existingClaim: ""
  storageClassName: ""
  storageSize: 1Gi

service:
  type: ClusterIP
  port: 3306

nodeSelector: {}

mariadb.rootPassword는 Secret Template이 참조하는 Field이고 service.type은 Kubernetes가 인식하는 ClusterIP 값을 사용한다. 실제 운영용 Values에는 평문 Password를 저장하지 않고 mariadb.existingSecret으로 이미 생성한 Secret을 참조한다.

14 ) Secret Template

Helm Template의 {{ ... }} 표현은 Jekyll Liquid와 충돌하므로 Code Block 전체를 Raw Tag로 감싼다.

다음 내용을 custom-mariadb/templates/secret.yaml로 저장한다.

{{- if not .Values.mariadb.existingSecret }}
apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-secret
  labels:
    app.kubernetes.io/name: custom-mariadb
    app.kubernetes.io/instance: {{ .Release.Name }}
type: Opaque
stringData:
  mariadb-root-password: {{ .Values.mariadb.rootPassword | quote }}
  mariadb-password: {{ .Values.mariadb.password | quote }}
{{- end }}

mariadb.existingSecret이 비어 있을 때만 Chart가 Secret을 생성한다. 외부 Secret 이름을 지정하면 이 Template은 Resource를 만들지 않는다.

15 ) Service와 PVC Template

다음 내용을 custom-mariadb/templates/service.yaml로 저장한다.

apiVersion: v1
kind: Service
metadata:
  name: {{ .Release.Name }}
  labels:
    app.kubernetes.io/name: custom-mariadb
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  type: {{ .Values.service.type }}
  selector:
    app.kubernetes.io/name: custom-mariadb
    app.kubernetes.io/instance: {{ .Release.Name }}
  ports:
    - name: mariadb
      port: {{ .Values.service.port }}
      targetPort: mariadb

다음 내용을 custom-mariadb/templates/pvc.yaml로 저장한다.

{{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: {{ .Release.Name }}-data
  labels:
    app.kubernetes.io/name: custom-mariadb
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  accessModes:
    - ReadWriteOnce
  {{- if .Values.persistence.storageClassName }}
  storageClassName: {{ .Values.persistence.storageClassName | quote }}
  {{- end }}
  resources:
    requests:
      storage: {{ .Values.persistence.storageSize }}
{{- end }}

Persistence가 활성화되고 existingClaim이 비어 있을 때만 PVC를 생성한다. storageClassName을 비워 두면 Cluster의 Default StorageClass 선택 규칙이 적용된다.

16 ) StatefulSet Template

다음 내용을 custom-mariadb/templates/statefulset.yaml로 저장한다.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: {{ .Release.Name }}
  labels:
    app.kubernetes.io/name: custom-mariadb
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  serviceName: {{ .Release.Name }}
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app.kubernetes.io/name: custom-mariadb
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: custom-mariadb
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      containers:
        - name: mariadb
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          env:
            - name: MARIADB_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: {{ default (printf "%s-secret" .Release.Name) .Values.mariadb.existingSecret }}
                  key: mariadb-root-password
            - name: MARIADB_DATABASE
              value: {{ .Values.mariadb.database | quote }}
            - name: MARIADB_USER
              value: {{ .Values.mariadb.user | quote }}
            - name: MARIADB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: {{ default (printf "%s-secret" .Release.Name) .Values.mariadb.existingSecret }}
                  key: mariadb-password
          ports:
            - name: mariadb
              containerPort: 3306
          {{- if .Values.persistence.enabled }}
          volumeMounts:
            - name: data
              mountPath: /var/lib/mysql
          {{- end }}
      {{- if .Values.persistence.enabled }}
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: {{ default (printf "%s-data" .Release.Name) .Values.persistence.existingClaim }}
      {{- end }}

StatefulSet의 Selector와 Pod Label은 Chart의 Release 이름까지 포함하여 다른 Release의 Pod를 관리하지 않게 한다. existingSecret과 existingClaim이 있으면 외부 Resource를 사용하고, 비어 있으면 Chart가 만든 Secret과 PVC 이름을 참조한다.

이 Chart는 하나의 MariaDB Instance를 위한 학습 예제이다. replicaCount를 1보다 크게 설정하면 여러 MariaDB Process가 같은 PVC를 사용하게 되므로 복제 구성이 되지 않으며 Data가 손상될 수 있다. MariaDB 복제는 Database의 복제 설정과 Pod별 Volume을 함께 제공하는 별도 Chart 구조가 필요하다.

17 ) Chart 검증과 설치

Chart를 Cluster에 적용하기 전에 구조와 Rendering 결과를 검사한다.

helm lint ./custom-mariadb
helm template my-custom-mariadb ./custom-mariadb \
  --namespace helm-lab

앞에서 만든 mariadb-auth Secret과 mariadb-pvc를 사용하려면 다음 내용을 custom-mariadb-lab-values.yaml로 저장한다.

mariadb:
  existingSecret: mariadb-auth

persistence:
  enabled: true
  existingClaim: mariadb-pvc

nodeSelector:
  kubernetes.io/hostname: worker1

외부 Secret, PVC와 Worker 배치 조건을 적용한 결과도 확인한다.

helm template my-custom-mariadb ./custom-mariadb \
  --namespace helm-lab \
  --values custom-mariadb-lab-values.yaml

Server 측 API 검증까지 수행하려면 Rendering 결과를 kubectl apply --dry-run=server에 전달한다.

helm template my-custom-mariadb ./custom-mariadb \
  --namespace helm-lab \
  --values custom-mariadb-lab-values.yaml | \
  kubectl apply \
    --namespace helm-lab \
    --dry-run=server \
    -f -

검증 후 Chart를 설치한다.

helm install my-custom-mariadb ./custom-mariadb \
  --namespace helm-lab \
  --create-namespace \
  --values custom-mariadb-lab-values.yaml

Release와 StatefulSet, Pod, Service와 PVC를 확인한다.

helm status my-custom-mariadb \
  --namespace helm-lab
kubectl get statefulsets,pods,services,persistentvolumeclaims \
  --namespace helm-lab

18 ) Upgrade와 Rollback

Values를 변경한 뒤 Upgrade하면 Release Revision이 증가한다.

helm upgrade my-custom-mariadb ./custom-mariadb \
  --namespace helm-lab \
  --values custom-mariadb-lab-values.yaml \
  --set image.tag=''

History와 적용된 Values를 확인한다.

helm history my-custom-mariadb \
  --namespace helm-lab
helm get values my-custom-mariadb \
  --namespace helm-lab
helm get manifest my-custom-mariadb \
  --namespace helm-lab

문제가 있으면 이전 Revision으로 Rollback한다.

helm rollback my-custom-mariadb  \
  --namespace helm-lab

Helm Rollback은 Kubernetes Resource Spec을 과거 Release Revision으로 되돌린다. Database File Format이나 이미 변경된 Data를 자동으로 복구하지 않으므로 Stateful Application은 Backup과 Migration 호환성을 별도로 확인해야 한다.

19 ) 실습 Resource 정리

Helm으로 설치한 Release를 확인하고 제거한다.

helm list --all-namespaces
helm uninstall my-custom-mariadb \
  --namespace helm-lab
helm uninstall my-mariadb \
  --namespace helm-lab
helm uninstall my-nginx \
  --namespace helm-lab

helm list --namespace helm-lab에서 존재하는 Release만 제거한다. 생성하지 않은 Release를 helm uninstall하면 찾을 수 없다는 오류가 발생한다.

정적 PV와 PVC는 Data 보존 여부를 확인한 뒤 별도로 처리한다.

kubectl get persistentvolume
kubectl get persistentvolumeclaim \
  --namespace helm-lab
kubectl delete -f mariadb-pv.yaml
kubectl delete -f mariadb-auth-secret.yaml \
  --ignore-not-found

persistentVolumeReclaimPolicy: Retain인 PV를 삭제해도 Worker의 /data/mariadb Data는 자동으로 삭제되지 않는다. Data가 더 이상 필요하지 않은지 확인한 뒤 해당 Worker에서 별도로 정리한다.

helm-lab이 이 실습에만 사용됐는지 확인한 뒤 Namespace를 삭제한다.

kubectl get all,secret,persistentvolumeclaim \
  --namespace helm-lab
kubectl delete namespace helm-lab

전체 정리

최종 정리

Helm은 여러 Kubernetes Resource를 Chart로 Packaging하고 설치 결과를 Release와 Revision으로 관리한다.

Chart와 Values를 Rendering한 결과가 Manifest이며 Control Plane은 이 최종 Resource만 처리한다.

외부 Chart는 Version, Image Registry, RBAC, Service와 Storage 설정을 확인한 뒤 설치한다.

stable과 incubator Repository는 Archive이며 현재 Chart는 Artifact Hub와 유지보수되는 Repository·OCI Registry에서 찾는다.

사용자 Chart는 helm package로 .tgz Archive를 만든 뒤 helm push로 OCI Registry에 배포하며 Chart 이름과 Version은 Chart.yaml에서 결정된다.

Bitnami Chart Source와 기존 Image의 제공 상태는 같지 않으므로 Rendering된 Image를 실제로 Pull할 수 있는지 확인해야 한다.

MariaDB PVC가 Pending이면 Pod Log보다 PVC Event, PV와 StorageClass를 먼저 확인한다.

Node Local Storage는 PV Node Affinity와 Pod 배치 조건을 같은 Worker에 맞춰야 한다.

Helm Template은 Jekyll Liquid와 충돌하지 않도록 Raw Tag로 감싸고 helm lint와 helm template로 검증한다.

Helm Rollback은 Resource Spec을 되돌리며 Database Data와 Schema를 자동으로 복원하지 않는다.

Kubernetes Blue-Green과 Canary 배포

2026-09-07T00:00:00+09:00

Rolling Update는 이전 Version과 새 Version의 Pod를 점진적으로 교체한다. Blue-Green은 두 Version을 별도 환경으로 유지한 뒤 Service의 연결 대상을 한 번에 바꾸고, Canary는 새 Version에 전달되는 Traffic을 제한하여 점진적으로 확대한다.

이 문서는 Kubernetes ReplicaSet과 Deployment의 Rollout과 Kubernetes Service Discovery와 외부 노출의 Service Selector를 알고 있다고 가정한다.

1 ) 배포 전략 비교

전략	Version 전환 방식	추가 Resource	Rollback 방식	주요 고려 사항
Rolling Update	이전 Pod를 줄이고 새 Pod를 늘림	`maxSurge`만큼 추가 Pod 가능	이전 Revision으로 Rollout	두 Version이 잠시 같은 Service에 존재
Blue-Green	두 환경을 모두 준비하고 Traffic 대상을 한 번에 변경	두 Version을 동시에 실행할 Resource 필요	Service Selector를 이전 환경으로 복원	전환 전 새 환경 검증과 Data 호환성 필요
Canary	새 Version의 Traffic 비율을 조금씩 확대	두 Version과 Traffic 제어 수단 필요	새 Version Traffic을 0으로 축소	지표, 판정 기준과 Session 처리 필요

배포 전략은 Pod 교체 방식만 결정한다. Database Schema, Message Format과 외부 API가 두 Version에서 호환되는지도 별도로 검토해야 한다.

2 ) Blue-Green 동작 구조

Blue-Green에서는 현재 운영 중인 Version을 Blue, 새 Version을 Green으로 구분한다. 두 Deployment는 서로 다른 color Label을 사용하며 Service는 그중 하나만 선택한다.

                       ┌─▶ Blue Deployment: v0.0.1
Client ─▶ Service ─────┤    color: blue
 selector.color=blue   │
                       └── Green Deployment: v0.0.2
                            color: green
                            전환 전 별도 검증

전환할 때 Pod를 다시 생성하는 것이 아니라 Service의 Selector를 blue에서 green으로 변경한다. EndpointSlice Controller가 새 Selector와 일치하는 Green Pod를 Endpoint로 반영하면 이후 Traffic이 Green으로 전달된다.

3 ) Blue와 Green Deployment 생성

현재 Version을 print-version-blue.yaml로 작성한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: print-version-blue
  labels:
    app: print-version
    color: blue
spec:
  replicas: 1
  selector:
    matchLabels:
      app: print-version
      color: blue
  template:
    metadata:
      labels:
        app: print-version
        color: blue
    spec:
      containers:
        - name: print-version
          image: ghcr.io/jpubdocker/print-version:v0.0.1
          ports:
            - containerPort: 8080

새 Version을 print-version-green.yaml로 작성한다. Resource 이름, color Label과 Image Version이 Blue와 다르다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: print-version-green
  labels:
    app: print-version
    color: green
spec:
  replicas: 1
  selector:
    matchLabels:
      app: print-version
      color: green
  template:
    metadata:
      labels:
        app: print-version
        color: green
    spec:
      containers:
        - name: print-version
          image: ghcr.io/jpubdocker/print-version:v0.0.2
          ports:
            - containerPort: 8080

Master 또는 kubeconfig가 설정된 관리 Client에서 두 Version을 배포한다.

kubectl apply -f print-version-blue.yaml
kubectl apply -f print-version-green.yaml
kubectl rollout status deployment/print-version-blue
kubectl rollout status deployment/print-version-green
kubectl get pods -l app=print-version --show-labels

두 Deployment가 모두 Ready여도 Service가 선택하지 않은 Green Pod에는 운영 Traffic이 전달되지 않는다. 전환 전에는 kubectl port-forward나 별도 검증용 Service를 이용하여 Green Version을 확인할 수 있다.

4 ) Service Selector로 Version 전환

Blue Version을 선택하는 Service를 print-version-service-color.yaml로 작성한다.

apiVersion: v1
kind: Service
metadata:
  name: print-version
  labels:
    app: print-version
spec:
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: print-version
    color: blue

Service를 적용하고 Endpoint가 Blue Pod를 가리키는지 확인한다.

kubectl apply -f print-version-service-color.yaml
kubectl get service print-version
kubectl get endpointslice \
  -l kubernetes.io/service-name=print-version \
  -o wide

지속적으로 Version을 확인할 Pod를 update-checker.yaml로 작성한다.

apiVersion: v1
kind: Pod
metadata:
  name: update-checker
  labels:
    app: update-checker
spec:
  containers:
    - name: update-checker
      image: ghcr.io/jpubdocker/debug:v0.1.0
      command:
        - sh
        - -c
        - |
          while true
          do
            VERSION=$(curl -s http://print-version/)
            echo "[$(date)] ${VERSION}"
            sleep 1
          done

Pod를 생성하고 응답 Version을 확인한다.

kubectl apply -f update-checker.yaml
kubectl logs -f pod/update-checker

Green으로 전환하려면 print-version-service-color.yaml의 color를 다음과 같이 변경한다.

selector:
  app: print-version
  color: green

변경된 Service를 적용하고 Endpoint와 Log를 다시 확인한다.

kubectl apply -f print-version-service-color.yaml
kubectl get endpointslice \
  -l kubernetes.io/service-name=print-version \
  -o wide
kubectl logs -f pod/update-checker

문제가 발견되면 같은 File의 color를 blue로 되돌려 다시 적용한다. 빠른 전환이 가능하려면 검증 기간 동안 Blue Deployment를 삭제하거나 축소하지 않아야 한다.

5 ) Blue-Green 전환 시 확인 사항

Service Selector 변경은 Application 내부 상태까지 전환하지 않는다. 다음 항목을 함께 확인한다.

Green Pod가 모두 Ready인지 확인한다.
Blue와 Green이 같은 Database나 Message Broker를 사용할 때 Schema와 Message가 양쪽 Version에서 호환되는지 확인한다.
기존 Connection과 처리 중인 요청이 Blue Pod에 남을 수 있음을 고려한다.
Kubernetes Health Check와 restartPolicy의 Readiness Probe와 Graceful Shutdown을 구성한다.
Rollback 판단 기준과 Blue 환경을 유지할 시간을 배포 전에 정한다.

6 ) Canary 배포

Canary 배포

새 Version에 제한된 Traffic만 전달하여 오류율과 지연 시간 등의 지표를 확인한 뒤 Traffic 비율을 단계적으로 확대하는 방식이다.

Canary에는 다음 세 요소가 필요하다.

동시에 실행되는 Stable Version과 Canary Version
Version별 Traffic을 구분하거나 비율을 조정할 수단
다음 단계 진행 또는 Rollback을 결정할 관찰 지표와 기준

단순히 Canary Pod가 Running 상태인지만 확인해서는 사용자 요청이 정상 처리되는지 판단할 수 없다. HTTP 오류율, 응답 시간, Application 오류와 주요 업무 지표를 함께 관찰해야 한다.

7 ) Replica 비율을 이용한 단순 Canary

가장 단순한 방식은 Stable과 Canary Deployment에 같은 app Label을 부여하고 하나의 Service가 두 Version을 모두 선택하게 하는 것이다.

Service selector: app=print-version
        │
        ├─ Stable Deployment: 9 Pods
        └─ Canary Deployment: 1 Pod

Stable과 Canary의 Deployment Selector는 track까지 포함하여 각 Controller가 자신의 Pod만 관리하게 하고, Service Selector는 공통 app Label만 사용한다.

# Stable Deployment의 핵심 Label
spec:
  replicas: 9
  selector:
    matchLabels:
      app: print-version
      track: stable
  template:
    metadata:
      labels:
        app: print-version
        track: stable

# Canary Deployment의 핵심 Label
spec:
  replicas: 1
  selector:
    matchLabels:
      app: print-version
      track: canary
  template:
    metadata:
      labels:
        app: print-version
        track: canary

# 두 Version을 함께 선택하는 Service
spec:
  selector:
    app: print-version

Pod가 9대와 1대라고 해서 모든 구간에서 요청이 정확히 90%와 10%로 분배된다고 보장되지는 않는다. Service는 요청 수를 기준으로 정밀한 가중치를 적용하는 Traffic Router가 아니며, Connection 재사용과 Client 동작도 실제 비율에 영향을 준다. 이 방식은 단순한 실습이나 낮은 정밀도의 검증에 적합하다.

8 ) Ingress Annotation을 이용한 가중치 분배

ingress-nginx는 Stable Ingress와 같은 Host·Path를 사용하는 Canary Ingress에 Annotation을 지정하여 일부 Traffic을 Canary Service로 전달할 수 있다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: print-version-canary
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
  ingressClassName: nginx
  rules:
    - host: print-version.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: print-version-canary
                port:
                  number: 80

이 Annotation은 Kubernetes Ingress의 공통 기능이 아니라 ingress-nginx 구현 전용 기능이다. ingress-nginx Controller는 2026년 3월 24일부로 유지보수가 종료되어 신규 Release와 보안 수정이 제공되지 않는다. 따라서 기존 격리 학습 환경의 동작 이해에만 사용하고 신규 운영 환경의 Canary 구성으로 선택하지 않는다. Ingress API와 Controller의 구분은 Kubernetes Ingress Resource와 HTTP Routing에서 확인할 수 있다.

운영 환경에서는 현재 유지보수되는 Gateway API 구현, Service Mesh 또는 배포 Controller가 지원하는 Traffic Router의 기능과 제약을 확인한다.

9 ) Argo Rollouts를 이용한 Canary 단계 관리

Argo Rollouts는 Kubernetes의 기본 Deployment가 아니라 별도 Controller와 CRD가 제공하는 Rollout Resource이다. 다음 Manifest를 적용하려면 Cluster에 Argo Rollouts Controller와 CRD가 먼저 설치되어 있어야 한다.

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: print-version-rollout
spec:
  replicas: 10
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause:
            duration: 1h
        - setWeight: 50
        - pause: {}
  selector:
    matchLabels:
      app: print-version-rollout
  template:
    metadata:
      labels:
        app: print-version-rollout
    spec:
      containers:
        - name: print-version
          image: ghcr.io/jpubdocker/print-version:v0.0.2
          ports:
            - containerPort: 8080

Step	동작
`setWeight: 10`	Canary 비중을 10으로 설정
`pause.duration: 1h`	1시간 동안 자동으로 대기하여 지표를 관찰할 시간 확보
`setWeight: 50`	다음 단계에서 Canary 비중을 50으로 확대
`pause: {}`	사용자가 재개할 때까지 무기한 대기

Traffic Router를 연결하지 않은 기본 Canary에서는 Argo Rollouts도 Replica 수로 Weight를 근사한다. 정밀한 Traffic 비율이 필요하면 선택한 Gateway API, Ingress 또는 Service Mesh Provider와 연동해야 한다.

Controller와 CRD가 준비된 환경에서는 다음과 같이 Resource 상태를 확인한다.

kubectl apply -f print-version-rollout.yaml
kubectl get rollouts.argoproj.io print-version-rollout
kubectl describe rollouts.argoproj.io print-version-rollout

pause: {} 단계에서는 관찰 지표를 확인한 뒤 수동으로 진행하거나 중단한다. 자동화된 배포에서는 AnalysisTemplate 등 별도의 판정 구성을 연결하여 다음 단계 진행 여부를 결정할 수 있다.

10 ) Session과 Canary Traffic

여러 Version이 동시에 요청을 처리할 때 Server Memory에 Session을 저장하면 사용자가 요청마다 다른 Version에 연결되어 상태가 끊길 수 있다. Sticky Session으로 같은 Backend 연결을 유지할 수 있지만 장기적으로는 다음 항목을 함께 검토한다.

공유 Session Store 사용 여부
Version 간 Cookie와 Session Format 호환성
Sticky Session 때문에 Canary Traffic 비율과 사용자 표본이 왜곡되는지 여부
Canary Pod 장애 시 Session Failover 방식

Sticky Session은 Canary의 필수 조건이 아니라 Application의 Session 저장 방식에 따라 선택하는 기능이다.

11 ) 전략 선택 기준

조건	적합한 출발점
Kubernetes 기본 Rollout으로 가용성을 유지하며 교체	Deployment Rolling Update
두 Version의 혼재를 피하고 즉시 전환·복원이 필요	Blue-Green과 Service Selector 전환
간단한 환경에서 대략적인 소수 사용자 검증	Replica 비율 기반 Canary
정밀한 Weight, 자동 분석과 단계 승격 필요	Argo Rollouts와 유지보수되는 Traffic Router 연동

어떤 전략을 선택하더라도 Readiness Probe, Graceful Shutdown, 관찰 지표, Rollback 조건과 Data 호환성을 먼저 준비해야 한다.

12 ) 실습 Resource 정리

Blue-Green 실습 Resource를 삭제한다.

kubectl delete -f update-checker.yaml --ignore-not-found
kubectl delete -f print-version-service-color.yaml --ignore-not-found
kubectl delete -f print-version-green.yaml --ignore-not-found
kubectl delete -f print-version-blue.yaml --ignore-not-found

Argo Rollouts 실습을 수행했다면 Rollout Resource도 삭제한다. Controller와 CRD는 다른 Rollout에서 사용할 수 있으므로 함께 제거하지 않는다.

kubectl delete -f print-version-rollout.yaml --ignore-not-found

전체 정리

최종 정리

Rolling Update는 두 ReplicaSet을 점진적으로 조정하고 Blue-Green은 Service Selector로 운영 대상을 한 번에 전환한다.

Blue-Green의 빠른 Rollback을 위해서는 이전 환경을 유지하고 두 Version의 Data 호환성을 확인해야 한다.

Canary는 새 Version의 Traffic을 제한하여 지표를 확인한 뒤 비율을 확대한다.

Replica 수를 이용한 Canary 비율은 근사치이며 정밀한 제어에는 별도 Traffic Router가 필요하다.

ingress-nginx Canary Annotation은 해당 Controller 전용이며 Controller의 유지보수가 종료되어 신규 운영 구성에 사용하지 않는다.

Argo Rollouts는 별도 CRD와 Controller가 필요한 확장 Resource이며 단계별 Weight와 Pause를 관리한다.

Readiness Probe, Graceful Shutdown, Session, 관찰 지표와 Rollback 조건이 배포 전략의 안전성을 결정한다.

다음 글인 Kubernetes Kustomize로 Manifest 구성 관리에서는 여러 Manifest를 조합하고 환경별 차이를 Overlay로 관리하는 방법을 다룬다.

VirtualBox Kubernetes Lab에 접속할 수 없었던 이유

2026-09-06T00:00:00+09:00

노트북에서 실행하던 Kubernetes 실습 VM을 별도의 데스크톱으로 이전하기 위해 노트북의 유선 LAN Cable을 데스크톱으로 옮겼다. 노트북은 Wi-Fi로 전환했지만 인터넷 연결부터 VirtualBox VM의 SSH 접속까지 연속해서 문제가 발생했다.

겉으로는 하나의 장애처럼 보였지만 Windows의 DHCP, VirtualBox의 Bridged Adapter와 Ubuntu VM의 Network 설정에서 서로 다른 문제가 이어진 상황이었다. 이 글에서는 확인된 사실과 당시의 추정을 구분하여 각 Network 계층을 어떤 순서로 확인했는지 정리한다.

1 ) 장애 발생 전 구성

나는 Windows 랩탑을 홈 네트워크 아래에 두고, VPN을 구성하여 외부에서 접속이 가능하도록 구성해두고 실습 시마다 사용해오고 있었다. 노트북의 VirtualBox에는 Kubernetes와 NFS 실습용 VM 네 개가 실행되고 있었다.

Windows Laptop
│
├── lab-control-plane  192.168.0.200
├── lab-worker1        192.168.0.201
├── lab-worker2        192.168.0.202
└── lab-nfs            192.168.0.203

각 VM의 Network Adapter는 Bridged Adapter로 구성되어 노트북의 Realtek 유선 NIC를 통해 192.168.0.0/24 Network에 연결되어 있었다.

VM
 │
VirtualBox Bridged Adapter
 │
Realtek Ethernet NIC
 │
ipTIME Router

실습 VM을 장기적으로 수용할 별도의 Linux Host를 준비하면서 노트북에 연결되어 있던 LAN Cable을 데스크톱으로 옮겼다. 물리 연결은 다음과 같이 변경되었다.

변경 전

Windows Laptop
      │ Ethernet
      ▼
ipTIME Router

변경 후

Linux Host ── Ethernet ── ipTIME Router

Windows Laptop ── Wi-Fi ── ipTIME Router

이 변경은 Kubernetes 설정 자체를 수정한 작업이 아니다. Host의 물리 Network 경로가 Ethernet에서 Wi-Fi로 바뀐 작업이다.

2 ) 장애를 세 단계로 분리

복구 과정에서 관찰한 증상은 다음 세 단계로 나뉘었다.

단계	관찰한 증상	확인할 계층
1	Wi-Fi AP에는 연결됐지만 인터넷을 사용할 수 없음	Windows IP·DHCP
2	Windows 인터넷은 복구됐지만 Host에서 VM으로 Ping·SSH 실패	Routing·VirtualBox Bridge
3	Bridge 설정 변경 후 일부 VM의 NIC는 존재하지만 `DOWN` 상태	Guest NIC·Netplan

단계별 장애를 구분하지 않으면 Windows DHCP 문제를 해결한 뒤에도 VM 접속 실패를 같은 원인으로 오해하기 쉽다.

3 ) Wi-Fi 연결과 IP 할당을 분리해서 확인

노트북은 Wi-Fi 이름과 신호 세기를 정상적으로 표시했지만 인터넷에 연결되지 않았다. 먼저 Windows에서 사용 중인 Adapter의 IP 설정을 확인했다.

ipconfig /all

Wi-Fi Adapter에는 다음과 같은 값이 표시되었다.

DHCP 사용           : 예
자동 구성 IPv4 주소 : 169.254.100.110
서브넷 마스크       : 255.255.0.0
기본 게이트웨이     : 없음

169.254.0.0/16은 Windows가 DHCP Server에서 IPv4 설정을 받지 못했을 때 사용하는 APIPA(Automatic Private IP Addressing) 범위이다. 이 주소와 Gateway가 없다는 결과로 다음 상태를 확인할 수 있었다.

Wi-Fi Association   성공
        │
        ▼
DHCP 주소 할당      실패
        │
        ▼
169.254.x.x 자동 구성
        │
        ▼
기본 Gateway 없음

Wi-Fi의 무선 연결 상태는 별도로 확인했다.

netsh wlan show interfaces

확인 결과 SSID, 신호 세기와 연결 상태는 정상으로 표시되었다. 따라서 이 시점의 문제는 AP와의 Association이 아니라 IPv4 설정을 받지 못한 상태였다.

DHCP Lease 재요청

처음에는 DHCP 주소를 반납하고 다시 요청했다.

ipconfig /release
ipconfig /renew

유선 LAN Cable이 제거된 Ethernet Adapter에서는 다음 메시지가 함께 출력되었다.

미디어의 연결이 끊긴 상태에서는 이더넷에서 작업을 수행할 수 없습니다.

이 메시지는 Cable이 연결되지 않은 Ethernet Adapter에 대한 결과이다. Wi-Fi의 DHCP 처리 결과와 구분해야 한다. Wi-Fi만 대상으로 실행하려면 Adapter 이름을 지정한다.

ipconfig /release "Wi-Fi"
ipconfig /renew "Wi-Fi"

Wi-Fi 갱신 과정에서는 다음 오류가 발생했다.

인터페이스 갱신하는 동안 오류 발생:
개체가 이미 있음

이 메시지만으로 중복된 IP Address나 Route가 정확한 원인이라고 확정할 수는 없다. 당시에는 Windows TCP/IP 상태 이상을 의심하고 현재 설정을 먼저 확인했다.

Get-NetIPConfiguration -InterfaceAlias "Wi-Fi"
Get-NetIPAddress -InterfaceAlias "Wi-Fi"
Get-NetRoute -InterfaceAlias "Wi-Fi"

Windows Network 설정 초기화

일반적인 DHCP 재요청으로 복구되지 않아 관리자 권한 Terminal에서 Winsock Catalog와 TCP/IP 설정을 초기화했다.

netsh winsock reset
netsh int ip reset

이 명령은 Network 설정에 영향을 준다. 기존 수동 IP, DNS나 별도 Network 구성이 있다면 먼저 기록하고, 다른 원인 확인 없이 첫 단계에서 실행하지 않는다. 적용을 완료하기 위해 Windows를 재부팅했다.

shutdown /r /t 0

재부팅 후 ipconfig /all에서 다음 상태를 확인했다.

IPv4 주소       : 192.168.0.x
서브넷 마스크   : 255.255.255.0
기본 게이트웨이 : 192.168.0.1
DHCP 사용       : 예

Wi-Fi 인터넷은 복구되었다. 다만 DHCP 응답을 받지 못한 최초 원인은 Packet Capture나 Windows Event 등으로 확인하지 못했다. 따라서 “Windows Network 초기화와 재부팅 후 복구됨”은 확인된 사실이지만, 특정 IP Object나 Route가 근본 원인이었다고 단정하지 않는다.

4 ) 인터넷 복구와 VM 접속 복구는 별개였다

Windows의 Wi-Fi 인터넷이 복구된 뒤에도 외부 SSH 에서 VirtualBox VM으로 접속할 수 없었다.

ping 192.168.0.200
ping 192.168.0.201
ssh <user>@192.168.0.200

반면 VM 사이의 통신은 유지되고 있었다.

lab-control-plane ↔ lab-worker1   정상
lab-control-plane ↔ lab-worker2   정상
worker            ↔ lab-nfs       정상
Windows Host       → VM            실패

이 결과는 Kubernetes Pod Network 전체가 중단됐다는 의미가 아니다. VM 내부 경로는 동작하고 있었고 Windows Host에서 VM으로 가는 경로만 실패했다. 따라서 Kubernetes Resource보다 먼저 Host Routing과 VirtualBox Network 연결을 확인했다.

Windows Routing Table을 조회했다.

route print

주요 결과는 다음과 같았다.

0.0.0/0       → 192.168.0.1   Interface 192.168.0.99
168.0.0/24  → 연결됨        Interface 192.168.0.99

VirtualBox Host-Only Adapter
254.70.191/16

Windows는 VM의 192.168.0.20x 주소를 Wi-Fi와 같은 Local Network의 주소로 판단하고 있었다. Host-Only Adapter는 해당 대역을 담당하지 않았다. 이 결과만으로 VirtualBox 설정을 확정할 수는 없지만, VM이 어떤 Host Interface에 Bridge되어 있는지 확인해야 한다는 범위를 정할 수 있었다.

5 ) 확정 원인은 Bridged Adapter의 대상 NIC였다

VM을 종료한 뒤 VirtualBox의 다음 설정을 확인했다.

VM 설정
└── Network
    └── Adapter 1
        ├── Attached to : Bridged Adapter
        └── Name        : Realtek PCIe GbE Family Controller

Bridged Adapter의 대상이 LAN Cable을 제거한 Realtek Ethernet NIC로 남아 있었다. 장애 전에는 이 경로가 유효했다.

VM
 │
VirtualBox Bridge
 │
Realtek Ethernet
 │
LAN Cable
 │
Router

Cable을 데스크톱으로 옮긴 뒤에는 같은 설정이 물리적으로 끊긴 Interface를 가리켰다.

VM
 │
VirtualBox Bridge
 │
Realtek Ethernet
 │
Cable 없음
 ╳

VirtualBox의 Bridged Adapter는 사용자가 선택한 Host Network Interface를 통해 Guest Traffic을 전달한다. Windows가 Wi-Fi로 인터넷에 연결되었다고 해서 기존 VM의 Bridge 대상도 자동으로 Wi-Fi NIC로 변경되는 것은 아니었다.

각 VM의 Bridge 대상 Name을 현재 연결된 Wi-Fi Adapter로 변경했다.

기존: Realtek PCIe GbE Family Controller
변경: Intel(R) Wi-Fi 6 AX201 160MHz

이 단계에서는 동시에 여러 설정을 바꾸지 않는 것이 중요하다. 우선 다음 값은 유지하고 Bridge 대상만 변경해야 원인과 결과를 분리할 수 있다.

Adapter Type
MAC Address
Promiscuous Mode
Cable Connected 상태

Wi-Fi Bridging은 Host OS, Wi-Fi Driver와 Access Point 구성에 따라 Ethernet Bridging과 다르게 동작하거나 제한될 수 있다. 따라서 Bridge 대상을 Wi-Fi NIC로 변경했다는 사실만으로 모든 환경에서 같은 결과가 보장되지는 않는다.

6 ) 가상 NIC 변경 후 발생한 두 번째 문제

Bridge 대상을 변경하는 과정에서 Guest에 보여줄 Adapter Type도 virtio-net으로 변경했다. 이후 lab-nfs를 제외한 일부 Ubuntu VM에서 Network가 올라오지 않았다.

ip addr

다음 상태가 확인되었다.

2: enp0s3: 
    state DOWN

enp0s3 Interface는 존재했다. 처음엔 “NIC가 유실됐네” 라고 생각했는데, 다음 상태로 표현하는 것이 정확하다고 한다.

NIC 존재
   │
   ▼
Link DOWN
   │
   ▼
IPv4 Address 없음

Adapter Type 변경이 직접 원인이었는지, Netplan 설정이 적용되지 않은 이유가 무엇인지는 당시 기록해두었던 자료만으로 확정할 수 없었다. 초반 이슈 이후로는 Interface 이름이 계속 enp0s3로 확인됐고 변경 전후 Netplan과 System Log를 모두 보존하지 못했기 때문이다.

Interface와 Netplan 확인

먼저 한 VM에서 Interface를 임시로 활성화했다.

sudo ip link set enp0s3 up
ip link show enp0s3
ip addr show enp0s3

ip link set으로 변경한 상태는 재부팅 후에도 유지되는 영구 Network 설정이 아니다. NIC를 올릴 수 있는지 확인한 뒤 Netplan을 점검했다.

ls -l /etc/netplan/
sudo cat /etc/netplan/*.yaml

Netplan의 Interface 이름과 ip addr에서 확인한 실제 이름이 같은지 확인했다.

network:
  version: 2
  ethernets:
    enp0s3:
      dhcp4: false
      addresses:
        - 192.168.0.200/24
      routes:
        - to: default
          via: 192.168.0.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 1.1.1.1

각 VM에는 해당 Node에 할당한 IP Address를 사용한다.

VM	Address
`lab-control-plane`	`192.168.0.200/24`
`lab-worker1`	`192.168.0.201/24`
`lab-worker2`	`192.168.0.202/24`
`lab-nfs`	`192.168.0.203/24`

여러 Netplan YAML File이 존재하면 설정이 함께 처리되므로 같은 Interface를 중복 정의하거나 서로 다른 값을 적용하는 File이 있는지도 확인해야 한다.

설정의 YAML 문법과 생성 결과를 먼저 검사했다.

sudo netplan generate

Network를 변경할 때는 가능하면 다음 명령으로 임시 적용하여 연결이 끊기면 이전 설정으로 돌아갈 수 있게 한다.

sudo netplan try

확인 후 설정을 적용한다.

sudo netplan apply

SSH로 접속한 상태에서 Network를 변경하면 연결을 잃을 수 있다. 이번과 같이 Guest Network 자체가 동작하지 않는 상황에서는 VirtualBox Console에서 작업하는 것이 안전하다.

적용 후 Interface, Route와 통신을 순서대로 확인했다.

ip addr show enp0s3
ip route
ping -c 3 192.168.0.1
ping -c 3 192.168.0.99

Netplan을 다시 적용한 뒤 각 VM의 고정 IP가 복구되었고 외부 네트워크에서 VPN에 접속된 Mac의 SSH와 Windows Host에서이 VM으로 Ping과 SSH가 가능해졌다.

7 ) 확인된 사실과 추정을 구분

복구됐다는 사실만으로 사용한 명령이 곧 근본 원인을 입증하는 것은 아니지만, 네트워크 구성이 변경될 때마다 비슷한 장애가 발생해왔었고, 다시 기억할 수 있도록 이번 장애의 판단 수준을 구분하면 다음과 같다.

항목	판단	근거
Windows가 정상 DHCP 주소를 받지 못함	확인됨	`169.254.x.x`, Gateway 없음
Wi-Fi Association 자체는 정상	확인됨	`netsh wlan show interfaces`의 연결 상태
Windows TCP/IP 내부 Object 충돌이 근본 원인	미확정	초기화 후 복구됐지만 직접 원인을 확인하지 못함
VM Bridge가 연결이 끊긴 Ethernet NIC를 참조함	확인됨	VirtualBox VM Network 설정에서 Realtek NIC 확인
해당 Bridge 설정이 Host에서 VM으로 접근하지 못한 원인	확인됨	물리 연결 상태와 Bridge 대상이 불일치했고 변경 후 경로 복구
Ubuntu VM의 `enp0s3`가 존재하지만 `DOWN` 상태	확인됨	VM의 `ip addr` 결과
Adapter Type 변경 후 Netplan 장애 발생	확인됨	Adapter에 따라 netplan에서 인터페이스를 재할당하여 복구
Guest Network 설정을 확인하고 다시 적용한 뒤 복구	확인됨	고정 IP, Ping과 SSH 복구

가장 명확했던 원인은 VirtualBox Bridge가 물리적으로 연결되지 않은 Host NIC를 계속 참조했다는 점이다.

8 ) 계층별 진단 순서

“통신이 안 된다”는 증상을 하나의 문제로 다루지 않고 아래에서 위로 확인했다.

Wi-Fi Association
        │
        ▼
IP Address와 DHCP
        │
        ▼
Default Gateway와 Host Route
        │
        ▼
VirtualBox Attachment Mode
        │
        ▼
Bridge 대상 Host NIC
        │
        ▼
Guest NIC Link 상태
        │
        ▼
Netplan Address와 Route
        │
        ▼
Ping과 SSH

각 단계의 판단 기준은 다음과 같다.

확인 결과	다음으로 볼 대상
Wi-Fi가 연결되지 않음	Wi-Fi Profile, 인증과 Adapter 상태
Wi-Fi 연결, `169.254.x.x`, Gateway 없음	DHCP와 Windows IP 설정
ipTIME 의 DHCP 충돌은 아니었음	ipTIME DHCP 서버 관리 및 내부 네트워크 설정
Host 인터넷 정상, Host에서 모든 VM 접근 실패	VirtualBox Attachment와 Bridge 대상
VM끼리 통신 가능, Host에서 VM만 실패	Host와 VM 사이의 VirtualBox 경로
Guest NIC가 보이지 않음	가상 NIC 연결 여부와 Guest Driver
Guest NIC가 존재하지만 `DOWN`	Link 상태와 Guest Network 설정
IP는 있지만 Gateway Ping 실패	Subnet, Route, Bridge와 물리 Network
Ping 성공, SSH만 실패	SSH Service, Port와 Firewall

이 순서를 사용하면 DHCP 장애 상태에서 SSH 설정을 바꾸거나, Guest NIC가 DOWN인 상태에서 Kubernetes 설정을 먼저 수정하는 일을 피할 수 있을 것 같다.

9 ) 재발 방지 기준

Host의 물리 Interface가 바뀌면 Bridge 대상을 확인한다

Bridged Adapter는 특정 Host Interface에 연결된다. Ethernet에서 Wi-Fi로 전환하거나 USB Ethernet Adapter를 교체했다면 모든 VM의 Bridge 대상을 확인한다.

한 번에 하나의 설정만 변경한다

Bridge 대상과 Adapter Type을 동시에 변경하면 어떤 변경이 장애를 만들었는지 분리하기 어렵다. 다음 순서로 하나씩 변경하고 매 단계에서 통신을 확인한다.

Bridge 대상 Host NIC 변경
Guest 부팅 후 NIC와 IP 확인
Gateway와 Host 통신 확인
필요한 경우에만 Adapter Type 변경
다시 Guest NIC와 Netplan 확인

MAC Address를 불필요하게 변경하지 않는다

DHCP Reservation이나 Network 접근 정책에서 MAC Address를 사용할 수 있다. Bridge 대상만 변경하는 작업에서는 Guest MAC Address를 유지한다.

Network 변경 전 현재 상태를 기록한다

Windows에서는 다음 결과를 보존한다.

ipconfig /all
route print
Get-NetIPConfiguration

Ubuntu VM에서는 다음 결과를 보존한다.

ip addr
ip route
sudo cat /etc/netplan/*.yaml

변경 전후 결과가 있으면 복구 여부뿐 아니라 정확한 원인까지 확인할 수 있다.

Netplan은 Console과 Rollback을 준비한다

Remote 접속 중 Network를 변경해야 한다면 netplan try를 우선 사용한다. Bridge, IP와 Route를 변경하는 작업은 연결이 끊길 수 있으므로 가능한 경우 Local Console이나 VirtualBox Console을 확보한다.

10 ) 최종 확인

각 계층의 복구 여부를 다음 순서로 확인했다.

Windows Host

ipconfig /all
ping 192.168.0.1
ping 192.168.0.200
ssh <user>@192.168.0.200

Ubuntu VM

ip addr show enp0s3
ip route
ping -c 3 192.168.0.1
ping -c 3 192.168.0.99

확인 결과는 다음과 같았다.

대상	결과
Windows Wi-Fi의 DHCP Address와 Default Gateway	복구
Windows 인터넷 연결	복구
Windows Host에서 VM Ping	복구
Windows Host에서 VM SSH	복구
VM 사이 통신	정상
Ubuntu VM의 고정 IP와 Default Route	복구

전체 정리

최종 정리

169.254.x.x 주소와 Gateway 부재는 Wi-Fi 연결 여부가 아니라 DHCP 주소 할당부터 확인해야 한다는 단서였다.

Windows 인터넷이 복구되어도 VirtualBox VM의 Network 경로가 자동으로 복구되는 것은 아니다.

VirtualBox VM은 연결이 끊긴 Realtek Ethernet NIC에 계속 Bridge되어 있었으며, 이것이 Host에서 VM으로 접근할 수 없었던 확정 원인이었다.

Guest의 enp0s3는 유실된 것이 아니라 존재하지만 DOWN 상태였고, Interface와 Netplan을 확인하고 다시 적용한 뒤 고정 IP가 복구되었다.

Network 장애는 Association, DHCP, Route, VirtualBox Bridge, Guest NIC, Netplan과 Application 순서로 계층을 나누어 확인한다.

Kubernetes Health Check와 restartPolicy

2026-09-04T00:00:00+09:00

Kubernetes는 Process가 실행 중이라는 사실만으로 Application이 정상이라고 판단하지 않는다. Worker의 kubelet은 Probe를 실행하여 Container의 생존 여부, 요청 처리 가능 여부와 시작 완료 여부를 확인한다. Probe 결과와 restartPolicy를 함께 이해하면 Container가 재시작되는 경우와 Service Traffic에서만 제외되는 경우를 구분할 수 있다.

1 ) Health Check와 Pod 상태

Probe는 Pod 전체가 아니라 Pod 안의 각 Container에 설정한다. 같은 Container에도 목적이 다른 Probe를 함께 설정할 수 있다.

Probe	확인 대상	실패가 계속될 때의 결과
Liveness Probe	Container가 계속 정상 동작할 수 있는가	kubelet이 해당 Container를 재시작함
Readiness Probe	현재 요청을 처리할 준비가 되었는가	Container는 유지하고 Pod를 Service Endpoint에서 제외함
Startup Probe	Application의 최초 시작이 끝났는가	성공할 때까지 Liveness·Readiness Probe를 보류하고, 계속 실패하면 Container를 재시작함

Liveness Probe는 Process가 살아 있지만 Deadlock이나 Memory Leak 등의 문제로 정상 응답하지 못하고, 재시작 없이는 회복하기 어려운 상태를 감지할 때 사용한다.

Readiness Probe는 Database 연결, Cache Load, 초기 Data 준비처럼 요청 처리에 필요한 조건을 확인한다. 일시적으로 실패해도 Container를 재시작하지 않으며, 다시 성공하면 Service Endpoint에 포함될 수 있다.

Startup Probe는 시작 시간이 긴 Application을 보호한다. Startup Probe가 성공하기 전에는 Liveness·Readiness Probe가 실행되지 않으므로, 시작 중인 Container가 Liveness Probe 실패로 반복 재시작되는 상황을 방지할 수 있다.

외부 Load Balancer의 Health Check와 kubelet의 Probe는 별개의 검사이다. Load Balancer의 검사 방식과 대상은 Cloud Provider와 구성에 따라 달라지며, 외부 검사만으로 Container 내부의 생존 상태와 준비 상태를 모두 판단할 수는 없다.

2 ) Control Plane과 Worker의 상태 처리

Probe 실행과 상태 반영 과정은 다음과 같다.

사용자가 Pod Spec에 Container별 Probe를 선언하여 API Server에 저장한다.
Scheduler가 Pod를 실행할 Worker를 선택한다.
Worker의 kubelet이 Pod Spec에 따라 Probe를 주기적으로 실행한다.
Liveness·Startup Probe가 실패 기준에 도달하면 kubelet이 해당 Container를 종료하고 restartPolicy에 따라 다시 시작한다.
Readiness Probe 결과는 Pod의 Ready와 ContainersReady Condition에 반영되어 API Server로 보고된다.
EndpointSlice Controller는 Ready 상태를 기준으로 Service가 요청을 전달할 Endpoint를 갱신한다.

따라서 Liveness 실패는 주로 Worker 안의 Container Lifecycle 변화로 나타나고, Readiness 실패는 Control Plane에 보고된 Pod Condition과 Service Endpoint 변화로 나타난다.

Kubernetes Pod Lifecycle과 kubectl wait에서 정리한 Running Phase는 Container가 실행 중임을 나타낸다. Application이 Traffic을 받을 준비가 되었는지는 Ready Condition과 Readiness Probe를 함께 확인해야 한다.

3 ) Probe 실행 방식

exec

Container 안에서 명령을 실행한다. 종료 코드가 0이면 성공이고, 그 외의 값이면 실패이다.

livenessProbe:
  exec:
    command:
      - test
      - -e
      - /ok.txt

Application 상태를 검증하는 명령이 Container Image 안에 존재해야 한다.

httpGet

kubelet이 지정한 Path와 Port로 HTTP GET 요청을 보낸다. 응답 Status Code가 200 이상 400 미만이면 성공으로 판단한다.

livenessProbe:
  httpGet:
    path: /health
    port: 80
    scheme: HTTP
    httpHeaders:
      - name: Host
        value: web.example.com
      - name: Authorization
        value: Bearer REPLACE_WITH_TOKEN

host Field는 접속할 대상 Host를 지정한다. HTTP Host Header가 필요하면 httpHeaders에 지정한다. 인증 정보는 Manifest에 직접 저장하지 않고 실제 환경의 Secret 관리 방식을 사용해야 한다.

tcpSocket

kubelet이 지정한 Port에 TCP Connection을 열 수 있는지 확인한다. Connection이 성립하면 성공이고 열 수 없으면 실패이다.

livenessProbe:
  tcpSocket:
    port: 80

TCP Probe는 Port가 열려 있는지는 확인할 수 있지만 Application이 요청을 올바르게 처리하는지까지 검증하지는 않는다.

4 ) Probe 주기와 실패 판정

세 Probe는 공통적으로 다음 시간 관련 Field를 사용한다.

Field	의미
`initialDelaySeconds`	Container 시작 후 첫 Probe까지 기다리는 시간
`periodSeconds`	Probe를 반복하는 간격
`timeoutSeconds`	한 번의 Probe 응답을 기다리는 제한 시간
`successThreshold`	실패 상태에서 성공으로 판단하기 위해 필요한 연속 성공 횟수
`failureThreshold`	실패 동작을 수행하기 위해 필요한 연속 실패 횟수

successThreshold는 1 이상이어야 한다. Liveness·Startup Probe에서는 반드시 1이어야 하며 Readiness Probe에는 더 큰 값을 사용할 수 있다.

Liveness Probe의 failureThreshold가 너무 작으면 일시적인 지연에도 Container가 재시작될 수 있다. 반대로 너무 크면 실제 장애 감지가 늦어진다. 시작 시간 때문에 Liveness Probe의 initialDelaySeconds를 과도하게 늘리는 대신 Startup Probe로 최초 시작 구간을 분리할 수 있다.

5 ) Liveness와 Readiness Probe 적용

다음 예제는 nginx의 /index.html을 Liveness Probe로 확인하고, /usr/share/nginx/html/50x.html의 존재 여부를 Readiness Probe로 확인한다. sample-healthcheck.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-healthcheck
  labels:
    app: sample-healthcheck
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      livenessProbe:
        httpGet:
          path: /index.html
          port: 80
          scheme: HTTP
        initialDelaySeconds: 5
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 1
        failureThreshold: 2
      readinessProbe:
        exec:
          command:
            - test
            - -e
            - /usr/share/nginx/html/50x.html
        initialDelaySeconds: 5
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 2
        failureThreshold: 1

Pod를 생성하고 두 Probe의 결과를 확인한다.

kubectl apply -f sample-healthcheck.yaml
kubectl wait \
  --for=condition=Ready \
  pod/sample-healthcheck \
  --timeout=60s
kubectl describe pod sample-healthcheck

kubectl describe의 Containers 영역에서 Liveness·Readiness 설정을 확인하고 Conditions 영역에서 Ready와 ContainersReady 값을 확인한다.

6 ) Liveness Probe 실패

Liveness Probe 실패가 Container 재시작으로 이어지는지 확인한다. 다음 내용을 sample-liveness.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-liveness
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      livenessProbe:
        httpGet:
          path: /index.html
          port: 80
          scheme: HTTP
        initialDelaySeconds: 5
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 1
        failureThreshold: 2

Pod를 생성하고 변화 과정을 감시한다.

kubectl apply -f sample-liveness.yaml
kubectl get pod sample-liveness --watch

다른 터미널에서 Liveness Probe가 확인하는 File을 삭제한다.

kubectl exec sample-liveness -- \
  rm -f /usr/share/nginx/html/index.html

연속 실패 횟수가 failureThreshold에 도달하면 kubelet이 nginx Container를 재시작한다. Pod Object가 새로 만들어지는 것은 아니므로 Pod 이름과 UID는 유지되고 RESTARTS가 증가한다. Container가 재시작되면 Image의 File System으로 다시 시작하므로 삭제했던 기본 index.html도 복구된다.

kubectl get pod sample-liveness \
  -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,RESTARTS:.status.containerStatuses[0].restartCount
kubectl describe pod sample-liveness

kubectl describe의 Event에서 Liveness Probe 실패와 Container 재시작 기록을 확인한다.

7 ) Readiness Probe 실패

Readiness 실패가 Service Endpoint에 미치는 영향을 확인한다. 다음 내용을 sample-readiness.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-readiness
  labels:
    app: sample-readiness
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      readinessProbe:
        exec:
          command:
            - test
            - -e
            - /usr/share/nginx/html/50x.html
        initialDelaySeconds: 5
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 2
        failureThreshold: 1
---
apiVersion: v1
kind: Service
metadata:
  name: sample-readiness-service
spec:
  selector:
    app: sample-readiness
  ports:
    - port: 80
      targetPort: 80

Pod와 Service를 생성하고 Ready 상태와 EndpointSlice를 확인한다.

kubectl apply -f sample-readiness.yaml
kubectl wait \
  --for=condition=Ready \
  pod/sample-readiness \
  --timeout=60s
kubectl get pod sample-readiness
kubectl get endpointslice \
  -l kubernetes.io/service-name=sample-readiness-service

Readiness Probe가 확인하는 File을 삭제한다.

kubectl exec sample-readiness -- \
  rm -f /usr/share/nginx/html/50x.html

Probe 실패 후 Pod의 READY 값과 EndpointSlice 상태를 다시 확인한다.

kubectl get pod sample-readiness --watch
kubectl get endpointslice \
  -l kubernetes.io/service-name=sample-readiness-service \
  -o yaml

Container는 재시작되지 않지만 Pod는 Ready 상태에서 벗어나고 Service의 정상 Endpoint에서 제외된다. File을 다시 생성하면 연속 두 번 성공한 뒤 Ready 상태로 돌아간다.

kubectl exec sample-readiness -- \
  touch /usr/share/nginx/html/50x.html
kubectl wait \
  --for=condition=Ready \
  pod/sample-readiness \
  --timeout=60s

8 ) Startup Probe로 시작 구간 보호

다음 예제는 Container가 시작된 지 20초 후 /tmp/started File을 생성한다. Startup Probe가 이 File을 발견하기 전에는 Liveness·Readiness Probe가 실행되지 않는다. sample-startup.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-startup
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      command:
        - /bin/sh
        - -c
        - |
          rm -f /tmp/started /tmp/probe.log
          (sleep 20; touch /tmp/started) &
          exec nginx -g 'daemon off;'
      startupProbe:
        exec:
          command:
            - /bin/sh
            - -c
            - |
              echo "[$(date)] startup" >> /tmp/probe.log
              test -e /tmp/started
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 1
        failureThreshold: 10
      livenessProbe:
        exec:
          command:
            - /bin/sh
            - -c
            - |
              echo "[$(date)] liveness" >> /tmp/probe.log
              test ! -e /tmp/liveness-fail
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 1
        failureThreshold: 3
      readinessProbe:
        exec:
          command:
            - /bin/sh
            - -c
            - |
              echo "[$(date)] readiness" >> /tmp/probe.log
              test ! -e /tmp/readiness-fail
        periodSeconds: 3
        timeoutSeconds: 1
        successThreshold: 1
        failureThreshold: 1

Pod를 생성하고 Probe 실행 순서를 확인한다.

kubectl apply -f sample-startup.yaml
kubectl get pod sample-startup --watch

다른 터미널에서 Probe 기록을 확인한다.

kubectl exec sample-startup -- \
  cat /tmp/probe.log

처음에는 startup만 기록된다. /tmp/started가 생성되어 Startup Probe가 성공하면 startup 검사는 끝나고 liveness와 readiness가 기록되기 시작한다.

이 예제에서 Startup Probe는 최대 약 30초 동안 시작 완료를 기다릴 수 있다. 그 안에 성공하지 못하면 kubelet은 해당 Container를 재시작한다. Pod Object 자체를 다시 생성하는 동작은 아니다.

9 ) restartPolicy

spec.restartPolicy는 Pod 안의 Container가 종료되었을 때 kubelet이 다시 시작할지를 결정한다. Pod를 새로 생성하는 정책이 아니다.

값	종료 코드 `0`	종료 코드 `0` 이외
`Always`	재시작	재시작
`OnFailure`	재시작하지 않음	재시작
`Never`	재시작하지 않음	재시작하지 않음

일반 Pod의 기본값은 Always이다. Deployment와 StatefulSet 같은 일반적인 장기 실행 Workload의 Pod Template도 Always를 사용한다. 완료형 Workload인 Job은 성공한 Container가 다시 시작되면 작업을 완료할 수 없으므로 OnFailure 또는 Never만 사용할 수 있다. Job의 재시도 방식은 Kubernetes Job과 CronJob에서 다룬다.

정상 종료한 Container도 Always에서 재시작되는지 확인한다. 다음 내용을 sample-restart-always.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-restart-always
spec:
  restartPolicy: Always
  containers:
    - name: tools-container
      image: busybox:1.36
      command:
        - /bin/sh
        - -c
        - exit 0

Pod를 생성하면 Process가 종료 코드 0으로 끝나지만 kubelet이 계속 Container를 재시작한다.

kubectl apply -f sample-restart-always.yaml
kubectl get pod sample-restart-always --watch
kubectl describe pod sample-restart-always

반복 종료가 발생하면 재시작 사이의 지연이 증가하며 kubectl의 STATUS에 CrashLoopBackOff가 표시될 수 있다. CrashLoopBackOff는 Pod Phase가 아니라 반복 실패에 대한 kubectl 상태 표시이다.

10 ) Probe와 restartPolicy의 연결

Liveness·Startup Probe 실패가 기준 횟수에 도달하면 kubelet은 실패한 Container를 종료한다. 이후 Container 수준의 restartPolicy 적용 결과에 따라 재시작 여부가 결정된다. Readiness Probe는 Container를 종료하지 않으므로 restartPolicy를 작동시키지 않는다.

상황	Container 종료	`restartPolicy` 적용	Service Traffic
Liveness 실패 기준 도달	종료함	적용함	재시작과 Ready 상태에 따라 제외될 수 있음
Readiness 실패	종료하지 않음	적용하지 않음	정상 Endpoint에서 제외됨
Startup 실패 기준 도달	종료함	적용함	시작 완료 전에는 Ready가 아님
Container Process 자체 종료	이미 종료됨	적용함	Ready가 아니므로 정상 Endpoint에서 제외됨

여러 Container가 있는 Pod에서는 Liveness 실패가 발생한 Container만 재시작한다. 다만 Container 중 하나라도 Ready 상태가 아니면 ContainersReady와 일반적인 Ready Condition에 영향을 줄 수 있다.

중간 정리

kubelet은 Worker에서 Container별 Probe를 실행한다.

Liveness와 Startup 실패는 Container 재시작으로 이어질 수 있고 Readiness 실패는 Traffic 전달을 중단한다.

restartPolicy는 종료된 Container의 재시작 여부를 결정하며 Pod Object를 다시 생성하지 않는다.

11 ) Init Container

Init Container

Main Container가 시작되기 전에 초기 설정이나 준비 작업을 완료하는 Container이다.

Init Container는 spec.initContainers에 여러 개를 선언할 수 있다. 목록 위에서부터 하나씩 실행되며 각 Init Container가 성공해야 다음 Init Container가 시작된다. 모든 초기화가 끝나야 spec.containers의 Main Container가 시작된다.

구분	Init Container	Main Container
시작 시점	Main Container보다 먼저 시작	모든 Init Container 성공 후 시작
여러 Container의 순서	선언 순서대로 하나씩 실행	기본적으로 서로 병렬로 시작
실행 형태	준비 작업을 마치고 정상 종료	일반적으로 Application Process를 계속 실행
주요 용도	설정 생성, 의존 대상 대기, 초기 Data 준비	실제 요청 처리와 Background 작업

초기화에만 필요한 Script나 Utility를 별도 Image에 둘 수 있으므로 Main Image의 구성과 권한을 줄이는 데 도움이 된다. Init Container와 Main Container가 결과를 공유하려면 공통 Volume을 Mount해야 한다. 서로의 Container File System은 자동으로 공유되지 않는다.

Control Plane과 Worker 관점의 실행 순서는 다음과 같다.

API Server에 저장된 Pod Spec
            │
            ▼
Scheduler가 Worker 선택
            │
            ▼
Worker의 kubelet
  ├── 첫 번째 Init Container 실행·성공 확인
  ├── 두 번째 Init Container 실행·성공 확인
  └── Main Container 실행
            │
            ▼
       Probe와 Ready 판정

Init Container가 실패하면 kubelet은 Pod의 restartPolicy에 따라 다시 시도한다. 초기화가 성공하지 않는 동안 Main Container는 시작되지 않는다.

12 ) Init Container 실습

다음 내용을 sample-initcontainer.yaml로 저장한다. 두 Init Container와 nginx Container는 emptyDir Volume을 공유한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-initcontainer
spec:
  initContainers:
    - name: output-1
      image: alpine:3.20
      command:
        - sh
        - -c
        - sleep 20; echo 1st > /usr/share/nginx/html/index.html
      volumeMounts:
        - name: html-volume
          mountPath: /usr/share/nginx/html
    - name: output-2
      image: alpine:3.20
      command:
        - sh
        - -c
        - sleep 10; echo 2nd > /usr/share/nginx/html/index.html
      volumeMounts:
        - name: html-volume
          mountPath: /usr/share/nginx/html
  containers:
    - name: nginx-container
      image: nginx:stable
      volumeMounts:
        - name: html-volume
          mountPath: /usr/share/nginx/html
  volumes:
    - name: html-volume
      emptyDir: {}

Pod를 적용하면서 STATUS와 Init Container 진행 번호를 관찰한다.

kubectl get pods --watch

다른 Terminal에서 다음 명령을 실행한다.

kubectl apply -f sample-initcontainer.yaml

초기화가 끝나면 각 Init Container의 Log와 Main Container가 읽는 File을 확인한다.

kubectl logs pod/sample-initcontainer -c output-1
kubectl logs pod/sample-initcontainer -c output-2
kubectl exec pod/sample-initcontainer -- \
  cat /usr/share/nginx/html/index.html

두 번째 Init Container가 첫 번째 Container의 File을 덮어쓰므로 최종 출력은 2nd이다. 이 결과는 두 작업이 병렬로 경쟁한 것이 아니라 선언 순서대로 완료되었음을 보여준다.

13 ) Container Lifecycle Hook

Container Lifecycle Hook은 Container 시작 직후나 종료 직전에 한 번 수행할 작업을 정의한다.

Hook	실행 시점	주요 용도
`postStart`	Container가 생성된 직후	초기화 신호 전달, Cache Warm-up, 내부 API 호출
`preStop`	Container가 종료되기 전	새 작업 수신 중단, Connection 정리, Application의 안전한 종료 요청

postStart와 Container의 ENTRYPOINT는 비동기적으로 시작되므로 어느 쪽이 먼저 실행된다고 보장되지 않는다. 다만 Kubernetes는 postStart가 완료될 때까지 Container를 완전히 Running 상태로 관리하지 않는다. 시작 전에 반드시 끝나야 하는 순차 작업은 postStart보다 Init Container가 적합하다.

Hook은 한 번의 Lifecycle Event에 대해 실행되며 Probe처럼 주기적으로 상태를 검사하지 않는다. Hook Handler가 실패하면 Kubernetes는 Container를 종료하고 Pod의 restartPolicy에 따라 처리한다. Hook 실행에는 별도의 Timeout Field가 없으므로 외부 호출이나 장시간 작업에는 명령 자체의 제한 시간과 실패 처리를 구성해야 한다.

exec Handler는 Container 안에서 명령을 실행한다.

postStart:
  exec:
    command:
      - /bin/sh
      - -c
      - sleep 10; touch /tmp/poststart

httpGet Handler는 지정한 Endpoint에 HTTP 요청을 보낸다.

postStart:
  httpGet:
    path: /warmup
    port: 8080
    host: application.example.com
    scheme: HTTP

postStart는 Application의 지속적인 정상 여부를 판정하지 않는다. 실행 중 상태 점검에는 Liveness·Readiness·Startup Probe를 사용한다.

14 ) Lifecycle Hook 실습

다음 내용을 sample-lifecycle-exec.yaml로 저장한다. postStart는 시작 표시 File을 만들고, preStop은 nginx에 안전한 종료를 요청한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-lifecycle-exec
spec:
  terminationGracePeriodSeconds: 30
  containers:
    - name: nginx-container
      image: nginx:stable
      lifecycle:
        postStart:
          exec:
            command:
              - /bin/sh
              - -c
              - sleep 10; touch /tmp/poststart
        preStop:
          exec:
            command:
              - /bin/sh
              - -c
              - |
                echo "preStop started" > /proc/1/fd/1
                nginx -s quit
                sleep 5

Pod를 적용하고 시작 상태를 관찰한다.

kubectl apply -f sample-lifecycle-exec.yaml
kubectl get pod sample-lifecycle-exec --watch

postStart가 끝난 뒤 생성된 File을 확인한다.

kubectl exec pod/sample-lifecycle-exec -- ls -l /tmp/poststart

한 Terminal에서 Log를 확인한다.

kubectl logs -f pod/sample-lifecycle-exec

다른 Terminal에서 Pod를 삭제하면 preStop started가 기록되고 Grace Period 안에서 nginx가 종료된다.

kubectl delete -f sample-lifecycle-exec.yaml

Pod가 완전히 삭제된 뒤에는 kubectl exec로 /tmp/prestop 같은 Container 내부 File을 확인할 수 없다. 종료 과정은 Hook Log, Application Log와 Event를 통해 관찰해야 한다.

15 ) Graceful Shutdown

Graceful Shutdown

처리 중인 요청과 Data를 가능한 한 안전하게 마무리한 뒤 Application Process를 종료하는 절차이다.

Pod 삭제나 Rolling Update로 Container가 종료될 때의 주요 흐름은 다음과 같다.

Pod 종료 요청
    │ terminationGracePeriodSeconds Countdown 시작
    ▼
preStop Hook 실행
    ▼
Container의 주 Process에 SIGTERM 전달
    ▼
Application이 신규 요청을 중단하고 기존 작업 정리
    ├── Grace Period 안에 종료 ──▶ 정상 종료
    └── 종료하지 못함 ──────────▶ SIGKILL로 강제 종료

terminationGracePeriodSeconds의 기본값은 30초이다. preStop 실행 시간과 Application이 SIGTERM을 처리하는 시간은 같은 Grace Period 안에서 사용된다. 단순히 값을 늘리기 전에 실제 요청 처리 시간, Connection 종료, Data Flush와 종료 Log를 측정해야 한다.

nginx는 SIGTERM을 받으면 빠르게 종료할 수 있다. Worker Process가 처리 중인 요청을 마치도록 하려면 preStop에서 nginx -s quit으로 Graceful Shutdown을 요청할 수 있다. Application마다 종료 Signal 처리 방식이 다르므로 Container의 PID 1 Process가 Signal을 전달받고 올바르게 처리하는지도 확인해야 한다.

Rolling Update에서 Readiness Probe, preStop, Grace Period는 서로 다른 역할을 한다.

구성	역할
Readiness Probe	새 요청을 받을 수 있는 Pod인지 판단
`preStop`	Container 종료 직전에 Application별 정리 작업 수행
`terminationGracePeriodSeconds`	종료 작업을 마칠 수 있는 전체 유예 시간 제공

16 ) 실습 Resource 정리

실습 중 생성한 Pod와 Service를 확인한다.

kubectl get pods
kubectl get service sample-readiness-service
kubectl get endpointslice \
  -l kubernetes.io/service-name=sample-readiness-service

Manifest로 생성한 Resource를 삭제한다.

kubectl delete -f sample-healthcheck.yaml
kubectl delete -f sample-liveness.yaml
kubectl delete -f sample-readiness.yaml
kubectl delete -f sample-startup.yaml
kubectl delete -f sample-restart-always.yaml
kubectl delete -f sample-initcontainer.yaml
kubectl delete -f sample-lifecycle-exec.yaml --ignore-not-found

전체 정리

최종 정리

Liveness Probe는 Container가 계속 동작할 수 있는지 확인하고, 실패 기준에 도달하면 kubelet이 해당 Container를 재시작한다.

Readiness Probe는 현재 요청을 처리할 수 있는지 확인하며, 실패한 Pod는 재시작하지 않고 Service의 정상 Endpoint에서 제외한다.

Startup Probe가 성공하기 전에는 Liveness·Readiness Probe를 실행하지 않아 시작 시간이 긴 Application의 반복 재시작을 방지한다.

Probe는 exec, httpGet, tcpSocket 방식으로 실행할 수 있으며 주기, Timeout과 성공·실패 횟수를 Application 특성에 맞게 설정한다.

Worker의 kubelet이 Probe를 실행하고 결과를 API Server에 보고하면 Control Plane의 Controller가 Ready 상태를 Service Endpoint에 반영한다.

restartPolicy는 Pod가 아니라 종료된 Container의 재시작 여부를 결정한다.

Init Container는 Main Container보다 먼저 선언 순서대로 실행되며 공통 Volume으로 초기화 결과를 전달할 수 있다.

postStart와 preStop은 Lifecycle Event에 한 번 실행되고 Probe는 Container 상태를 주기적으로 검사한다.

Graceful Shutdown에서는 preStop과 Application의 종료 처리가 같은 terminationGracePeriodSeconds 안에 완료되어야 한다.

Kubernetes Resource 관리와 Autoscaling

2026-09-03T00:00:00+09:00

Kubernetes는 Container가 요청하는 Resource를 기준으로 Pod를 Worker에 배치하고, kubelet과 Container Runtime을 통해 실행 중인 Resource 사용을 제한한다. Namespace에는 LimitRange와 ResourceQuota를 적용할 수 있으며, Resource Request는 Cluster와 Pod Autoscaling 판단에도 사용된다.

1 ) Cluster API Resource와 관리 범위

Cluster를 운영할 때 자주 확인하는 Resource는 Cluster 범위와 Namespace 범위로 나뉜다.

Resource	범위	역할
Node	Cluster	Worker의 상태와 Capacity·Allocatable 표시
Namespace	Cluster	Namespace 범위 Resource의 논리적 구분
PersistentVolume	Cluster	Cluster에 제공되는 Storage 표현
ResourceQuota	Namespace	Resource 사용량과 Object 개수 제한
ServiceAccount	Namespace	Pod와 Process의 API Identity 제공
Role	Namespace	Namespace 안의 API 권한 정의
ClusterRole	Cluster	Cluster 범위 또는 재사용 가능한 API 권한 정의
RoleBinding	Namespace	Namespace 안의 주체에 Role·ClusterRole 연결
ClusterRoleBinding	Cluster	Cluster 범위에서 주체에 ClusterRole 연결
NetworkPolicy	Namespace	선택한 Pod의 Ingress·Egress Traffic 제어

Node와 Namespace의 기본 조회는 다음 명령으로 확인한다.

# Master 또는 관리 Client에서 실행
kubectl get nodes -o wide
kubectl get node worker1 -o yaml
kubectl get namespaces
kubectl get pods -n kube-system
kubectl get pods --all-namespaces

Node Object는 일반 Workload처럼 사용자가 반복해서 생성·삭제하는 Resource가 아니다. kubelet 등록과 Node Bootstrap 과정에서 Cluster에 추가되며 운영 중에는 상태, Capacity, Condition과 배치된 Pod를 자주 확인한다.

-A는 --all-namespaces의 축약 Option이다. -a는 모든 Namespace를 조회하는 Option이 아니다.

Namespace의 구조와 생성 방법은 Kubernetes Namespace와 kubectl 기본 사용에서, PV는 Kubernetes Volume과 Persistent Storage에서 설명한다.

2 ) Resource Request와 Limit

Container의 resources.requests와 resources.limits에는 CPU, Memory와 Ephemeral Storage 등을 지정할 수 있다. Device Plugin을 사용하면 GPU 같은 Extended Resource도 요청할 수 있다.

설정	Control Plane과 Worker에서의 역할
`requests`	Scheduler가 Pod를 배치할 수 있는 Node를 판단할 때 사용
`limits`	kubelet과 Container Runtime이 실행 중인 Container의 사용 상한을 적용

CPU는 Clock Frequency가 아니라 CPU Unit으로 지정한다. 1 CPU는 물리 Core 또는 Virtual Core 하나에 해당하며 1000m과 같다.

값	의미
`1000m`	1 CPU
`500m`	0.5 CPU
`100m`	0.1 CPU
`512Mi`	512 Mebibyte
`1Gi`	1 Gibibyte

Request는 Container가 항상 실제로 소비하는 최솟값이 아니다. Scheduler의 배치 판단 기준이며, CPU 경합 시에는 CPU Share의 가중치에도 사용된다. Node에 여유가 있으면 Container는 Request보다 많은 CPU와 Memory를 사용할 수 있다.

Limit 적용 방식은 Resource마다 다르다.

CPU Limit을 초과하려 하면 Linux Kernel이 CPU 시간을 Throttling한다.
Memory Limit은 반응적으로 적용되며, Memory 부족이 감지되면 OOM Killer가 Container Process를 종료할 수 있다.

3 ) CPU와 Memory Request·Limit 실습

실습 Resource가 기존 Workload에 미치는 영향을 줄이기 위해 resource-lab Namespace를 사용한다. Namespace가 없다면 Master 또는 관리 Client에서 생성한다.

kubectl create namespace resource-lab
kubectl get namespace resource-lab

다음 내용을 sample-resource.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-resource
  namespace: resource-lab
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sample-resource
  template:
    metadata:
      labels:
        app: sample-resource
    spec:
      containers:
        - name: nginx-container
          image: nginx:stable
          resources:
            requests:
              memory: 512Mi
              cpu: 500m
            limits:
              memory: 1Gi
              cpu: "1"

Master 또는 관리 Client에서 Deployment를 생성하고 Rollout 상태를 확인한다.

kubectl apply -f sample-resource.yaml
kubectl rollout status deployment/sample-resource \
  -n resource-lab
kubectl get pods -n resource-lab \
  -l app=sample-resource -o wide

Control Plane의 Scheduler는 Container별 Request를 합산하여 배치 가능한 Worker를 선택한다. Worker의 kubelet은 Pod Spec의 Limit을 Container Runtime에 전달하고 Runtime은 Linux cgroup을 통해 CPU와 Memory 제한을 적용한다.

Pod에 저장된 Resource 설정을 확인한다.

kubectl get pods -n resource-lab \
  -l app=sample-resource -o json \
  | jq '.items[].spec.containers[].resources'

4 ) Request만 지정한 경우

다음 내용을 sample-resource-only-requests.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-resource-only-requests
  namespace: resource-lab
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sample-resource-only-requests
  template:
    metadata:
      labels:
        app: sample-resource-only-requests
    spec:
      containers:
        - name: nginx-container
          image: nginx:stable
          resources:
            requests:
              memory: 256Mi
              cpu: 200m

kubectl apply -f sample-resource-only-requests.yaml
kubectl get pods -n resource-lab \
  -l app=sample-resource-only-requests
kubectl get pods -n resource-lab \
  -l app=sample-resource-only-requests -o json \
  | jq '.items[].spec.containers[].resources'

Request만 있고 Limit이 없으면 해당 Resource에 Container별 상한이 설정되지 않는다. CPU는 Node의 여유 Resource를 더 사용할 수 있고, Memory 사용이 증가하여 Node 전체에 Memory Pressure가 발생하면 OOM이나 Pod Eviction으로 이어질 수 있다.

5 ) Limit만 지정한 경우

Admission 단계에서 다른 기본값이 적용되지 않았다면 특정 Resource의 Limit만 지정했을 때 Kubernetes는 같은 값을 Request로 복사한다.

다음 내용을 sample-resource-only-limits.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-resource-only-limits
  namespace: resource-lab
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      resources:
        limits:
          memory: 256Mi
          cpu: 200m

Pod를 생성한 뒤 API Server에 저장된 Request와 Limit을 확인한다.

kubectl apply -f sample-resource-only-limits.yaml
kubectl get pod sample-resource-only-limits \
  -n resource-lab -o json \
  | jq '.spec.containers[].resources'

Namespace에 LimitRange 등 Admission 단계의 기본값이 있으면 결과가 달라질 수 있다. Scheduling Resource를 명확히 관리하려면 Request와 Limit을 모두 명시한다.

6 ) Ephemeral Storage 제한

Local Ephemeral Storage는 Pod가 실행되는 Node의 임시 저장 공간이다. kubelet이 측정하는 주요 대상은 다음과 같다.

Container Log
Container의 Writable Layer
Disk 기반 emptyDir Data

Memory 기반 emptyDir은 Ephemeral Storage가 아니라 Container Memory 사용량으로 계산된다.

다음 내용을 sample-ephemeral-storage.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-ephemeral-storage
  namespace: resource-lab
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      resources:
        requests:
          ephemeral-storage: 1Gi
        limits:
          ephemeral-storage: 2Gi

kubectl apply -f sample-ephemeral-storage.yaml
kubectl wait --for=condition=Ready \
  pod/sample-ephemeral-storage \
  -n resource-lab --timeout=120s

Container의 Writable Layer에 2GiB File 생성을 시도한다.

kubectl exec -n resource-lab sample-ephemeral-storage -- \
  dd if=/dev/zero of=/dummy bs=1M count=2049

사용량이 Limit을 초과하면 kubelet이 Pod를 Eviction 대상으로 표시할 수 있다. File System 구성과 kubelet의 Local Storage 측정 조건에 따라 결과 시점이 달라질 수 있으므로 Pod 상태와 Event를 함께 확인한다.

kubectl get pod sample-ephemeral-storage \
  -n resource-lab --watch
kubectl describe pod sample-ephemeral-storage \
  -n resource-lab
kubectl get events -n resource-lab \
  --sort-by=.lastTimestamp

여러 Container가 있는 Pod의 Ephemeral Storage Limit은 Container별 Limit의 합으로 계산한다. Pod 사용량에는 Container의 Writable Layer와 Log 및 Disk 기반 emptyDir 사용량이 포함된다.

7 ) Node Capacity와 Allocatable

Node의 전체 Capacity가 모두 Pod에 할당되는 것은 아니다. kubelet은 OS와 Kubernetes Component가 사용할 Resource를 고려하여 status.allocatable에 Pod가 사용할 수 있는 양을 표시한다.

kubectl get node worker1 \
  -o custom-columns='NAME:.metadata.name,CPU:.status.capacity.cpu,ALLOCATABLE_CPU:.status.allocatable.cpu,MEMORY:.status.capacity.memory,ALLOCATABLE_MEMORY:.status.allocatable.memory'
kubectl describe node worker1

설정	용도
`kubeReserved`	kubelet과 Container Runtime 등 Kubernetes 관련 Daemon Resource 예약
`systemReserved`	OS와 System Daemon Resource 예약
Eviction Threshold	Node Resource 고갈 전에 kubelet이 Pod를 Eviction할 기준

kubeReserved와 systemReserved는 kubelet에서 구성하는 값이며 모든 Cluster에 같은 값이 자동으로 적용되는 것은 아니다. 실제 Pod 배치 가능량은 Node의 status.allocatable에서 확인한다.

8 ) Node-pressure Eviction

Worker의 kubelet에 있는 Eviction Manager는 Memory, Disk 공간과 File System Inode 등의 상태를 주기적으로 확인한다. Threshold가 충족되면 Node 전체의 Resource 고갈을 막기 위해 Pod를 종료하고 Resource를 회수한다.

구분	동작
Soft Threshold	조건이 `evictionSoftGracePeriod` 동안 지속된 뒤 Eviction 시작
Hard Threshold	Grace Period `0s`로 즉시 Eviction 시작
`evictionMaxPodGracePeriod`	Soft Eviction에서 허용할 Pod 종료 Grace Period 상한

evictionSoftGracePeriod는 Threshold가 얼마나 지속돼야 하는지를 나타낸다. Pod 종료에 허용할 시간과 같은 설정이 아니다. Node-pressure Eviction은 Pod의 terminationGracePeriodSeconds나 PodDisruptionBudget을 그대로 따르지 않는다.

kubelet은 다음 순서로 Eviction 대상을 평가한다.

고갈된 Resource의 실제 사용량이 Request를 초과했는지 확인한다.
Pod Priority가 낮은 Pod를 우선한다.
실제 사용량이 Request를 얼마나 초과했는지 비교한다.

kubectl describe node에서 MemoryPressure, DiskPressure, PIDPressure Condition과 Event를 확인한다.

kubectl describe node worker1

# worker1에서 실행
sudo journalctl -u kubelet --since "10 minutes ago"

9 ) Scheduling 불가와 Overcommit

Resource Request를 수용할 Worker가 없으면 Pod는 Pending 상태에 머문다. 이는 실제 CPU·Memory 사용률이 100%라는 의미가 아니라 Scheduler가 계산한 Allocatable 대비 Request가 부족하다는 의미이다.

Resource Overcommit은 일반적으로 Node Capacity보다 큰 Limit 총량을 허용하여 Workload가 동시에 최대치를 사용하지 않는다는 전제로 Resource를 배치하는 방식이다. Request 부족으로 Pod를 배치하지 못하는 상태와 구분해야 한다.

다음 내용을 sample-resource-scale.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-resource-scale
  namespace: resource-lab
spec:
  replicas: 2
  selector:
    matchLabels:
      app: sample-resource-scale
  template:
    metadata:
      labels:
        app: sample-resource-scale
    spec:
      containers:
        - name: nginx-container
          image: nginx:stable
          resources:
            requests:
              memory: 512Mi
              cpu: 500m
            limits:
              memory: 1Gi
              cpu: "1"

kubectl apply -f sample-resource-scale.yaml
kubectl scale deployment/sample-resource-scale \
  -n resource-lab --replicas=6
kubectl get pods -n resource-lab \
  -l app=sample-resource-scale -o wide

실제 Cluster에 충분한 Resource가 있으면 여섯 Pod가 모두 실행될 수 있다. Pending Pod가 발생한 경우 Pod Event와 Node의 할당 현황을 확인한다.

kubectl describe pod  \
  -n resource-lab
kubectl describe node worker1

kubectl describe node의 Allocated resources는 실제 사용량이 아니라 Pod Spec에 선언된 Request와 Limit의 합계이다. 실제 사용량은 Metrics Server가 제공하는 kubectl top으로 구분해 확인한다.

10 ) 여러 Container의 Resource 계산

Scheduler는 Pod 단위로 Worker를 선택하므로 Pod에 포함된 Container의 Resource를 합산한다.

일반 Application Container의 같은 Resource Request와 Limit은 모두 합산한다.
일반 Init Container는 순차 실행되므로 같은 Resource에서 가장 큰 Init Container 값을 사용한다.
Application Container 합계와 Init Container의 최댓값 중 큰 값을 Pod의 Scheduling 기준으로 사용한다.

Pod의 유효 Request
  = max(
      모든 Application Container Request의 합,
      Init Container Request 중 최댓값
    )

이 계산은 Init Container가 Application Container보다 큰 초기화 Resource를 요구할 때 해당 Pod가 실행 가능한 Worker를 확보하는 데 사용된다.

11 ) Cluster Autoscaler

Cluster Autoscaler는 실행할 Node가 부족한 Pod를 감지하고 연동된 Infrastructure의 Node Group 크기를 조정한다. 단순한 Node CPU·Memory 평균 사용률이 아니라 Scheduler가 배치하지 못한 Pod와 해당 Pod의 Request를 주요 판단 기준으로 사용한다.

Pod 생성
  → Scheduler가 모든 Node의 Allocatable과 Request 비교
  → 적합한 Node가 없어 Pod가 Pending
  → Cluster Autoscaler가 확장 가능 여부 확인
  → Infrastructure Node Group 확장
  → 새 Worker 준비와 Cluster 등록
  → Scheduler가 Pending Pod 배치

Request를 지나치게 크게 설정하면 실제 사용량이 낮아도 Pod가 배치되지 않아 Scale-out이 발생할 수 있다. 반대로 Request를 지나치게 낮게 설정하면 실제 부하가 높아도 Scheduler는 여유가 있다고 판단할 수 있다.

Cluster Autoscaler는 실제 Node를 생성할 수 있는 Infrastructure와 연결되어야 한다.

환경	연동 구조 예시
AWS	Auto Scaling Group의 Desired Capacity 조정 및 Tag 기반 Node Group 탐색
직접 구축한 VM 환경	VM 생성, OS 준비와 `kubeadm join`까지 자동화 필요
Cluster API 사용 환경	Machine Resource와 Infrastructure Provider로 Node Lifecycle 관리

Cluster API는 On-premise 환경에서 사용할 수 있는 선택지 중 하나이며, kubeadm Cluster에 Cluster Autoscaling을 자동으로 제공하는 기능은 아니다.

Request와 Limit은 임의의 고정 비율로 결정하지 않고 Application의 부하 Test와 관측 결과를 기준으로 조정한다. Memory Limit이 지나치게 낮으면 부하 Test 중 OOM Kill이 발생할 수 있고 Request가 실제 요구량보다 크면 Scheduling과 Node 확장 효율이 낮아질 수 있다.

12 ) LimitRange

LimitRange는 Namespace 안에서 Container, Pod 또는 PVC에 허용할 Resource 범위를 정의한다. 새 Object가 API Server의 Admission 단계를 통과할 때 적용되며 이미 실행 중인 Pod의 Resource 설정은 변경하지 않는다.

Field	역할
`default`	Container에 Limit이 없을 때 적용할 기본 Limit
`defaultRequest`	Container에 Request가 없을 때 적용할 기본 Request
`max`	허용할 최대 Resource
`min`	허용할 최소 Resource
`maxLimitRequestRatio`	Limit과 Request 사이의 최대 비율

type: Container에서는 위 항목을 모두 사용할 수 있다. Pod 범위에서는 기본값을 주입하는 default, defaultRequest를 사용하지 않으며, PVC에는 Storage Request의 min과 max를 적용한다.

다음 내용을 sample-limitrange-container.yaml로 저장한다.

apiVersion: v1
kind: LimitRange
metadata:
  name: sample-limitrange-container
  namespace: resource-lab
spec:
  limits:
    - type: Container
      default:
        memory: 512Mi
        cpu: 500m
      defaultRequest:
        memory: 256Mi
        cpu: 250m
      max:
        memory: 1025Mi
        cpu: "1"
      min:
        memory: 128Mi
        cpu: 125m
      maxLimitRequestRatio:
        memory: "2"
        cpu: "2"

kubectl apply -f sample-limitrange-container.yaml
kubectl describe limitrange sample-limitrange-container \
  -n resource-lab

13 ) LimitRange 위반 확인

CPU Request와 Limit이 최소값 125m보다 작은 Pod를 생성한다. 다음 내용을 sample-pod-below-min.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-pod-below-min
  namespace: resource-lab
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      resources:
        requests:
          cpu: 100m
        limits:
          cpu: 100m

kubectl apply -f sample-pod-below-min.yaml

API Server는 LimitRange의 최소 CPU보다 작다는 Forbidden 응답으로 생성을 거부한다.

다음에는 Limit과 Request 비율이 4인 Pod를 확인한다. 내용을 sample-pod-over-ratio.yaml로 저장한다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-pod-over-ratio
  namespace: resource-lab
spec:
  containers:
    - name: nginx-container
      image: nginx:stable
      resources:
        requests:
          cpu: 125m
        limits:
          cpu: 500m

kubectl apply -f sample-pod-over-ratio.yaml

설정된 maxLimitRequestRatio.cpu가 2이므로 비율 4인 요청은 Forbidden 응답으로 거부된다. 실패한 요청은 Pod Resource를 생성하지 않는다.

14 ) ResourceQuota Object 개수 제한

ResourceQuota는 Namespace 전체에서 사용할 수 있는 Resource 양과 생성 가능한 Object 수를 제한한다. 기존 Object를 삭제하거나 설정을 변경하지는 않지만, Quota가 생성되면 Namespace의 기존 Object도 현재 사용량에 포함된다.

다음 내용을 sample-resourcequota-count.yaml로 저장한다.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: sample-resourcequota-count
  namespace: resource-lab
spec:
  hard:
    count/persistentvolumeclaims: "10"
    count/services: "10"
    count/secrets: "10"
    count/configmaps: "10"
    count/replicationcontrollers: "10"
    count/deployments.apps: "10"
    count/replicasets.apps: "10"
    count/statefulsets.apps: "10"
    count/jobs.batch: "10"
    count/cronjobs.batch: "10"

count/deployments.extensions는 제거된 extensions API Group을 대상으로 하므로 현재 Manifest에 사용하지 않는다.

kubectl apply -f sample-resourcequota-count.yaml
kubectl describe resourcequota sample-resourcequota-count \
  -n resource-lab

ConfigMap 열한 개 생성을 시도한다.

for i in $(seq 1 11); do
  kubectl create configmap "conf-${i}" \
    --from-literal=key1=val1 \
    -n resource-lab
done

Namespace에 이미 존재하는 ConfigMap을 포함하여 총수가 10에 도달하면 다음 생성 요청이 거부된다. Kubernetes가 자동으로 만든 kube-root-ca.crt ConfigMap 등이 있을 수 있으므로 실패 순서를 고정하지 않고 ResourceQuota의 현재 사용량을 확인한다.

kubectl describe resourcequota sample-resourcequota-count \
  -n resource-lab
kubectl get configmaps -n resource-lab

15 ) ResourceQuota Key 종류

count/[.] 형식 외에도 Kubernetes가 정의한 Object별 Quota Key와 StorageClass별 Key를 사용할 수 있다. 두 형식은 단순히 옛날 방식과 최근 방식으로 나뉘지 않는다.

다음 내용을 sample-resourcequota-special.yaml로 저장한다.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: sample-resourcequota-special
  namespace: resource-lab
spec:
  hard:
    sample-storageclass.storageclass.storage.k8s.io/persistentvolumeclaims: "10"
    services.loadbalancers: "10"
    services.nodeports: "10"
    pods: "10"
    persistentvolumeclaims: "10"
    replicationcontrollers: "10"
    secrets: "10"
    configmaps: "10"
    services: "10"
    resourcequotas: "10"

Key	제한 대상
`services.loadbalancers`	`type: LoadBalancer` Service 수
`services.nodeports`	Service가 사용하는 NodePort 수
`pods`	Terminal 상태가 아닌 Pod 수
`.storageclass.storage.k8s.io/persistentvolumeclaims`	해당 StorageClass를 요청하는 PVC 수

kubectl apply -f sample-resourcequota-special.yaml
kubectl describe resourcequota sample-resourcequota-special \
  -n resource-lab

16 ) ResourceQuota 사용량 제한

ResourceQuota는 CPU, Memory, Storage와 Extended Resource의 Namespace 전체 합계도 제한할 수 있다.

다음 내용을 sample-resourcequota-usable.yaml로 저장한다.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: sample-resourcequota-usable
  namespace: resource-lab
spec:
  hard:
    requests.memory: 2Gi
    requests.storage: 5Gi
    sample-storageclass.storageclass.storage.k8s.io/requests.storage: 5Gi
    requests.ephemeral-storage: 5Gi
    requests.nvidia.com/gpu: "2"
    limits.cpu: "4"
    limits.ephemeral-storage: 10Gi

GPU 같은 Extended Resource는 Overcommit을 지원하지 않으므로 Quota에는 requests. 형식만 사용한다. limits.nvidia.com/gpu는 유효한 Extended Resource Quota Key가 아니다.

kubectl apply -f sample-resourcequota-usable.yaml
kubectl describe resourcequota sample-resourcequota-usable \
  -n resource-lab

같은 Namespace에 ResourceQuota가 여러 개 있으면 새 Object는 모든 Quota 조건을 만족해야 한다.

17 ) Horizontal Pod Autoscaler

Horizontal Pod Autoscaler(HPA)

Metric 값을 기준으로 Deployment나 StatefulSet 같은 확장 가능한 Workload의 Replica 수를 자동 조정하는 API Resource와 Controller이다.

HPA는 Deployment, StatefulSet, ReplicaSet과 ReplicationController처럼 Scale Subresource를 제공하는 대상의 Replica를 조정할 수 있다. 부하가 높으면 Replica를 늘리고 낮으면 줄인다. CPU 사용률처럼 Request 대비 비율을 사용하는 Resource Metric은 대상 Pod의 Container에 해당 Resource Request가 정의돼 있어야 계산할 수 있다.

HPA Controller의 기본 동기화 주기는 30초가 아니라 15초이다. 실제 값은 kube-controller-manager의 horizontalPodAutoscalerSyncPeriod 설정에 따라 달라질 수 있다.

기본 Replica 계산식은 다음과 같다.

desiredReplicas
  = ceil(
      currentReplicas
      × currentMetricValue
      ÷ desiredMetricValue
    )

두 Pod의 CPU 사용률이 각각 100%, 90%라면 평균은 95%이다. 목표 평균 사용률이 50%일 때 계산 결과는 다음과 같다.

ceil(2 × 95 ÷ 50)
= ceil(3.8)
= 4

따라서 허용 범위와 Stabilization 동작 등 다른 조건을 제외한 기본 계산 결과는 Replica 네 개이다. Metric 수집 상태는 Kubernetes Resource 조회와 Pod Debugging의 Metrics Server와 kubectl top 절에서 확인할 수 있다.

18 ) HPA 동작 구조와 준비 상태 확인

HPA는 Control Plane에서 실행되는 Controller와 Worker에서 수집되는 Metric을 연결하여 동작한다.

Worker의 kubelet이 Container의 CPU·Memory 사용량을 수집한다.
Metrics Server가 각 Node의 kubelet에서 Metric을 수집하여 Metrics API로 제공한다.
Control Plane의 HPA Controller가 Metrics API에서 대상 Pod의 Metric을 조회한다.
HPA Controller가 계산한 Replica 수를 Deployment의 Scale Subresource에 반영한다.
Deployment Controller가 변경된 Replica 수에 맞춰 Pod를 생성하거나 제거한다.
새 Pod가 필요하면 Scheduler가 Worker를 선택하고, 해당 Worker의 kubelet과 Container Runtime이 Container를 실행한다.

HPA를 사용하기 전에 Kubernetes Resource 조회와 Pod Debugging에서 설치한 Metrics Server와 Metric 수집 상태를 확인한다.

kubectl get pods -n kube-system \
  -l k8s-app=metrics-server
kubectl get apiservice v1beta1.metrics.k8s.io
kubectl top nodes
kubectl top pods -A

kubectl top 결과가 나오지 않는 상태에서는 Resource Metric 기반 HPA 실습을 진행할 수 없다. 먼저 Metrics Server Pod, APIService와 kubelet 통신 상태를 확인해야 한다.

19 ) HPA 실습

HPA가 CPU 사용률을 계산할 수 있도록 CPU Request를 지정한 Deployment를 생성한다. 다음 내용을 nginx-hpa.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-hpa
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-hpa
  template:
    metadata:
      labels:
        app: nginx-hpa
    spec:
      containers:
        - name: nginx
          image: nginx:stable
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi
          ports:
            - containerPort: 80

Cluster 안에서 부하 발생 Pod가 nginx에 접근할 수 있도록 다음 내용을 nginx-hpa-service.yaml로 저장한다.

apiVersion: v1
kind: Service
metadata:
  name: nginx-hpa-service
spec:
  selector:
    app: nginx-hpa
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

CPU 평균 사용률이 Request의 50%를 넘으면 Replica를 늘리도록 다음 내용을 nginx-hpa-autoscaler.yaml로 저장한다.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-hpa
  minReplicas: 1
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

세 Resource를 생성하고 연결 상태를 확인한다.

kubectl apply -f nginx-hpa.yaml
kubectl apply -f nginx-hpa-service.yaml
kubectl apply -f nginx-hpa-autoscaler.yaml

kubectl get deployment,service,hpa
kubectl describe hpa nginx-hpa

TARGETS가 /50%로 계속 표시되면 CPU Request와 Metrics Server 상태를 함께 확인한다.

부하에 따른 Replica 변화 확인

두 터미널에서 HPA와 Pod의 변화를 각각 관찰한다.

kubectl get hpa nginx-hpa --watch

kubectl get pods -l app=nginx-hpa --watch

다른 터미널에서 Service로 요청을 반복 전송하는 Pod 세 개를 실행한다.

kubectl run load-generator \
  --image=busybox:1.36 \
  --restart=Never \
  -- /bin/sh -c \
  "while true; do wget -q -O- http://nginx-hpa-service; done"

kubectl run load-generator1 \
  --image=busybox:1.36 \
  --restart=Never \
  -- /bin/sh -c \
  "while true; do wget -q -O- http://nginx-hpa-service; done"

kubectl run load-generator2 \
  --image=busybox:1.36 \
  --restart=Never \
  -- /bin/sh -c \
  "while true; do wget -q -O- http://nginx-hpa-service; done"

HPA가 즉시 반응하지 않을 수 있다. Metric 수집과 HPA 동기화가 진행된 뒤 CPU 사용률, DESIRED Replica와 Pod 수가 변하는지 확인한다.

kubectl top pods -l app=nginx-hpa
kubectl get hpa nginx-hpa
kubectl get deployment nginx-hpa

부하 발생 Pod를 삭제하면 CPU 사용률이 낮아지고 Stabilization 조건에 따라 Replica가 다시 줄어든다.

kubectl delete pod \
  load-generator load-generator1 load-generator2
kubectl get hpa nginx-hpa --watch

20 ) HPA Metric과 Target

autoscaling/v2 HPA는 다음 Metric Source를 사용할 수 있다.

Metric Type	판단 대상	예시
`Resource`	Pod의 CPU·Memory 같은 Resource 사용량	CPU Request 대비 평균 사용률
`ContainerResource`	Pod 안의 특정 Container Resource 사용량	Application Container의 CPU 사용률
`Pods`	각 Pod에서 수집한 Custom Metric	Pod별 Connection 수
`Object`	하나의 Kubernetes Object와 연결된 Metric	Ingress의 초당 요청 수
`External`	Kubernetes Object와 직접 연결되지 않은 외부 Metric	Load Balancer QPS, Queue 길이

Resource Metric의 Target은 다음과 같이 구분한다.

Target Type	의미	예시
`Utilization`	Resource Request 대비 평균 사용률	CPU Request의 `50%`
`AverageValue`	Pod 하나당 Metric의 평균값	Pod당 Memory `500Mi`
`Value`	Object·External Metric의 전체 목표값	Queue 전체 길이

여러 Metric을 지정하면 HPA는 각 Metric으로 필요한 Replica 수를 계산한 뒤 가장 큰 값을 사용한다. 따라서 CPU와 Memory 중 하나만 목표치를 초과해도 Scale Out이 발생할 수 있다.

21 ) 다중 Metric과 Scaling Behavior

앞서 만든 nginx-hpa-autoscaler.yaml을 다음 내용으로 변경한다. CPU 사용률과 평균 Memory 사용량을 함께 확인하고, Replica 증감 속도를 제한하는 설정이다. autoscaling/v2beta2는 Kubernetes 1.26부터 제공되지 않으므로 현재 API인 autoscaling/v2를 사용한다.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-hpa
  minReplicas: 1
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50
    - type: Resource
      resource:
        name: memory
        target:
          type: AverageValue
          averageValue: 500Mi
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15
        - type: Pods
          value: 4
          periodSeconds: 15
      selectPolicy: Max

behavior의 주요 항목은 다음과 같다.

항목	역할
`scaleUp`	Replica를 늘릴 때 적용할 정책
`scaleDown`	Replica를 줄일 때 적용할 정책
`policies.type: Percent`	현재 Replica 수를 기준으로 허용할 변화 비율
`policies.type: Pods`	일정 시간 동안 변경할 수 있는 Pod 개수
`periodSeconds`	정책이 허용하는 변화량을 계산할 기간
`selectPolicy`	여러 Policy 중 사용할 Policy 선택
`stabilizationWindowSeconds`	이전 권장값을 고려하여 급격한 변동을 줄이는 시간

Scale Up의 selectPolicy: Max는 100% 증가와 Pod 네 개 증가 중 더 큰 변화량을 허용한다. selectPolicy: Disabled를 해당 방향에 지정하면 그 방향의 Scaling을 비활성화할 수 있다.

변경된 HPA를 적용하고 실제 설정을 확인한다.

kubectl apply -f nginx-hpa-autoscaler.yaml
kubectl get hpa nginx-hpa -o yaml

22 ) Vertical Pod Autoscaler

Vertical Pod Autoscaler(VPA)

Container의 실제 Resource 사용량을 분석하여 CPU·Memory Request 권장값을 계산하고, Update Mode에 따라 이를 Pod에 적용하는 Autoscaler이다.

HPA는 주로 Replica 수를 늘리거나 줄이는 Horizontal Scaling을 담당한다. VPA는 Container 하나에 필요한 CPU·Memory Request를 조정하는 Vertical Scaling을 담당한다. Request가 실제 사용량보다 지나치게 작으면 성능과 Scheduling이 불안정해질 수 있고, 지나치게 크면 Worker의 Resource가 낭비될 수 있다.

VPA는 Kubernetes 기본 구성 요소가 아니므로 별도로 설치해야 한다. 설치 후에는 다음 구성 요소가 협력한다.

구성 요소	역할
Recommender	Resource 사용 이력을 바탕으로 Request 권장값 계산
Updater	Update Mode에 따라 기존 Pod를 교체할지 판단
Admission Controller	새 Pod 생성 시 VPA 권장값을 Pod Request에 반영

VPA 설치가 필요한 환경에서는 공식 Autoscaler 저장소를 내려받아 설치 스크립트를 실행한다.

git clone https://github.com/kubernetes/autoscaler.git
cd autoscaler/vertical-pod-autoscaler
./hack/vpa-up.sh

TLS 인증서 오류가 발생하면 원인을 해결해야 한다. 전역 Git 설정에서 TLS 검증을 비활성화하면 이후 모든 Repository 연결의 검증이 생략되므로 사용하지 않는다.

CRD와 VPA 구성 요소를 확인한다.

kubectl get crd verticalpodautoscalers.autoscaling.k8s.io
kubectl get pods -n kube-system | grep vpa
kubectl api-resources | grep -i verticalpodautoscaler

VPA 설치 방식과 지원하는 Update Mode는 사용하는 VPA Release와 Kubernetes Version에 따라 확인해야 한다.

23 ) VPA Recommendation 실습

작은 Request를 지정한 Deployment를 생성한다. 다음 내용을 vpa-deployment.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-vpa
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-vpa
  template:
    metadata:
      labels:
        app: nginx-vpa
    spec:
      containers:
        - name: nginx
          image: nginx:stable
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 512Mi
          ports:
            - containerPort: 80

기존 Pod를 변경하지 않고 Recommendation만 확인하도록 다음 내용을 nginx-vpa-autoscaler.yaml로 저장한다.

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: nginx-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-vpa
  updatePolicy:
    updateMode: "Off"

두 파일을 적용한다.

kubectl apply -f vpa-deployment.yaml
kubectl apply -f nginx-vpa-autoscaler.yaml
kubectl get deployment,pods,vpa

VPA가 사용량을 관찰하고 Recommendation을 계산할 시간이 필요하다. 일정 시간 뒤 결과를 확인한다.

kubectl describe vpa nginx-vpa
kubectl get vpa nginx-vpa \
  -o jsonpath='{.status.recommendation}'

Recommendation의 주요 값은 다음과 같다.

항목	의미
`Lower Bound`	안정적인 동작을 위해 권장되는 Resource 범위의 하한
`Upper Bound`	권장되는 Resource 범위의 상한
`Target`	VPA의 Container Resource Policy를 반영한 Request 권장값
`Uncapped Target`	Container Resource Policy를 적용하기 전 사용량 기반 권장값

실습의 Off Mode에서는 Recommendation이 표시되더라도 기존 Pod의 Request는 자동으로 바뀌지 않는다.

24 ) VPA Update Mode와 HPA 조합

VPA의 Update Mode는 Resource 권장값을 언제 적용할지 결정한다.

Update Mode	동작
`Off`	권장값만 계산하고 Pod Resource를 변경하지 않음
`Initial`	새 Pod가 생성될 때만 권장값 적용
`Recreate`	권장값 적용이 필요하면 기존 Pod를 제거하고 새 Pod에 반영
`InPlaceOrRecreate`	가능한 경우 실행 중인 Pod를 변경하고, 불가능하면 Pod를 교체
`InPlace`	지원되는 Resource를 실행 중인 Pod에 직접 변경

Auto는 Deprecated 상태이며 현재는 Recreate와 같은 방식으로 동작한다. 새 설정에는 의도를 명확히 나타내는 Mode를 사용한다. In-place Mode는 Kubernetes와 VPA가 해당 기능을 지원하는지 먼저 확인해야 한다.

VPA와 HPA가 같은 CPU Resource를 동시에 조정하면 서로의 판단에 영향을 줄 수 있다. CPU 사용률 기반 HPA는 현재 사용량을 CPU Request와 비교하는데, VPA가 그 Request를 변경하면 HPA의 계산 기준도 변하기 때문이다.

HPA 기준	VPA 대상	판단
CPU 사용률	CPU Request	계산 기준이 변하므로 충돌 가능성이 있음
CPU 사용률	Memory Request	서로 다른 Resource를 조정하므로 역할 분리가 가능함
Request 수·Queue 길이 같은 외부 Metric	CPU·Memory Request	Replica 수와 개별 Pod Resource의 판단 기준을 분리할 수 있음
CPU 사용률	`Off` Mode의 CPU·Memory Recommendation	자동 변경 없이 권장값을 검토할 수 있음

운영 환경에서는 Application 특성, Pod 교체 영향과 HPA Metric을 확인한 뒤 Mode와 조정 대상을 결정한다.

중간 정리

HPA Controller는 Metric을 기준으로 Workload Replica 수를 조정한다.

VPA는 Container의 Resource 사용량을 분석하여 CPU·Memory Request 권장값을 계산한다.

같은 Resource를 기준으로 HPA와 VPA를 함께 사용하면 계산 기준이 서로 영향을 줄 수 있다.

25 ) 실습 Resource 정리

HPA와 VPA 실습 Resource를 확인한다.

kubectl get deployment,service,hpa,vpa
kubectl get pods

HPA 실습 Resource를 삭제한다.

kubectl delete -f nginx-hpa-autoscaler.yaml
kubectl delete -f nginx-hpa-service.yaml
kubectl delete -f nginx-hpa.yaml
kubectl delete pod \
  load-generator load-generator1 load-generator2 \
  --ignore-not-found

VPA 실습 Resource를 삭제한다.

kubectl delete -f nginx-vpa-autoscaler.yaml
kubectl delete -f vpa-deployment.yaml

VPA 자체는 다른 Workload에서도 사용할 수 있으므로 이 실습만을 이유로 설치 구성 요소까지 제거하지 않는다.

Resource 관리 실습용 Namespace 안의 Resource도 확인한다.

kubectl get all -n resource-lab
kubectl get limitranges,resourcequotas \
  -n resource-lab
kubectl get configmaps -n resource-lab

resource-lab이 이 실습에만 사용됐는지 확인한 뒤 Namespace를 삭제한다. Namespace를 삭제하면 그 안의 Resource도 함께 삭제된다.

kubectl delete namespace resource-lab

전체 정리

최종 정리

Request는 Scheduler의 Pod 배치 기준이고 Limit은 실행 중인 Container에 적용할 Resource 상한이다.

CPU Limit은 Throttling으로 적용되고 Memory Limit은 OOM Kill로 이어질 수 있다.

kubelet은 Memory와 Disk 등의 Node-pressure를 감지하여 Threshold와 Pod 우선순위에 따라 Eviction한다.

LimitRange는 개별 Object의 기본값과 허용 범위를 제어하고 ResourceQuota는 Namespace 전체 사용량과 Object 수를 제한한다.

Cluster Autoscaler는 배치되지 못한 Pod의 Request를 기준으로 Node 확장을 판단하고 HPA는 Metric을 기준으로 Workload Replica를 조정한다.

HPA는 Metric을 기준으로 Replica 수를 조정하고 VPA는 CPU·Memory Request 권장값을 계산하거나 적용한다.

HPA와 VPA를 함께 사용할 때는 같은 Resource가 양쪽의 판단 기준이 되지 않도록 Metric과 조정 대상을 구분한다.

다음 글인 Kubernetes Health Check와 restartPolicy에서는 kubelet이 Container 상태를 점검하고 실패에 대응하는 과정을 다룬다.

renamed.log

Git 이력 관리와 Branch 작업

1 ) SourceTree와 Git CLI

2 ) Local Repository에서 Version 생성

Repository 준비

첫 번째 Commit

두 번째 Commit

3 ) Commit History 조회

4 ) Tag로 Version 표시

Lightweight Tag

Annotated Tag

5 ) Version 비교

HEAD, ^와 ~

6 ) File 변경 복구

Stage 취소

Working Tree 변경 폐기

7 ) Commit 되돌리기

Soft Reset

Mixed Reset

Hard Reset

Revert

8 ) Stash로 변경 임시 보관

9 ) Branch와 HEAD

Branch 삭제

10 ) Merge

Fast-forward Merge

Merge Commit

Merge 충돌

11 ) Rebase

12 ) Non-fast-forward Push와 Merge의 차이

전체 정리

GitHub Remote Repository 작업 흐름

1 ) GitHub와 Git

2 ) Remote Repository 인증 방식

HTTPS와 Personal Access Token

SSH 인증

GitHub CLI 인증

3 ) 올바른 Remote URL

4 ) Clone과 Fork

Clone

Fork

5 ) Remote 연결과 변경

Remote 추가

Remote URL 변경

Remote 이름 변경

Remote 연결 제거

6 ) Fetch와 Pull

Fetch

Pull

7 ) Local Repository를 GitHub에 Push

Local Repository 확인

8 ) SourceTree에서 Remote 작업

9 ) Push 실패 진단

현재 연결 상태 확인

GitHub CLI 인증 확인

SSH 인증 확인

Remote History 확인

10 ) Credential 노출 대응

전체 정리

Container Image Registry와 Kubernetes Image Pull

1 ) Image Registry

2 ) Public Registry와 Private Registry

3 ) Image 배포 흐름

4 ) Docker Hub에 Image 배포

로그인

Tag와 Push

Public과 Private Repository

5 ) Kubernetes의 Image Pull

Public Image를 사용하는 Deployment

Private Image와 imagePullSecrets

6 ) 자체 Registry 구성

격리된 실습용 Registry 실행

Local Registry에 Push

7 ) HTTP Registry와 TLS Registry

Docker Engine의 실습용 HTTP 허용

8 ) Kubernetes Worker의 containerd Registry 설정

hosts.toml 작성

containerd 1.x의 config_path

containerd 2.x의 config_path

Deprecated Registry 설정

`HEAD`, `^`와 `~`

9 ) Branch와 `HEAD`

Private Image와 `imagePullSecrets`

`hosts.toml` 작성

containerd 1.x의 `config_path`

containerd 2.x의 `config_path`

`.gitignore`