JSON 파일로 Settings Management 구성하기

JSON 파일로 Settings Management 구성하기 (Configure Settings Management with a JSON file)

admin-settings.json 파일을 사용해 조직 전체의 Docker Desktop 설정을 구성하고 강제하는 방법을 알려드릴게요.

출처: 문서

본문

Settings Management를 사용하면 admin-settings.json 파일로 조직 전반의 Docker Desktop 설정을 구성하고 강제할 수 있어요. 이렇게 하면 Docker Desktop 환경을 표준화하고 모든 사용자에게 일관된 구성을 보장할 수 있답니다.

구독: Business · 대상: 관리자

사전 요구사항

시작하기 전에 다음이 준비되어 있는지 확인하세요:

  • 조직에 대한 강제된 Sign-in (Enforce sign-in for your organization)
  • Docker Business 구독

admin-settings.json 파일이 있으면 Docker Desktop에서 sign-in이 강제돼요. 이는 인증이 필요한 비즈니스 기능을 위한 것이에요. 사용자가 로그인되어 있고 Docker Business 조직에 속해 있어야 해요. 두 조건 중 하나라도 충족되지 않으면 설정 파일은 무시됩니다.

1단계: 설정 파일 만들기

admin-settings.json 파일은 두 가지 방법으로 만들 수 있어요:

  1. --admin-settings 설치 플래그를 사용해 파일을 자동 생성:

  2. 수동으로 생성 (UTF-8 BOM 없이) 후 다음 위치에 배치:

    • Mac: /Library/Application Support/com.docker.docker/admin-settings.json
    • Windows: C:\ProgramData\DockerDesktop\admin-settings.json
    • Linux: /usr/share/docker-desktop/admin-settings.json

중요: 무단 변경을 방지하기 위해 보호된 디렉터리에 파일을 배치하세요. Jamf 같은 Mobile Device Management (MDM) 도구를 사용해 조직 규모로 파일을 배포하세요.

2단계: 설정 구성하기

팁: 사용 가능한 설정, 지원 플랫폼, 각 설정과 함께 동작하는 구성 방법의 전체 목록은 Settings reference에서 확인하세요.

admin-settings.json 파일은 구조화된 키를 사용해 구성 가능한 설정과 값이 강제되는지 여부를 정의해요.

각 설정은 사용자 권한을 제어하는 locked 필드를 지원해요:

  • locked가 true로 설정되면 사용자는 Docker Desktop, CLI, 또는 구성 파일에서 해당 값을 변경할 수 없어요.
  • locked가 false로 설정되면 값이 기본 제안(default suggestion)처럼 동작하고 사용자가 여전히 업데이트할 수 있어요.
  • 사용자가 settings-store.json, settings.json, 또는 daemon.json에서 해당 값을 이미 사용자 지정한 경우, locked가 false인 설정은 기존 설치에서 무시돼요.

그룹화된 설정 (Grouped settings)

Docker Desktop은 일부 설정을 단일 토글로 묶어 전체 섹션을 제어해요. 여기에는 다음이 포함돼요:

  • Enhanced Container Isolation (ECI): 전체 기능을 켜고 끄는 메인 토글(enhancedContainerIsolation)과 특정 구성용 하위 설정을 사용해요.
  • Kubernetes: 클러스터 구성용 하위 설정과 메인 토글(kubernetes.enabled)을 사용해요.
  • Docker Scout: scout 객체 아래에 설정을 그룹화해요.

그룹화된 설정을 구성할 때:

  1. 메인 토글을 설정해 기능을 활성화하세요.
  2. 그 그룹 안의 하위 설정을 구성하세요.
  3. 메인 토글을 잠그면 사용자는 그 그룹의 어떤 설정도 수정할 수 없어요.

enhancedContainerIsolation 예시:

"enhancedContainerIsolation": {
  "locked": true,  // This locks the entire ECI section
  "value": true,   // This enables ECI
  "dockerSocketMount": {  // These are sub-settings
    "imageList": {
      "images": ["docker.io/testcontainers/ryuk:*"]
    }
  }
}

