본문으로 건너뛰기
버전: 1.0.4

3.2. 컨트롤러

어떨 때 보는가​

  • 애플리케이션이 몇 개 떠 있는지 확인할 때
  • 새 버전이 제대로 배포되었는지 볼 때
  • 파드 수를 늘리거나 줄일 때
  • 배포한 뒤 문제가 생겨 되돌려야 할 때

컨트롤러란 무엇인가​

파드는 그 자체로는 다시 만들어지지 않습니다. 파드를 직접 만들어 두면, 그 파드가 종료되는 순간 애플리케이션도 함께 사라집니다. 노드가 내려가도 마찬가지입니다.

컨트롤러는 이 문제를 해결합니다. 사용자가 "원하는 상태" 를 정해 두면, 컨트롤러가 클러스터를 계속 지켜보며 실제 상태를 그 상태에 맞춥니다.

예를 들어 "복제본 3개" 라고 정해 두면 이렇게 동작합니다.

실제로 일어난 일컨트롤러가 하는 일
파드 하나가 종료됐다 (2개 남음)새 파드를 하나 만들어 3개로 맞춥니다
노드가 내려가 파드 2개가 사라졌다남은 노드에 2개를 새로 띄웁니다
누군가 파드를 손으로 지웠다다시 만듭니다
복제본을 5로 바꿨다2개를 더 만듭니다

사람이 지켜보지 않아도 됩니다. 이것이 Kubernetes 를 쓰는 가장 큰 이유 중 하나입니다.

선언형이라는 말의 뜻​

Kubernetes 를 설명할 때 "선언형" 이라는 말이 나옵니다. 명령형과 비교하면 이해하기 쉽습니다.

방식지시 내용문제가 생기면
명령형"이 프로그램을 실행해라"종료돼도 아무 일도 일어나지 않습니다
선언형"이 프로그램이 3개 떠 있어야 한다"종료되면 시스템이 다시 맞춥니다

컨트롤러는 선언형을 실현하는 장치입니다. 사용자는 결과만 적고, 그 결과에 도달하는 과정은 컨트롤러가 맡습니다.

Console 에서 복제본 수를 바꾸거나 이미지를 고치는 것은 "원하는 상태" 를 고치는 것 입니다. 실제 파드를 직접 건드리는 것이 아닙니다.

Deployment 란​

상태를 저장하지 않는 애플리케이션 을 관리하는 컨트롤러입니다. 웹 서버, API 서버처럼 어느 파드가 요청을 받아도 결과가 같은 경우에 씁니다.

Deployment 가 하는 일은 세 가지입니다.

하는 일설명
개수 유지정해진 복제본 수를 지킵니다
무중단 교체새 버전을 배포할 때 하나씩 바꿔 서비스를 끊지 않습니다
되돌리기이전 버전 기록을 남겨 문제가 생기면 돌아갑니다

"상태를 저장하지 않는다" 는 것은 파드 안에 남겨야 할 데이터가 없다는 뜻입니다. 데이터는 데이터베이스나 별도 저장 공간에 두고, 파드는 언제 종료되고 다시 만들어져도 상관없어야 합니다.

파드마다 고유한 데이터가 필요하면 Deployment 가 아니라 StatefulSet 을 씁니다(아래 참고).

Deployment 가 파드를 관리하는 구조​

Deployment 는 파드를 직접 만들지 않습니다. 중간에 ReplicaSet 이 있습니다.

Deployment 가 파드를 관리하는 구조

새 버전을 배포하면 새 ReplicaSet 이 하나 더 생깁니다. 옛 ReplicaSet 은 복제본 0 으로 남아 이력이 됩니다. 되돌리기는 옛 ReplicaSet 의 복제본을 다시 올리는 것입니다.

목록에 같은 이름 앞부분을 가진 ReplicaSet 이 여럿 보이는 것은 그동안의 배포 이력입니다.

Deployment 목록​

워크로드 > 배포 로 들어갑니다.

Deployment 목록
열설명이렇게 읽습니다
이름Deployment 이름
네임스페이스속한 네임스페이스
파드사용 가능한 파드 / 원하는 파드두 수가 다르면 배포가 진행 중이거나 문제가 있습니다
복제본설정한 복제본 수
상태배포의 지금 상태아래 표 참고
경과 시간만든 뒤 지난 시간

상태 칸에는 다음 표시가 나옵니다.

표시뜻
사용 가능사용할 수 있는 파드가 하나 이상 있습니다
사용할 수 없음사용할 수 있는 파드가 하나도 없습니다
롤아웃 진행 중지금 파드를 교체하고 있습니다
일시 중지됨롤아웃을 일시 중지해 두었습니다. 설정을 바꿔도 반영되지 않습니다
롤아웃 실패정해진 시간 안에 롤아웃이 끝나지 않았습니다
Pod 부족사용할 수 있는 파드가 원하는 수보다 적습니다. 파드가 시작되는 중이거나, 시작하지 못하는 상태일 수 있습니다
축소 중사용할 수 있는 파드가 원하는 수보다 많습니다. 남는 파드를 줄이는 중입니다
복제 실패Kubernetes 가 파드를 만들지 못했습니다. 표시에 마우스를 올리면 사유가 나옵니다

롤아웃이 끝나고 파드 수가 원하는 수와 같으면 사용 가능 만 표시합니다.

Pod 부족·축소 중 은 롤아웃 진행 중·일시 중지됨·롤아웃 실패 가 표시되지 않을 때만 나옵니다. 예를 들어 복제본 수를 1 에서 2 로 늘리는 중에는 사용 가능 과 Pod 부족 이 함께 표시됩니다.

복제본 수가 0 인 배포는 상태 칸이 비어 있습니다. 일시 중지 중이면 일시 중지됨 만 표시합니다.

표 위쪽 요약에는 배포: 정상 수/전체 수 와 함께 해당하는 배포가 있을 때만 다음 칩이 나옵니다.

