4.10. kubectl 플러그인으로 빌드·배포
어떨 때 쓰는가
- Console 에서 만든 빌드 설정을 명령 한 줄로 다시 빌드하고 싶을 때
- 빌드·배포를 자동화 스크립트나 CI 파이프라인에 넣을 때
- 여러 네임스페이스의 빌드 상태를 한 번에 확인할 때
kubectl cop 은 kubectl 플러그인 입니다. Console 의 빌드 메뉴에서 하던 일(빌드 설정
만들기, 빌드 시작, 로그 보기, 배포)을 명령줄에서 그대로 합니다.
Console 과 같은 자원을 씁니다. 명령으로 만든 빌드 설정은 Console 의 빌드 > 빌드 설정 목록에 그대로 나오고, Console 에서 만든 빌드 설정도 명령으로 빌드할 수 있습니다. 어느 쪽으로 시작해도 되고, 중간에 바꿔도 됩니다.
4.5 장의 Bastion 스크립트와는 다릅니다. 스크립트는 Bastion 에서 S2I 도구를 직접 실행하지만, 이 플러그인은 클러스터 안에서 빌드를 실행 합니다. Console 로 빌드했을 때와 같은 방식입니다.
화면과 명령의 대응
| Console | 명령 | 하는 일 |
|---|---|---|
| 빌드 설정 생성 폼 [적용] (4.2 장) | new-build | 빌드 설정과 파드 0개짜리 Deployment 를 만듭니다 |
| [빌드 시작] | start-build | 빌드 작업(Job)을 만듭니다 |
| [배포] | deploy | 성공한 빌드의 이미지로 배포합니다 |
| 위 셋을 차례로 | new-app | 설정 생성 · 빌드 · 배포를 한 번에 합니다 |
명령은 현재 kubeconfig 의 접속 정보와 권한을 그대로 씁니다. 별도 로그인 절차는 없고, kubeconfig 계정에 없는 권한은 명령으로도 쓸 수 없습니다(7.1 장).
설치 확인
COP 를 설치하면 Bastion 에 함께 설치됩니다. 두 명령으로 확인합니다.
kubectl plugin list
kubectl cop version
kubectl plugin list 에 kubectl-cop 이 나오고 kubectl cop version 이 버전을 출력하면 쓸 수
있습니다. 명령을 찾지 못한다고 나오면 설치 담당자에게 확인을 요청하십시오.
명령 형태
공식 형태는 kubectl cop <명령> 이고, cop 을 빼고 써도 같은 동작입니다.
kubectl cop start-build sample-app -n egov # 공식 형태
kubectl start-build sample-app -n egov # 짧은 형태, 같은 동작
이 장의 예시는 짧은 형태를 씁니다. cop 없이 쓸 수 있는 이름은 다음 열 가지입니다.
new-app · new-build · start-build · cancel-build · builds · buildconfigs · bc ·
builders · deploy · build-logs
두 이름은 kubectl 기본 명령과 겹칩니다. kubectl 은 자기 기본 명령을 플러그인보다 먼저 찾으므로, 로그와 버전은 아래 이름을 씁니다.
| 하려는 일 | 쓰는 명령 | 쓰면 안 되는 것 |
|---|---|---|
| 빌드 로그 보기 | kubectl build-logs 또는 kubectl cop logs | kubectl logs — kubectl 기본 명령이 실행됩니다 |
| 플러그인 버전 보기 | kubectl cop version | kubectl version — 클러스터 버전이 나옵니다 |
이 장의 예시는 4.1 장과 같은 egov 네임스페이스와 sample-app 빌드 설정을 씁니다.
네임스페이스는 모든 명령에서 -n 으로 지정합니다.
새로 만들기
빌드 설정을 만드는 명령은 두 가지입니다.
| 명령 | 하는 일 |
|---|---|
new-build | 빌드 설정만 만듭니다. 빌드는 시작하지 않습니다 |
new-app | 빌드 설정을 만들고, 로그를 보며 빌드한 뒤, 성 공하면 배포까지 합니다 |
빌더 이미지와 Git 주소 지정
두 가지 형식이 있고 결과는 같습니다. <빌더>~<git-uri> 는 물결표(~)로 둘을 이어 붙이는
형식입니다.
# 빌더와 Git 주소를 '~' 로 이어서
kubectl new-build registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret -n egov
# 빌더를 옵션으로
kubectl new-build http://bitbucket.example.com/scm/sample-app.git \
--builder registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest \
--source-secret git --push-secret default-registry-secret -n egov
쓸 수 있는 빌더 이미지 목록은 다음 명령으로 봅니다. Console 빌드 설정 생성 폼의 빌더 이미지 목록과 같은 값입니다(4.2 장).
kubectl builders
만들고 배포까지 한 번에 하려면 new-app 을 씁니다.
kubectl new-app registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret -n egov
자주 쓰는 옵션
아래 옵션은 new-build 와 new-app 에 모두 있습니다. 가운데 열은 그 값이 Console 빌드 설정
화면의 어느 항목에 해당하는지입니다.
| 옵션 | Console 의 항목 | 설명 |
|---|---|---|
--name | 이름 | 생략하면 Git 저장소 이름을 씁니다 |
--to | 빌드 출력 > 이미지 | 생략하면 <기본 레지스트리>/apps/<네임스페이스>/<이름> |
--ref | 소스 > Git 브랜치·태그 | 생략하면 기본 브랜치 |
--context-dir | 소스 > 컨텍스트 디렉터리 | 저장소 안 하위 디렉터리를 빌드할 때 |
--env K=V | 빌드 전략 > 환경 변수 | 여러 번 지정할 수 있습니다. 값 목록은 4.9 장 |
--source-secret | 소스 > 소스 자격증명 Secret | Git 접속 정보 Secret 이름 |
--push-secret | 빌드 출력 > Push Secret | 레지스트리 접속 정보 Secret 이름 |
--pull-secret | 빌드 전략 > Pull Secret | 빌더 이미지를 받는 데 인증이 필요할 때 |
--tag-strategy | 빌드 출력 > 태그 방식 | GitRef(기본) 또는 Unique. 두 방식의 차이는 4.2 장 |
--target | 배포 대상 Deployment 이름 | 생략하면 빌드 설정 이름과 같습니다 |
--cache-pvc | 고급 옵션 > 볼륨 | <PVC이름>:<마운트경로> 형식. 빌드 시간 줄이기는 4.2 장 |
--force | — | 다른 빌드 설정이 쓰던 Deployment 가 있어도 진행합니다 |
new-app 에만 있는 옵션은 두 가지입니다.
| 옵션 | 설명 |
|---|---|
--no-deploy | 빌드까지만 하고 배포하지 않습니다. 나중에 deploy 로 배포합니다 |
--no-follow | 로그를 출력하지 않습니다 |
캐시 볼륨과 배포 대상 이름까지 지정한 예시입니다.
kubectl new-build registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret \
--cache-pvc maven-m2-cache:/home/jboss/.m2 --target sample-app-web -n egov
빌드와 배포
빌드 설정을 한 번 만든 뒤로는 아래 순서를 되풀이합니다. Console 에서 [빌드 시작] 과 [배포] 를 번갈아 누르는 것과 같습니다.
| 순서 | 명령 | 언제 씁니다 |
|---|---|---|
| 1 | start-build | 소스를 고쳐 커밋한 뒤 |
| 2 | builds | 빌드가 끝났는지 확인할 때 |
| 3 | build-logs | 진행 상황이나 실패 원인을 볼 때 |
| 4 | cancel-build | 진행 중인 빌 드를 중단할 때 |
| 5 | deploy | 성공한 빌드를 배포할 때 |
빌드 시작
kubectl start-build sample-app -n egov
빌드 작업을 만들고 바로 끝납니다. 끝날 때까지 기다리려면 옵션을 붙입니다.
| 옵션 | 동작 |
|---|---|
--follow | 로그를 출력하면서 끝날 때까지 기다립니다 |
--wait | 로그 없이 끝날 때까지 기다립니다 |
kubectl start-build sample-app -n egov --follow
빌드가 실패하면 실패한 단계와 사유를 출력합니다. --follow 를 쓰지 않았다면 실패한 컨테이너
로그의 마지막 부분도 함께 출력합니다.
이력 확인
kubectl builds sample-app -n egov
빌드 이름, 단계, 만들어진 이미지, 시작 시각이 나옵니다. Console 의 빌드 목록과 같은 내용입니다(4.3 장). 빌드 설정 이름을 생략하면 그 네임스페이스의 모든 빌드를 봅니다.
로그 보기
kubectl build-logs sample-app -n egov
빌드는 git-clone · assemble · s2i-build 세 단계이고, 명령은 이 순서로 이어서 출력합니다.
컴파일과 패키징 결과는 assemble 단계에 나옵니다. 각 단계가 무엇을 하는지는
4.3 장에 있습니다.
| 옵션 | 동작 |
|---|---|
-f | 진행 중인 빌드의 로그를 계속 받습니다 |
-c <단계> | 한 단계만 봅니다. git-clone · assemble · s2i-build 중 하나 |
kubectl build-logs sample-app -n egov -f -c assemble
빌드 설정 이름 대신 빌드 이름을 줘도 됩니다. 그러면 그 빌드의 로그를 봅니다.
빌드 취소
kubectl cancel-build sample-app -n egov
진행 중인 빌드가 없으면 그 사실만 알리고 아무것도 하지 않습니다.
배포
kubectl deploy sample-app -n egov
가장 최근에 성공한 빌드의 이미지로 배포합니다. Deployment 가 없으면 만들고, 있으면 이미지를 바꿉니다. 이미지에 공개 포트 정보가 있으면 접속 경로(Service)도 처음 한 번 만들어집니다.
특정 빌드로 배포하려면 빌드 이름을 지정합니다.
kubectl deploy sample-app -n egov --build build-sample-app-20260916103000-ab12
조회
빌드 설정 목록
kubectl bc -n egov
빌드 설정마다 Git 주소, 출력 이미지, 마지막 빌드, 배포 상태가 한 줄로 나옵니다. STATUS 열은
최근 성공 빌드의 이미지와 지금 배포된 이미지를 비교한 결과입니다.
| STATUS | 뜻 |
|---|---|
| 최신 | 최근 성공 빌드가 그대로 배포되어 있습니다 |
| 다름 | 빌드는 했는데 아직 배포하지 않았습니다. Console 의 "최신 빌드 미배포" 와 같습니다 |
| 미배포 | 배포 대상 Deployment 가 아직 없습니다 |
| 빌드 없음 / 성공한 빌드 없음 | 배포할 이미지가 없습니다 |
| 비교 불가 (빌드 이미지 기록 없음) | 아래 "자주 겪는 것" 의 마지막 항목을 보십시오 |
여러 네임스페이스를 한 번에 보려면 -A 를 붙입니다. builds 도 같습니다.
kubectl bc -A
기본 kubectl 로 보기
플러그인 없이 표준 명령으로도 조회할 수 있습니다.
kubectl get buildconfigs.build.openmaru.io -n egov
kubectl logs job/build-sample-app-20260916103000-ab12 -n egov --all-containers
빌드 이름을 알면 위와 같이 로그를 볼 수 있습니다. --all-containers 를 빼면 마지막 단계
(s2i-build)만 나옵니다.
자주 겪는 것
| 증상 | 원인 | 조치 |
|---|---|---|
| "빌더 이미지를 지정하세요" 와 함께 목록이 출력됨 | 빌더를 주지 않았습니다 | 출력된 목록에서 하나를 골라 다시 실행합니다. 목록은 kubectl builders 와 같습니다 |
| "진행 중인 빌드가 있습니다: ..." 로 끝남 (종료 코드 2) | 같은 빌드 설정의 빌드가 이미 실행 중입니다 | 끝날 때까지 기다리거나 cancel-build 로 취소한 뒤 다시 시작합니다 |
"default" 네임스페이스에는 빌드·배포 리소스를 만들 수 없습니다 | -n 을 주지 않았거나 default 를 지정했습니다 | 애플리케이션 네임스페이스를 -n 으로 지정합니다 |
| "클러스터 구성요소용 네임스페이스입니다" | kube- 로 시작하는 네임스페이스를 지정했습니다 | 애플리케이션 네임스페이스를 지정합니다 |
Ctrl+C 로 빠져나왔는데 빌드가 계속됨 | 정상 동작입니다 | Ctrl+C 는 로그 출력만 멈춥니다. 빌드를 멈추려면 cancel-build 를 씁니다 |
bc 의 STATUS 가 "비교 불가 (빌드 이미지 기록 없음)" | 태그 방식이 GitRef 이고, 그 빌드의 파드가 정리되어 만들어진 이미지 주소를 알 수 없습니다 | 배포 여부는 Console 배포 상세에서 확인합니다(3.2 장). 매번 확인해야 하면 태그 방식을 Unique 로 바꿉니다(4.2 장) |
빌드 자체가 실패하는 증상은 화면에서 하든 명령줄에서 하든 원인이 같습니다. 4.2 장의 "실패할 때 확인할 것" 에서 증상을 찾으십시오.
Console 에서 결과 확인
명령줄로 빌드·배포해도 결과는 Console 에서 확인 합니다.
| 확인할 것 | 어디에서 |
|---|---|
| 빌드 설정과 최근 빌드 상태 | 빌드 > 빌드 설정 (4.2 장) |
| 빌드 로그와 이력 | 빌드 > 빌드 (4.3 장) |
| 파드가 기동됐는지, 로그 | 워크로드 > Pod (3.1 장) |
| 배포된 이미지 태그 | 워크로드 > 배포 상세 (3.2 장) |
| 외부 접속 주소 | 네트워킹 > 인그레스 (5.1 장) |
배포된 이미지 태그가 방금 빌드한 것과 같은지 Deployment 상세에서 확인하십시오.