웹 서비스 배포하기¶

이 튜토리얼에서 무엇을 배우나요?¶

이 튜토리얼은 완성된 컨테이너 이미지를 Runway 플랫폼 위에서 웹 서비스로 배포하는 실습입니다.

예제로 문서 사이트(정적 사이트) 이미지를 사용하지만, 이미지가 무엇이든 배포 방법은 동일합니다.

튜토리얼을 마치면 아래 경험을 직접 해볼 수 있습니다:

컨테이너 이미지를 Gitea 레지스트리에 푸시하는 방법
bitnami nginx 헬름 차트로 커스텀 이미지를 배포하는 방법
bitnami 차트 기본값에서 반드시 바꿔야 하는 values.yaml 항목
ArgoCD와 kubectl로 배포 상태를 확인하고 오류 원인을 파악하는 방법

용어 알아보기

Gitea: 오픈소스 Git 저장소 서비스. 이 튜토리얼에서는 컨테이너 이미지 레지스트리로 사용합니다.
Docker: 컨테이너 이미지를 빌드하고 레지스트리에 푸시하는 도구입니다.
Helm: Kubernetes 애플리케이션 패키지 관리 도구. 차트(Chart)라는 템플릿 단위로 Kubernetes 리소스를 배포합니다.
bitnami nginx 차트: nginx 웹 서버를 Kubernetes에 배포하는 Helm 차트입니다. bitnami가 공식 이미지 기준으로 설계했기 때문에 커스텀 이미지 사용 시 별도 설정이 필요합니다.
values.yaml: 헬름 차트의 기본 설정값을 재정의하는 파일입니다. 이미지 경로, 리소스, 보안 설정 등을 지정합니다.
ArgoCD: GitOps 기반 배포 자동화 도구. Runway에서 헬름 배포 상태를 시각적으로 확인할 수 있습니다.
HTTPRoute: Gateway API 기반 외부 트래픽 라우팅 설정. Runway 플랫폼에서 LoadBalancer 대신 사용합니다.

이 튜토리얼에서 사용하는 도구¶

도구	사용자 접근 방식	이 튜토리얼에서의 역할
Gitea	docker login / docker push	컨테이너 이미지 저장 (레지스트리)
Helm	Runway 앱 배포 UI	bitnami nginx 차트 배포
ArgoCD	Runway 앱 상세 페이지 > ArgoCD URL	배포 상태 확인 및 오류 진단
kubectl	터미널 (선택)	Pod 로그 및 이벤트 상세 확인

Runway에서 웹 서비스 배포가 동작하는 방식¶

이미지를 레지스트리에 올리면, Runway에서 헬름 차트를 통해 Kubernetes 위에 서비스로 배포됩니다.

flowchart LR
    subgraph local["로컬 환경"]
        IMG["컨테이너 이미지\n(사전 빌드 완료)"]
    end

    subgraph runway["Runway 플랫폼"]
        GT["Gitea\n이미지 레지스트리"]
        HC["Helm 차트\n(bitnami nginx)"]
        K8S["Kubernetes Pod\nnginx 실행"]
        GW["Gateway API\nHTTPRoute"]
    end

    IMG -->|"docker push"| GT
    GT -->|"이미지 pull"| K8S
    HC -->|"배포 설정 적용"| K8S
    K8S --> GW
    GW -->|"외부 URL 노출"| USER["사용자"]

왜 이렇게 설정해야 하나요?¶

bitnami 차트와 커스텀 이미지의 충돌

bitnami 차트는 bitnami 공식 이미지를 기준으로 만들어졌습니다. 커스텀 이미지로 교체하면 기본값 그대로는 동작하지 않습니다. 주요 이유는 두 가지입니다.

bitnami 이미지에만 있는 초기화 스크립트(initContainer)가 커스텀 이미지에는 없음
bitnami 이미지는 non-root 실행을 전제로 설계됐지만, 일반 nginx는 root 권한이 필요함

이 튜토리얼의 핵심은 어떤 항목을 왜 바꿔야 하는지 이해하는 것입니다.

Runway의 외부 접근 방식

Runway 플랫폼은 LoadBalancer 대신 Gateway API 기반으로 외부 트래픽을 처리합니다. 서비스 타입을 ClusterIP로 설정하고, httpRoute를 통해 외부 URL과 연결해야 합니다.

전체 흐름¶

flowchart TD
    A["시작 전 준비 (공통)\nWorkspace · Project ID 확인"]
    B["1단계. 사전 준비\n샘플 레포 클론 · Docker · Gitea 계정 확인"]
    C["2단계. 이미지 레지스트리 푸시\nGitea 로그인 · 이미지 빌드 & push"]
    D["3단계. 헬름 차트 배포\nvalues.yaml 작성 · Runway에서 앱 배포"]
    E["4단계. 배포 상태 확인 및 오류 해결\nArgoCD · kubectl로 상태 확인"]

    A --> B --> C --> D --> E