본문으로 건너뛰기

도메인 설정

서비스를 배포한 후 사용자들이 도메인을 통해 접근할 수 있도록 설정합니다. KIWI는 런타임 환경(K8s, Docker/Podman)에 따라 다양한 연결 방식을 제공하며, TLS 인증서 설정도 지원합니다.

왜 도메인 설정이 필요한가요?
  • 기억하기 쉬운 주소: IP 주소 대신 app.example.com 같은 도메인으로 접근
  • 보안 통신: TLS/HTTPS로 데이터 암호화
  • 서비스 라우팅: 하나의 서버에서 여러 서비스를 도메인으로 구분

도메인 설정 탭

접근 방법​

  1. [서비스 관리] 페이지에서 대상 서비스의 운영 카드를 클릭합니다.
  2. 운영 모달에서 도메인 설정 탭을 선택합니다.

연결 방식​

KIWI는 런타임 환경에 따라 사용 가능한 연결 방식이 다릅니다.

K8s 런타임에서 사용 가능한 연결 방식​

  • Ingress: K8s Ingress 리소스를 생성하여 도메인을 서비스에 연결합니다. Ingress Controller(nginx, traefik, haproxy)를 통해 트래픽을 라우팅하며, cert-manager 연동으로 TLS 인증서를 자동 발급할 수 있습니다. 가장 권장하는 방식입니다.
  • NodePort: K8s Service를 NodePort 타입으로 노출합니다. 30000~32767 범위의 포트를 사용하며, 외부 IP를 직접 지정할 수 있습니다. Ingress Controller가 없는 환경에서 사용합니다.
  • LoadBalancer: 클라우드 환경에서 외부 로드밸런서를 자동으로 생성합니다. 클라우드 서비스가 외부 IP를 자동 할당합니다.
  • 외부 Nginx: K8s 클러스터 외부에 있는 별도의 Nginx 서버에 리버스 프록시 설정을 배포합니다. SSH를 통해 Nginx 설정 파일을 생성하고 적용합니다.
  • DNS Only: 도메인 정보만 기록합니다. 인프라 변경 없이 관리 목적으로 도메인을 등록할 때 사용합니다.

Docker/Podman 런타임에서 사용 가능한 연결 방식​

  • 프로젝트 Nginx: Docker Compose 프로젝트 내의 Nginx 컨테이너에 리버스 프록시 설정을 추가합니다. SSH를 통해 프로젝트 디렉토리의 nginx/conf.d에 설정 파일을 생성하고 docker exec으로 Nginx를 리로드합니다.
  • 외부 Nginx: Docker 호스트 외부의 별도 Nginx 서버에 리버스 프록시를 설정합니다. K8s의 외부 Nginx와 동일한 방식입니다.
  • DNS Only: 도메인 정보만 기록합니다.

도메인 목록​

도메인 설정 탭에서는 해당 서비스에 등록된 모든 도메인을 목록으로 확인할 수 있습니다.

  • 호스트명: 등록된 도메인 이름입니다. 와일드카드(*.example.com)도 지원합니다.
  • 연결 방식: 해당 도메인의 연결 타입입니다 (Ingress, NodePort, 외부 Nginx 등).
  • TLS: TLS 인증서 사용 여부입니다.
  • 상태: 현재 프록시 상태입니다.
    • 대기 중: 생성되었지만 아직 인프라에 적용하지 않은 상태
    • 적용 중: 인프라에 적용하는 중
    • 활성: 성공적으로 적용되어 정상 동작 중
    • 실패: 마지막 적용이 실패한 상태
  • 마지막 동기화: 마지막으로 인프라 상태를 동기화한 시간입니다.
  • 작업: 적용/동기화, 수정, 삭제 버튼입니다.

도메인 추가​

Step 1: 도메인 추가 모달 열기​

도메인 설정 탭에서 도메인 추가 버튼을 클릭합니다.

Step 2: 기본 정보 입력​

  • 호스트명 (필수): 연결할 도메인을 입력합니다. 예: app.example.com
  • 연결 방식 (필수): 런타임 환경에 따라 사용 가능한 연결 방식이 자동으로 필터링됩니다.

