Controller Node

The controller node is an EC2 host deployed by SOCA to provide:

Web interface
Nodes provisioning mechanisms,
Analytics scripts and general automation
OpenLDAP server (if not using Active Directory)
Scheduler (OpenPBS)

This is the brain of your SOCA environment and you most likely will never have to change anything on the boostrap sequence unless you are planning to do specific customizations based on your own corporate environment requirements.

Your controller can be deployed on Intel, AMD or Graviton instance type. No further configuration is needed, as SOCA will automatically detect the architecture and install relevant packages (e.g x86_64 vs aarch64). Modifications can only be done prior to launching a new SOCA installation.

Bootstrap Code:¶

Bootstrap code is located inside the installer/resources/user_data/controller/ folder

01_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. This script only prepare the machine by installing/upgrading awscli and mounting the relevant filesystem. Finally, the machine will download 02_checkprerequisite script and execute it.

02_prerequisites¶

This script contains additional actions that could not make it to 01_user_data due to UserData size limitation. It contains some variables that are populated at CDK launch, but will wait until CloudFormation stack is created as some variable needed by 03_setup does not exist until the deployment is completed (e.g: ControllerPrivateHostname is not known at CDK install time as the Controller Instance does not exist yet)

03_setup¶

This is the final setup script which will take care of final operations (e.g: install scheduler packages, join the host to OpenLDAP or Active Directory etc ...).

Bootstrap Sequence¶

sequenceDiagram
  autonumber
  SOCA Admin->>installer/resources/src/cdk_construct.py: Launch soca_installer.sh
  loop
     installer/resources/src/cdk_construct.py->>installer/resources/src/cdk_construct.py: Render 01_user_data.sh from 01_user_data.sh.j2 
  end 
  Note right of installer/resources/src/cdk_construct.py: Template rendered using Jinja2
  loop
     installer/resources/src/cdk_construct.py->>installer/resources/src/cdk_construct.py: Render 02_prerequisites.sh from 02_prerequisites.sh.j2 
  end 
  Note right of installer/resources/src/cdk_construct.py: Template rendered using Jinja2

  installer/resources/src/cdk_construct.py->>Amazon S3: Upload 02_prerequisites.sh
  installer/resources/src/cdk_construct.py->>Amazon S3: Upload 03_setup.sh.j2
  installer/resources/src/cdk_construct.py->>EC2 Controller Node: Launch EC2 Controller Node and assign 01_user_data.sh as UserData
   loop
      EC2 Controller Node->>EC2 Controller Node: Execute 01_user_data.sh
  end 
  EC2 Controller Node->>Amazon S3: Download 02_prerequisites.sh
  loop
      EC2 Controller Node->>EC2 Controller Node: Execute 02_prerequisites.sh
  end 
  EC2 Controller Node->>Amazon S3: Download 03_setup.sh.j2
  loop
      EC2 Controller Node->>EC2 Controller Node: Render 03_setup.sh
      EC2 Controller Node->>EC2 Controller Node: Execute 03_setup.sh

  end

Info

Final setup.sh is rendered from 03_setup.sh.j2 using Jinja2 via /apps/soca/<CLUSTER_ID>/cluster_manager/tools/j2generator

Bootstrap Flow¶

Here is an high-level overview of the entire bootstrap flow generated by the scripts mentioned above:

  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--Controller Node-->F[Controller Extra Scripts];
      F-->G[Common scripts];
      G-->H[Controller Node Ready]

Customize Controller Bootstrap Code¶

We recommend you to add your customizations to 03_setup.sh.j2. Do not edit 01_user_data.sh.j2 unless you can confirm the rendered file will be less than 16kb after your modifications.

Any UserData bigger than 16kb will cause CDK to exit, and you will need to restart the installation.

Modifications can only be done before installing a new SOCA environment.

View Controller 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

02_prerequisite.sh and 03_setup.sh logs can be found on /root folder.