koyeb dashboard 사용법: 배포 상태와 로그를 한 화면에서 확인하기

koyeb dashboard는 Koyeb에 올린 서비스의 배포 상태, 로그, 환경 변수, 도메인 설정을 웹에서 관리하는 콘솔입니다. 장애가 났을 때 가장 먼저 열게 되는 화면이기도 하고, 새 버전을 올린 뒤 정상적으로 트래픽을 받는지 확인하는 창구이기도 합니다. 이 글은 서버 운영과 배포를 담당하는 백엔드 개발자가 대시보드에서 무엇을 어떤 순서로 확인하면 되는지, 그리고 어떤 작업은 CLI나 API로 넘기는 편이 나은지를 정리합니다.

한눈에 보기

Koyeb의 대시보드는 애플리케이션과 서비스 단위로 구성됩니다. 하나의 애플리케이션 아래에 여러 서비스가 붙고, 각 서비스가 실제로 실행되는 인스턴스와 배포 이력을 가집니다. 그래서 대시보드에서 무언가를 볼 때는 항상 "어느 애플리케이션의 어느 서비스인가"를 먼저 확인하는 습관이 중요합니다.

핵심 화면은 크게 네 갈래로 나뉩니다. 서비스의 현재 상태를 요약해 보여주는 개요 영역, 배포 이력과 결과를 보여주는 배포 영역, 실행 중인 인스턴스의 로그를 스트리밍하는 로그 영역, 그리고 환경 변수와 헬스 체크, 스케일, 리전 같은 설정을 다루는 설정 영역입니다. 배포 방식은 Git 저장소 연동, 컨테이너 이미지 참조, CLI를 통한 배포 등 여러 갈래를 지원하며, 어떤 방식으로 올렸든 이후 관리는 같은 대시보드 화면에서 이뤄집니다.

중요한 특징은 대시보드가 보여주는 리소스 모델이 CLI와 API의 그것과 동일하다는 점입니다. 화면에서 보이는 서비스, 배포, 인스턴스가 곧 CLI 명령과 API 호출의 대상이므로, 대시보드에서 익힌 개념을 그대로 자동화 스크립트로 옮길 수 있습니다.

대시보드 주요 영역 비교

영역	확인하는 내용	주로 여는 상황
Overview	서비스 상태, 최근 배포 결과, 인스턴스 요약	배포 직후 정상 기동 여부를 볼 때
Deployments	배포 이력, 성공·실패 결과, 이전 버전 정보	새 버전이 실패해 원인을 좁힐 때
Logs	빌드 로그와 런타임 로그 스트림	예외 추적, 부팅 실패 원인 확인
Metrics	CPU와 메모리 사용 추세	인스턴스 규모 조정을 판단할 때
Settings	환경 변수, 시크릿, 헬스 체크, 리전, 도메인	설정 변경과 재배포가 필요할 때
Console	서비스 컨테이너 안에서 명령 실행	설정 파일 확인, 네트워크 진단

표에서 알 수 있듯 대시보드는 관찰 도구와 변경 도구의 성격이 섞여 있습니다. 로그와 지표는 보기만 하면 되지만, 설정 화면에서 값을 바꾸면 실제 운영 환경이 달라집니다. 그래서 설정 영역을 열 때는 변경 전후 상태를 기록해 두는 편이 안전합니다.

단계별로 배포 확인하기

첫 단계는 로그인 후 올바른 조직과 프로젝트를 선택하는 것입니다. 여러 조직에 속해 있다면 화면 상단의 조직 선택이 잘못되어 있지 않은지 먼저 확인합니다. 여기서 잘못된 조직을 보고 있으면 서비스가 사라진 것처럼 보이는 착시가 생깁니다.

다음은 서비스 생성 또는 기존 서비스 선택입니다. 새 서비스를 만든다면 배포 원천을 고릅니다. Git 저장소를 연결하면 브랜치에 푸시할 때마다 자동으로 빌드와 배포가 이어지는 흐름을 만들 수 있고, 이미 빌드된 컨테이너 이미지를 참조하면 빌드 단계를 생략할 수 있습니다.

