Codeflow와 Deployflow로 CI/CD 파이프라인 구축

카카오클라우드의 Codeflow와 Deployflow를 함께 사용하여 소스 코드 관리, 컨테이너 이미지 빌드, 쿠버네티스 배포로 이어지는 기본 CI/CD 파이프라인을 구성합니다.

기본 정보

예상 소요 시간: 60분
사전 준비 사항
- IAM 액세스 키
- 로컬 환경에서 git, kubectl, ssh 명령을 실행할 수 있는 환경 (이미지 빌드용 Docker는 Step 3의 러너 VM에 설치)
- Kubernetes Engine으로 쿠버네티스 클러스터 구축 (워커 노드 1대 이상)
- kubectl 제어 설정 — 로컬에서 대상 클러스터 접속(kubeconfig)
- Container Registry 리포지토리

연계 튜토리얼

이 문서는 Codeflow와 Deployflow를 연결해 기본 CI/CD 파이프라인을 구성하는 튜토리얼입니다. 이 문서에서 cicd-app-demo 애플리케이션을 배포한 뒤, 같은 애플리케이션에 Blue/Green 배포 전략을 적용하는 과정은 Deployflow로 Blue/Green 배포 전략 구현에서 이어서 확인할 수 있습니다.

시나리오 소개

이 튜토리얼에서는 카카오클라우드의 Codeflow와 Deployflow를 사용해 기본 CI/CD 파이프라인을 구성합니다. 애플리케이션 소스 코드와 쿠버네티스 매니페스트를 Codeflow 리포지토리에서 관리하고, Codeflow 워크플로우로 컨테이너 이미지를 빌드한 뒤, Deployflow가 매니페스트 변경을 Kubernetes Engine 클러스터에 반영하도록 설정합니다.

튜토리얼을 완료하면 Codeflow 워크플로우 실행만으로 컨테이너 이미지가 새 태그로 빌드·푸시되고, 매니페스트 변경이 Deployflow를 통해 클러스터에 반영되는 흐름을 확인할 수 있습니다.

전체 흐름은 다음과 같습니다.

소스 관리(Codeflow): 애플리케이션 소스 코드와 쿠버네티스 매니페스트를 Codeflow 리포지토리에 저장합니다.
이미지 빌드(Codeflow Actions): Codeflow 워크플로우를 실행하면 self-hosted 러너가 컨테이너 이미지를 빌드합니다.
이미지 업로드(Container Registry): 빌드된 이미지를 카카오클라우드 Container Registry에 푸시합니다.
매니페스트 갱신(Codeflow Actions): 워크플로우가 새 이미지 태그로 배포 매니페스트(k8s/deployment.yaml)를 업데이트하고 다시 커밋합니다.
배포 자동화(Deployflow): Deployflow가 매니페스트 변경을 감지하여 쿠버네티스 클러스터에 동기화합니다. 이때 클러스터는 매니페스트에 명시된 이미지를 Container Registry에서 pull 하여 Pod를 실행합니다.

마지막으로 Deployflow 배포 상태, Service 접속 결과, 워크플로우 재실행 시 변경 사항이 클러스터에 반영되는지 확인합니다.

[로컬] git push ──▶ Codeflow 리포지토리 ──▶ Codeflow 워크플로우(러너)
                          │                        │
                          │                        ├──① 이미지 빌드 ──▶ Container Registry  (이미지 저장)
                          │                        │
                          ├◀───────────────────────┴── ② 매니페스트 태그 갱신·커밋 (리포지토리로 커밋)
                          │
                          ▼
                  Deployflow ──▶ Kubernetes Engine 클러스터에 배포

시작하기 전에

IAM 액세스 키 발급

Codeflow의 Git 인증(clone/push)과 Container Registry 인증에는 IAM 액세스 키가 필요합니다.

콘솔 우측 상단 계정 메뉴 > 계정 설정 > 자격 증명 > IAM 액세스 키로 이동합니다.
[IAM 액세스 키 생성] 버튼을 클릭하고, 사용할 프로젝트를 선택하여 키를 발급합니다.
발급 시 표시되는 액세스 키 ID와 보안 액세스 키를 안전한 곳에 보관합니다.

주의

보안 액세스 키는 생성 직후에만 확인할 수 있습니다. 분실 시 재발급해야 합니다. 자세한 발급 방법은 액세스 키 생성하기를 참고하세요.

