업스트림 프록시 구성

업스트림 프록시 구성 (Configure an upstream proxy)

로컬 샌드박스와 데몬의 아웃바운드 트래픽을 기업·네트워크 프록시로 라우팅하는 방법을 알아볼게요.

출처: 문서

본문

이 페이지는 로컬 샌드박스와 로컬 데몬의 프록시 설정을 설명해요. 클라우드 샌드박스 이그레스 제어는 Cloud network policy 문서를 보세요.

중요 (Important): 업스트림 프록시 지원은 실험적이에요. 이 페이지에 설명된 모든 것 — 프록시 URL, PAC 파일, SOCKS5, OS 시스템 프록시 사용, 프록시 인증, 그것들을 설정하는 설정 값 — 은 바뀔 수 있어요. 피드백과 버그 보고는 docker/sbx-releases 저장소에 공유하세요.

업스트림 프록시는 Docker Sandboxes가 인터넷으로 가는 길에 아웃바운드 트래픽을 전달하는 기업·네트워크 프록시예요. 이것은 어떤 목적지가 허용되는지 결정하는 네트워크 정책과 분리돼요. 업스트림 프록시는 허용된 트래픽이 그 목적지에 어떻게 도달하는지를 결정해요.

Docker Sandboxes는 두 종류의 아웃바운드 트래픽을 보내며, 각각 독립적으로 프록시할 수 있어요:

  • 샌드박스 트래픽 — 샌드박스 안에서의 네트워크 접근
  • 데몬 트래픽 — sbx 데몬 자체의 접근(이미지 pull, 텔레메트리, 기능 플래그 포함). sbx login과 sbx diagnose --upload의 CLI 요청도 이 범위를 사용해요.

기본 동작 (Default behavior)

기본적으로 두 종류의 트래픽 모두 운영체제의 프록시 설정(거기에 설정된 PAC URL 포함)을 사용해요. 아무것도 구성할 필요 없어요. macOS와 Windows에서 sbx는 실행 중에 OS 프록시 설정을 추적하므로 네트워크, VPN, PAC 구성 변경이 재시작 없이 반영돼요. OS에 프록시가 없으면 트래픽은 직접 연결돼요.

수동으로 프록시 설정하기 (Set a proxy manually)

sbx settings set으로 한 종류 또는 두 종류의 트래픽 기본값을 덮어써요:

$ sbx settings set proxy http://proxy.corp:3128  # both kinds of traffic
$ sbx settings set proxy.sandbox socks5://proxy.corp:1080  # sandbox traffic only
$ sbx settings set proxy.daemon direct  # daemon traffic only

프록시 값은 다음 중 하나가 될 수 있어요:

값 (Value) 의미 (Meaning)
(설정 안 됨) 더 넓은 범위, 그다음 환경 변수, 그다음 OS 시스템 프록시(기본)로 대체
http://host:port 또는 https://host:port HTTP 또는 HTTPS 프록시
socks5://host:port 또는 socks5h://host:port SOCKS5 프록시
pac+http://host/proxy.pac, pac+https://host/proxy.pac, file:///path/proxy.pac PAC(proxy auto-config) 파일
system OS 시스템 프록시 사용을 강제
direct 프록시 없이 직접 연결을 강제

socks5://는 연결이 프록시에 넘겨지기 전에 DNS가 로컬에서 해석돼요. socks5h://는 DNS 해석이 프록시에 위임돼요.

프록시에서 목적지 제외하기 (Exclude destinations from the proxy)

제외 목록도 같은 범위를 반영해요. 각각 호스트, 도메인 접미사, IP 주소, CIDR 범위의 쉼표 구분 목록이나, 프록시를 완전히 우회하는 *를 받아요:

$ sbx settings set no_proxy "*.internal.corp,10.0.0.0/8"  # both kinds of traffic
$ sbx settings set no_proxy.sandbox "*.svc.cluster.local"  # sandbox traffic only
$ sbx settings set no_proxy.daemon "registry.internal"  # daemon traffic only

환경 변수 (Environment variables)

sbx는 셸에서 실행되므로 표준·레거시 프록시 환경 변수도 존중해서, 기존 설정이 마이그레이션 없이 계속 동작해요:

  • HTTP_PROXY, HTTPS_PROXY, NO_PROXY(그리고 소문자 형태) — 표준 변수. proxy나 no_proxy 설정이 없으면 두 종류의 트래픽 모두에 적용돼요.
  • DOCKER_SANDBOXES_PROXY와 DOCKER_SANDBOXES_NO_PROXY — proxy.sandbox와 no_proxy.sandbox의 환경 변수 형태. 샌드박스 트래픽에만 적용되고 데몬 트래픽에는 절대 영향이 없어요.

환경 변수 변경을 CLI와 데몬에 적용하는 방법은 Settings environment variables 문서를 보세요.

우선순위 (Precedence)