그다음은 빌드와 실행 설정입니다. 런타임, 빌드 명령, 실행 명령, 서비스가 수신 대기할 포트를 지정합니다. 여기서 포트가 실제 애플리케이션이 바인딩하는 포트와 어긋나면 헬스 체크가 실패하고 배포가 정상으로 표시되지 않습니다. 컨테이너 환경에서는 외부 인터페이스에 바인딩해야 한다는 점도 함께 확인해야 합니다.

이어서 환경 변수와 시크릿을 등록합니다. 일반 환경 변수는 값이 그대로 보이지만 시크릿으로 등록한 값은 화면에서 가려집니다. 데이터베이스 접속 문자열이나 외부 API 토큰은 시크릿으로 넣는 것이 기본입니다.

설정이 끝나면 리전과 인스턴스 규모를 정하고 헬스 체크 경로를 지정합니다. 헬스 체크는 단순히 프로세스가 살아 있는지가 아니라, 실제로 요청을 처리할 수 있는 상태인지를 확인하는 엔드포인트로 잡는 편이 좋습니다. 배포가 끝나면 개요 화면에서 상태를 확인하고, 로그 화면에서 부팅 로그에 오류가 없는지 훑어봅니다. 마지막으로 도메인을 연결하고 실제 요청이 정상 응답하는지 확인합니다.

로그와 지표를 읽는 방법

로그 화면은 빌드 로그와 런타임 로그를 구분해서 보여줍니다. 배포가 실패했을 때 가장 흔한 원인은 빌드 단계에 있으므로, 실패한 배포를 선택해 빌드 로그부터 확인하는 것이 순서입니다. 빌드는 성공했는데 서비스가 뜨지 않는다면 런타임 로그에서 포트 바인딩, 필수 환경 변수 누락, 마이그레이션 실패 같은 항목을 봅니다.

지표 화면은 시간에 따른 자원 사용 추세를 보여줍니다. 순간적인 값보다 추세를 보는 것이 중요합니다. 배포 직후 일시적으로 사용량이 튀는 것은 정상일 수 있으므로, 일정 시간이 지난 뒤에도 높은 수준이 유지되는지를 봅니다. 추세가 계속 우상향이면 인스턴스 규모나 코드 경로를 함께 점검해야 합니다.

로그는 스트리밍 방식으로 보는 화면이므로, 지나간 시점을 길게 되돌려 보는 용도로는 한계가 있습니다. 장기 보관이 필요한 로그는 애플리케이션에서 외부 수집기로 직접 보내는 구조를 갖추는 편이 안전합니다.

상황별 선택: 대시보드, CLI, API

상황	권장 수단	이유
최초 배포와 설정 탐색	대시보드	각 항목이 어떤 의미인지 화면으로 확인 가능
장애 직후 원인 파악	대시보드	로그와 지표를 오가며 빠르게 확인
반복되는 배포 자동화	CLI 또는 API	사람 손을 거치지 않고 동일 절차 재현
여러 서비스 일괄 설정	API 또는 선언적 설정	화면 반복 작업을 줄일 수 있음
일회성 진단 명령	대시보드 콘솔	별도 접속 설정 없이 컨테이너 내부 확인

처음 서비스를 올릴 때는 대시보드가 학습 도구로 유용합니다. 반면 같은 설정을 여러 환경에 반복 적용해야 하는 시점부터는 CLI와 API로 옮기는 것이 좋습니다. 대시보드에서 한 번 성공시킨 설정을 그대로 스크립트로 옮기면, 이후에는 리뷰 가능한 형태로 배포 절차를 관리할 수 있습니다.

주의할 점

환경 변수를 바꾸면 보통 새 배포가 필요합니다. 값을 저장했다고 실행 중인 인스턴스에 즉시 반영되는 것이 아니므로, 변경 후 배포 이력에서 새 배포가 정상적으로 완료됐는지 확인해야 합니다.