예시 admin-settings.json 파일

다음 샘플은 일반적인 엔터프라이즈 설정이 구성된 admin-settings.json 파일이에요. 이 예시를 admin-settings.json 구성과 함께 템플릿으로 사용할 수 있어요:

{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false,
    "pac": "",
    "embeddedPac": ""
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac": "",
    "embeddedPac": "",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value": "{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value": "192.168.65.0/24"
    }
  },
  "kubernetes": {
    "locked": false,
    "enabled": false,
    "showSystemContainers": false,
    "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value": "{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path": "$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  },
  "enableInference": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCP": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCPPort": {
    "locked": true,
    "value": 12434
  },
  "enableInferenceCORS": {
    "locked": true,
    "value": ""
  },
  "enableInferenceGPUVariant": {
    "locked": true,
    "value": true
  },
  "portBindingBehavior": {
    "locked": true,
    "value": "default-port-binding"
  }
}

3단계: 설정 적용하기

설정은 Docker Desktop이 재시작되고 사용자가 로그인한 후에 적용돼요.

새 설치의 경우:

  1. Docker Desktop을 실행하세요.
  2. Docker 계정으로 로그인하세요.

기존 설치의 경우:

  1. Docker Desktop을 완전히 종료하세요.
  2. Docker Desktop을 다시 실행하세요.

중요: Docker Desktop을 완전히 종료하고 다시 열어야 해요. 메뉴에서 재시작하는 것만으로는 충분하지 않습니다.

admin-settings.json 구성

다음 표들은 admin-settings.json 파일에서 사용할 수 있는 모든 설정을 설명해요.

참고: 일부 설정은 플랫폼 전용이거나 최소 Docker Desktop 버전이 필요해요. 요구사항은 Version 열을 확인하세요.

일반 설정 (General settings)

파라미터 OS 설명
configurationFileVersion 구성 파일 형식의 버전을 지정해요.
analyticsEnabled 값이 false로 설정되면 Docker Desktop이 사용 통계를 Docker로 보내지 않아요.
disableUpdate 값이 true로 설정되면 Docker Desktop 업데이트 확인 및 알림이 비활성화돼요.
blockDockerLoad 값이 true로 설정되면 사용자는 더 이상 docker load를 실행할 수 없고, 시도하면 오류를 받아요.
displayedOnboarding 값이 true로 설정되면 온보딩 설문이 새 사용자에게 표시되지 않아요. false로 설정해도 효과가 없어요.
desktopTerminalEnabled 값이 false로 설정되면 개발자는 Docker 터미널로 호스트 머신과 상호작용하거나 Docker Desktop에서 직접 명령을 실행할 수 없어요.
exposeDockerAPIOnTCP2375 Windows 전용 지정된 포트에서 Docker API를 노출해요. 값이 true이면 Docker API가 포트 2375에 노출돼요. 참고: 이는 인증되지 않으므로 적절한 방화벽 규칙으로 보호되는 경우에만 활성화해야 해요.
silentModulesUpdate 값이 true로 설정되면 Docker Desktop이 재시작이 필요 없는 구성 요소를 자동으로 업데이트해요. 예: Docker CLI 또는 Docker Scout 구성 요소.

확장 (Extensions)

파라미터 OS 설명
extensionsEnabled 값이 false로 설정되면 Docker Extensions가 비활성화돼요.
onlyMarketplaceExtensions 값이 true로 설정되면 개발자는 명령줄로 다른 확장을 설치할 수 없어요.
extensionsPrivateMarketplace 값이 true로 설정되면 프라이빗 마켓플레이스가 활성화되어, 공개 Docker 마켓플레이스 대신 관리자가 정의하고 제어하는 콘텐츠에 Docker Desktop이 연결되도록 해요.
extensionsPrivateMarketplaceAdminContactURL 개발자가 프라이빗 마켓플레이스에서 새 확장을 요청할 수 있는 연락 링크를 정의해요.