Step 3: 연결 방식별 설정​

선택한 연결 방식에 따라 추가 설정이 달라집니다.

Ingress 설정​

  • Upstream 서비스 (필수): 트래픽을 전달할 K8s Service를 선택합니다. 드롭다운에서 클러스터 내 서비스 목록이 자동으로 조회됩니다. 직접 입력도 가능합니다 (서비스명.네임스페이스:포트 형식).
  • Ingress Class (필수): 사용할 Ingress Controller를 선택합니다. nginx, traefik, haproxy를 지원합니다.

NodePort 설정​

  • Upstream 서비스 (필수): 노출할 K8s Service를 선택합니다.
  • NodePort (선택): 사용할 포트 번호입니다 (30000~32767). 비워두면 자동 할당됩니다.
  • External IPs (선택): 외부에서 접근할 IP 주소를 지정합니다. 여러 개 입력 가능합니다.

LoadBalancer 설정​

  • Upstream 서비스 (필수): 노출할 K8s Service를 선택합니다.
  • 클라우드 프로바이더가 자동으로 외부 IP를 할당합니다.

외부 Nginx 설정​

  • Upstream 주소 (필수): 트래픽을 전달할 서비스 주소입니다 (IP:포트 형식).
  • SSH 접속 정보 (필수): Nginx 서버에 SSH로 접속하기 위한 정보입니다.
    • 호스트, 포트(기본 22), 사용자명
    • 인증 방식: 비밀번호 또는 SSH 키
    • 장비 관리에 등록된 장비를 선택하여 자동 입력할 수 있습니다.
    • 다중 홉 SSH도 지원합니다.
  • 설정 파일 경로 (선택): Nginx conf 파일이 저장될 경로입니다. 기본값은 /etc/nginx/conf.d입니다.

프로젝트 Nginx 설정​

  • Upstream 서비스 (필수): Docker Compose 서비스명과 포트입니다 (서비스명:포트 형식).
  • 프로젝트 디렉토리의 nginx/conf.d에 설정 파일이 자동 생성됩니다.

DNS Only​

  • 추가 설정 없이 호스트명만 입력하면 됩니다. 도메인 정보를 기록하는 용도입니다.

Step 4: TLS 설정 (선택)​

TLS를 활성화하면 HTTPS 접속이 가능합니다.

  • TLS 비활성화: HTTP만 사용합니다.
  • 자동 (cert-manager): Ingress 연결 방식에서만 사용 가능합니다. K8s cert-manager가 인증서를 자동으로 발급하고 갱신합니다.
  • 수동: 인증서를 직접 업로드합니다. 인증서 파일 경로(외부 Nginx) 또는 인증서 내용을 입력합니다.

Step 5: 저장​

설정을 확인하고 추가 버튼을 클릭하여 도메인을 등록합니다.

도메인 등록 후 적용 필요

도메인을 추가하면 "대기 중" 상태로 생성됩니다. 실제 인프라에 반영하려면 적용 작업을 실행해야 합니다. DNS Only는 예외로 즉시 "활성" 상태가 됩니다.

도메인 적용​

등록한 도메인을 실제 인프라에 적용하는 과정입니다.

K8s 연결 방식 (Ingress, NodePort, LoadBalancer)​

  1. 도메인 목록에서 적용할 도메인의 적용 버튼(구름 업로드 아이콘)을 클릭합니다.
  2. KIWI가 자동으로 K8s 리소스(Ingress YAML, Service 수정 등)를 생성하거나 업데이트합니다.
  3. 적용이 완료되면 상태가 활성으로 변경됩니다.

외부 Nginx 연결 방식​

  1. 도메인 목록에서 적용할 도메인의 동기화 버튼을 클릭합니다.
  2. SSH 자격증명 입력 모달이 나타납니다. 인증 정보를 입력합니다:
    • 비밀번호 인증: 사용자명과 비밀번호
    • SSH 키 인증: 사용자명과 SSH 개인 키 파일(.pem, .key) 업로드
  3. KIWI가 SSH로 Nginx 서버에 접속하여:
    • 기존 설정 파일 존재 여부를 확인합니다.
    • 새 설정 파일을 생성합니다 (기존 파일이 있으면 덮어쓸지 확인)
    • nginx -t로 설정을 검증합니다.
    • 검증 성공 시 Nginx를 리로드합니다.
  4. 적용이 완료되면 상태가 활성으로 변경됩니다.