Container Registry 생성

빌드한 컨테이너 이미지를 보관할 저장소를 생성합니다.

카카오클라우드 콘솔 > Container Pack > Container Registry 메뉴에서 [리포지토리 생성] 버튼을 클릭합니다.
아래 정보를 참고하여 리포지토리를 생성합니다.

구분 설정값
공개 여부 비공개
리포지토리 이름 tutorial
태그 덮어쓰기 가능
이미지 스캔 자동

구분	설정값
공개 여부	비공개
리포지토리 이름	`tutorial`
태그 덮어쓰기	가능
이미지 스캔	자동

쿠버네티스 클러스터 준비

Deployflow는 이미 준비된 쿠버네티스 클러스터에 배포하는 서비스입니다. Kubernetes Engine으로 쿠버네티스 클러스터 구축 가이드를 참고하여 클러스터를 생성합니다.

또한 Step 5(이미지 Pull 시크릿 생성)와 배포 결과 확인 단계에서 로컬 kubectl로 클러스터를 조회합니다. kubectl 제어 설정 가이드를 참고하여, 로컬 환경에서 대상 클러스터에 접속(kubeconfig)할 수 있도록 미리 구성해 두세요.

워커 노드는 반드시 1대 이상

노드 풀에 워커 노드가 1대 이상 있어야 합니다. 노드가 0개이면 배포해도 Pod가 스케줄될 곳이 없어 Pending 상태로 멈춥니다. (이벤트: no nodes available to schedule pods)

시작하기

Step 1. Codeflow 리포지토리 생성

카카오클라우드 콘솔 > Developer Tools > Codeflow 메뉴로 이동합니다. 처음 사용하는 경우 [서비스 시작하기] 버튼을 클릭합니다.

리포지토리 메뉴에서 [리포지토리 생성] 버튼을 클릭하고, 아래 정보를 입력합니다.

항목	값	설명
이름	`cicd-app-demo`	리포지토리 이름
설명	(선택)	리포지토리 설명
기본 브랜치 이름	`main`	최초 생성되는 기본 브랜치
승인 규칙	단일 승인	풀 리퀘스트 머지에 필요한 승인 조건

