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

# 建立自訂 RStudio 映像
<a name="rstudio-byoi-create"></a>

**重要**  
允許 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 建立 Amazon SageMaker 資源的自訂 IAM 政策也必須授與許可，才能將標籤新增至這些資源。需要將標籤新增至資源的許可，因為 Studio 和 Studio Classic 會自動標記它們建立的任何資源。如果 IAM 政策允許 Studio 和 Studio Classic 建立資源，但不允許標記，則在嘗試建立資源時可能會發生 "AccessDenied" 錯誤。如需詳細資訊，請參閱[提供標記 SageMaker AI 資源的許可](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
提供許可來建立 SageMaker 資源的 [AWS Amazon SageMaker AI 的 受管政策](security-iam-awsmanpol.md) 已包含建立這些資源時新增標籤的許可。

此主題說明如何使用 SageMaker AI 主控台和 AWS CLI建立自訂 RStudio 映像。如果您使用 AWS CLI，則必須從本機電腦執行這些步驟。下列步驟無法從 Amazon SageMaker Studio Classic 內運作。

當您建立映像時，SageMaker AI 也會建立一個初始映像版本。每個映像版本代表存放在 [Amazon Elastic 容器登錄檔 (ECR)](https://console.aws.amazon.com/ecr/) 中的容器映像。容器映像必須在 RStudio 中使用的要求。如需詳細資訊，請參閱[自訂 RStudio 映像規格](rstudio-byoi-specs.md)。

如需本機測試映像和解決常見問題的相關資訊，請參閱 [SageMaker Studio 自訂映像範例儲存庫](https://github.com/aws-samples/sagemaker-studio-custom-image-samples/blob/main/DEVELOPMENT.md)。

**Topics**
+ [將 SageMaker AI 相容 RStudio Docker 容器映像新增至 Amazon ECR](#rstudio-byoi-sdk-add-container-image)
+ [從主控台建立 SageMaker 映像](#rstudio-byoi-create-console)
+ [從 建立映像 AWS CLI](#rstudio-byoi-create-cli)

## 將 SageMaker AI 相容 RStudio Docker 容器映像新增至 Amazon ECR
<a name="rstudio-byoi-sdk-add-container-image"></a>

請使用下列步驟，將 Docker 容器映像新增至 Amazon ECR：
+ 建立 Amazon ECR 儲存庫。
+ 向 Amazon ECR 進行身分驗證。
+ 建立 SageMaker AI 相容 RStudio Docker 映像檔。
+ 將映像推送至 Amazon ECR 儲存庫。

**注意**  
Amazon ECR 儲存庫必須與網域 AWS 區域 位於相同的 中。

**若要建置並新增 Docker 映像至 Amazon ECR**

1. 使用 AWS CLI命令在 Amazon ECR 儲存庫中建立儲存庫。若要使用 Amazon ECR 主控台建立儲存庫，請參閱[建立儲存庫](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html)。

   ```
   aws ecr create-repository \
       --repository-name rstudio-custom \
       --image-scanning-configuration scanOnPush=true
   ```

   回應：

   ```
   {
       "repository": {
           "repositoryArn": "arn:aws:ecr:us-east-2:acct-id:repository/rstudio-custom",
           "registryId": "acct-id",
           "repositoryName": "rstudio-custom",
           "repositoryUri": "acct-id.dkr.ecr.us-east-2.amazonaws.com/rstudio-custom",
           ...
       }
   }
   ```

1. 使用從 `create-repository` 命令做為回應傳回的儲存庫 URI，向 Amazon ECR 進行身分驗證。確定 Docker 應用程式為執行中。如需詳細資訊，請參閱[登錄檔身分驗證](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html#registry_auth)。

   ```
   aws ecr get-login-password | \
       docker login --username AWS --password-stdin <repository-uri>
   ```

   回應：

   ```
   Login Succeeded
   ```

1. 建置 Docker 影像。從包含 Dockerfile 的目錄執行以下命令。

   ```
   docker build .
   ```

1. 使用唯一標籤標記您的建置映像。

   ```
   docker tag <image-id> "<repository-uri>:<tag>"
   ```

1. 將容器映像推送至 Amazon ECR 儲存庫。如需詳細資訊，請參閱 [ImagePush](https://docs.docker.com/engine/api/v1.40/#operation/ImagePush) 和[推送映像](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html)。

   ```
   docker push <repository-uri>:<tag>
   ```

   回應：

   ```
   The push refers to repository [<account-id>.dkr.ecr.us-east-2.amazonaws.com/rstudio-custom]
   r: digest: <digest> size: 3066
   ```

## 從主控台建立 SageMaker 映像
<a name="rstudio-byoi-create-console"></a>

**建立映像**

1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 在左側導覽窗格中，選擇**管理員組態**。

1. 在**管理員組態**下，選擇**映像**。

1. 在**自訂映像**頁面中，選擇**建立映像**。

1. 對於**映像來源**，請在 Amazon ECR 中輸入容器映像的登錄檔路徑。路徑格式如下。

   ` acct-id.dkr.ecr.region.amazonaws.com/repo-name[:tag] or [@digest] `

1. 選擇**下一步**。

1. 在**映像屬性**下，輸入下列內容：
   + 映像名稱 – 在目前 AWS 區域中，名稱必須是您帳戶中唯一的。
   + (選用) 影像顯示名稱 – 顯示在網域使用者介面中的名稱。如果未提供，`Image name` 則會顯示出來。
   + (選用) 描述 – 映像的一項描述。
   + IAM 角色 – 該角色必須以連接 [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) 政策。使用下拉式選單，選取下列其中一個選項：
     + 建立新角色 — 指定您希望筆記本使用者可以存取的任何其他 Amazon Simple Storage Service (Amazon S3) 儲存貯體。如果您不想允許其他儲存貯體的存取，請選擇**無**。

       SageMaker AI 會將 `AmazonSageMakerFullAccess` 政策連接到角色。此角色可讓您的筆記本使用者存取核取記號旁列出的 Amazon S3 儲存貯體。
     + 輸入自訂 IAM 角色 ARN — 輸入 IAM 角色的 Amazon Resource Name (ARN)。
     + 使用現有角色 — 從清單中選擇一個現有角色。
   + (選用) 映像標籤 — 選擇**新增標籤**。您最多可以新增 50 個標籤。可以使用 SageMaker AI 主控台或 SageMaker AI `Search` API 來搜尋標籤。

1. 在**映像類型**下，選取 RStudio 映像。

1. 選擇**提交**。

新映像會顯示在**自訂映像**清單中並以重點標示。已成功建立映像後，您可以選擇映像名稱來檢視其屬性，或選擇**建立版本**建立其他版本。

**若要建立其他映像版本**

1. 在與映像相同的行上選擇**建立版本**。

1. 對於**映像來源**，請輸入 Amazon ECR 映像的登錄檔路徑。該映像不應與先前版本的 SageMaker AI 映像中使用的映像相同。

若要在 RStudio 中使用自訂映像，您必須將其連接至您的網域。如需詳細資訊，請參閱[連接自訂 SageMaker 映像。](rstudio-byoi-attach.md)。

## 從 建立映像 AWS CLI
<a name="rstudio-byoi-create-cli"></a>

本節將示範如何使用 AWS CLI建立自訂 Amazon SageMaker 映像。

使用下列步驟建立 SageMaker 映像：
+ 建立 `Image`。
+ 建立 `ImageVersion`。
+ 建立一個程式組態檔案。
+ 建立 `AppImageConfig`。

**若要建立 SageMaker 映像實體**

1. 建立一個 SageMaker 映像。角色 ARN 至少必須已連接 `AmazonSageMakerFullAccessPolicy` 政策。

   ```
   aws sagemaker create-image \
       --image-name rstudio-custom-image \
       --role-arn arn:aws:iam::<acct-id>:role/service-role/<execution-role>
   ```

   回應：

   ```
   {
       "ImageArn": "arn:aws:sagemaker:us-east-2:acct-id:image/rstudio-custom-image"
   }
   ```

1. 從映像建立 SageMaker 映像版本。將映像推送到 Amazon ECR 時，傳遞您選擇的唯一標籤值。

   ```
   aws sagemaker create-image-version \
       --image-name rstudio-custom-image \
       --base-image <repository-uri>:<tag>
   ```

   回應：

   ```
   {
       "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/rstudio-image/1"
   }
   ```

1. 檢查映像版本是否已成功建立。

   ```
   aws sagemaker describe-image-version \
       --image-name rstudio-custom-image \
       --version 1
   ```

   回應：

   ```
   {
       "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/rstudio-custom-image/1",
       "ImageVersionStatus": "CREATED"
   }
   ```
**注意**  
如果回應為 `"ImageVersionStatus": "CREATED_FAILED"`，則回應也會包含失敗原因。許可問題是導致失敗的常見原因。您也可以檢查您的 Amazon CloudWatch Logs。日誌群組的名稱為 `/aws/sagemaker/studio`。日誌串流的名稱為 `$domainID/$userProfileName/KernelGateway/$appName`。

1. 建立名為 `app-image-config-input.json` 的組態檔案。應用程式映像組態用於配置做為核心閘道應用程式執行 SageMaker 映像。

   ```
   {
       "AppImageConfigName": "rstudio-custom-config"
   }
   ```

1. 使用建立於上一步的檔案來建立 AppImaage 組態。

   ```
   aws sagemaker create-app-image-config \
       --cli-input-json file://app-image-config-input.json
   ```

   回應：

   ```
   {
       "AppImageConfigArn": "arn:aws:sagemaker:us-east-2:acct-id:app-image-config/r-image-config"
   }
   ```