칩세는 대상
비정상: N사용할 수 없는 파드가 있는 배포
일시 중지됨: N롤아웃을 일시 중지한 배포
스케일다운: N복제본 수가 0 인 배포
Request/Limit 미설정: N요청량·상한을 하나도 정하지 않은 파드가 있는 배포
Limit 미설정: N요청량은 있지만 상한이 없는 파드가 있는 배포

칩을 누르면 해당하는 배포만 남습니다(1.2 장).

2/3 가 몇 분 넘게 유지되면 파드 목록에서 준비되지 않은 파드를 찾아 이벤트를 확인하십시오 (3.1 장).

Deployment 만들기 — 가이드 편집​

목록 제목 옆의 + 를 누르면 탭이 네 개 있는 창이 열립니다.

Deployment 만들기 — 가이드 편집
탭설명언제 씁니다
가이드 편집배포 전용 입력 서식기본값. 대부분 이것으로 충분합니다
YAML 편집설정을 YAML 로 직접 입력다른 배포를 복사해 올 때
폼 편집모든 항목을 자동 생성된 서식으로가이드 편집에 없는 항목이 필요할 때
API 문서각 항목의 설명항목의 뜻이 궁금할 때

창 오른쪽 위의 템플릿 을 고르면 미리 만들어 둔 정의(예: Nginx 웹서버 Deployment)를 불러옵니다. 비워 두면 빈 서식에서 시작합니다.

이름만 채우면 따라오는 값​

이름을 입력하면 라벨·선택 조건·컨테이너 이름이 함께 채워집니다. Deployment 는 같은 이름을 다섯 군데에 적어야 하고, 그중 선택 조건과 파드 라벨이 어긋나면 저장이 거부됩니다. 직접 고친 값은 그대로 두므로, 필요하면 각 항목을 따로 바꿀 수 있습니다.

이미지는 따라오지 않습니다. 배포할 이미지는 레지스트리에 이미 올라간 것 중에서 고르는 값이라, 이름에서 만들어 낸 주소를 넣으면 대개 없는 이미지를 가리키게 됩니다. 아래 "이미지는 목록에서 고릅니다" 를 보십시오.

반대로 이미지를 먼저 고르면 이름이 채워집니다. 이름 칸이 비어 있을 때 고른 이미지의 이름을 넣습니다. 예를 들어 apps 프로젝트의 sample-app 을 고르면 이름이 sample-app 이 되고, 라벨·선택 조건·컨테이너 이름도 함께 따라옵니다. 이름을 직접 적어 두었으면 바꾸지 않습니다.

이미지 이름에는 배포 이름에 쓸 수 없는 문자(.·_)가 들어갈 수 있습니다. 그런 문자는 - 로 바꾸고 63자까지만 넣습니다. 마음에 들지 않으면 이름 칸에서 고치십시오.

가이드 편집 입력 항목​

항목설명예시
이름배포 이름. 네임스페이스 안에서 겹치지 않아야 합니다sample-app
네임스페이스배포할 곳egov
복제유지할 파드 개수. 비우면 12
이미지 지정 방식내부 레지스트리에서 선택 / 외부 레지스트리의 이미지 이름내부 레지스트리에서 선택
프로젝트 · 이미지 · 태그내부 레지스트리에서 고를 때apps / sample-app / master-3b7ede8-2
이미지 풀 정책이미지를 언제 다시 받을지Always
이미지 풀 시크릿레지스트리 접속 정보. 이미지 목록을 읽을 때도 씁니다default-registry-secret
포트컨테이너가 열어 두는 포트. Service 가 이 포트를 가리킵니다8080
환경 변수컨테이너에 전달할 값SPRING_PROFILES_ACTIVE
클러스터 기본 정책아래 "보안 설정" 참고켬

컨테이너 이름은 따로 적지 않습니다. 이름 칸에서 자동으로 따라옵니다.

고급 옵션 을 펼치면 요청·제한 자원(100m / 128Mi 등)과 노드 선택 조건을 지정할 수 있습니다. 비워 두면 요청도 상한도 없습니다.

창 아래의 Service도 같이 만들기 를 켜면 Service 가 함께 만들어집니다. 포트 칸에 적은 포트를 대상으로 하는 Service 라, 배포한 애플리케이션을 바로 클러스터 안에서 부를 수 있습니다. 기본은 꺼짐입니다.

시크릿에서 받는 환경 변수​

환경 변수 중에는 값을 직접 적지 않고 다른 곳에서 가져오는 것이 있습니다. 비밀번호를 시크릿에 두고 이름만 가리키는 방식이 대표적입니다.

그런 항목은 값 칸이 잠기고 어디서 가져오는지 표시됩니다.

이름 CLICKHOUSE_PASSWORD 값 시크릿 · openmaru-observ-clickhouse · admin-password
표시뜻
시크릿 · 이름 · 키시크릿에서 가져옵니다
구성 맵 · 이름 · 키구성 맵에서 가져옵니다
Pod 필드 · 경로파드 이름·네임스페이스·파드 주소처럼 실행할 때 정해지는 값입니다
컨테이너 리소스 · …컨테이너에 정한 CPU·메모리 한도 값입니다

값을 직접 적어 덮어쓸 수 없게 막아 둔 것입니다. 여기에 값을 적으면 원래의 참조가 사라지고, 비밀번호를 적었다면 그 값이 배포 정의에 그대로 남습니다. 배포 정의는 시크릿보다 많은 사람이 볼 수 있으므로 시크릿에 둔 의미가 없어집니다.

바꾸려면 그 줄을 지우고 다시 넣거나, YAML 편집 탭에서 고치십시오.

이름 칸은 그대로 고칠 수 있습니다. 참조는 값에 붙는 것이라 이름을 바꿔도 따라옵니다.

시크릿이나 구성 맵을 통째로 환경 변수로 받는 배포도 있습니다. 그런 항목은 이 목록에 나오지 않고 그대로 유지되며, 항목 설명에 개수만 알려 줍니다.

컨테이너가 여러 개인 배포​