파일 공유 및 에뮬레이션 (File sharing and emulation)

파라미터 OS 설명
filesharingAllowedDirectories 개발자가 파일 공유를 추가할 수 있는 경로를 지정해요. $HOME, $TMP, $TEMP를 경로 변수로도 허용해요. 경로를 추가하면 해당 하위 디렉터리도 허용돼요. sharedByDefault가 true로 설정되면 팩토리 리셋 시 또는 Docker Desktop이 처음 시작될 때 해당 경로가 추가돼요.
useVirtualizationFrameworkVirtioFS macOS 전용 값이 true로 설정되면 VirtioFS가 파일 공유 메커니즘으로 설정돼요. 참고: useVirtualizationFrameworkVirtioFS와 useGrpcfuse가 모두 true이면 VirtioFS가 우선합니다. 둘 다 false이면 최소 하나의 파일 공유 메커니즘이 활성화되어야 하므로 Docker Desktop이 오류와 함께 시작에 실패해요.
useGrpcfuse macOS 전용 값이 true로 설정되면 gRPC Fuse가 파일 공유 메커니즘으로 설정돼요.
useVirtualizationFrameworkRosetta macOS 전용 값이 true로 설정되면 Docker Desktop이 Apple Silicon에서 x86_64/amd64 바이너리 에뮬레이션을 가속화하기 위해 Rosetta를 켜요. 참고: 이는 또한 자동으로 "Use Virtualization framework"를 활성화해요.

Docker Scout

파라미터 OS 설명
scout useBackgroundIndexing을 false로 설정하면 이미지 저장소에 로드된 이미지의 자동 인덱싱이 비활성화돼요. sbomIndexing을 false로 설정하면 사용자가 Docker Desktop에서 이미지를 검사하거나 docker scout CLI 명령을 사용해 이미지를 인덱싱할 수 없게 돼요.

프록시 설정 (Proxy settings)

Docker Desktop에는 범위가 다른 두 가지 별개의 프록시 설정이 있어요:

  • proxy (App Proxy): Docker Desktop 호스트 수준 트래픽(Dekstop 애플리케이션, Docker CLI, 확장)을 관리해요. 또한 containersProxy가 명시적으로 구성되지 않았을 때 데몬의 폴백(fallback) 역할을 해요. containersProxy가 설정되면 proxy는 데몬 또는 컨테이너 트래픽에 역할을 하지 않아요.
  • containersProxy: 항상 docker image pull을 관리해요. 모든 docker image pull 및 Compose pull 작업은 PAC 파일 규칙을 포함해 containersProxy를 통과해요. 또한 transparentPorts가 구성되면 실행 중인 컨테이너의 아웃바운드 트래픽도 관리해요.
파라미터 OS 설명
proxy mode가 manual 대신 system으로 설정되면 Docker Desktop이 시스템에서 프록시 값을 가져오고 http, https, exclude에 설정된 값을 무시해요. 프록시 서버를 수동 구성하려면 mode를 manual로 변경하세요. 프록시 포트가 사용자 지정이면 http 또는 https 속성에 지정하세요. 예: "https": "http://myotherproxy.com:4321". exclude 속성은 프록시를 우회할 호스트와 도메인의 쉼표 구분 목록을 지정해요.
windowsDockerdPort Windows 전용 Windows Docker 데몬이 연결할 수 있도록 로컬에서 이 포트로 Docker Desktop의 내부 프록시를 노출해요. 0으로 설정하면 무작위 사용 가능 포트가 선택돼요. 값이 0보다 크면 그 정확한 값을 포트로 사용해요. 기본값은 -1이며 이는 옵션을 비활성화해요.
enableKerberosNtlm true로 설정하면 Kerberos 및 NTLM 인증이 활성화돼요. 기본값은 false입니다. 자세한 내용은 설정 문서를 참조하세요.
pac PAC 파일 URL을 지정해요. 예: "pac": "http://proxy/proxy.pac".
embeddedPac 내장 PAC(Proxy Auto-config) 스크립트를 지정해요. 예: "embeddedPac": "function FindProxyForURL(url, host) { return \"DIRECT\"; }". 이 설정은 HTTP, HTTPS, Proxy bypass, PAC 서버 URL보다 우선해요.

