업스트림 프록시 구성하기

업스트림 프록시 구성하기

업스트림 프록시는 Docker Sandboxes가 인터넷으로 나가는 아웃바운드 트래픽을 전달할 때 통과시키는 회사 또는 네트워크 프록시예요. 이것은 어떤 대상이 허용되는지 결정하는 네트워크 정책과는 별개예요. 업스트림 프록시는 허용된 트래픽이 어떻게 대상에 도달하는지를 결정해요.

출처: 문서

본문

이 페이지는 로컬 샌드박스와 로컬 데몬의 프록시 설정을 다뤄요. 클라우드 샌드박스 이그레스 제어는 Cloud network policy를 참고해요.

중요: 업스트림 프록시 지원은 실험적이에요. 이 페이지에서 설명하는 모든 것 — 프록시 URL, PAC 파일, SOCKS5, OS 시스템 프록시 사용, 프록시 인증, 그리고 이를 구성하는 설정 — 은 변경될 수 있어요. 피드백과 버그 리포트는 docker/sbx-releases 저장소에 공유해요.

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

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

기본 동작 (Default behavior)

기본적으로 두 종류의 트래픽 모두 운영체제의 프록시 설정을 사용해요. 여기에는 그곳에 구성된 PAC URL도 포함돼요. 별도로 구성할 필요가 없어요. macOS와 Windows에서 sbx는 실행 중에 OS 프록시 설정을 추적하므로, 네트워크·VPN·PAC 구성이 바뀌어도 재시작 없이 반영돼요. OS에 프록시가 구성되어 있지 않으면 트래픽은 직접(direct) 나가요.

수동으로 프록시 설정하기

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

프록시 값은 다음 중 하나일 수 있어요.

값 의미
(설정 안 함) 더 넓은 범위로 폴백한 뒤 환경 변수, 그리고 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(프록시 자동 구성) 파일
system OS 시스템 프록시 강제 사용
direct 프록시 없는 직접 연결 강제

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

프록시에서 제외할 대상

제외 목록은 같은 범위를 반영해요. 각각 호스트, 도메인 접미사, 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. Direct

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

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

변경이 적용되는 시점

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

  • 샌드박스 범위(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_* 환경 변수는 별개의 경우예요. 위 "환경 변수"에서 설명한 대로 샌드박스 트래픽만 제어하지만, sbx는 데몬이 시작할 때 데몬의 환경에서 이를 읽으므로, 변경하려면 데몬 재시작도 필요해요. 이 변수 중 하나가 저장된 설정을 덮어쓰면, 저장된 설정이 적용되도록 변수를 해제하고 데몬을 재시작해요.

시스템 또는 PAC 프록시를 사용 중일 때도 sbx는 OS 수준 프록시 변경(네트워크 전환, VPN 연결, PAC 내용 업데이트 등)을 실시간으로 추적해요.

인증 (Authentication)

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

프록시 URL의 자격 증명

자격 증명을 프록시 URL에 넣어요. HTTP·HTTPS 프록시는 http://user:pass@host:port, SOCKS5는 socks5://user:pass@host:port의 형태예요. 이 방식은 모든 플랫폼에서 동작하며 Basic 인증으로 챌린지하는 프록시를 다뤄요.

통합 Windows 인증

CONNECT에 407 챌린지로 응답하고 통합 스킴(NTLM 또는 Kerberos/Negotiate)만 받아들이는 프록시는, 대신 Windows 로그인 신원으로 당신을 인증할 수 있어요. 이것은 옵트인이며 기본적으로 꺼져 있어요.

$ sbx settings set proxy.integratedAuth true

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

신원은 호스트에 남아 있어요. 업스트림 프록시에 대한 인증은 네트워크 정책이 이미 적용된 뒤, 샌드박스 경계의 호스트 쪽에서 일어나므로, 어떤 자격 증명도 샌드박스에 들어가지 않으며 샌드박스가 도달할 수 있는 대상도 바뀌지 않아요.

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

  • 네트워크 격리 — 트래픽이 어떻게 샌드박스를 떠나고 통과하는 네트워크 정책인지
  • 문제 해결: API 호출이 인증서 오류로 실패 — 프록시가 HTTPS 트래픽을 검사할 때 내부 루트 CA 설치하기

더 알아보기 (Learn more)