시크릿은 저장 후 값을 다시 읽어낼 수 없는 경우가 많습니다. 화면에서 가려진 값을 억지로 복원하려 하기보다, 원본은 별도의 비밀 관리 수단에 두고 대시보드에는 주입만 하는 구조가 좋습니다.

리전과 같은 항목은 나중에 바꾸기 어렵거나 재배포를 동반합니다. 처음 만들 때 신중하게 정하고, 변경이 필요하면 서비스 재생성까지 고려한 계획을 세워야 합니다.

헬스 체크 설정을 느슨하게 두면 실제로는 응답하지 않는 인스턴스가 정상으로 표시될 수 있습니다. 반대로 너무 짧은 주기와 엄격한 기준을 두면 순간적인 지연에도 배포가 실패로 처리됩니다. 애플리케이션의 초기화 시간을 고려해 여유를 두는 편이 좋습니다.

대시보드와 CLI는 같은 리소스를 바꿉니다. 여러 사람이 동시에 설정을 만지면 마지막 변경이 이기므로, 운영 환경 설정은 변경 절차를 정하고 이력를 남기는 편이 안전합니다.

요금과 인스턴스 정책은 시점에 따라 달라질 수 있습니다. 특정 플랜의 사양이나 과금 기준은 공식 가격 페이지에서 직접 확인하는 것이 정확합니다.

자주 묻는 질문

koyeb dashboard에서 배포 실패 원인은 어디서 확인하나요?

배포 목록에서 실패로 표시된 항목을 선택하면 단계별 로그를 볼 수 있습니다. 빌드 단계에서 멈췄는지, 이미지가 만들어졌지만 기동에 실패했는지를 먼저 구분하면 원인 범위가 크게 줄어듭니다. 이후 런타임 로그에서 포트와 환경 변수를 확인합니다.

대시보드에서 바꾼 설정은 즉시 반영되나요?

대부분의 설정 변경은 새 배포를 통해 반영됩니다. 저장 후 배포 이력에 새 항목이 생기고 그것이 정상 완료됐는지 확인해야 실제 운영 환경에 적용됩니다. 반영 여부가 애매할 때는 인스턴스 목록의 생성 시각을 함께 보는 것이 도움이 됩니다.

대시보드와 CLI를 같이 써도 문제가 없나요?

둘은 같은 리소스를 다루므로 함께 써도 됩니다. 다만 동시에 같은 설정을 수정하면 나중 변경이 앞선 변경을 덮어쓸 수 있습니다. 자동화는 CLI와 API로, 긴급 확인은 대시보드로 역할을 나누면 충돌을 줄일 수 있습니다.

로그는 얼마나 오래 보관되나요?

보관 정책은 플랜과 문서 기준에 따라 달라질 수 있으므로 공식 문서에서 확인하는 것이 정확합니다. 운영 로그를 오래 남겨야 한다면 애플리케이션 단에서 외부 수집기로 전송하는 구조를 함께 준비하는 편이 좋습니다.

서비스가 갑자기 응답하지 않을 때 가장 먼저 볼 화면은 어디인가요?

개요 화면에서 인스턴스 상태와 최근 배포 시각을 확인하고, 바로 로그 화면으로 이동해 재시작이나 예외가 반복되는지 봅니다. 최근 배포가 있었다면 그 시점 전후의 로그를 비교하는 것이 원인 파악에 가장 빠릅니다.

출처

Koyeb 공식 문서: https://www.koyeb.com/docs
Koyeb 배포 가이드: https://www.koyeb.com/docs/deploy
Koyeb CLI 레퍼런스: https://www.koyeb.com/docs/reference/cli
Koyeb 요금 안내: https://www.koyeb.com/pricing

대시보드 사용법을 익혔다면 다음 단계는 운영 자동화입니다. devbull에 정리된 배포 플랫폼 관련 운영 글과 함께 읽으면, 헬스 체크 설계부터 로그 수집, 환경 변수 관리까지 이어서 점검할 수 있습니다. 관련 글은 https://devbull.tech/ 에서 확인하실 수 있습니다.