참고: 프록시 구성은 두 곳에 구성해야 하므로 특별한 경우예요:

  1. 조직의 Docker Home.
  2. Docker Desktop이 설치된 사용자 시스템.

사용자 머신에서는 admin-settings.json 파일을 통해 또는 Docker Desktop 설치 중 설치 플래그를 사용해 프록시를 구성하세요. 자세한 지침은 설치 가이드를 참조하세요. Docker Desktop이 사용자 sign-in을 완료하고 Docker Home에서 조직 설정을 가져오기 전에 어떤 프록시 서버를 사용해야 하는지 알아야 하므로 이 추가 구성이 필요해요.

컨테이너 프록시 (Container proxy)

파라미터 OS 설명
containersProxy docker image pull(항상 강제)과 실행 중인 컨테이너 아웃바운드 트래픽(transparentPorts가 설정된 경우 강제)의 프록시를 구성해요. 자세한 내용은 Air-Gapped Containers를 참조하세요.
pac PAC 파일 URL을 지정해요. 예: "pac": "http://containerproxy/proxy.pac".
embeddedPac 내장 PAC(Proxy Auto-config) 스크립트를 지정해요. 예: "embeddedPac": "function FindProxyForURL(url, host) { return \"PROXY 192.168.92.1:2003\"; }". 이 설정은 HTTP, HTTPS, Proxy bypass, PAC 서버 URL보다 우선해요.

Linux VM 설정

파라미터 OS 설명
linuxVM Linux VM 옵션과 관련된 파라미터 및 설정 - 편의를 위해 여기에 함께 그룹화했어요.
wslEngineEnabled Windows 전용 값이 true로 설정되면 Docker Desktop이 WSL 2 기반 엔진을 사용해요. 설치 시 --backend=<backend name> 플래그로 설정된 모든 것을 덮어써요.
dockerDaemonOptions 값이 true로 설정되면 Docker Engine 구성 파일의 옵션을 덮어써요. Docker Engine reference를 참조하세요. 보안을 위해 Enhanced Container Isolation이 활성화되면 몇 가지 구성 속성이 덮어써질 수 있다는 점에 유의하세요.
vpnkitCIDR *.docker.internal에 대한 vpnkit DHCP/DNS에 사용되는 네트워크 범위를 덮어써요.

Windows 컨테이너

파라미터 OS 설명
windowsContainers windowsContainers 옵션과 관련된 파라미터 및 설정 - 편의를 위해 여기에 함께 그룹화했어요.
dockerDaemonOptions Linux 데몬 구성 파일의 옵션을 덮어써요. Docker Engine reference를 참조하세요.

참고: 이 설정은 Docker Home을 통해 구성할 수 없어요.

Kubernetes 설정

파라미터 OS 설명
kubernetes enabled가 true로 설정되면 Docker Desktop 시작 시 Kubernetes 단일 노드 클러스터가 시작돼요. showSystemContainers가 true로 설정되면 Kubernetes 컨테이너가 Docker Desktop Dashboard와 docker ps 실행 시 표시돼요. imagesRepository 설정으로 Docker Desktop이 컨트롤 플레인 Kubernetes 이미지를 가져올 저장소를 지정할 수 있어요.

참고: imagesRepository를 Enhanced Container Isolation (ECI)과 함께 사용할 때는 다음 이미지를 ECI Docker 소켓 마운트 이미지 목록에 추가하세요:

  • [imagesRepository]/desktop-cloud-provider-kind:
  • [imagesRepository]/desktop-containerd-registry-mirror:

이 컨테이너들은 Docker 소켓을 마운트하므로 ECI 이미지 목록에 추가해야 해요. 그렇지 않으면 ECI가 마운트를 차단하고 Kubernetes가 시작되지 않아요.

네트워킹 설정 (Networking settings)

