Update documentation for version 2.0

Author: ivan-khvostishkov

Flow_Diagrams.md

@@ -2,17 +2,24 @@
 
 - [Training job with SSM](#training-job-with-ssm)
 - [Training job with SSH](#training-job-with-ssh)
+- [Local IDE to SageMaker Studio to with SSH](#local-ide-to-sagemaker-studio-to-with-ssh)
 
 #### Training job with SSM
 
 This flow corresponds to the [Connecting to SageMaker training jobs with SSM](README.md#training) procedure.
 
-![Screenshot](images/Flow_Train_SSM.png)
+![Screenshot - Training job with SSM](images/Flow_Train_SSM.png)
 
 
 #### Training job with SSH
 
 This flow corresponds to the [Remote code execution with PyCharm / VSCode over SSH](README.md#remote-interpreter) procedure.
 
-![Screenshot](images/Flow_Train_SSH.png)
+![Screenshot - Training job with SSH](images/Flow_Train_SSH.png)
 
+
+#### Local IDE to SageMaker Studio to with SSH
+
+This flow corresponds to the [Local IDE integration with SageMaker Studio over SSH for PyCharm / VSCode](README.md#studio) procedure.
+
+![Screenshot - Local IDE to SageMaker Studio to with SSH](images/Flow_IDE.png)

images/Flow_IDE.png

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Commands:
-# connect <kernel_gateway_name> [--ssh-only] [--domain <domain-id>] [--user <profile-name>] [<extra_ssh_args>]
+# connect <kernel_gateway_name> [--ssh-only] [<extra_ssh_args>]
 # run-command <command> <args...>
 # TODO: create <kernel_gateway_name> [--recreate] --domain <domain> --user <profile-name> --image datascience-1.0 --instance ml.t3.medium
 # TODO: list (all apps from all users and domains marked with '*' if can connect with SSH and with '!' if user don't match)

images/Flow_Train_SSH.png

@@ -0,0 +1,204 @@
+See https://pdf.plantuml.net/PlantUML_Language_Reference_Guide_en.pdf
+
+@startuml
+actor Developer as dev
+participant "SageMaker SSH Helper \n library (local)" as sm_ssh_helper_local
+participant "Amazon SageMaker Studio" as sagemaker_studio
+participant "VPC \n private or managed" as vpc
+participant "SageMaker SSH Helper \n library (remote)" as sm_ssh_helper_remote
+participant "SSH server" as ssh
+participant "SSM agent" as ssm_agent
+participant "AWS Systems Manager \n (SSM)" as ssm
+participant "IAM" as iam
+
+dev -> sagemaker_studio: Create kernel gateway app
+note left of dev
+Ex.:
+Data Science 2.0
+end note
+
+sagemaker_studio -> vpc: Start containers
+activate vpc
+vpc -> vpc: Start kernel gateway
+note left vpc
+jupyter kernelgateway
+end note
+activate vpc
+
+
+dev -> vpc: Run life-cycle configuration
+note left of dev
+kernel-lc-config.sh
+end note
+
+dev -> vpc: Alternatively, run IDE notebook
+note left of dev
+SageMaker_SSH_IDE.ipynb
+end note
+
+
+vpc -> sm_ssh_helper_remote: Setup IDE
+activate vpc
+
+activate sm_ssh_helper_remote
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Print connect metadata
+
+note left sm_ssh_helper_remote
+sm-ssh-ide
+get-metadata
+end note
+
+sm_ssh_helper_remote --> dev:
+
+note right dev
+App name: sagemaker-data-science-ml-m5-large-1234567890abcdef0
+User profile name: terry-whitlock
+Domain: d-egm0dexample
+end note
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Configure and \n install IDE libs
+note left sm_ssh_helper_remote
+sm-ssh-ide
+configure
+end note
+
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Configure and \n install SSH libs
+activate sm_ssh_helper_remote
+note right sm_ssh_helper_remote
+sm-setup-ssh
+configure
+end note
+deactivate sm_ssh_helper_remote
+
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Initialize SSM
+activate sm_ssh_helper_remote
+note left sm_ssh_helper_remote
+sm-ssh-ide
+init-ssm
+end note
+
+note right sm_ssh_helper_remote
+sm-init-ssm
+end note
+sm_ssh_helper_remote -> ssm: Create activation
+sm_ssh_helper_remote -> ssm_agent: Register
+ssm_agent -> ssm:
+note right ssm_agent
+mi-01234567890abcdef
+end note
+ssm --> ssm_agent:
+deactivate sm_ssh_helper_remote
+
+note left sm_ssh_helper_remote
+sm-ssh-ide
+start
+end note
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Save environment \n for remote shell
+note right sm_ssh_helper_remote
+sm-save-env
+end note
+
+sm_ssh_helper_remote -> ssh: Start SSH server
+activate ssh
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Start VNC and \n Jupyter server
+
+
+sm_ssh_helper_remote -> ssm_agent: Start SSM agent
+note left sm_ssh_helper_remote
+sm-ssh-ide
+ssm-agent
+end note
+activate ssm_agent
+ssm_agent -> ssm: Go online
+
+
+note right dev
+sm-local-ssh-ide set-domain d-egm0dexample
+sm-local-ssh-ide set-user terry-whitlock
+end note
+
+note right dev
+sm-local-ssh-ide connect sagemaker-data-science-ml-m5-large-1234567890abcdef0
+end note
+dev -> sm_ssh_helper_local: Connect
+sm_ssh_helper_local -> sm_ssh_helper_local: Get instance IDs
+sm_ssh_helper_local -> ssm: List and filter instances
+sm_ssh_helper_local -> sm_ssh_helper_local: Repeat until successful \n or timeout
+
+note right sm_ssh_helper_local
+mi-01234567890abcdef, ...
+end note
+
+activate sm_ssh_helper_local
+note right sm_ssh_helper_local
+sm-connect-ssh-proxy mi-01234567890abcdef
+end note
+sm_ssh_helper_local -> sm_ssh_helper_local: Generate SSH key pair
+sm_ssh_helper_local -> ssm: Copy SSH public key through S3
+
+ssm -> iam: Check SendCommand \n permissions
+ssm -> ssm_agent: Run command
+ssm_agent -> ssm_agent: Copy key from S3
+sm_ssh_helper_local -> ssm: Start SSH session proxy \n over SSM
+
+ssm -> iam: Check StartSession \n permissions
+
+ssm -> ssm_agent: Start SSH session
+ssm_agent -> ssm_agent: Start SSH proxy tunnel
+ssm_agent --> sm_ssh_helper_local:
+sm_ssh_helper_local -> ssm_agent: Start SSH port forwarding \n over SSM proxy tunnel
+ssm_agent -> ssh: Start SSH proxy \n tunnel session
+activate ssh
+
+
+dev -> dev: Connect from IDE
+activate dev
+note right dev
+ssh sagemaker-studio
+end note
+dev -> ssh: Connect with SSH through forwarded SSH port
+ssh --> dev:
+
+dev -> vpc: Run and debug code remotely with IDE
+deactivate dev
+
+dev -> vpc: Open Jupyter \n in browser
+dev -> vpc: Connect with \n VNC client
+
+...Development is in progress...
+
+dev -> sm_ssh_helper_remote: Interrupt notebook kernel and stop services
+
+note left sm_ssh_helper_remote
+sm-ssh-ide
+stop
+end note
+
+sm_ssh_helper_remote -> ssm_agent: Stop SSM agent
+deactivate ssm_agent
+
+sm_ssh_helper_remote -> ssh: Stop SSH server
+deactivate ssh
+
+deactivate ssh
+
+sm_ssh_helper_remote -> sm_ssh_helper_remote: Stop VNC and \n Jupyter server
+
+deactivate vpc
+deactivate sm_ssh_helper_remote
+
+dev -> vpc: Stop app
+
+
+
+deactivate vpc
+
+deactivate vpc
+deactivate sm_ssh_helper_local
+
+@enduml

sagemaker_ssh_helper/sm-local-ssh-ide

@@ -38,6 +38,10 @@ dev -> sagemaker: Create training job \n (fit estimator)
 note left of dev
 sourcedir.tar.gz
 end note
+sagemaker --> dev:
+note right of dev
+Job name: ssh-training-example-2023-07-25-03-18-04-490
+end note
 
 sagemaker -> vpc: Start containers
 note left vpc
@@ -61,6 +65,11 @@ activate vpc
 activate sm_ssh_helper_remote
 
 sm_ssh_helper_remote -> sm_ssh_helper_remote: Configure and \n install libs
+note left sm_ssh_helper_remote
+sm-setup-ssh
+configure
+end note
+
 sm_ssh_helper_remote -> sm_ssh_helper_remote: Save environment \n for remote shell
 note left sm_ssh_helper_remote
 sm-save-env
@@ -95,7 +104,7 @@ sm-wait
 end note
 
 note right dev
-sm-local-ssh-training connect <training_job_name>
+sm-local-ssh-training connect ssh-training-example-2023-07-25-03-18-04-490
 end note
 dev -> sm_ssh_helper_local: Connect
 sm_ssh_helper_local -> sm_ssh_helper_local: Get instance IDs