SageMaker Studio JupyterLab 環境でカスタムイメージを使用する際の問題のトラブルシューティング方法を教えてください。

所要時間3分

カスタムイメージを使用して Amazon SageMaker Studio JupyterLab 環境を構築するときに発生する問題をトラブルシューティングしたいと考えています。

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI のエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

アクセス許可を確認する

Amazon Elastic Container Registry (Amazon ECR) リポジトリにイメージをプッシュするには、適切な AWS Identity and Access Management (IAM) アクセス許可が必要です。

SageMaker Studio ユーザーのカスタム IAM ポリシーには、スペースの作成、画像の表示、一覧表示を行うための sagemaker.ListImage アクセス許可が含まれている必要があります。

WORKDIR Dockerfile 命令を使用する

SageMaker Studio に関連付けられている Amazon Elastic Block Store (Amazon EBS) ボリュームは /home/sagemaker-user にマウントされています。マウントパスは変更できません。カスタムイメージが /home/sagemaker-user 内で動作することを確認するには、/home/sagemaker-user 内のサブフォルダに WORKDIR Dockerfile 命令を追加して、イメージの作業ディレクトリを設定します。詳細については、Dockerdocs のウェブサイトの「WORKDIR」を参照してください。

注: カスタムイメージでは /opt/.sagemakerinternal、/opt/ml、または /var/log/studio の予約ディレクトリを使用しないでください。SageMaker AI はこれらのディレクトリを使用してメタデータとログを保存します。

Dockerfile の設定を確認する

次の Docker ファイルの例では、Python パッケージをインストールし、アクセス許可のないユーザーにスコープを設定します。

FROM public.ecr.aws/amazonlinux/amazonlinux:2

ARG NB_USER="sagemaker-user"
ARG NB_UID="1000"
ARG NB_GID="100"
RUN yum install —assumeyes python3 shadow-utils && \
useradd —create-home —shell /bin/bash —gid "${NB_GID}" —uid ${NB_UID} ${NB_USER} && \
yum clean all && \
python3 -m pip install jupyterlab

RUN python3 -m pip install —upgrade pip

RUN python3 -m pip install —upgrade urllib3==1.26.6

USER ${NB_UID}
CMD jupyter lab —ip 0.0.0.0 —port 8888 \
--ServerApp.base_url="/jupyterlab/default" \
--ServerApp.token='' \
--ServerApp.allow_origin='*'

ログを確認する

カスタムイメージを作成または起動するときに引き続き問題が発生する場合は、Amazon CloudWatch Logs の SageMaker AI Studio ログを確認してください。/aws/sagemaker/studio ロググループと domain-id/app-name/JupyterLab/default ログストリームでエラーメッセージを探してください。

ログで見つけたエラーメッセージに応じて、問題をトラブルシューティングしてください。

"NotFoundError" エラーメッセージを解決する

ユーザー ID (UID) とグループ ID (GID) の Docker 仕様とカスタムイメージ定義が一致しない場合、次のエラーメッセージが表示されます。

"NotFoundError: SageMaker is unable to launch the app using the image [Image ARN].Ensure that the UID/GID provided in the AppImageConfig matches the default UID/GID defined in the image."

ファイルシステムは sagemaker-user ユーザ名をサポートしています。SageMaker は 1000 の UID と 100 の GID をサポートしています。Dockerfile をビルドするときは、UID を 1000 に、GID を 100 に設定します。必要に応じて、ユーザーに sudo アクセス許可を付与してください。

この問題を解決するには、次の手順を実行します。

イメージをビルドしたら、次のコマンドを実行してユーザー設定を確認します。

docker run -it $IMAGE_URI

想定される出力:

UID=1000(sagemaker-user) GID=100(sagemaker-user) groups=100(sagemaker-user)

Dockerfile に JupyterLab サーバーを起動するために必要な設定が含まれていることを確認します。次の CMD Dockerfile 命令をファイルに追加します。

