Merge pull request #24 from knaresh/improvdoc

Improve documentation to clarify How to update Image
aws-samples · Apr 12, 2022 · 7f8393f · 7f8393f
2 parents a0a0b16 + 23c70d6
commit 7f8393f
Show file tree

Hide file tree

Showing 8 changed files with 282 additions and 24 deletions.
diff --git a/examples/conda-env-kernel-image/README.md b/examples/conda-env-kernel-image/README.md
@@ -14,21 +14,26 @@ Build the Docker image and push to Amazon ECR.
 # Modify these as required. The Docker registry endpoint can be tuned based on your current region from https://docs.aws.amazon.com/general/latest/gr/ecr.html#ecr-docker-endpoints
 REGION=<aws-region>
 ACCOUNT_ID=<aws-account-id>
+IMAGE_NAME=conda-env-kernel
 
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
 
 # Build and push the image
-IMAGE_NAME=conda-env-kernel
 aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
 docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
 docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
 ```
 
 ### Using with SageMaker Studio
-
-Create a SageMaker Image (SMI) with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```bash
-# Role in your account to be used for SMI. Modify as required.
+# Role in your account to be used for SageMakerImage. Modify as required.
 
 ROLE_ARN=arn:aws:iam::${ACCOUNT_ID}:role/RoleName
 aws --region ${REGION} sagemaker create-image \
@@ -62,4 +67,30 @@ If you have an existing Domain, you can also use the `update-domain`
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
 ```
 
-Create a User Profile, and start a Notebook using the SageMaker Studio launcher.
+Create a User Profile, and start a Notebook using the SageMaker Studio launcher.
+
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
diff --git a/examples/echo-kernel-image/README.md b/examples/echo-kernel-image/README.md
@@ -11,10 +11,13 @@ Build the Docker image and push to Amazon ECR.
 # Modify these as required. The Docker registry endpoint can be tuned based on your current region from https://docs.aws.amazon.com/general/latest/gr/ecr.html#ecr-docker-endpoints
 REGION=<aws-region>
 ACCOUNT_ID=<account-id>
+IMAGE_NAME=custom-echo-kernel
 
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
 
 # Build the image
-IMAGE_NAME=custom-echo-kernel
 aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
 docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
 ```
@@ -25,7 +28,10 @@ docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAG
 
 ### Using with SageMaker Studio
 
-Create a SageMaker Image with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```
 # Role in your account to be used for the SageMaker Image
@@ -60,4 +66,31 @@ If you have an existing Domain, you can also use the `update-domain`
 
 ```
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
-```
+```
+
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
diff --git a/examples/jupyter-docker-stacks-julia-image/README.md b/examples/jupyter-docker-stacks-julia-image/README.md
@@ -12,10 +12,13 @@ Build the Docker image and push to Amazon ECR.
 # Modify these as required. The Docker registry endpoint can be tuned based on your current region from https://docs.aws.amazon.com/general/latest/gr/ecr.html#ecr-docker-endpoints
 REGION=<aws-region>
 ACCOUNT_ID=<aws-account-id>
+IMAGE_NAME=julia-datascience
 
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
 
 # Build the image
-IMAGE_NAME=julia-datascience
 aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
 docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
 ```
@@ -26,7 +29,10 @@ docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAG
 
 ### Using with SageMaker Studio
 
-Create a SageMaker Image (SMI) with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```
 # Role in your account to be used for SMI. Modify as required.
@@ -65,4 +71,30 @@ If you have an existing Domain, you can also use the `update-domain`
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
 ```
 
-Now create a user, and start a Notebook using the SageMaker Studio launcher 
+Now create a user, and start a Notebook using the SageMaker Studio launcher 
+
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
diff --git a/examples/python-poetry-image/README.md b/examples/python-poetry-image/README.md
@@ -11,20 +11,25 @@ Build the Docker image and push to Amazon ECR.
 # Modify these as required. The Docker registry endpoint can be tuned based on your current region from https://docs.aws.amazon.com/general/latest/gr/ecr.html#ecr-docker-endpoints
 REGION=<aws-region>
 ACCOUNT_ID=<account-id>
+IMAGE_NAME=custom-poetry-kernel
+
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
 
 # Build the image
-IMAGE_NAME=custom-poetry-kernel
 aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
 docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
-```
 
