Skip to content

Virtual Desktop Node

A Virtual Desktop Node (also known as DCV Node) is a machine deployed for Virtual Desktop (Linux or Windows).

Linux Virtual Desktop:

Bootstrap Code:

user_data

Important

User Data is limited to 16kb size. It's not recommended to change the content of this file.

This is the default EC2 User Data generated at instance launch via CDK and is located inside the installer/resources/user_data/login_node/ folder. This script only prepare the machine by installing/upgrading awscli and performing some filesystem operations.

The script will wait for the filesystem to be fully operational and CloudFormation stack to be completed, then render and execute /apps/soca/CLUSTER_ID/cluster_node_bootstrap/compute_node/setup.sh script.

Note

The first Login Node is launched during the SOCA install. Because of that, there is some loop that wait for the Controller to create the filesystem hierarchy. This loop is only effective for the very first login node deployed.

Add your own customization to /apps/soca/CLUSTER_ID/cluster_node_boostrap/windows_virtual_desktop/setup.ps.j2. Windows templates can be found under /apps/soca/CLUSTER_ID/cluster_node_boostrap/templates/windows

setup.sh

This file is responsible for the main setup phase of your node. Template is located on /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node. This file can be updated post-SOCA deployment.

setup_post_reboot.sh

This file is responsible for the main setup phase and is executed after the first reboot triggered by setup.sh. Template is located on /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node. This file can be updated post-SOCA deployment.

extra/virtual_desktop.sh

This file is responsible for installing Amazon DCV and the Graphical environment (MATE, Gnome) on your node. Template is located on /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node. This file can be updated post-SOCA deployment.

setup_user_customization.sh

This file is the perfect place if you want to add your own set of configuration while not touching the existing node bootstrap sequence. Template is located on /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node. You can update this file post-SOCA deployment.

Bootstrap Sequence

sequenceDiagram
  autonumber
  SOCA User->>dcv_cloudformation_builder.py: Request a new Linux Virtual Desktop
  loop
     dcv_cloudformation_builder.py->>dcv_cloudformation_builder.py: Render UserData from user_data.sh.j2 
     dcv_cloudformation_builder.py->>dcv_cloudformation_builder.py: Render setup.sh script from setup.sh.j2 
     dcv_cloudformation_builder.py->>dcv_cloudformation_builder.py: Render setup_post_reboot.sh script from setup_post_reboot.sh.j2 
     dcv_cloudformation_builder.py->>dcv_cloudformation_builder.py: Render setup_user_customizations.sh script from setup_user_customizations.sh.j2 
  end 
  Note right of dcv_cloudformation_builder.py: Rendered templates are stored on cluster_node_boostrap/logs/compute_node/<job_id>/
  dcv_cloudformation_builder.py->>EC2 Virtual Desktop  Node: Launch EC2 Virtual Desktop Nodea nd assign UserData
  loop
      EC2 Virtual Desktop  Node->>EC2 Virtual Desktop  Node: Execute UserData
      EC2 Virtual Desktop  Node->>EC2 Virtual Desktop  Node: Execute setup.sh script
      EC2 Virtual Desktop  Node->>EC2 Virtual Desktop  Node: Execute setup_post_reboot.sh script
      EC2 Virtual Desktop  Node->>EC2 Virtual Desktop  Node: Execute setup_user_customizations.sh script
  end

Info

setup.sh is rendered from /apps/soca/CLUSTER_ID/cluster_node_bootstrap/compute_node/setup.sh.j2 using Jinja2 via /apps/soca/<CLUSTER_ID>/cluster_manager/tools/j2generator

Note

Unlike HPC/Virtual Desktop nodes, there is no PostReboot actions for login nodes, as actions performed via /apps/soca/CLUSTER_ID/cluster_node_bootstrap/compute_node/setup_post_reboot.sh are specific to HPC jobs of Virtual destkop nodes.

Bootstrap Flow

  graph TD;
      A[SOCA EC2 Node Provisioned] --> B{Architecture?};
      B-- x86_64 -->C[Install x86_64 packages];
      B-- aarch64 -->D[Install aarch64 packages];
      C-->E{Check Node Type};
      D-->E;
      E--Virtual Desktop Node-->G[Virtual Desktop Node Extra Scripts];
      G-->H[Common scripts];
      H-->I[Virtual Desktop  Ready]

Capacity Provisioning

Here is the entire capacity provisioned flow after a virtual desktop is requested from web ui

  graph TD;
      A[Virtual Desktop is requested] --> B[SOCA Launch CloudFormation stack via **api/v1/dcv/create_~ linux windows ~_desktop.py**];
      B-->C{Capacity is provisioned?};
      C--noo-->D[Wait];
      C--yes-->E[Virtual Desktop state is automatically updated via **api/v1/dcv/create_desktop.py***];
      E-->F[Virtual Desktop is ready];
      F-.->G[User decide to terminate the session];
      G-->H[CloudFormation Stack is deleted via  **api/v1/dcv/create_~ linux windows ~_desktop.py**];

Customize Login Node Bootstrap Code

We recommend you to add your customizations to /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node/setup_user_customization.sh.j2. Alternatively, you can update /apps/soca/CLUSTER_ID/cluster_node_boostrap/compute_node/setup.sh.j2.

This file is common to HPC nodes, Virtual Desktop nodes and Login Nodes. Use the following condition if you want to limit your changes to only apply to Login Nodes:

{% if context.get("/job/NodeType") == "dcv_node" %}
  echo "This code is only executed on Linux Virtual Desktop (dcv) Node"
{% endif %}

Danger - Read me

Modifying a file under /cluster_node_boostrap has immediate effect and will not require any service restart.

Any error in your script may prevent SOCA to successfully provision capacity. If you suspect an error, check the logs mentioned below.

Always create a backup of the file before modifying it.

Do not edit 01_user_data.sh.j2 unless you can confirm the rendered file will be less than 16kb after your modifications.

If you need to edit the UserData post-SOCA deployment, navigate to EC2 Console > Launch Template and create a new version of the Login Node launch template using the updated UserData.

View Virtual Desktop Node Logs

Depending the operating system, UserData log can be found on the same host under:

  • /var/log/cloud-init.log
  • /var/log/cloud-init-output.log
  • /var/log/message

setup.sh logs can be found on the shared filesystem: /apps/soca/CLUSTER_ID/cluster_node_boostrap/logs/dcv_node

Windows

Bootstrap sequence for Windows Virtual Desktop is managed by powershell scripts available on /apps/soca/CLUSTER_ID/cluster_node_boostrap/windows_virtual_desktop:

Bootstrap Code:

setup.ps

On Windows, this file file combine both UserData and the entire node boostrap sequence.

Customize Virtual Desktop Node Bootstrap Code

Add your own customization to /apps/soca/CLUSTER_ID/cluster_node_boostrap/windows_virtual_desktop/setup.ps.j2. Windows templates can be found under /apps/soca/CLUSTER_ID/cluster_node_boostrap/templates/windows

View Virtual Desktop Node Logs

Run the following powershell command to access the boostrap logs stored on the Virtual Desktop Node

  • User Data: Get-Content C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log
  • SOCA Bootstrap Log: Get-Content C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecutionSOCA.log