Nginx 설정 검증

적용 시 nginx -t 테스트가 실패하면 설정이 롤백됩니다. 오류 메시지를 확인하고 Upstream 주소나 설정을 수정한 후 다시 시도하세요.

프로젝트 Nginx 연결 방식​

  1. 도메인 목록에서 적용할 도메인의 적용 버튼을 클릭합니다.
  2. KIWI가 SSH로 Docker 호스트에 접속하여 프로젝트 디렉토리의 nginx/conf.d에 설정 파일을 생성합니다.
  3. docker exec으로 프로젝트 Nginx 컨테이너를 리로드합니다.

외부 Nginx 서버 동기화​

외부 Nginx를 사용하는 도메인이 있으면 외부 Nginx 동기화 기능을 사용할 수 있습니다. 이 기능은 Nginx 서버의 실제 설정 파일과 KIWI에 등록된 도메인 목록을 비교하고 동기화합니다.

  1. 도메인 목록 상단의 외부 Nginx 동기화 버튼을 클릭합니다.
  2. SSH 자격증명을 입력합니다.
  3. KIWI가 서버의 conf 파일을 스캔하고 DB와 비교합니다.
  4. 결과를 확인합니다:
    • 동기화됨: 서버와 DB가 일치하는 도메인
    • 서버에만 존재: 서버에는 있지만 KIWI에 등록되지 않은 도메인
    • DB에만 존재: KIWI에 등록되어 있지만 서버에 설정이 없는 도메인
  5. 서버에만 존재하는 도메인은 가져오기로 KIWI에 등록할 수 있습니다.

도메인 관리​

도메인 수정​

  1. 도메인 목록에서 수정할 도메인의 수정 버튼(연필 아이콘)을 클릭합니다.
  2. 수정 모달에서 필요한 정보를 변경합니다.
  3. 수정 버튼을 클릭하여 저장합니다.
  4. 변경 사항을 인프라에 반영하려면 다시 적용을 실행합니다.

도메인 삭제​

  1. 도메인 목록에서 삭제할 도메인의 삭제 버튼(휴지통 아이콘)을 클릭합니다.
  2. 확인 대화상자에서 삭제를 클릭합니다.
삭제 시 주의

도메인을 삭제하면 해당 도메인으로의 접근이 차단될 수 있습니다. K8s Ingress 방식은 리소스도 함께 삭제됩니다.

문제 해결​

적용 실패​

  • Nginx -t 검증 실패: Upstream 주소가 올바른지 확인하세요. 잘못된 주소나 포트를 지정하면 Nginx 설정 검증이 실패합니다.
  • SSH 연결 실패: 외부 Nginx 서버의 SSH 접속 정보를 확인하세요. 비밀번호나 SSH 키가 올바른지, 방화벽에서 SSH 포트가 열려 있는지 확인합니다.
  • K8s 리소스 생성 실패: Ingress Controller가 설치되어 있는지, Service가 존재하는지 확인하세요.

도메인 접근 불가​

  • DNS 설정 확인: 도메인이 서버 IP를 가리키도록 DNS A 레코드 또는 CNAME이 설정되어 있는지 확인합니다.
  • 상태 확인: 도메인 목록에서 상태가 "활성"인지 확인합니다. "대기 중"이면 적용을 실행하세요.
  • 방화벽 확인: 80/443 포트가 외부에서 접근 가능한지 확인합니다.

TLS 인증서 오류​

  • cert-manager 확인: 자동 TLS 사용 시 K8s 클러스터에 cert-manager가 설치되어 있는지 확인합니다.
  • 인증서 경로 확인: 수동 TLS 사용 시 인증서 파일 경로가 올바른지 확인합니다.

관련 가이드​