-```
 docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
 ```
 
 ### Using it with SageMaker Studio
 
-Create a SageMaker Image with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```
 # Role in your account to be used for the SageMaker Image
@@ -61,7 +66,33 @@ If you have an existing Domain, you can use the `update-domain` command.
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
 ```
 
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
+
 ### Notes
 
 * Since SageMaker Studio overrides `ENTRYPOINT` and `CMD` instructions (see [documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-byoi-specs.html)), this sample disables the Poetry virtual environments as recommended in their [FAQ](https://python-poetry.org/docs/faq/#i-dont-want-poetry-to-manage-my-virtual-environments-can-i-disable-it). 
-* Note that `ipykernel` must be installed on custom images for SageMaker Studio. If this package is not installed by default on the parent image, then it should be included in the `pyproject.toml` file. 
+* Note that `ipykernel` must be installed on custom images for SageMaker Studio. If this package is not installed by default on the parent image, then it should be included in the `pyproject.toml` file. 
diff --git a/examples/r-image/README.md b/examples/r-image/README.md
@@ -16,6 +16,10 @@ Build the Docker image and push to Amazon ECR.
 REGION=<aws-region>
 ACCOUNT_ID=<account-id>
 
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
+
 
 # Build the image
 IMAGE_NAME=custom-r
@@ -29,7 +33,10 @@ docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAG
 
 ### Using with SageMaker Studio
 
-Create a SageMaker Image with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```
 # Role in your account to be used for the SageMaker Image
@@ -64,4 +71,30 @@ If you have an existing Domain, you can also use the `update-domain`
 
 ```
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
-```
+```
+
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
diff --git a/examples/rapids-image/README.md b/examples/rapids-image/README.md
@@ -14,6 +14,10 @@ Build the Docker image and push to Amazon ECR.
 REGION=<aws-region>
 ACCOUNT_ID=<account-id>
 
+# Create ECR Repository. Ignore if it exists. For simplcity, all examples in the repo
+# use same ECR repo with different image tags
+aws --region ${REGION} ecr create-repository --repository-name smstudio-custom
+
 
 # Build the image
 IMAGE_NAME=custom-rapids
@@ -38,7 +42,10 @@ sm-docker build .
 ```
 
 
-Create a SageMaker Image with the image in ECR. 
+Create a SageMaker Image (SMI) with the image in ECR. Request parameter RoleArn value is used to get
+ECR image information when and Image version is created. After creating Image, create an Image Version during which 
+SageMaker stores image metadata like SHA etc. Everytime an image is updated in ECR, a new image version should be created.
+See [Update Image](#updating-image-with-sageMaker-studio)
 
 ```
 # Role in your account to be used for the SageMaker Image
@@ -75,6 +82,32 @@ If you have an existing Domain, you can also use the `update-domain`
 aws --region ${REGION} sagemaker update-domain --cli-input-json file://update-domain-input.json
 ```
 
+### Update Image with SageMaker Studio
+If you found an issue with your image or want to update Image with new features, Use following steps
+
+Re-Build and push the image to ECR
+
+```
+# Build and push the image
+aws --region ${REGION} ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom
+docker build . -t ${IMAGE_NAME} -t ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}
+```
+
+
+Create new App Image Version.
+```
+aws --region ${REGION} sagemaker create-image-version \
+    --image-name ${IMAGE_NAME} \
+    --base-image "${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/smstudio-custom:${IMAGE_NAME}"
+
+# Verify the image-version is created successfully. Do NOT proceed if image-version is in CREATE_FAILED state or in any other state apart from CREATED.
+aws --region ${REGION} sagemaker describe-image-version --image-name ${IMAGE_NAME}
+```
+
+
+Re-Create App in SageMaker studio. 
+
 ### Note
 
 - Please use the included `Python [conda env:rapids]' kernel within Studio