파라미터 OS 설명
defaultNetworkingMode Windows 및 Mac 전용 새 Docker 네트워크의 기본 IP 프로토콜을 정의해요: dual-stack(IPv4 + IPv6, 기본값), ipv4only, 또는 ipv6only.
dnsInhibition Windows 및 Mac 전용 컨테이너에 반환되는 DNS 레코드 필터링을 제어해요. 옵션: auto(권장), ipv4, ipv6, none.
portBindingBehavior Linux 기반 컨테이너 전용 포트 바인딩 제한과 기본 동작을 정의하여, 관리자가 사용자가 컨테이너에서 포트를 노출하는 방법을 제어하게 해줘요. 옵션: default-port-binding, default-local-port-binding, local-only-port-binding. Docker Desktop 버전 4.52 이상. 자세한 내용은 Networking을 참조하세요.

AI 설정

파라미터 OS 설명
enableInference enableInference를 true로 설정하면 Docker Model Runner가 활성화돼요.
enableInferenceTCP 호스트 측 TCP 지원을 활성화해요. 이 설정은 먼저 Docker Model Runner 설정이 활성화되어 있어야 해요.
enableInferenceTCPPort 노출된 TCP 포트를 지정해요. 이 설정은 먼저 Docker Model Runner 및 호스트 측 TCP 지원 설정이 활성화되어 있어야 해요.
enableInferenceCORS 허용된 CORS 오리진을 지정해요. 빈 문자열은 모두 거부, *는 모두 허용, 또는 쉼표 구분 값 목록. 이 설정은 먼저 Docker Model Runner 및 호스트 측 TCP 지원 설정이 활성화되어 있어야 해요.
enableInferenceGPUVariant Windows 전용 enableInferenceGPUVariant를 true로 설정하면 GPU 기반 추론이 활성화돼요. 이에 필요한 추가 구성 요소는 Docker Desktop에 기본 포함되지 않으므로 ~/.docker/bin/inference에 다운로드돼요.

베타 기능 (Beta features)

중요: Docker Desktop 버전 4.41 이하에서는 이러한 설정 중 일부가 Features in development 페이지의 Experimental features 탭에 있었어요.

파라미터 OS 설명
allowBetaFeatures 값이 true로 설정되면 베타 기능이 활성화돼요.
enableDockerAI allowBetaFeatures가 true이면 enableDockerAI를 true로 설정해 기본적으로 Gordon을 활성화해요. 이 설정은 allowBetaFeatures 설정과 독립적으로 제어할 수 있어요.
enableDockerMCPToolkit allowBetaFeatures가 true이면 enableDockerMCPToolkit을 true로 설정해 기본적으로 MCP Toolkit 기능을 활성화해요. 이 설정은 allowBetaFeatures 설정과 독립적으로 제어할 수 있어요.
allowExperimentalFeatures 값이 true로 설정되면 실험적 기능이 활성화돼요.

Enhanced Container Isolation

파라미터 OS 설명
enhancedContainerIsolation 값이 true로 설정되면 Docker Desktop이 Linux 사용자 네임스페이스를 통해 모든 컨테이너를 권한 없이(unprivileged) 실행하고, Docker Desktop VM 내부의 민감한 구성을 수정하지 못하게 하며, 다른 고급 기법으로 컨테이너를 격리해요. 자세한 내용은 Enhanced Container Isolation을 참조하세요.
dockerSocketMount 기본적으로 enhanced container isolation은 컨테이너로 Docker Engine 소켓의 bind-mount(예: docker run -v /var/run/docker.sock:/var/run/docker.sock ...)를 차단해요. 이 설정으로 이를 통제된 방식으로 완화할 수 있어요. 자세한 내용은 ECI Configuration을 참조하세요.
imageList Docker Engine 소켓을 bind-mount할 수 있는 컨테이너 이미지를 나타내요.
commandList 컨테이너가 bind-mount된 Docker Engine 소켓을 통해 실행할 수 있는 명령을 제한해요.

더 알아보기 (Learn more)