本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 開始使用本機模式
<a name="studio-updated-local-get-started"></a>

下列各節概述在 Amazon SageMaker Studio 中開始使用本機模式所需的步驟，包括：
+ 完成先決條件
+ 設置 `EnableDockerAccess`
+ Docker安裝

## 先決條件
<a name="studio-updated-local-prereq"></a>

完成下列先決條件，以在 Studio 應用程式中使用本機模式：
+ 若要從 Amazon Elastic Container Registry 儲存庫提取映像，託管 Amazon ECR 映像的帳戶必須為使用者的執行角色提供存取許可。網域的執行角色也必須允許 Amazon ECR 存取。
+ 使用以下命令，確認您使用的是最新版的 Studio Python SDK： 

  ```
  pip install -U sagemaker
  ```
+ 若要使用本機模式和 Docker 功能，請使用 AWS Command Line Interface (AWS CLI) 設定網域 `DockerSettings` 的下列參數： 

  ```
  EnableDockerAccess : ENABLED
  ```
+ 使用 `EnableDockerAccess`，您也可以使用控制網域中的使用者是否可以使用本機模式。根據預設，Studio 應用程式中不允許本機模式和 Docker 功能。如需詳細資訊，請參閱[設置 `EnableDockerAccess`](#studio-updated-local-enable)。
+ 遵循 [Docker安裝](#studio-updated-local-docker-installation)中的步驟，在 Studio 應用程式中安裝 Docker CLI。
+ 針對 [無根 Docker 組態](#studio-updated-local-rootless)，請確定您的 VPC 具有針對所需 Docker 登錄檔設定的適當端點和路由。

## 設置 `EnableDockerAccess`
<a name="studio-updated-local-enable"></a>

下列各節說明如何在網域具有公有網際網路存取或處於 `VPC-only` 模式時設定 `EnableDockerAccess`。

**注意**  
對 `EnableDockerAccess` 的變更僅適用於網域更新後建立的應用程式。更新網域後，您必須建立新的應用程式。

**公有網際網路存取**

下列範例命令展示如何在建立新網域或使用公有網際網路存取更新現有網域時設定 `EnableDockerAccess`：

```
# create new domain
aws --region region \
    sagemaker create-domain --domain-name domain-name \
    --vpc-id vpc-id \
    --subnet-ids subnet-ids \
    --auth-mode IAM \
    --default-user-settings "ExecutionRole=execution-role" \
    --domain-settings '{"DockerSettings": {"EnableDockerAccess": "ENABLED"}}' \
    --query DomainArn \
    --output text

# update domain
aws --region region \
    sagemaker update-domain --domain-id domain-id \
    --domain-settings-for-update '{"DockerSettings": {"EnableDockerAccess": "ENABLED"}}'
```

**`VPC-only` 模式**

在 `VPC-only` 模式下使用網域時，Docker 映像推送和提取請求會透過服務 VPC 路由，而不是客戶設定的 VPC。由於此功能，管理員可以設定受信任 AWS 帳戶 的清單，使用者可以向其提出 Amazon ECR Docker 提取和推送操作請求。

如果 Docker向 AWS 帳戶 不在信任清單中的 發出映像推送或提取請求 AWS 帳戶，則請求會失敗。`VPC-only`模式不支援在 Amazon Elastic Container Registry (Amazon ECR) 外部Docker提取和推送操作。

預設 AWS 帳戶 會信任下列項目：
+ 託管 SageMaker AI 網域的帳戶。
+ 託管下列 SageMaker 映像的 SageMaker AI 帳戶：
  + DLC 架構映像
  + Sklearn、Spark、XGBoost 處理映像

若要設定其他信任的清單 AWS 帳戶，請指定 `VpcOnlyTrustedAccounts`值，如下所示：

```
aws --region region \
    sagemaker update-domain --domain-id domain-id \
    --domain-settings-for-update '{"DockerSettings": {"EnableDockerAccess": "ENABLED", "VpcOnlyTrustedAccounts": ["account-list"]}}'
```

**注意**  
啟用 [無根 Docker 組態](#studio-updated-local-rootless) 時，`VpcOnlyTrustedAccounts` 會被忽略，而且 Docker 流量會透過您的 VPC 組態路由，從而允許存取您的 VPC 可連線的任何登錄檔。

## 無根 Docker 組態
<a name="studio-updated-local-rootless"></a>

啟用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DockerSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DockerSettings.html) 時，Studio 會使用[無根 Docker 常駐程式](https://docs.docker.com/engine/security/rootless/)，透過 VPC 路由流量。這可提供增強的安全性，並允許存取其他 Docker 登錄檔。與 `RootlessDocker` 的主要差異為：
+ 您的 VPC 組態會決定哪些登錄檔可供 Docker 操作存取。`VpcOnlyTrustedAccounts` 會被忽略，而 Docker 流量會透過您的 VPC 組態路由。

若要使用無根 Docker，您需要為 `DockerSettings` 同時將 `EnableDockerAccess` 和 `RootlessDocker` 設定為 `ENABLED`。例如，在上述 [設置 `EnableDockerAccess`](#studio-updated-local-enable) 範例中，您可以修改網域設定以包含：

```
'{"DockerSettings": {"EnableDockerAccess": "ENABLED", "RootlessDocker": "ENABLED"}}'
```

## Docker安裝
<a name="studio-updated-local-docker-installation"></a>

若要使用 Docker，您必須從 Studio 應用程式的終端手動安裝 Docker。如果網域可存取網際網路，則安裝 Docker 的步驟會有所不同。

### 網際網路存取
<a name="studio-updated-local-docker-installation-internet"></a>

如果網域是在具有公有網際網路存取的情況下或在網際網路存取受限的 `VPC-only` 模式下建立，請使用下列步驟來安裝 Docker。

1. (選用) 如果您的網域是在網際網路存取受限的 `VPC-only` 模式下建立，請建立可存取 Docker 網站的公有 NAT 閘道。如需指示，請參閱 [NAT 閘道](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。

1. 導覽至您要在其中安裝 Docker 的 Studio 應用程式終端機。

1. 若要返回應用程式的作業系統，請從終端執行下列命令：

   ```
   cat /etc/os-release
   ```

1. 遵循 [Amazon SageMaker AI 本機模式範例儲存庫](https://github.com/aws-samples/amazon-sagemaker-local-mode/tree/main/sagemaker_studio_docker_cli_install)中應用程式作業系統的指示安裝 Docker。

   例如，在 Ubuntu 上安裝 Docker 時，請遵循 [https://github.com/aws-samples/amazon-sagemaker-local-mode/blob/main/sagemaker\$1studio\$1docker\$1cli\$1install/sagemaker-ubuntu-focal-docker-cli-install.sh](https://github.com/aws-samples/amazon-sagemaker-local-mode/blob/main/sagemaker_studio_docker_cli_install/sagemaker-ubuntu-focal-docker-cli-install.sh) 中的指令碼，並考量下列事項：
   + 如果鏈結的命令失敗，請一次執行一個命令。
   + Studio 僅支援 Docker 版本 `20.10.X.` 和 Docker Engine API 版本 `1.41`。
   + 在 Studio 中使用 Docker CLI 不需要下列套件，而且可以略過其安裝：
     + `containerd.io`
     + `docker-ce`
     + `docker-buildx-plugin`
**注意**  
您不需要在應用程式中啟動 Docker 服務。根據預設，託管 Studio 應用程式的執行個體會執行 Docker 服務。所有 Docker API 呼叫都是自動透過 Docker 服務路由。

1. 使用公開的 Docker 通訊端進行 Studio 應用程式內的 Docker 互動。根據預設，會公開下列通訊端：

   ```
   unix:///docker/proxy.sock
   ```

   預設 `USER` 的下列 Studio 應用程式環境變數會使用此公開的通訊端：

   ```
   DOCKER_HOST
   ```

### 沒有網際網路存取
<a name="studio-updated-local-docker-installation-no-internet"></a>

如果網域是在沒有網際網路存取的 `VPC-only` 模式下建立，請使用下列步驟來安裝 Docker。

1. 導覽至您要在其中安裝 Docker 的 Studio 應用程式終端機。

1. 從終端執行下列命令，以返回應用程式的作業系統：

   ```
   cat /etc/os-release
   ```

1. 將必要的 Docker `.deb` 檔案下載到您的本機電腦。如需下載 Studio 應用程式作業系統所需檔案的相關指示，請參閱[安裝 Docker 引擎](https://docs.docker.com/engine/install/)。

   例如，遵循[從套件安裝](https://docs.docker.com/engine/install/ubuntu/#install-from-a-package)中的步驟 1–4，從 Ubuntu 上的套件安裝 Docker，並考量下列事項：
   + 從套件安裝 Docker。使用其他方法安裝 Docker 將會失敗。
   + 安裝對應至 Docker 版本 `20.10.X` 的最新套件。
   + 下列套件不需要在 Studio 中使用 Docker CLI。您不需要安裝下列項目：
     + `containerd.io`
     + `docker-ce`
     + `docker-buildx-plugin`
**注意**  
您不需要在應用程式中啟動 Docker 服務。根據預設，託管 Studio 應用程式的執行個體會執行 Docker 服務。所有 Docker API 呼叫都是自動透過 Docker 服務路由。

1. 將 `.deb` 檔案上傳至 Amazon EFS 檔案系統或應用程式的 Amazon EBS 檔案系統。

1. 從 Studio 應用程式終端手動安裝 `docker-ce-cli` 和 `docker-compose-plugin` `.deb` 套件。如需詳細資訊和指示，請參閱 Docker 文件網站上的[從套件安裝](https://docs.docker.com/engine/install/ubuntu/#install-from-a-package)中的步驟 5。

1. 使用公開的 Docker 通訊端進行 Studio 應用程式內的 Docker 互動。根據預設，會公開下列通訊端：

   ```
   unix:///docker/proxy.sock
   ```

   預設 `USER` 的下列 Studio 應用程式環境變數會使用此公開的通訊端：

   ```
   DOCKER_HOST
   ```