가이드 편집은 첫 번째 컨테이너만 다룹니다. 컨테이너가 둘 이상인 배포를 열면 "이 배포에는 컨테이너가 N개 있습니다. 여기서는 첫 번째만 편집합니다" 라는 안내가 컨테이너 항목에 나옵니다.

로그 수집기나 프록시 같은 곁다리 컨테이너를 추가하거나 고치려면 YAML 편집 탭을 쓰십시오.

보안 설정만은 파드 전체에 함께 적용됩니다. 클러스터 정책은 컨테이너 하나만 어겨도 파드 전체를 거부하므로, 이 설정은 모든 컨테이너에 같이 반영됩니다.

이미지는 목록에서 고릅니다​

이미지를 지정하는 방법이 두 가지입니다.

방법언제 씁니다
내부 레지스트리에서 선택사내 레지스트리에 이미 올라간 이미지를 배포할 때. 기본값입니다
외부 레지스트리의 이미지 이름사내 레지스트리 밖의 이미지를 쓸 때. 주소를 포함한 전체 이름을 적습니다

내부 레지스트리에서 선택 을 고르면 칸이 세 개로 나뉩니다.

칸고르는 것예시
프로젝트레지스트리 안의 묶음apps
이미지그 프로젝트에 올라간 이미지sample-app
태그그 이미지의 버전master-3b7ede8-2

앞 칸을 골라야 다음 칸의 목록이 나옵니다. 프로젝트를 고르면 그 프로젝트의 이미지 목록을, 이미지를 고르면 그 이미지의 태그 목록을 레지스트리에서 읽어 옵니다. 앞 칸을 바꾸면 뒤 칸은 비워집니다.

태그 목록은 최근에 올린 태그부터 나옵니다. 태그 옆에는 레지스트리에 올린 시각이 시간대와 함께 나옵니다(예: 2026-10-06 22:57 (UTC+9)). 시각은 설정의 날짜 표시용 시간대 를 따릅니다(9.4 장).

태그는 목록에 없는 값도 적을 수 있습니다. 아직 올리지 않은 태그로 배포를 미리 만들어 두는 경우에 씁니다. 비워 두면 latest 로 받아오는데, 폐쇄망에서는 latest 태그가 없는 경우가 많으므로 되도록 지정하십시오.

태그까지 고르면 포트가 자동으로 채워집니다. 그 이미지가 열어 두도록 만들어진 포트를 레지스트리에서 읽어 첫 번째 컨테이너의 포트 칸에 넣습니다. 예를 들어 Java 애플리케이션 이미지는 보통 8080·8443·8778 이 들어갑니다. 직접 고친 포트는 태그를 바꿔도 그대로 둡니다.

목록을 읽지 못하면 그 이유가 칸 아래에 나옵니다. 이때도 외부 레지스트리의 이미지 이름 을 골라 전체 주소를 직접 적으면 배포를 만들 수 있습니다.

보안 설정 — 클러스터 기본 정책​

보안 항목의 클러스터 기본 정책 스위치는 켜진 채로 시작합니다. 이 클러스터는 라벨이 없는 네임스페이스에 Pod Security Admission restricted 가 적용되므로, 끄고 저장하면 배포는 만들어지지만 파드가 뜨지 않습니다.

켜 두려면 컨테이너 이미지가 root 가 아닌 사용자(USER)로 만들어져 있어야 합니다. 공개 이미지 중에는 root 로 도는 것이 있으므로(예: nginx 공식 이미지), 그런 경우 nginxinc/nginx-unprivileged 처럼 root 가 아닌 이미지를 쓰는 것이 먼저입니다.

정말 root 로 실행해야 한다면 스위치를 끕니다. 끄면 화면에 경고가 나오며, 그 배포를 두는 네임스페이스에 pod-security.kubernetes.io/enforce 라벨을 baseline 또는 privileged 로 붙여야 파드가 뜹니다. 운영 담당자에게 확인하십시오.

이 폼이 다루지 않는 보안 설정이 이미 들어 있는 배포에서는 스위치가 잠기고, 그 이유가 아래에 표시됩니다. 그런 배포는 YAML 편집 탭에서 수정하십시오.

Deployment 상세​

이름을 누르면 상세 화면이 열립니다.

Deployment 상세
구역무엇을 알 수 있는가
메타데이터이름, 네임스페이스, 라벨, 주석
전략새 버전으로 바꾸는 방식
선택기(Selector)어떤 라벨의 파드를 자기 것으로 보는지
컨테이너이미지, 태그, 환경 변수, 요청·제한 자원
조건배포 진행 상태
관련 자원만들어진 ReplicaSet 과 파드

컨테이너 이미지의 태그를 확인하십시오. 배포한 버전이 실제로 반영되었는지 여기서 봅니다.

선택 조건은 만든 뒤 바꿀 수 없습니다. 이 값으로 자기 파드를 찾기 때문에, 바꾸면 기존 파드와의 연결이 끊어집니다.

조건 에서 배포 상태를 읽습니다.

화면에는 조건마다 뱃지가 하나씩 나옵니다. 조건이 만족되면 초록, 아니면 빨강입니다.

조건정상일 때 뱃지아닐 때 뱃지아닐 때의 뜻
Available사용 가능사용할 수 없음준비된 파드가 모자랍니다
Progressing진행 중진행 중 아님배포가 멈췄습니다. 사유를 확인합니다

진행 중 뱃지에 마우스를 올리면 사유가 나옵니다. 배포가 정상으로 끝났으면 NewReplicaSetAvailable 입니다.

배포가 일정 시간(기본 10분) 안에 끝나지 않으면 ProgressDeadlineExceeded 로 바뀝니다. 새 파드가 뜨지 못하고 있다는 뜻이므로 파드 이벤트를 보십시오.

새 파드가 Running 인데 배포가 안 끝나면 준비 상태 검사를 확인하십시오. 롤링 업데이트는 새 파드가 준비 상태가 되어야 다음 파드를 교체합니다. 검사가 계속 실패하면 첫 파드에서 멈춘 채 진행되지 않습니다(3.1 장).

편집 버튼과 ⋯ 메뉴​

