Ansible Roles ============= Documentation for NSP ansible roles. -------------------------------------------------------------------------------- .. _aocc_role: aocc ---- `Description` ^^^^^^^^^^^^^ Installs the AOCC compiler and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_AOCC_version_variable: ``NSP_AOCC_version`` """""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_AOCC_create_module_variable: ``NSP_AOCC_create_module`` """""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. .. _NSP_AOCC_clear_source_variable: ``NSP_AOCC_clear_source`` """"""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Clear previous build source files. -------------------------------------------------------------------------------- .. _codee_role: codee ----- `Description` ^^^^^^^^^^^^^ Installs Codee and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_CODEE_version_variable: ``NSP_CODEE_version`` """"""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_CODEE_license_file_variable: ``NSP_CODEE_license_file`` """""""""""""""""""""""""" :Type: **str** :Required: **true** :Description: This variable specifies which license file codee should use. License files should be placed in ``"{{ [NSP_install_root, 'codee/licenses'] | path_join }}"``. .. _NSP_CODEE_create_module_variable: ``NSP_CODEE_create_module`` """"""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. -------------------------------------------------------------------------------- .. _cuda_role: cuda ---- `Description` ^^^^^^^^^^^^^ Installs CUDA and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_CUDA_version_variable: ``NSP_CUDA_version`` """""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_CUDA_driver_variable: ``NSP_CUDA_driver`` """"""""""""""""""" :Type: **str** :Required: **true** :Description: The Nvidia driver version specified in the download URL. .. _NSP_CUDA_architecture_variable: ``NSP_CUDA_architecture`` """"""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"linux"`` :Description: The CUDA architecture specified in the download URL. .. _NSP_CUDA_create_module_variable: ``NSP_CUDA_create_module`` """""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. -------------------------------------------------------------------------------- .. _files_role: files ----- `Description` ^^^^^^^^^^^^^ Deploys files and directories to specified locations. All of the source files should be stored in your ``playbook`` directory under a folder called ``files``. `Variables` ^^^^^^^^^^^ .. _NSP_FILES_inventory_variable: ``NSP_FILES_inventory`` """"""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``[]`` :Description: Mapping of file/directories and their target locations. Each entry is a dictionary that takes two mandatory keys ``src`` and ``dest`` and one optional key ``file_permissions``. ``file_permissions`` overrides the value of :ref:`NSP_file_permissions_variable` for a given entry. .. code:: yaml NSP_FILES_inventory: - src: dest: file_permissions: -------------------------------------------------------------------------------- .. _gcc_role: gcc --- `Description` ^^^^^^^^^^^^^ Installs GCC and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_GCC_version_variable: ``NSP_GCC_version`` """"""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_GCC_enabled_languages_variable: ``NSP_GCC_enabled_languages`` """"""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``["c", "c++", "fortran"]`` :Description: The languages that the build will support. .. _NSP_GCC_create_module_variable: ``NSP_GCC_create_module`` """"""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. .. _NSP_GCC_clear_source_variable: ``NSP_GCC_clear_source`` """""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Clear previous build source files. -------------------------------------------------------------------------------- .. _init_role: init ---- `Description` ^^^^^^^^^^^^^ The init role initializes the system init scripts and adds your content to them. To add contents, create a directory called ``init`` in the directory that contains your playbook. In the ``init`` directory create the files ``profile.j2`` and ``cshrc.j2`` with your desired content. .. note:: The ``init`` directory and accompanying files are completely optional. Without them, blank init scripts will be created. `Variables` ^^^^^^^^^^^ .. _NSP_INIT_wipe_variable: ``NSP_INIT_wipe`` """"""""""""""""" :Type: **bool** :Required: **false** :Default: ``false`` :Description: Wipe and recreate the init scripts on every run. -------------------------------------------------------------------------------- .. _llvm_role: llvm ---- `Description` ^^^^^^^^^^^^^ Installs LLVM and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_LLVM_version_variable: ``NSP_LLVM_version`` """""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_LLVM_projects_variable: ``NSP_LLVM_projects`` """"""""""""""""""""" :Type: **list** :Required: **false** :Default: ``["clang", "lld", "openmp", "compiler-rt"]`` :Description: LLVM projects to build. .. _NSP_LLVM_runtimes_variable: ``NSP_LLVM_runtimes`` """"""""""""""""""""" :Type: **list** :Required: **false** :Default: ``["libcxx", "libcxxabi", "libunwind"]`` :Description: Library runtimes to build. .. _NSP_LLVM_create_module_variable: ``NSP_LLVM_create_module`` """""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. .. _NSP_LLVM_clear_source_variable: ``NSP_LLVM_clear_source`` """"""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Clear previous build source files. -------------------------------------------------------------------------------- .. _lmod_role: lmod ---- `Description` ^^^^^^^^^^^^^ The lmod role configures and under certain circumstances installs lmod. The main part of the configuration is for a lmod hook that can be configured to look for modules in spack projections and add paths to ``MODULEPATH`` when appropriate. It also supports having custom lmod `rc.lua `_, `admin.list `_, and `lmodrc.lua `_ files. These files should be placed in a directory named ``lmod`` that resides with your system playbook. .. note:: The ``lmod`` directory and accompanying files are completely optional. If no template files are provided the lmod role will skip generating them. In the same directory you may also place additional Lmod hooks. These hooks will only be copied if they are registered with :ref:`NSP_LMOD_additional_hooks_variable`. `Variables` ^^^^^^^^^^^ .. _NSP_LMOD_install_type_variable: ``NSP_LMOD_install_type`` """"""""""""""""""""""""" :Type: **str** :Required: **true** :Allowed Values: ``["internal", "external"]`` :Description: This toggles the lmod role installing its own Lmod or using an external installation. .. _NSP_LMOD_version_variable: ``NSP_LMOD_version`` """""""""""""""""""" :Type: **str** :Required: **false** :Description: The version to install (only applies if :ref:`NSP_LMOD_install_type_variable` = ``internal``). .. _NSP_LMOD_enable_tcl_variable: ``NSP_LMOD_enable_tcl`` """"""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``false`` :Description: Build support for tcl module files (only applies if :ref:`NSP_LMOD_install_type_variable` = ``internal``). .. _NSP_LMOD_default_module_paths_variable: ``NSP_LMOD_default_module_paths`` """"""""""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``[]`` :Description: List of paths to add to ``MODULEPATH`` (only applies if :ref:`NSP_LMOD_install_type_variable` = ``internal``). .. note:: The path in ``NSP_module_root`` will automatically be added. So, there is no need to add it to ``NSP_LMOD_default_module_paths``. .. _NSP_LMOD_DefApps_modules_variable: ``NSP_LMOD_DefApps_modules`` """""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``[]`` :Description: A list of modules to load in the ``DefApps`` module. .. note:: If you are installing lmod with NSP then the ``DefApps`` module will be set to load automatically. If you are using an external lmod installation you will have to configure loading ``DefApps`` outside of NSP by setting the ``LMOD_SYSTEM_DEFAULT_MODULES`` environment variable. .. _NSP_LMOD_hierarchy_root_variable: ``NSP_LMOD_hierarchy_root`` """"""""""""""""""""""""""" :Type: **path** :Required: **false** :Default: ``"{{ [NSP_install_root, 'spack/modules'] | path_join }}"`` :Description: Root path of the module hierarchy. .. _NSP_LMOD_hierarchy_variable: ``NSP_LMOD_hierarchy`` """""""""""""""""""""" :Type: **dict** :Required: **false** :Default: ``{}`` :Description: This variable holds a list of components for module projections. For example: .. code:: yaml NSP_LMOD_hierarchy: compiler: members: ['gcc', 'llvm'] paths: - {path: '|compiler.name|-|compiler.version|', weight: 20} - {path: '|mpi.name|-|mpi.version|/|compiler.name|-|compiler.version|', weight: 30} level: 0 mpi: members: ['openmpi', 'mpich'] paths: - {path: '|mpi.name|-|mpi.version|/|compiler.name|-|compiler.version|', weight: 30} level: 1 Notice the two components named ``compiler`` and ``mpi``. Each component has a list of ``members``. These members are the names of modules that belong to that component. In the module files for these members, they should share the same ``family("...")`` so that they are mutually exclusive. For each component we also define a list of ``paths``. These paths template the paths that the hook should add/remove from ``MODULEPATH``. Take for example the first path defined for compiler. If ``gcc/12.3.0`` were loaded then ``|compiler.name|-|compiler.version|`` would become ``gcc-12.3.0``. These paths are combined with :ref:`NSP_LMOD_hierarchy_root_variable` to create the final path to add to ``MODULEPATH``. If :ref:`NSP_LMOD_enable_spack_compiler_projections_variable` is set then additional parts are added to the path to accommodate spack's automatic additions for compiler and version. Each path also has an associated ``weight``. The last item in each component is ``level`` which sets the order that the different component members are printed in the lmod header for ``module avail``. .. _NSP_LMOD_nv_mappings_variable: ``NSP_LMOD_nv_mappings`` """""""""""""""""""""""" :Type: **dict** :Required: **false** :Default: ``{}`` :Description: Converts module names to their package names in spack. For example: .. code:: yaml NSP_LMOD_nv_mappings: gcc-native/12.3.0: {name: 'gcc', version: '%s'} # maps to gcc/12.3.0 llvm/18.1.3: {name: 'clang', version: '%s-gfortran12'} # %s substitutes in the value from the system module Sometimes, spack uses a different name for a package than the system does. For example, on Cray systems we now have ``gcc-native`` but spack just uses ``gcc``. By default the hook will not pick up on the difference. In order to fix this problem you can define an entry here that will remap a module name to the spack equivalent. .. _NSP_LMOD_enable_spack_compiler_projections_variable: ``NSP_LMOD_enable_spack_compiler_projections`` """""""""""""""""""""""""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles the addition of paths in the hook that Spack adds in module projections for compiler and version. .. caution:: When in doubt (and using with Spack), leave this variable with its default value. .. _NSP_LMOD_path_names_variable: ``NSP_LMOD_path_names`` """"""""""""""""""""""" :Type: **dict** :Required: **false** :Default: ``[]`` :Description: Defines lmod section header names for paths that meet the specified regexes. For example: .. code:: yaml NSP_LMOD_path_names: /opt/cray: "[ Cray Programming Environment ]" All modules that reside somewhere under ``/opt/cray`` will appear in the ``[ Cray Programming Environment ]`` section when using ``module avail``. .. _NSP_LMOD_enable_logging_variable: ``NSP_LMOD_enable_logging`` """"""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``false`` :Description: Enable logging of module loads. .. _NSP_LMOD_logging_url_variable: ``NSP_LMOD_logging_url`` """""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"http://localhost:8080/"`` :Description: API URL to send module loads to. .. _NSP_LMOD_additional_hooks_variable: ``NSP_LMOD_additional_hooks`` """"""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``[]`` :Description: A list of additional hooks to activate. Additional hooks must be located in the playbook directory under a sub-directory called ``lmod``. The hook files must be named ``.lua.j2``. -------------------------------------------------------------------------------- .. _miniforge3_role: miniforge3 ---------- `Description` ^^^^^^^^^^^^^ The miniforge3 role installs miniforge3 with the specified packages in the base environment. And optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_MINIFORGE3_version_variable: ``NSP_MINIFORGE3_version`` """""""""""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_MINIFORGE3_revision_variable: ``NSP_MINIFORGE3_revision`` """"""""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"0"`` :Description: The version revision to install. .. _NSP_MINIFORGE3_base_packages_variable: ``NSP_MINIFORGE3_base_packages`` """""""""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``[]`` :Description: A list of packages to install in the base environment. .. _NSP_MINIFORGE3_clean_install_variable: ``NSP_MINIFORGE3_clean_install`` """""""""""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Delete installer and re-download. .. _NSP_MINIFORGE3_create_module_variable: ``NSP_MINIFORGE3_create_module`` """""""""""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. -------------------------------------------------------------------------------- .. _nsp_role: nsp --- `Description` ^^^^^^^^^^^^^ This is a meta role that sets up needed infrastructure for the other NSP roles. `Variables` ^^^^^^^^^^^ .. _NSP_system_name_variable: ``NSP_system_name`` """"""""""""""""""" :Type: **str** :Required: **true** :Description: The system's name. .. _NSP_help_email_variable: ``NSP_help_email`` """""""""""""""""" :Type: **str** :Required: **true** :Description: Help email. .. _NSP_site_name_variable: ``NSP_site_name`` """"""""""""""""" :Type: **str** :Required: **true** :Description: Name of HPC site. .. _NSP_install_root_variable: ``NSP_install_root`` """""""""""""""""""" :Type: **path** :Required: **false** :Default: ``"{{ ['/sw', NSP_system_name] | path_join }}"`` :Description: The path prefix to NSP installed software. .. _NSP_module_root_variable: ``NSP_module_root`` """"""""""""""""""" :Type: **path** :Required: **false** :Default: ``"{{ [NSP_install_root, 'modules'] | path_join }}"`` :Description: The path prefix to NSP software modules. .. _NSP_max_threads_variable: ``NSP_max_threads`` """"""""""""""""""" :Type: **int** :Required: **false** :Default: ``"{{ [((ansible_processor_nproc * 0.75) | int | abs), 16] | min }}"`` :Description: Number of threads to use when building software. .. _NSP_scratch_directory_variable: ``NSP_scratch_directory`` """"""""""""""""""""""""" :Type: **path** :Required: **false** :Default: ``"{{ ['/tmp', ansible_user_id] | path_join }}"`` :Description: Scratch directory to perform builds in. .. _NSP_keep_scratch_clear_variable: ``NSP_keep_scratch_clear`` """""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``false`` :Description: Toggle retention of scratch directory contents after builds. .. _NSP_user_variable: ``NSP_user`` """""""""""" :Type: **str** :Required: **false** :Default: ``"{{ ansible_user_uid }}"`` :Description: The unix user for software installations. .. _NSP_group_variable: ``NSP_group`` """"""""""""" :Type: **str** :Required: **false** :Default: ``"{{ ansible_user_gid }}"`` :Description: The unix group for software installation. .. _NSP_file_permissions_variable: ``NSP_file_permissions`` """""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"644"`` :Description: The unix permissions for files (non-executables). .. _NSP_executable_permissions_variable: ``NSP_executable_permissions`` """""""""""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"755"`` :Description: The unix permissions for executables (including folders). .. _NSP_architecture_variable: ``NSP_architecture`` """""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"{{ ansible_architecture }}"`` :Description: Hardware architecture to target. -------------------------------------------------------------------------------- .. _nvhpc_role: nvhpc ----- `Description` ^^^^^^^^^^^^^ Installs NVHPC SDK and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_NVHPC_version_variable: ``NSP_NVHPC_version`` """"""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_NVHPC_cuda_version_variable: ``NSP_NVHPC_cuda_version`` """""""""""""""""""""""""" :Type: **str** :Required: **false** :Default: ``"multi"`` :Description: SDK CUDA version(s). .. _NSP_NVHPC_create_module_variable: ``NSP_NVHPC_create_module`` """"""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. -------------------------------------------------------------------------------- .. _oneapi_role: oneapi ------ `Description` ^^^^^^^^^^^^^ Installs Intel's OneAPI and optionally generates a module file. `Variables` ^^^^^^^^^^^ .. _NSP_ONEAPI_version_variable: ``NSP_ONEAPI_version`` """""""""""""""""""""" :Type: **str** :Required: **true** :Description: The version to install. .. _NSP_ONEAPI_base_toolkit_url_variable: ``NSP_ONEAPI_base_toolkit_url`` """"""""""""""""""""""""""""""" :Type: **str** :Required: **true** :Description: The download URL for the base toolkit installer. .. _NSP_ONEAPI_base_toolkit_components_variable: ``NSP_ONEAPI_base_toolkit_components`` """""""""""""""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``["intel.oneapi.lin.dpcpp-ct", "intel.oneapi.lin.dpcpp_dbg", "intel.oneapi.lin.dpl", "intel.oneapi.lin.tbb.devel", "intel.oneapi.lin.dpl", "intel.oneapi.lin.dal.devel", "intel.oneapi.lin.ipp.devel", "intel.oneapi.lin.ippcp.devel", "intel.oneapi.lin.mkl.devel", "intel.oneapi.lin.advisor", "intel.oneapi.lin.vtune"]`` :Description: The base toolkit components to install. .. _NSP_ONEAPI_hpc_toolkit_url_variable: ``NSP_ONEAPI_hpc_toolkit_url`` """""""""""""""""""""""""""""" :Type: **str** :Required: **true** :Description: The download URL for the HPC toolkit installer. .. _NSP_ONEAPI_hpc_toolkit_components_variable: ``NSP_ONEAPI_hpc_toolkit_components`` """"""""""""""""""""""""""""""""""""" :Type: **list** :Required: **false** :Default: ``["intel.oneapi.lin.ifort-compiler"]`` :Description: The HPC toolkit components to install. .. _NSP_ONEAPI_create_module_variable: ``NSP_ONEAPI_create_module`` """""""""""""""""""""""""""" :Type: **bool** :Required: **false** :Default: ``true`` :Description: Toggles module generation. -------------------------------------------------------------------------------- .. _spack_role: spack ----- `Description` ^^^^^^^^^^^^^ The spack role clones and patches Spack and templates environments for deployment. If you have any spack extentions they should be placed in the playbook directory under ``spack/extentions``. Extensions will be deployed in ``"{{ [NSP_SPACK_config_directory, 'extensions'] | path_join }}"`` . All Spack patch files should go in the playbook directory under ``spack/patches``. `Variables` ^^^^^^^^^^^ .. _NSP_SPACK_config_directory_variable: ``NSP_SPACK_config_directory`` """""""""""""""""""""""""""""" :Type: **path** :Required: **false** :Default: ``"{{ [NSP_install_root, 'spack/configs'] | path_join }}"`` :Description: The target directory for spack configuration files. .. _NSP_SPACK_repo_variable: ``NSP_SPACK_repo`` """""""""""""""""" :Type: **str** :Required: **false** :Default: ``"https://github.com/spack/spack.git"`` :Description: The Spack repo to clone. .. _NSP_SPACK_versions_variable: ``NSP_SPACK_versions`` """""""""""""""""""""" :Type: **dict** :Required: **true** :Description: Defines available spack versions for the environments. Specifying a ``git_reference`` is mandatory but the patch file is optional. .. code:: yaml NSP_SPACK_versions: v0.23.1: git_reference: 2bfcc69 patch: v0.23.1.patch .. _NSP_SPACK_environments_variable: ``NSP_SPACK_environments`` """""""""""""""""""""""""" :Type: **dict** :Required: **true** :Description: Defines spack environments. For example: .. code:: yaml NSP_SPACK_environments: example_env: spack_version: v0.23.1 specific_templates: - spack shared_templates: - bootstrap - compilers - concretizer - config - mirrors - modules - packages For each environment you should create a directory with the same name in the playbook directory under ``spack/environments``. ``spack_version`` should reference a spack version defined in :ref:`NSP_SPACK_versions_variable`. We like to split our spack configuration for each environment into multiple files. ``specific_templates`` are templates that are specific to each environment. They should be placed under ``spack/environments/`` in your playbook directory. ``shared_templates`` are used by all of the environments and should be placed under ``spack/environments``.