CMD jupyter lab —ip 0.0.0.0 —port 8888 \
 —ServerApp.base_url="/jupyterlab/default" \
  —ServerApp.token='' \
   —ServerApp.allow_origin='*'```

注: CMD 命令の詳細については、Dockerdocs のウェブサイトの「CMD」を参照してください。

AWS CLI コマンド describe-app-image-config を実行して、カスタムイメージの AppImageConfig に正しい UID と GID が割り当てられていることを確認します。
```
aws sagemaker describe-app-image-config —app-image-config-name APP-CONFIG-NAME
```
注: APP-CONFIG-NAME を、実際のアプリイメージ設定名に置き換えてください。SageMaker AI コンソールを使用してアプリイメージ設定を表示することもできます。
Docker イメージを再構築し、それを Amazon ECR に追加します。
JupyterLab スペースを再起動します。

"ContainerExecutionFailedError" エラーメッセージを解決する

SageMaker Studio で JupyterLab を使用するときに Dockerfile に必要な構成がない場合、次のエラーメッセージが表示されることがあります。

"Creating JupyterLab application for space: hc-test-new ContainerExecutionFailedError: SageMaker is unable to launch the app because the container entrypoint for image [43xxxxx0.dkr.ecr.eu-central-1.amazonaws.com/jupyterlab-custom-hc@sha256:bae93f0342ba56624b132159354a22d540d65d200a0624dae637a4c005b66789] is not configured correctly.Please change the entrypoint for the image or use a different image to launch the app.Output: [App container prematurely exited with status [exited], exit code [1], and error []."

この問題を解決するには、Dockerfile に以下の必要な設定を追加します。

Python 3.x を含むベースイメージを使用します。
次のコマンドを実行して JupyterLab をインストールします。
```
pip install jupyterlab
```

次の必須環境変数を設定します。

ENV SHELL=/bin/bash
ENV NB_USER=sagemaker-user
ENV NB_UID=1000
ENV NB_GID=100

SageMaker ユーザーがまだない場合は、次のコマンドを実行してユーザーを作成します。

useradd -m -s /bin/bash -N -u ${NB_UID} ${NB_USER}

次のコマンドを実行して作業ディレクトリを設定します。
```
WORKDIR ${HOME}
```
次のコマンドを実行してユーザーを設定します。
```
USER ${NB_USER}
```

次のコマンドを実行して、JupyterLab を実行するためのエントリポイントを設定します。

ENTRYPOINT ["jupyter-lab"]CMD ["—ServerApp.ip=0.0.0.0", "—ServerApp.port=8888", "—ServerApp.allow_origin=*", "—ServerApp.token=''", "—ServerApp.base_url=/jupyterlab/default"]

"400 ResourceNotFound" エラーメッセージを解決する

SageMaker Studio で画像が一致しない場合、次のエラーメッセージが表示されることがあります。

"[400] ResourceNotFound: Image with ARN arn:aws:sagemaker:us-east-1:123456789:image/codeeditor-image"

上記のエラーは、次の理由で発生する場合があります。

以前のイメージバージョンを削除したが、最初に SageMaker Studio からデタッチしなかった。
ドメイン設定内のイメージの Amazon リソースネーム (ARN) が、使用可能なイメージバージョンと一致しない。
参照イメージバージョンが AWS アカウントに存在しなくなった。

この問題を解決するには、次の手順を実行します。

イメージバージョンがアカウントに存在することを確認します。
イメージが SageMaker Studio に正しくアタッチされていることを確認します。

次の update-domain コマンドを実行して、最新の SageMaker Studio イメージに更新します。

aws sagemaker update-domain \
    --domain-id example-domain-name \
    --default-user-settings '{
        "JupyterLabAppSettings": {
            "CustomImages": [
                {
                    "ImageName": "example-image-name",
                    "ImageVersionNumber": example-image-version-number,
                    "AppImageConfigName": "example-domain-app-image-config-name"
                }
            ]
        },
        "CodeEditorAppSettings": {
            "CustomImages": [
                {
                    "ImageName": "cbi-ds-sagemaker-base-code-editor-v1-image",
                    "AppImageConfigName": "example-domain-app-image-config-name"
                }
            ]
        }
    }'

注: example-domain-name、example-image-name、example-image-version-number、example-domain-app-config-name を実際の設定の値に置き換えてください。