자주 고치는 값은 YAML 을 몰라도 창에서 고칩니다. 배포·상태 저장 세트·데몬 세트 상세 화면의 구역 제목 오른쪽에 편집 버튼이 있습니다. 아이콘에 마우스를 올리면 버튼 이름이 보입니다.

자리버튼
메타데이터 제목 오른쪽라벨·주석 편집(태그 아이콘)
컨테이너 사양 제목 오른쪽상태 검사 편집(심장 박동 아이콘), 리소스 제한 편집(계기판 아이콘), 환경 변수 편집

같은 동작은 상세 화면 머리 맨 오른쪽의 ⋯(작업 더 보기) 메뉴와 목록 행 오른쪽의 ⋯ 메뉴, 토폴로지 카드의 우클릭 메뉴(2.2 장)에도 있습니다. 메뉴에는 Pod 수 편집 과, 이 배포로 배포하는 빌드 설정이 있으면 빌드 설정 편집 도 나옵니다.

  • 권한이 있는 버튼과 항목만 보입니다.
  • 바꾼 항목만 저장합니다. 창을 연 뒤 다른 사람이 같은 항목을 바꾸었으면 저장하지 않고 그 항목의 열 때 값과 지금 값을 보여 줍니다. 최신 값으로 새로고침 을 누르면 그 항목만 최신 값으로 바뀌고, 입력한 다른 값은 그대로 남습니다.
  • Helm 이나 Argo CD 가 관리하는 워크로드는 창에 안내가 나옵니다. 다음 업그레이드나 동기화 때 원래 값으로 돌아갈 수 있으니 설정 저장소나 Helm 값에도 같은 값을 반영하십시오.

상태 검사 편집​

컨테이너가 정상인지 확인하는 검사(프로브)는 YAML 편집 없이 팝업에서 고칠 수 있습니다. Deployment·StatefulSet·DaemonSet 상세 화면의 컨테이너 사양 제목 오른쪽에서 상태 검사 편집 (심장 박동 아이콘) 버튼을 누릅니다. 바로 오른쪽의 계기판 아이콘은 리소스 제한 편집, 그다음은 환경 변수 편집 입니다.

검사확인하는 것실패하면
Readiness 프로브컨테이너가 요청을 처리할 준비가 되었는지실행 중이어도 트래픽을 받지 않습니다
Liveness 프로브컨테이너가 실행 중인지컨테이너가 종료됩니다
Startup 프로브컨테이너 안의 애플리케이션이 시작되었는지컨테이너가 종료됩니다

세 검사는 모두 선택 사항입니다. 없는 검사는 ○○ 프로브 추가 를 눌러 만들고, 프로브 제거 로 없앱니다. 컨테이너가 둘 이상이면 위쪽 탭으로 컨테이너를 고르고, 적용 을 한 번 누르면 모든 컨테이너가 함께 저장됩니다.

항목설명
유형HTTP GET · 컨테이너 명령 · TCP 소켓
포트HTTP GET · TCP 소켓에서 필수. 번호 또는 컨테이너 포트 이름
실패 임계 값 · 성공 임계 값실패·성공으로 판단하기까지의 연속 횟수. Liveness·Startup 의 성공 임계 값은 1 만 허용됩니다
초기 지연 · 기간 · 시간 제한초 단위. 칸을 비우면 쿠버네티스 기본값(0 · 10 · 1초)이 적용됩니다

시간 제한 기본값 1초는 응답이 느린 애플리케이션에서 정상 컨테이너도 종료시킬 수 있습니다. 기존 검사를 열면 이미 1 이 들어 있을 수 있으니, 애플리케이션의 응답 시간에 맞게 늘리십시오.

적용하면 파드가 순서대로 교체됩니다. 롤아웃이 일시 중지된 Deployment 는 재개할 때 반영되고, 업데이트 방식이 OnDelete 인 StatefulSet·DaemonSet 은 파드를 삭제해야 반영됩니다.

팝업을 연 뒤 다른 사용자가 같은 컨테이너의 검사를 바꿨으면 저장하지 않고 "다른 곳에서 상태 검사가 변경되었습니다" 를 표시합니다. 팝업을 닫고 다시 열어 최신 값을 확인한 뒤 고치십시오. 이미지·환경 변수 등 검사가 아닌 설정이 바뀐 경우에는 그대로 저장됩니다.

gRPC 유형 검사는 팝업에서 고칠 수 없습니다. 안내 문구만 표시되며 YAML 편집에서 수정합니다.

ArgoCD 나 Helm 으로 관리하는 워크로드는 콘솔에서 바꾼 검사가 다음 동기화나 업그레이드 때 원래 값으로 돌아갈 수 있습니다. 설정 저장소나 Helm 값에도 같은 값을 반영하십시오(4.7 장).

리소스 제한 편집​

컨테이너의 CPU·메모리 요청과 제한은 컨테이너 사양 제목 오른쪽의 리소스 제한 편집(계기판 아이콘) 버튼으로 고칩니다. 컨테이너마다 CPU 요청·제한, 메모리 요청·제한 네 칸이 있고, 적용 을 누르면 바꾼 값만 저장됩니다. 바꾼 것이 없으면 적용 이 비활성화됩니다.

항목설명
CPU 단위millicores(m) · cores. 1 cores = 1000 m
메모리 단위MiB · GiB. YAML 에서 512M 처럼 다른 단위로 넣은 값은 그 단위가 목록에 추가되어 그대로 보입니다
빈 칸그 값을 지웁니다
  • 제한은 요청보다 작을 수 없습니다. 입력 중에 해당 칸에 안내가 나오고 적용 이 비활성화됩니다.
  • 요청을 지워도 제한이 있으면, 새로 만들어지는 파드의 요청은 제한과 같은 값이 됩니다(쿠버네티스 기본 동작).
  • 저장한 값은 쿠버네티스 표준 표기로 바뀌어, 다시 열면 단위가 달라 보일 수 있습니다(예: 1.5 cores → 1500 m).
  • 팝업에서 정확히 읽을 수 없는 값(예: 1e3)은 그 칸만 잠기고 "이 값은 YAML 편집에서 수정합니다" 가 표시됩니다. 다른 칸은 고칠 수 있으며, 잠긴 값은 저장할 때 바뀌지 않습니다.
  • GPU·임시 스토리지처럼 팝업에 없는 리소스 설정은 저장해도 바뀌지 않습니다.

