Kernels personalizados en JupyterHub

Esta guía describe los pasos necesarios para configurar kernels personalizados de Python en JupyterHub. Esto permite que los usuarios definan entornos específicos con conda, virtualenv o cargas de módulos para ejecutar notebooks interactivos.

Crear la carpeta de kernels

Jupyter busca kernels en varios directorios, entre ellos está el directorio:

~/.local/share/jupyter/kernels/

Para comenzar, cree esta carpeta si aún no existe:

mkdir -p ~/.local/share/jupyter/kernels

Crear el directorio del kernel

Dentro de ~/.local/share/jupyter/kernels/, cree un subdirectorio por cada kernel personalizado que desee registrar. El nombre del directorio será el identificador del kernel.

Ejemplo:

mkdir ~/.local/share/jupyter/kernels/Python-for-HPC

Puede definir múltiples kernels, cada uno en su subdirectorio.

Instalar paquetes necesarios en el entorno

Antes de continuar, es necesario que el entorno que se usará como kernel tenga instalado el paquete ipykernel. Esto permite que Jupyter se comunique correctamente con el entorno. En caso de que se este creando un ambiente de Miniconda la instalación sería de la siguiente manera:

Active el entorno e instale el paquete:

# Activar entorno conda o virtualenv
conda activate Python-for-HPC

# Instalar ipykernel
conda install -c conda-forge ipykernel

Asegúrese de hacer esto para cada entorno que desee usar como kernel personalizado. Tambien se pueden instalar otros paquetes que se quieran usar.

Crear el archivo kernel.json

En el subdirectorio del kernel, cree un archivo llamado kernel.json con el siguiente contenido:

{
  "argv": [
    "/home/USER/.local/share/jupyter/kernels/KERNEL_NAME/init.sh",
    "-f",
    "{connection_file}"
  ],
  "display_name": "KERNEL_NAME",
  "language": "python"
}

Este archivo es usado por jupyter para leer los contenidos de los kernels, y sus configuraciones.

Parámetros:

  • Reemplace USER por su nombre de usuario.

  • Reemplace KERNEL_NAME por el nombre del kernel (debe coincidir con el nombre del directorio).

  • "display_name" es el nombre mostrado en la interfaz de Jupyter.

Crear el script init.sh

Este script configura el entorno (activa el entorno conda, carga módulos, etc.) antes de lanzar el kernel de Python. Este es ejecutado por el archivo kernel.json para cargar los requerimientos del ambiente. Ubíquelo dentro del mismo directorio del kernel (~/.local/share/jupyter/kernels/KERNEL_NAME/) y asegúrese de que tenga permisos de ejecución:

chmod +x init.sh

Ejemplo de contenido de init.sh:

#!/bin/bash

export CONDA_TARGET_DIR=/work/USER/miniconda3

module purge  # Limpia los módulos cargados previamente

# Activar entorno conda
source ${CONDA_TARGET_DIR}/bin/activate Python-for-HPC

# Asegurar que los paquetes Python del entorno conda tengan prioridad
## Cambiar la versión de Python de acuerdo a la versión usada en el ambiente
export PYTHONPATH=${CONDA_TARGET_DIR}/envs/Python-for-HPC/lib/python3.11/site-packages:${PYTHONPATH}

# Cargar módulos necesarios (ejemplo: CUDA)
module load cuda/11.6.2-gcc-9.3.0

# Ejecutar el kernel
exec python -m ipykernel "$@"

El nombre del script (init.sh) debe coincidir exactamente con el indicado en el kernel.json. La línea final exec python -m ipykernel "$@" es obligatoria. Sin ella, el kernel no se ejecutará correctamente.

Verificación de kernel

  1. Reinicie la sesión en JupyterHub.

  2. Cree un nuevo notebook.

  3. Verifique que su kernel personalizado aparezca en la lista de kernels.

  4. Pruebe ejecutándolo con:

!which python
!echo $PYTHONPATH

El resultado debería de ser la ruta a la herramienta Python, así como la ubicación de sus paquetes.