재우니 개발자 블로그

Docker 컨테이너 안의 ASP.NET Core 8에서 로컬 PC의 MSSQL 연결하기

"도커 안에서는 로컬이 로컬이 아니라고요?" ASP.NET Core 8을 컨테이너에서 돌리다가 MSSQL 연결이 안 돼서 머리 쥐어뜯으셨던 분들, 모이세요.

 

 

안녕하세요! 요즘 ASP.NET Core 8로 새 프로젝트를 진행 중인데, 도커로 배포 환경을 구성하다가 한참을 헤맸던 경험이 있어요. 특히, Docker 컨테이너 안에서 로컬 PC에 설치된 MSSQL에 접근하려고 할 때 ‘왜 안 되는 거지?’ 싶었던 적 있으시죠? 저도 그랬답니다. 그래서 오늘은 제가 직접 겪은 삽질(?)과 해결법을 바탕으로, Docker 안의 ASP.NET Core 8 앱에서 로컬 MSSQL로 접근하는 방법을 차근차근 알려드릴게요.

 

Docker 네트워크 기본 개념 이해하기

Docker 컨테이너는 기본적으로 격리된 환경이기 때문에, 로컬 PC에 직접 접근하는 게 자연스럽지 않아요. 그래서 컨테이너 간 통신이나 호스트 PC 접근을 위해선 docker network에 대한 이해가 필요합니다. Docker는 기본적으로 bridge, host, none 세 가지 네트워크 드라이버를 제공합니다. 보통 우리가 사용하는 기본 네트워크는 bridge인데, 이건 컨테이너끼리는 통신 가능하지만 로컬 PC에는 직접 접근이 안 돼요.

컨테이너에서 로컬 PC에 접근하는 방법

컨테이너에서 호스트 PC의 MSSQL에 접근하려면 네트워크 상의 주소를 올바르게 지정해야 합니다. 특히 Windows에서는 host.docker.internal이 마법처럼 해결책이 되죠. 이 주소는 Docker for Windows/Mac에서 호스트를 지칭하는 DNS 이름이에요.

플랫폼 호스트 주소 비고
Windows / Mac host.docker.internal Docker 공식 지원
Linux 172.17.0.1 (bridge gateway) 수동 확인 필요

ASP.NET Core에서 MSSQL 연결 문자열 설정

ASP.NET Core의 appsettings.json 파일에 연결 문자열을 작성할 때는 도커 컨테이너에서 사용할 주소 기준으로 작성해야 해요. 일반적으로 localhost로 되어 있다면, 컨테이너에서는 자기 자신을 바라보기 때문에 연결 오류가 발생하죠.

  1. host.docker.internal 사용
  2. SQL Server 포트 확인 (기본 1433)
  3. 유저 인증 정보 확인 (SQL 인증/Windows 인증)
  4. 연결 문자열 예시: Server=host.docker.internal;Database=TestDB;User Id=sa;Password=your_password;

Windows 방화벽과 DNS 문제 해결

로컬 PC의 MSSQL이 외부 접근을 허용하도록 설정되어 있지 않으면, 아무리 컨테이너에서 연결하려 해도 실패해요. 특히 방화벽에서 1433 포트가 열려 있지 않거나, SQL Server가 TCP 연결을 수락하지 않도록 되어 있다면 문제가 생기죠.

 

SQL Server Configuration Manager에서 TCP/IP를 활성화하고, Windows 방화벽에서 인바운드 규칙을 설정해줘야 해요.

그리고 host.docker.internal이 DNS에서 인식되지 않는 경우, 수동으로 hosts 파일을 수정하거나 Docker 데몬에 별도 네트워크 라우팅을 설정해야 할 수도 있습니다.

 

SQLServerManager16.msc 를 실행하여 sql server configuration manager 프로그램을 실행한다.

 

 

tcp/ip 를 사용으로 변경한다.

 

실제 docker-compose 예제 코드

docker-compose를 사용하면 여러 서비스 간 설정을 깔끔하게 관리할 수 있어요. MSSQL을 로컬에서 실행 중이고 ASP.NET Core 웹앱만 컨테이너로 돌릴 경우, 다음과 같은 방식으로 설정할 수 있습니다.

항목 설명
network_mode bridge (기본), 필요시 host 사용
environment ConnectionStrings:Server=host.docker.internal

자주 발생하는 문제와 해결 팁

아무리 잘 설정해도 실수는 있기 마련이에요. 제가 겪었던 자잘한 문제들을 정리해봤어요. 혹시나 같은 삽질을 줄일 수 있길 바라며...

  • MSSQL TCP/IP 안 켜져 있음
  • 컨테이너의 DNS가 host.docker.internal을 못 찾음
  • 방화벽에서 포트 1433 막혀 있음
  • SQL 인증 계정 설정 안 돼 있음

 

 

Q Docker 컨테이너에서 왜 localhost로 MSSQL이 연결되지 않나요?

컨테이너 내부의 localhost는 컨테이너 자체를 가리킵니다. 호스트 PC를 지칭하려면 다른 주소를 사용해야 합니다.

Q Windows에서 host.docker.internal이 작동하지 않으면?

Docker 버전 확인 후, 최신으로 업데이트해 보세요. 안 되면 hosts 파일 수정을 고려해볼 수 있습니다.

Q SQL Server가 TCP 연결을 수락하도록 하려면?

SQL Server Configuration Manager에서 TCP/IP 설정을 활성화하고, 재시작하세요.

Q Docker에서 SQL 인증 오류가 나요

연결 문자열에서 사용자 계정과 비밀번호가 정확한지, SQL 인증이 허용되어 있는지 확인하세요.

Q Linux 환경에서는 host.docker.internal이 안 먹혀요

Linux에서는 브리지 게이트웨이 주소(보통 172.17.0.1)를 직접 확인해서 사용해야 합니다.

Q docker-compose로도 연결이 안 될 때는?

환경 변수 설정을 다시 확인하고, 컨테이너 내부에서 ping이나 telnet으로 접속 가능 여부를 테스트해 보세요.

 

 

오늘 내용이 조금 복잡하긴 했죠? 저도 이 설정 때문에 정말 많이 삽질했었거든요. 근데 진짜 신기하게도, 알고 나면 별 거 아니에요. Docker 안에서 로컬 MSSQL 연결만 제대로 되면 개발이 훨씬 수월해지니까요. 혹시 글을 보면서 궁금한 점이나 오류 겪으신 분들 계시면 댓글로 알려주세요! 같이 머리 맞대고 해결해 봅시다 😊

 

 

docker, asp.net core, mssql, host.docker.internal, docker 네트워크, docker-compose, sqlserver 연결, 윈도우 방화벽, 개발환경 설정, 도커 연결문제