[생성] 버튼을 클릭하면 리포지토리가 생성되고 목록에 추가됩니다.
생성된 리포지토리를 선택하고 세부 정보 탭의 URL을 복사합니다. (https://codeflow-git.kr-central-2.kakaocloud.com/<프로젝트>/cicd-app-demo.git 형식)

Step 2. 예제 애플리케이션 준비 및 푸시

예제로 argoproj/rollouts-demo를 사용합니다. 이 앱은 COLOR 빌드 인자로 화면 색을 지정할 수 있어 배포 결과를 브라우저에서 쉽게 확인할 수 있습니다. 소스를 받아 Codeflow cicd-app-demo 리포지토리로 푸시하고, 쿠버네티스 매니페스트와 워크플로우를 추가합니다.

예제 소스를 복제하고, 원격을 Codeflow 리포지토리로 변경합니다. Git 인증은 발급한 IAM 액세스 키를 URL에 포함해 수행합니다.
```
git clone https://github.com/argoproj/rollouts-demo cicd-app-demo
cd cicd-app-demo
git branch -M main   # rollouts-demo 기본 브랜치(master)를 main으로 변경
git remote set-url origin https://${ACCESS_KEY_ID}:${SECRET_ACCESS_KEY}@codeflow-git.kr-central-2.kakaocloud.com/${PROJECT}/cicd-app-demo.git
```
변수 설명
ACCESS_KEY_ID🖌︎ IAM 액세스 키 ID
SECRET_ACCESS_KEY🖌︎ 보안 액세스 키
PROJECT🖌︎ 카카오클라우드 프로젝트 이름
안내
rollouts-demo에는 Go 소스와 Dockerfile이 포함돼 있어 별도로 앱 코드를 작성할 필요가 없습니다. Dockerfile은 빌드 시 전달한 COLOR 값을 이미지에 반영하고, 앱은 이 값을 사용해 화면 색을 표시합니다.

배포 매니페스트를 k8s/ 디렉터리에 작성합니다. 이 경로가 이후 Deployflow의 Raw Manifest 경로가 됩니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cicd-app-demo
  namespace: deployflow
  labels:
    app: cicd-app-demo
spec:
  replicas: 2
  revisionHistoryLimit: 3
  selector:
    matchLabels:
      app: cicd-app-demo
  template:
    metadata:
      labels:
        app: cicd-app-demo
    spec:
      imagePullSecrets:
        - name: cr-pull-secret          # 프라이빗 CR 이미지 pull용 (Step 5에서 생성)
      containers:
        - name: cicd-app-demo
          image: ${PROJECT}.kr-central-2.kcr.dev/tutorial/cicd-app-demo:blue
          imagePullPolicy: Always
          ports:
            - name: http
              containerPort: 8080
          readinessProbe:
            httpGet: { path: /, port: http }
            initialDelaySeconds: 3
            periodSeconds: 5

변수	설명
PROJECT🖌︎	카카오클라우드 프로젝트 이름

k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: cicd-app-demo
  namespace: deployflow
  labels:
    app: cicd-app-demo
  annotations:
    # 퍼블릭 IP를 가진 NLB 생성
    loadbalancer.ke.kakaocloud.com/load-balancer-type: 'NLB'
    service.beta.kubernetes.io/openstack-internal-load-balancer: 'false'
spec:
  type: LoadBalancer
  selector:
    app: cicd-app-demo
  ports:
    - name: http
      port: 80
      targetPort: http

Service를 LoadBalancer로 두는 이유

실습 애플리케이션을 브라우저에서 확인하기 위해 Service를 LoadBalancer 유형으로 생성합니다. 카카오클라우드 Kubernetes Engine에서 퍼블릭 IP를 가진 로드 밸런서를 생성하려면 openstack-internal-load-balancer: 'false' 어노테이션을 사용합니다. 자세한 설정은 로드 밸런서 유형 서비스 생성을 참고하세요.

과금·노출 주의

퍼블릭 로드 밸런서는 로드 밸런서 요금이 부과되고 앱이 인터넷에 공개됩니다. 실습이 끝나면 애플리케이션과 서비스(로드 밸런서)를 삭제하세요.

빌드·배포를 자동화할 워크플로우를 .codeflow/workflows/ 경로에 작성합니다. color와 tag를 입력받아 이미지를 빌드하고, 배포 매니페스트의 이미지 태그를 갱신한 뒤 다시 커밋합니다. 워크플로우 파일은 기본 브랜치에 있어야 콘솔에서 인식됩니다.

.codeflow/workflows/cicd.yml
name: cicd

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Docker Image Tag'
        required: true
        default: 'blue'
      color:
        description: 'Color (blue/green)'
        required: true
        default: 'blue'

env:
  DOCKER_IMAGE_TAG: ${{ github.event.inputs.tag }}

jobs:
  build:
    runs-on: [ codeflow-runner ]     # Step 3에서 등록할 러너 라벨과 일치해야 함
    steps:
      - uses: actions/checkout@v7
      - name: Docker buildx 설정
        uses: docker/setup-buildx-action@v4
        with:
          driver: docker-container
      - name: Container Registry 로그인
        uses: docker/login-action@v4
        with:
          registry: ${{ vars.KCR_REPO_PROJECT }}.kr-central-2.kcr.dev
          username: ${{ vars.KCR_REPO_USER }}
          password: ${{ vars.KCR_REPO_SECRET }}
      - name: 이미지 빌드·푸시 (COLOR 값을 이미지에 고정)
        uses: docker/build-push-action@v4
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64
          push: true
          tags: ${{ vars.KCR_REPO_PROJECT }}.kr-central-2.kcr.dev/tutorial/cicd-app-demo:${{ env.DOCKER_IMAGE_TAG }}
          build-args: |
            COLOR=${{ github.event.inputs.color }}

  update-manifest:
    runs-on: [ codeflow-runner ]
    needs: build
    steps:
      - uses: actions/checkout@v7
      - name: 매니페스트 이미지 태그 갱신·커밋
        run: |
          IMAGE=${{ vars.KCR_REPO_PROJECT }}.kr-central-2.kcr.dev/tutorial/cicd-app-demo:${{ env.DOCKER_IMAGE_TAG }}
          sed -i "s|image: .*/cicd-app-demo:.*|image: ${IMAGE}|" k8s/deployment.yaml
          git config user.email "ci@codeflow"
          git config user.name "codeflow-ci"
          if git diff --quiet k8s/deployment.yaml; then
            echo "변경 없음 — 커밋 생략"
          else
            git add k8s/deployment.yaml
            git commit -m "ci: update image to ${{ env.DOCKER_IMAGE_TAG }}"
            # 커밋을 리포지토리로 되돌려 푸시 — Git 인증에 IAM 액세스 키(KCR_REPO_*) 재사용
            git remote set-url origin https://${{ vars.KCR_REPO_USER }}:${{ vars.KCR_REPO_SECRET }}@codeflow-git.kr-central-2.kakaocloud.com/${{ vars.KCR_REPO_PROJECT }}/cicd-app-demo.git
            git push origin HEAD:main
          fi

워크플로우 트리거

이 워크플로우는 수동 실행(workflow_dispatch) 방식으로, 콘솔에서 color와 tag를 입력해 실행합니다(Step 4). 이 튜토리얼에서는 처음 배포할 이미지 태그와 색상 값을 모두 blue로 입력합니다.

매니페스트와 워크플로우를 커밋하고 푸시합니다.
commit & push
```
git add k8s .codeflow
git commit -m "init: manifests, workflow"
git push origin main
```
푸시가 완료되면 콘솔 리포지토리 상세 > 코드 / 커밋 탭에서 반영된 내용을 확인할 수 있습니다.

자격 증명 관리

워크플로우 변수(vars.KCR_REPO_*)에 저장한 IAM 액세스 키는 Container Registry 로그인과 매니페스트 커밋 푸시(Git 인증)에 함께 사용됩니다. 운영 환경에서는 권한 범위를 검토한 전용 액세스 키를 사용하고, 키가 불필요하게 공유되지 않도록 관리하세요.

Step 3. 러너용 카카오클라우드 VM 생성 및 러너 등록

워크플로우를 실제로 실행하려면 self-hosted 러너가 필요합니다. 여기서는 로컬 PC 대신 카카오클라우드 Virtual Machine(VM) 에 러너를 구성합니다. VM은 상시 켜져 있어 로컬 PC보다 안정적이며, 이미지 빌드를 위해 VM에 Docker를 설치해 사용합니다.

러너용 VM 생성: 카카오클라우드 콘솔 > Compute > Beyond Compute Service > Virtual Machine 메뉴 > 인스턴스 탭에서 [인스턴스 생성] 버튼을 클릭하고, 아래와 같이 생성합니다.

구분	항목	설정/입력값	비고
기본 정보	이름	`codeflow-runner`
	개수	1
이미지		Ubuntu 22.04
인스턴스 유형		m2a.large	이미지 빌드 부하에 맞게 조정
볼륨	루트 볼륨	30	Docker 이미지 빌드 공간 확보
키 페어		`{USER_KEYPAIR}`	⚠️ 키 페어는 최초 1회 안전하게 보관 (분실 시 복구 불가)
네트워크	서브넷	퍼블릭 서브넷	인터넷 통신 필요
	보안 그룹	`codeflow-runner-sg`	본인 IP에서 SSH(22) 인바운드 허용

안내

러너 VM은 Codeflow Git 호스트(codeflow-git.kr-central-2.kakaocloud.com)와 Container Registry(*.kcr.dev)로 아웃바운드 인터넷 접근이 필요합니다. 퍼블릭 서브넷 + 퍼블릭 IP를 사용하거나, 프라이빗 서브넷이면 NAT를 구성하세요. 보안 그룹은 본인 IP에서의 SSH(22) 인바운드만 열면 됩니다.

VM 접속 및 Docker 설치: 인스턴스에 퍼블릭 IP를 연결한 뒤 로컬에서 SSH로 접속하고, 러너가 이미지를 빌드할 수 있도록 Docker를 설치합니다.

chmod 400 ${KEY_FILE}.pem
ssh -i ${KEY_FILE}.pem ubuntu@${VM_PUBLIC_IP}

# VM 내부에서
sudo apt-get update
sudo apt-get install -y docker.io
sudo usermod -aG docker ubuntu   # sudo 없이 docker 사용
newgrp docker                    # 또는 SSH 재접속

변수	설명
KEY_FILE🖌︎	키 파일 이름
VM_PUBLIC_IP🖌︎	러너 VM 퍼블릭 IP

리포지토리 토큰 확인: 리포지토리 상세 > 액션 설정 > 리포지토리 설정의 리포지토리 토큰을 복사합니다. (러너 등록에 사용 — Git 인증용 IAM 액세스 키와는 다릅니다.)

이제 러너를 실행합니다. VM에 Docker가 설치돼 있으므로 실행 파일 방식과 컨테이너 방식 중 하나를 선택합니다. (--labels / KC_CODEFLOW_RUNNER_LABELS 값은 워크플로우의 runs-on(codeflow-runner)과 일치해야 합니다.)

실행 파일 방식
컨테이너 방식

콘솔 액션 설정 > 러너 탭에서 Linux(amd64) 다운로드 링크를 복사해 VM에서 내려받고 실행 권한을 부여한 뒤, 러너를 등록하고 데몬을 실행합니다. (러너 토큰 = 리포지토리 토큰)

# 1) 다운로드 + 실행 권한
curl -L -o codeflow_runner "${RUNNER_URL}"
chmod +x ./codeflow_runner

# 2) 러너 등록
./codeflow_runner register \
  --endpoint-url https://codeflow-git.kr-central-2.kakaocloud.com \
  --token ${REPO_TOKEN} \
  --name vm-runner \
  --labels codeflow-runner \
  --no-interactive

# 3) 데몬 실행 (백그라운드 상시 실행)
nohup ./codeflow_runner daemon > runner.log 2>&1 &

변수	설명
RUNNER_URL🖌︎	Linux amd64 러너 다운로드 URL
REPO_TOKEN🖌︎	리포지토리 토큰

(VM은 Linux이므로 macOS의 xattr 격리 해제 단계는 필요 없습니다.)

러너를 컨테이너로 실행하면 다운로드·등록 과정 없이 한 번에 구동됩니다(등록 자동). 인증에 IAM 액세스 키가 필요합니다.

export KC_CODEFLOW_ENDPOINT_URL='https://codeflow-git.kr-central-2.kakaocloud.com'
export KC_CODEFLOW_ACCESS_KEY_ID='${ACCESS_KEY_ID}'
export KC_CODEFLOW_SECRET_ACCESS_ID='${SECRET_ACCESS_KEY}'
export KC_CODEFLOW_RUNNER_REGISTRATION_TOKEN='${REPO_TOKEN}'
export KC_CODEFLOW_RUNNER_NAME='vm-runner'
export KC_CODEFLOW_RUNNER_LABELS='codeflow-runner'
export KC_CODEFLOW_RUNNER_EPHEMERAL='false'

변수	설명
ACCESS_KEY_ID🖌︎	IAM 액세스 키 ID
SECRET_ACCESS_KEY🖌︎	보안 액세스 키
REPO_TOKEN🖌︎	리포지토리 토큰

컨테이너 실행
docker run -d --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e KC_CODEFLOW_ENDPOINT_URL="${KC_CODEFLOW_ENDPOINT_URL}" \
  -e KC_CODEFLOW_ACCESS_KEY_ID="${KC_CODEFLOW_ACCESS_KEY_ID}" \
  -e KC_CODEFLOW_SECRET_ACCESS_ID="${KC_CODEFLOW_SECRET_ACCESS_ID}" \
  -e KC_CODEFLOW_RUNNER_REGISTRATION_TOKEN="${KC_CODEFLOW_RUNNER_REGISTRATION_TOKEN}" \
  -e KC_CODEFLOW_RUNNER_NAME="${KC_CODEFLOW_RUNNER_NAME}" \
  -e KC_CODEFLOW_RUNNER_LABELS="${KC_CODEFLOW_RUNNER_LABELS}" \
  -e KC_CODEFLOW_RUNNER_EPHEMERAL="${KC_CODEFLOW_RUNNER_EPHEMERAL}" \
  --name codeflow_runner \
  <러너 이미지 URL>

안내

KC_CODEFLOW_RUNNER_EPHEMERAL: true면 단일 작업(Job) 수행 후 러너가 자동 종료·등록 해제, false(기본)면 작업 완료 후에도 계속 대기·처리합니다.
러너 이미지 URL은 콘솔 액션 설정에서 제공되는 값을 사용합니다(환경에 따라 변경될 수 있음).

러너 실행 후, 콘솔 액션 설정 > 러너에서 등록된 러너의 상태가 Idle로 보이면 정상입니다. (대기 시 Idle, 작업 처리 시 Active)

안내

러너 다운로드 링크·상세 옵션은 콘솔 액션 설정 > 러너 탭과 Codeflow 액션 설정 문서에서 제공됩니다. 러너 VM이 켜져 있고 러너가 실행 중인 동안 워크플로우가 처리됩니다. 더 안정적으로 운영하려면 systemd 서비스 등록이나 쿠버네티스 클러스터 배포도 고려하세요.

Step 4. 워크플로우로 이미지 빌드 및 배포 매니페스트 갱신

워크플로우에서 사용할 변수를 등록합니다. 리포지토리 상세 > 액션 설정 > 변수에서 [생성] 버튼을 클릭하여 아래 변수를 추가합니다. (Container Registry 로그인에 사용)

키 값
KCR_REPO_PROJECT 카카오클라우드 프로젝트 이름
KCR_REPO_USER IAM 액세스 키 ID
KCR_REPO_SECRET 보안 액세스 키
콘솔 리포지토리 상세 > 워크플로우 > 워크플로우 파일에서 .codeflow/workflows/cicd.yml이 인식됐는지 확인하고 [워크플로우 실행]을 클릭합니다. 브랜치(main)와 파라미터를 아래와 같이 입력해 blue 이미지를 빌드합니다.

파라미터 값 설명
tag blue 이미지 태그
color blue 화면 색 (build-arg로 이미지에 고정)
워크플로우 실행 이력 탭에서 실행 상태를 확인합니다. 상태는 Queued → Running → Succeeded 순으로 진행되며, [⋮] > 로그 보기로 단계별 로그를 확인할 수 있습니다.

로그 화면 예시

안내
실행이 Queued에서 멈춰 있으면 ① 러너 데몬이 실행 중인지, ② 워크플로우의 runs-on 라벨과 러너의 --labels(codeflow-runner)가 일치하는지 확인하세요.
워크플로우가 성공하면 두 가지가 반영됩니다.
- Container Registry에 cicd-app-demo:blue 이미지(파란 화면)가 푸시됩니다. 콘솔 Container Pack > Container Registry > tutorial 리포지토리에서 확인합니다.
- k8s/deployment.yaml의 image 태그가 :blue로 갱신되고 codeflow-ci가 자동 커밋합니다. 이 커밋이 곧 Deployflow의 동기화 대상입니다.

키	값
`KCR_REPO_PROJECT`	카카오클라우드 프로젝트 이름
`KCR_REPO_USER`	IAM 액세스 키 ID
`KCR_REPO_SECRET`	보안 액세스 키

파라미터	값	설명
`tag`	`blue`	이미지 태그
`color`	`blue`	화면 색 (build-arg로 이미지에 고정)

Step 5. 이미지 Pull 시크릿 생성

비공개 Container Registry 이미지를 클러스터가 받아오려면 대상 네임스페이스에 docker-registry 시크릿이 필요합니다. 로컬에서 대상 클러스터에 접속(kubeconfig)한 뒤 아래 명령을 실행합니다.

kubectl create namespace deployflow

kubectl -n deployflow create secret docker-registry cr-pull-secret \
  --docker-server=${PROJECT}.kr-central-2.kcr.dev \
  --docker-username=${ACCESS_KEY_ID} \
  --docker-password=${SECRET_ACCESS_KEY}

변수	설명
PROJECT🖌︎	카카오클라우드 프로젝트 이름
ACCESS_KEY_ID🖌︎	IAM 액세스 키 ID
SECRET_ACCESS_KEY🖌︎	보안 액세스 키

안내

시크릿 이름(cr-pull-secret)과 네임스페이스(deployflow)는 Step 2의 k8s/deployment.yaml에 지정한 값과 일치해야 합니다.

Step 6. Deployflow 애플리케이션 생성

이제 Codeflow 리포지토리의 매니페스트를 대상 클러스터에 배포하는 Deployflow 애플리케이션을 생성합니다.

카카오클라우드 콘솔 > Developer Tools > Deployflow 메뉴로 이동합니다. 좌측 메뉴는 애플리케이션 / 승인 관리로 구성됩니다.
애플리케이션 메뉴에서 [애플리케이션 생성] 버튼을 클릭하고, 기본 정보에 이름과 설명을 입력합니다.

클러스터 정보 / 소스 정보 / 배포 방식을 아래와 같이 입력합니다.

항목	값	설명
이름	`cicd-app-demo`	애플리케이션 이름
배포 클러스터	(생성한 클러스터)	배포 대상 쿠버네티스 클러스터 (노드 ≥ 1)
네임스페이스 이름	`deployflow`	대상 네임스페이스
소스 리포지토리	`cicd-app-demo`	매니페스트가 있는 Codeflow 리포지토리
소스 브랜치	`main`	사용할 브랜치
배포 방식	Raw Manifest	경로의 YAML을 그대로 적용
Raw Manifest 경로	`k8s`	리포지토리 루트 기준 상대 경로 (앞 슬래시 없이)

배포 방식 3가지

Raw Manifest: 경로의 YAML을 그대로 적용
Kustomize: kustomization.yaml 기반 오버레이 적용
Helm: Helm 차트 기반 배포

(선택) 승인 설정 / 고급 옵션을 필요에 따라 설정합니다. 본 튜토리얼은 기본값으로 두고 진행해도 됩니다.

옵션	설명
승인 설정 옵션	켜면 동기화·배포·롤백이 즉시 적용되지 않고 승인 요청으로 생성됩니다. 지정한 승인자가 콘솔 좌측 승인 관리 메뉴에서 승인해야 반영됩니다. (기본: 미사용)
리소스 삭제 옵션	동기화·삭제 시 하위 리소스 정리 방식 - Foreground: 연관 하위 리소스까지 모두 삭제된 후 완료 (기본) - Background: 대상 리소스를 즉시 삭제하고 하위 리소스는 백그라운드 정리 - Non-cascading: 하위 리소스는 유지하고 선택한 대상만 삭제
ServerSideApply	적용 계산을 API 서버가 수행(필드 소유권 추적). 큰 매니페스트/CRD나 여러 컨트롤러가 같은 리소스를 관리할 때 유리합니다. 단순 배포는 미사용으로 둬도 됩니다.

우측 요약 정보에서 입력값을 최종 확인하고 [생성] 버튼을 클릭합니다. 목록으로 돌아와 새 애플리케이션의 상태 / 동기화 상태 / 배포 전략 상태 / 클러스터 / 소스 리포지토리를 확인합니다.

Step 7. 동기화 및 배포 결과 확인

생성 직후에는 소스 매니페스트와 클러스터 상태가 다르므로 동기화 상태가 Out of Sync(동기화 필요)입니다. 수동으로 동기화하여 배포합니다.

애플리케이션을 선택하면 하단 상세 영역이 열립니다. 상단 탭으로 상태를 확인할 수 있습니다. 세부 정보에서 동기화 상태 / 소스 리비전 / 경로가 Out of Sync인지 확인합니다.

탭	내용
세부 정보	이름, 배포 클러스터, 네임스페이스, 소스/리비전/경로, 상태와 동기화 상태
승인 상태	승인 설정 옵션 사용 시 승인 요청 상태 (미사용이면 비어 있음)
배포 전략	자동 동기화 등 배포 방식 설정 (Step 8)
리소스	토폴로지(Application → Deployment → ReplicaSet → Pod → Service) 및 리소스 상세(요약/매니페스트/이벤트/로그)
히스토리	배포/롤백 이력

상세 영역 상단의 [동기화] 버튼을 클릭합니다. 동기화 팝업창에서 리소스 삭제 옵션과 강제 동기화 사용 여부를 확인하고, 하단의 [동기화]를 클릭하면 "동기화에 성공했습니다." 메시지가 표시됩니다.
동기화 상태가 Synced, 상태가 Healthy인지 확인합니다.
리소스 탭에서 배포 결과를 토폴로지(Application → Deployment → ReplicaSet → Pod → Service)로 확인합니다. 각 리소스의 요약/매니페스트/이벤트/로그를 볼 수 있습니다.
Service의 퍼블릭 EXTERNAL-IP로 접속해 파란(blue) 화면(rollouts-demo)을 확인합니다. LoadBalancer 프로비저닝에 1~2분 정도 걸립니다.
```
kubectl -n deployflow get svc cicd-app-demo -w
# EXTERNAL-IP가 <pending> → 퍼블릭 IP로 바뀌면 Ctrl+C
# 브라우저에서 http://<EXTERNAL-IP> 접속 → 파란 화면
```
파란(blue) 화면 예시

tip

성공 메시지 후에도 상태가 바로 바뀌지 않으면 최신화를 눌러 매니페스트와 실제 클러스터 상태의 차이를 다시 조회하세요.

Pod가 Pending / ImagePullBackOff이면

Pod가 Pending이고 애플리케이션의 상태가 Missing에서 멈추면, 대부분 대상 클러스터에 노드가 없는 경우입니다. (시작하기 전에 참고)
ImagePullBackOff가 보이면, 대상 네임스페이스에 이미지 Pull 시크릿(cr-pull-secret) 이 없거나 잘못된 것입니다. (Step 5 참고)

리소스 상세의 이벤트 탭에서 원인을 확인할 수 있습니다.

Step 8. 자동 동기화 설정 및 CI/CD 흐름 확인

이 단계에서는 먼저 Deployflow에서 자동 동기화를 설정한 뒤, Codeflow에서 워크플로우를 다시 실행합니다. Codeflow 워크플로우가 새 이미지를 빌드·푸시하고 매니페스트의 이미지 태그를 갱신해 커밋하면, Deployflow가 변경된 매니페스트를 기준으로 클러스터를 자동 동기화하는지 확인합니다.

Deployflow에서 자동 동기화 설정

Deployflow 콘솔에서 애플리케이션을 선택하고 상세 영역의 [배포 전략 설정] 버튼을 클릭합니다.
배포 전략 설정 옵션을 사용으로 켜고, 배포 유형을 자동 동기화로 선택한 뒤 [저장]을 클릭합니다.
목록과 상세의 배포 전략 상태가 자동 동기화로 표시되는지 확인합니다.

Codeflow에서 워크플로우 실행

Codeflow 콘솔의 리포지토리 상세 > 워크플로우에서 Step 4에서 실행했던 워크플로우를 다시 실행합니다. 실행 파라미터는 아래와 같이 입력합니다.

파라미터 값 설명
tag v2 새 이미지 태그
color blue 화면 색
워크플로우 실행이 성공한 뒤, Deployflow 애플리케이션에서 자동 동기화 결과를 확인합니다.
- Codeflow 워크플로우가 새 이미지(cicd-app-demo:v2)를 빌드·푸시하고, k8s/deployment.yaml의 태그를 갱신·커밋합니다.
- Deployflow가 매니페스트 변경을 감지하여 동기화하고, 마지막 동기화 일시와 리소스 토폴로지가 갱신됩니다.
- Deployflow 애플리케이션의 동기화 상태가 Synced, 상태가 Healthy로 표시됩니다.

파라미터	값	설명
`tag`	`v2`	새 이미지 태그
`color`	`blue`	화면 색

주의

자동 동기화를 켜면 소스 변경이 대상 애플리케이션에 바로 반영됩니다. 대상 애플리케이션/클러스터/네임스페이스/경로가 올바른지 신중히 확인하세요.

롤백 (rollback)

배포 후 문제가 발생하면 Deployflow 애플리케이션의 히스토리 탭에서 이전 배포 이력을 확인하고 롤백할 수 있습니다. 롤백 전에는 대상 히스토리 ID와 매니페스트 내용을 확인하세요.

자동 동기화가 켜져 있으면 이후 소스 매니페스트 변경 시 다시 최신 상태로 동기화될 수 있습니다. 롤백 상태를 유지하려면 Codeflow 리포지토리의 매니페스트도 함께 되돌려야 합니다.

다음 단계

이 문서에서는 Codeflow 워크플로우와 Deployflow Raw Manifest 배포를 연결해 기본 CI/CD 파이프라인을 구성했습니다. 같은 애플리케이션에 Blue/Green 배포 전략을 적용하고, Green 버전 검증 후 트래픽을 전환하려면 Deployflow로 Blue/Green 배포 전략 구현을 진행하세요.

시나리오 소개​

시작하기 전에​

IAM 액세스 키 발급​

Container Registry 생성​

쿠버네티스 클러스터 준비​

시작하기​

Step 1. Codeflow 리포지토리 생성​

Step 2. 예제 애플리케이션 준비 및 푸시​

Step 3. 러너용 카카오클라우드 VM 생성 및 러너 등록​

Step 4. 워크플로우로 이미지 빌드 및 배포 매니페스트 갱신​

Step 5. 이미지 Pull 시크릿 생성​

Step 6. Deployflow 애플리케이션 생성​

Step 7. 동기화 및 배포 결과 확인​

Step 8. 자동 동기화 설정 및 CI/CD 흐름 확인​

Deployflow에서 자동 동기화 설정​

Codeflow에서 워크플로우 실행​

다음 단계​