각 종류의 트래픽에 대해 첫 번째 일치가 승리해요:

  1. 범위별 값: 샌드박스 트래픽은 proxy.sandbox 또는 DOCKER_SANDBOXES_PROXY, 데몬 트래픽은 proxy.daemon
  2. proxy 설정
  3. 셸의 HTTP_PROXY 또는 HTTPS_PROXY
  4. OS 시스템 프록시(기본)
  5. 직접 연결

일치하는 제외 목록(no_proxy.<scope>, 그다음 no_proxy)이 선택된 프록시에 적용되고, 표준 NO_PROXY 변수는 환경 경로에서 여전히 적용돼요.

예를 들어 proxy가 공유 프록시를 지정하고 proxy.sandbox가 direct로 설정되면, 샌드박스 트래픽은 직접 연결하고 데몬 트래픽은 공유 프록시를 사용해요. 프록시 설정이 없으면 HTTP_PROXY가 OS 시스템 프록시보다 우선해요.

변경이 적용되는 시점 (When changes take effect)

프록시 설정은 소비자에 따라 다른 시점에 적용돼요:

  • 샌드박스 범위(proxy.sandbox, no_proxy.sandbox, proxy·no_proxy의 샌드박스 쪽)는 샌드박스 네트워크 프록시가 만들어질 때 해석돼요. 변경 후 만든 샌드박스는 갱신된 설정을 사용해요. 기존 샌드박스는 sbx daemon restart가 네트워크 프록시를 재빌드할 때까지 선택된 업스트림 프록시를 유지해요. 샌드박스를 재시작하는 것만으로는 충분하지 않아요.
  • 데몬 범위(proxy.daemon, no_proxy.daemon, proxy·no_proxy의 데몬 쪽)는 데몬이 시작될 때 한 번 해석돼요. 데몬 자체 트래픽의 변경은 sbx daemon restart가 필요해요.
  • 지원되는 CLI 클라이언트는 각 호출마다 데몬 범위 설정을 읽어요. sbx login과 sbx diagnose --upload를 포함해요. 변경은 데몬 재시작 없이 다음 호출에 적용돼요.

DOCKER_SANDBOXES_* 환경 변수는 별도의 경우예요. Environment variables에서 설명한 대로 샌드박스 트래픽만 제어하지만, sbx는 데몬이 시작할 때 데몬의 환경에서 읽으므로, 하나를 바꾸면 데몬 재시작도 필요해요. 이 변수가 저장된 설정을 덮어쓰면, 저장된 설정이 적용되도록 변수를 해제하고 데몬을 재시작하세요.

system이나 PAC 프록시를 사용할 때 sbx는 OS 수준 프록시 변경(네트워크 전환, VPN 연결, PAC 콘텐츠 갱신)을 여전히 실시간으로 추적해요.

인증 (Authentication)

업스트림 프록시가 인증을 요구한다면 sbx는 두 메커니즘을 지원해요.

프록시 URL의 자격 증명 (Credentials in the proxy URL)

프록시 URL에 자격 증명을 넣어요: HTTP·HTTPS 프록시에는 http://user:pass@host:port, SOCKS5에는 socks5://user:pass@host:port. 이것은 모든 플랫폼에서 동작하고 Basic 인증으로 도전하는 프록시를 덮어요.

통합 Windows 인증 (Integrated Windows authentication)

CONNECT에 407 도전으로 답하고 통합 체계(NTLM 또는 Kerberos/Negotiate)만 받는 프록시는 Windows 로그인 정체성으로 인증할 수 있어요. 이 기능은 선택이며 기본적으로 꺼져 있어요:

$ sbx settings set proxy.integratedAuth true

이 설정은 범위가 없어요: 샌드박스와 데몬 트래픽 모두에 적용돼요. 프록시가 여러 체계를 제공하면 Negotiate가 NTLM보다 선호되는 가장 강한 체계가 사용돼요. 변경은 다른 프록시 설정과 같은 일정을 따릅니다: 지원되는 CLI 클라이언트는 다음 호출에서, 샌드박스를 만들 때, 데몬 트래픽과 기존 샌드박스 프록시는 sbx daemon restart 후에 적용돼요.

여러분의 정체성은 호스트에 남아요. 업스트림 프록시에 대한 인증은 네트워크 정책이 이미 적용된 후 샌드박스 경계의 호스트 쪽에서 일어나므로, 자격 증명이 샌드박스에 들어가지 않고 샌드박스가 도달할 수 있는 목적지에는 아무것도 바뀌지 않아요.

이것은 Windows SSPI에 의존하므로 macOS나 Linux에서는 효과가 없어요. 그 플랫폼에서는 프록시 URL의 자격 증명이 유일한 옵션이에요.

  • Network isolation — 트래픽이 샌드박스를 떠나는 방식과 통과하는 네트워크 정책
  • Troubleshooting: API calls fail with a certificate error — 프록시가 HTTPS 트래픽을 검사할 때 내부 루트 CA 설치하기

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.