팝업을 연 뒤 다른 사용자가 같은 컨테이너의 CPU·메모리 값을 바꿨으면 저장하지 않고 "다른 곳에서 리소스 제한이 변경되었습니다" 를 표시합니다. 팝업을 닫고 다시 열어 최신 값을 확인한 뒤 고치십시오. 이미지·환경 변수 등 리소스가 아닌 설정이 바뀐 경우에는 그대로 저장됩니다.

적용하면 파드가 순서대로 교체됩니다. ArgoCD·Helm 으로 관리하는 워크로드는 상태 검사와 마찬가지로 다음 동기화 때 원래 값으로 돌아갈 수 있습니다.

라벨·주석 편집​

라벨과 주석을 표에서 한 줄씩 고칩니다. YAML 들여쓰기를 신경 쓰지 않아도 되고, OPENMARU APM·OpenTelemetry 자동 계측도 같은 창에서 켭니다.

  1. 메타데이터 제목 오른쪽의 라벨·주석 편집(태그 아이콘)을 누릅니다.
  2. 라벨·주석·자동 계측 탭 중 하나를 고릅니다.
  3. 줄마다 키 와 값 을 넣습니다. 줄을 더하려면 라벨 추가·주석 추가 를 누르고, 지우려면 줄 끝의 삭제 버튼을 누릅니다.
  4. 적용 을 누릅니다. 버튼의 숫자는 고친 칸 수입니다.
라벨·주석 편집

라벨·주석 탭은 위아래 두 구역으로 나뉩니다. 어느 구역을 고치느냐에 따라 Pod 가 교체되는지가 다릅니다.

구역붙는 곳적용하면
위 (예: 배포 라벨)워크로드 자체Pod 는 그대로입니다
아래 (Pod 라벨·Pod 주석)모든 PodPod 가 교체됩니다

자동 계측 탭 에서는 애플리케이션 코드를 고치지 않고 모니터링 에이전트를 넣습니다.

구역고를 것
OPENMARU APM계측 사용 을 켜고, 에이전트를 넣을 컨테이너·버전·이미지 풀 정책 을 고릅니다. 비워 두면 설치 기본값을 씁니다
OpenTelemetry언어(Java·Node.js·Python·.NET)와 컨테이너 를 고릅니다
자동 계측 탭
  • 각 칸 아래의 Pod 템플릿에 쓰는 키 에서 실제로 저장될 키와 값을 미리 볼 수 있습니다.
  • 자동 계측은 해당 오퍼레이터(OPENMARU APM 오퍼레이터, OpenTelemetry 오퍼레이터)가 설치된 클러스터에서 동작합니다. 설정에 문제가 있으면 탭 이름 옆에 경고 아이콘이 붙고 창에 이유가 나옵니다.
  • 선택기에 쓰이는 라벨처럼 바꾸면 안 되는 키는 잠겨 있습니다. 마우스를 올리면 이유가 나옵니다.

환경 변수 편집​

환경 변수를 컨테이너별로 고칩니다. 값을 직접 적거나, 시크릿·구성 맵의 키를 목록에서 골라 연결합니다.

  1. 컨테이너 사양 제목 오른쪽의 환경 변수 편집 을 누릅니다. 컨테이너가 여럿이면 위쪽 탭에서 컨테이너를 고릅니다.
  2. 단일 값 (env) 구역에서 줄마다 이름 과 소스 를 정하고 값을 넣습니다.
  3. 구성 맵이나 시크릿의 값을 한꺼번에 받으려면 기존 구성 맵 또는 시크릿에서 모든 값 (envFrom) 구역을 펼쳐 종류와 이름을 고릅니다. 필요하면 접두사 (선택 사항) 를 넣습니다.
  4. 적용 을 누릅니다.
환경 변수 편집
소스값 넣는 법
값값을 직접 적습니다
시크릿이 네임스페이스의 시크릿과 키를 고릅니다. 비밀 값은 화면에 보이지 않습니다
구성 맵이 네임스페이스의 구성 맵과 키를 고릅니다
  • 값에 $(이름) 을 쓰면 위쪽 줄의 변수를 가져다 씁니다. 아래쪽 줄의 변수는 쓸 수 없으니 줄 순서를 확인하십시오.
  • 환경 변수는 Pod 안에서 쓰는 값이라 적용하면 Pod 가 교체됩니다.

배포 방식 — Deployment 설정​

전략동작언제 씁니다
RollingUpdate새 파드를 하나씩 띄우고 옛 파드를 하나씩 내립니다기본값. 서비스가 끊기지 않습니다
Recreate옛 파드를 모두 내린 뒤 새 파드를 띄웁니다두 버전이 동시에 뜨면 안 될 때

Recreate 는 서비스가 잠시 멈춥니다. 데이터베이스 스키마가 바뀌어 옛 버전과 새 버전이 공존할 수 없는 경우에만 씁니다.

RollingUpdate 에는 조절 값이 두 개 있습니다.

값뜻기본값
maxSurge원하는 수보다 몇 개까지 더 띄워도 되는지25%
maxUnavailable동시에 몇 개까지 없어도 되는지25%

maxUnavailable: 0 으로 두면 배포 중에도 정상 파드 수가 유지됩니다. 대신 자원이 잠시 더 필요합니다.

설정은 이렇게 적습니다.

apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
namespace: my-app
spec:
replicas: 4
revisionHistoryLimit: 10 # 되돌릴 수 있는 이력 개수
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1 # 개수 또는 비율("25%")
maxUnavailable: 0 # 배포 중에도 4개를 유지합니다
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app # selector 와 같아야 합니다
annotations:
kubernetes.io/change-cause: "1.2.0 - 로그인 오류 수정"
spec:
containers:
- name: app
image: registry.example.com/my-app:1.2.0
항목설명
maxSurge원하는 수보다 더 띄울 수 있는 개수. 0 이면 자원을 더 쓰지 않지만 배포가 느립니다
maxUnavailable동시에 없어도 되는 개수. 0 이면 서비스 대수가 줄지 않습니다
revisionHistoryLimit남길 이력 개수. 이 수를 넘으면 오래된 것부터 지워지고 그 리비전으로는 되돌릴 수 없습니다
change-cause 주석배포 이력의 변경 사유 열에 표시됩니다

maxSurge 와 maxUnavailable 을 둘 다 0 으로 둘 수는 없습니다. 새로 띄울 수도, 내릴 수도 없어 배포가 진행되지 않습니다. 적용할 때 거부됩니다.

change-cause 를 넣어 두십시오. 넣지 않으면 배포 이력의 변경 사유가 <none> 으로 남아, 되돌릴 리비전을 고를 때 이미지 태그와 시각만으로 판단해야 합니다.

Recreate 는 조절 값이 없습니다.

strategy:
type: Recreate

블루그린·카나리처럼 Service 를 함께 다루는 배포 방식은 4.8 장에서 다룹니다. 이 절의 strategy 는 Deployment 하나 안에서 끝나는 설정입니다.

StatefulSet 이란​

파드마다 고유한 정체성과 저장 공간이 필요한 애플리케이션 을 관리하는 컨트롤러입니다.

Deployment 의 파드는 서로 구별되지 않습니다. 이름 뒤에 무작위 문자열이 붙고, 다시 만들어지면 이름이 달라집니다. 저장 공간도 공유하거나 없습니다.

StatefulSet 은 다릅니다.

특징DeploymentStatefulSet
파드 이름무작위 (web-7d4f-x8k2)순번 (db-0, db-1, db-2)
만드는 순서동시에0번부터 차례로
지우는 순서동시에마지막 번호부터 거꾸로
저장 공간공유하거나 없음파드마다 하나씩 고정
네트워크 이름없음파드마다 고정된 이름

핵심은 "다시 만들어도 같은 것" 이라는 점입니다. db-0 이 종료됐다가 다시 떠도 이름이 db-0 이고, 이전에 쓰던 저장 공간에 그대로 다시 연결됩니다. 데이터가 유지됩니다.

StatefulSet 을 쓰는 경우​

상황이유
데이터베이스 (MySQL, PostgreSQL)각 인스턴스가 자기 데이터 파일을 가집니다
메시지 큐 (Kafka)파티션이 특정 인스턴스에 할당되어 있습니다
분산 저장소 (Elasticsearch)노드마다 담당 데이터가 다릅니다
클러스터 구성원이 서로를 이름으로 찾아야 할 때고정된 네트워크 이름이 필요합니다

순서대로 만드는 것이 왜 중요한가. 데이터베이스 클러스터는 보통 첫 번째 인스턴스가 먼저 떠서 초기화한 뒤, 나머지가 거기에 합류합니다. 동시에 뜨면 서로 상대를 못 찾아 실패합니다.

순서대로 지우는 것도 중요합니다. 마지막 번호부터 빼야 남은 구성원끼리 정족수를 유지할 수 있습니다.

워크로드 > 상태저장 세트 에서 봅니다. 화면 구성은 Deployment 와 같습니다.

StatefulSet 만들기 — 가이드 편집​

목록 제목 옆의 + 를 누르면 Deployment 와 같은 가이드 편집 서식 이 열립니다. 컨테이너 · 이미지 · 포트 · 환경 변수 · 보안 설정은 앞의 "Deployment 만들기 — 가이드 편집" 과 같으므로 그쪽을 보십시오. 다른 것은 서비스 이름 한 칸뿐입니다.

항목DeploymentStatefulSet
복제있음있음
서비스 이름없음있음 (비우면 워크로드 이름이 들어갑니다)

서비스 이름​

이 StatefulSet 의 파드들을 가리킬 Service 의 이름 입니다. 이 이름으로 파드마다 고정된 네트워크 이름이 생깁니다.

db-0.db-svc.egov.svc.cluster.local
└ 서비스 이름 칸에 적은 값

비워 두면 워크로드 이름이 그대로 들어갑니다. 이름 칸에 db 를 치면 서비스 이름도 db 가 됩니다. 직접 고치면 고친 값을 쓰고, 그 뒤에 이름을 바꿔도 덮어쓰지 않습니다.

이름과 다르게 지을 이유는 대개 없습니다. 관례상 같게 둡니다.

서비스 이름은 만든 뒤에 바꿀 수 없습니다. 수정 화면에서는 이름 · 네임스페이스와 함께 이 칸이 잠깁니다.

헤드리스 Service 가 함께 만들어집니다​

StatefulSet 을 만들면 서비스 이름과 같은 이름의 헤드리스(Headless) Service 가 함께 만들어집니다. 창 아래의 Service도 같이 만들기 가 StatefulSet 에서는 기본으로 켜져 있습니다.

따로 만들지 않아도 되는 이유가 있습니다. 그 Service 가 없으면 파드별 고정 이름이 만들어지지 않는데, StatefulSet 자체는 정상으로 뜹니다. 무엇이 빠졌는지 화면에 드러나지 않아 나중에 파드끼리 연결이 안 될 때에야 알게 됩니다.

만들어지는 Service 는 이렇습니다.

항목값
이름서비스 이름 칸의 값
유형헤드리스 (clusterIP: None)
선택 조건StatefulSet 의 파드 라벨
포트컨테이너 포트

필요 없으면 토글을 끄십시오. 나중에 일반 Service 로 바꾸려면 지우고 다시 만들어야 합니다 — 헤드리스 여부는 만든 뒤에 바꿀 수 없습니다(5.1 장).

헤드리스여야만 하는 것은 아닙니다. 파드끼리 서로를 찾아야 할 때(데이터베이스 복제, Kafka)만 필수입니다. 그 경우가 StatefulSet 을 쓰는 대표적인 이유라 기본값으로 둡니다.

DaemonSet 이란​

모든 노드에 파드를 하나씩 띄우는 컨트롤러입니다. 복제본 수를 정하지 않고, 노드 수만큼 자동으로 맞춥니다.

상황동작
새 노드를 클러스터에 추가그 노드에도 파드가 자동으로 생깁니다
노드를 클러스터에서 제거그 노드의 파드가 사라집니다

노드마다 하나씩 있어야 하는 것에 씁니다.

쓰임예
로그 수집각 노드의 컨테이너 로그를 모아 보냅니다
지표 수집노드의 CPU·메모리를 재서 보냅니다
네트워크노드 사이 통신을 담당합니다
저장소노드의 디스크를 파드에 제공합니다

워크로드 > 데몬 세트 에서 봅니다. 원하는 수 는 보통 노드 수와 같습니다.

목록의 + 로 만들 때도 Deployment 와 같은 가이드 편집 서식 이 열립니다. 다른 것은 복제 칸이 없다 는 점뿐입니다 — 파드 수를 사람이 정하지 않고 노드 수가 정하기 때문입니다.

수가 노드 수보다 적으면 일부 노드에 배치되지 못한 것입니다. 테인트가 걸린 노드는 허용 오차가 없으면 제외되므로(2.1 장), 관리 노드가 빠져 있는 것은 정상일 수 있습니다.

ReplicaSet 이란​

정해진 개수의 파드를 유지 하는 컨트롤러입니다. 개수 유지만 하고 버전 관리나 무중단 교체 기능은 없습니다.

직접 만들지 않습니다. Deployment 가 내부적으로 만들어 씁니다. 목록에 나오는 것은 배포 이력이므로 지우지 마십시오.

워크로드 > 복제 세트 에서 봅니다.

상태뜻
복제본이 0 이 아님지금 쓰이는 버전
복제본이 0이전 버전. 되돌리기에 쓰입니다

어떤 컨트롤러를 고를 것인가​

질문예아니오
파드마다 다른 데이터를 저장해야 하나?StatefulSet다음 질문으로
모든 노드에 하나씩 있어야 하나?DaemonSet다음 질문으로
한 번 실행하고 끝나는 작업인가?Job·CronJob (3.3 장)Deployment

대부분의 애플리케이션은 Deployment 로 충분합니다.

복제본 수 조절​

상세 화면 오른쪽 위의 조절 버튼을 누릅니다.

  1. 조절 버튼을 누릅니다.
  2. 원하는 복제본 수를 넣습니다.
  3. 저장하면 곧바로 반영됩니다.

목록 행이나 상세 화면 머리의 ⋯ 메뉴에서는 Pod 수 편집 을 누릅니다.

부하에 따라 자동으로 조절하려면 오토스케일링을 씁니다(3.5 장).

자동 조절을 설정한 자원의 복제본 수를 손으로 바꾸면 곧 자동 설정값으로 되돌아갑니다.

재시작​

상세 화면 오른쪽 위의 재시작 버튼을 누르면 설정을 바꾸지 않고 파드만 새로 띄웁니다. 목록에서는 행 오른쪽 ⋯ 메뉴의 재시작 을 씁니다. 누르면 확인 창이 열립니다.

ConfigMap 이나 Secret 을 고친 뒤 값을 반영할 때 씁니다. 환경 변수로 주입한 값은 파드를 새로 띄워야 바뀌기 때문입니다(3.4 장).

재시작은 롤링 업데이트로 진행되므로 서비스가 끊기지 않습니다. 파드를 하나씩 지우는 것과 결과는 같지만 순서가 통제됩니다.

동작 원리는 이렇습니다. Console 이 파드 템플릿에 "다시 시작한 시각" 주석을 넣습니다. 템플릿이 바뀌었으므로 Kubernetes 가 새 버전 배포로 보고 롤링 업데이트를 시작합니다. 이미지나 설정은 그대로입니다.

롤아웃이 일시 중지된 Deployment 를 재시작하면 일시 중지도 함께 풀립니다. 일시 중지 중에 수정한 설정도 이때 함께 반영됩니다. 확인 창에 이 내용이 표시됩니다. 목록에서 여러 배포를 골라 재시작해도 같습니다.

롤아웃 일시 중지와 재개​

Deployment 상세 화면 오른쪽 위, 또는 배포 목록의 행 오른쪽 ⋯ 메뉴에서 롤아웃 일시 중지 와 롤아웃 재개 를 누릅니다. 일시 중지 중에는 같은 자리의 버튼이 롤아웃 재개 로 바뀝니다.

설정을 여러 번 나눠 고칠 때 씁니다. 평소에는 이미지·환경 변수·자원 값을 고쳐 저장할 때마다 파드가 교체됩니다. 세 군데를 고치면 교체도 세 번 일어납니다. 일시 중지해 두면 고친 내용이 쌓이기만 하고, 재개하거나 재시작할 때 한 번에 반영됩니다.

버튼결과확인 창
롤아웃 일시 중지이후 설정을 바꿔도 파드를 교체하지 않습니다없음
롤아웃 재개일시 중지 중에 고친 설정을 반영합니다. 일시 중지 전에 진행 중이던 롤아웃이 있으면 이어서 진행합니다. 둘 다 없으면 파드가 교체되지 않습니다파드가 교체될 때, 또는 교체 여부를 확인하지 못했을 때만
재시작고친 것이 없어도 파드를 교체합니다. 일시 중지도 함께 풀립니다항상

일시 중지 중에는 다음 자리에 표시가 나옵니다.

자리표시
상세 화면 정보롤아웃: 일시 중지됨
배포 목록의 상태 칸일시 중지됨
목록 위쪽 요약일시 중지됨: N. 누르면 일시 중지된 배포만 남습니다
  • 롤아웃 일시 중지는 Deployment 에서만 쓸 수 있습니다. StatefulSet·DaemonSet 에는 Kubernetes 가 해당 설정(spec.paused)을 제공하지 않습니다.
  • 일시 중지 중에도 복제본 수 변경은 바로 반영됩니다. 멈추는 것은 설정 변경에 따른 파드 교체뿐입니다.
  • 상태 검사 편집·리소스 제한 편집으로 바꾼 값도 재개할 때 반영됩니다.

일시 중지를 잊고 두면 이후의 설정 변경이 모두 반영되지 않습니다. 수정을 마쳤으면 재개하거나 재시작하십시오.

배포 이력 보기​

상세 화면 오른쪽 위의 시계 모양 아이콘(배포 히스토리)을 누르면 그동안의 배포 기록이 나옵니다.

지원 대상은 세 가지입니다.

자원이력 보기롤백
Deployment가능가능
DaemonSet가능가능
StatefulSet가능불가 (이력만 봅니다)

이력 표에는 이렇게 나옵니다.

열설명
리비전배포 순번. 숫자가 클수록 최근입니다
이름그 리비전을 담고 있는 ReplicaSet 이름
이미지그때 배포된 컨테이너 이미지와 태그
변경 사유배포할 때 남긴 설명. 없으면 <none>
생성 시각그 리비전이 만들어진 때
상태지금 쓰이는 리비전이면 현재 로 표시됩니다

이미지 태그를 보면 어느 버전인지 바로 압니다. 태그를 latest 로 고정해 쓰면 리비전마다 같은 값이 나와 구분할 수 없으니, 빌드할 때 태그를 다르게 두십시오(4.2 장).

변경 사유 는 배포할 때 kubernetes.io/change-cause 주석을 넣어야 채워집니다. 넣지 않으면 <none> 으로 남습니다. 무엇 때문에 배포했는지 남겨 두면 나중에 되돌릴 리비전을 고르기 쉽습니다.

롤백하는 방법​

새 버전을 배포했는데 문제가 생겼을 때 이전 상태로 되돌립니다.

  1. 되돌릴 자원(Deployment 또는 DaemonSet)의 상세 화면을 엽니다.
  2. 오른쪽 위의 시계 모양 아이콘 을 눌러 배포 히스토리를 엽니다.
배포 히스토리
  1. 돌아갈 리비전을 찾습니다. 이미지 태그와 생성 시각으로 확인합니다.
  2. 그 줄 오른쪽 작업 칸의 되돌리기 아이콘을 누릅니다.
  3. 롤링 업데이트가 시작됩니다. 잠시 뒤 이력이 갱신됩니다.

지금 쓰이는 리비전에는 되돌리기 아이콘이 없습니다. 위 그림에서 리비전 183 은 현재 표시와 활성 상태가 붙어 있고 작업 칸이 비어 있습니다. 이미 그 상태이므로 되돌릴 것이 없기 때문입니다. 나머지 줄은 비활성 이고 각각 되돌리기 아이콘을 갖습니다.

돌아갈 리비전은 이미지 태그와 생성 시각으로 고릅니다. 위 그림처럼 이미지 태그가 모두 같으면 리비전만으로는 무엇이 달라졌는지 알 수 없습니다. 이때는 생성 시각으로 "문제가 생기기 전 마지막 배포" 를 찾습니다. 변경 사유를 남겨 두었다면 그 값이 가장 확실한 단서입니다.

롤백하면 무엇이 되돌아가는가​

파드 템플릿 전체 가 그 리비전 상태로 돌아갑니다.

항목되돌아가는가
컨테이너 이미지와 태그예
환경 변수예
자원 요청·상한예
연결된 볼륨·ConfigMap·Secret 이름예
복제본 수아니오. 현재 값을 유지합니다
ConfigMap·Secret 의 내용아니오. 참조만 되돌아갑니다
데이터베이스 데이터아니오

복제본 수가 그대로인 것은 의도된 동작입니다. 롤백은 "어떤 버전을 띄울지" 를 되돌리는 것이지 "몇 개를 띄울지" 를 되돌리는 것이 아닙니다.

ConfigMap 내용은 되돌아가지 않습니다. 설정값을 고친 것이 문제였다면 롤백만으로는 해결되지 않습니다. ConfigMap 도 함께 되돌려야 합니다(3.4 장).

롤백 뒤에 확인할 것​

확인어디에서
파드가 새로 떠서 준비 상태가 되었는가워크로드 > Pod (3.1 장)
이미지 태그가 의도한 것인가Deployment 상세의 컨테이너
이력에서 리비전이 늘었는가배포 히스토리

롤백해도 리비전 번호는 앞으로 나아갑니다. 리비전 5에서 3으로 되돌리면 내용은 3과 같은 리비전 6이 만들어집니다. 되돌린 것도 하나의 배포로 기록되기 때문입니다.

롤백이 안 될 때​

증상원인조치
되돌릴 리비전이 목록에 없음보관 개수를 넘어 지워졌습니다아래 "이력 보관 개수" 참고
롤백했는데 파드가 안 뜸그때 쓰던 이미지가 레지스트리에서 지워졌습니다이미지를 다시 올리거나 재빌드
롤백했는데 증상이 그대로원인이 애플리케이션이 아니라 설정·데이터에 있습니다ConfigMap·Secret·외부 연동 확인
StatefulSet 에 롤백 버튼이 없음지원하지 않습니다아래 참고

StatefulSet 은 이력만 보고 롤백할 수 없습니다. 파드마다 저장 공간이 연결되어 있어 버전을 되돌려도 데이터는 그대로이고, 옛 버전이 새 형식의 데이터를 읽지 못할 수 있기 때문입니다. 되돌려야 하면 편집에서 이미지 태그를 직접 이전 값으로 고치고, 데이터 호환성을 먼저 확인하십시오.

이력 보관 개수​

Deployment 상세의 리비전 히스토리 제한 값만큼 이력이 남습니다. 기본은 10입니다.

이 수를 넘으면 오래된 리비전부터 지워지고, 지워진 리비전으로는 롤백할 수 없습니다. 배포가 잦은 애플리케이션이라면 값을 늘려 두십시오.

목록에서 복제본 0 인 ReplicaSet 을 지우지 마십시오. 그것이 이력입니다.