Uso de JupyterHub en Big Data Service 3.0.26 o versiones anteriores

Utilice JupyterHub para gestionar blocs de notas de Big Data Service 3.0.26 o versiones anteriores de ODH 1.x para grupos de usuarios.

Requisitos

Para poder acceder a JupyterHub desde un explorador, un administrador debe:

  • Haga que el nodo esté disponible para las conexiones entrantes de los usuarios. La dirección IP privada del nodo se debe asignar a una dirección IP pública. Como alternativa, el cluster se puede configurar para utilizar un bastion host u Oracle FastConnect. Consulte Connecting to Cluster Nodes with Private IP Addresses.
  • Abra el puerto 8000 en el nodo configurando las reglas de entrada en la lista de seguridad de la red. Consulte Definición de reglas de seguridad.

JupyterHub Credenciales por defecto

Las credenciales de conexión de administrador por defecto para JupyterHub en Big Data Service 3.0.21 y anteriores son:

  • Nombre de usuario: jupyterhub
  • Contraseña: contraseña del administrador de Apache Ambari. Se trata de la contraseña del administrador del cluster que se especificó cuando se creó el cluster.
  • Nombre de principal para el cluster de HA: jupyterhub
  • Tabla de claves para un cluster de HA: /etc/security/keytabs/jupyterhub.keytab

Las credenciales de inicio de sesión de administrador por defecto para JupyterHub en Big Data Service 3.0.22 a 3.0.26 son:

  • Nombre de usuario: jupyterhub
  • Contraseña: contraseña del administrador de Apache Ambari. Se trata de la contraseña del administrador del cluster que se especificó cuando se creó el cluster.
  • Nombre de principal para el cluster de alta disponibilidad: jupyterhub/<FQDN-OF-UN1-Hostname>
  • Tabla de claves para un cluster de HA: /etc/security/keytabs/jupyterhub.keytab
    Ejemplo:
    Principal name for HA cluster: jupyterhub/pkbdsv2un1.rgroverprdpub1.rgroverprd.oraclevcn.com
              Keytab for HA cluster: /etc/security/keytabs/jupyterhub.keytab 

El administrador crea usuarios adicionales y sus credenciales de conexión, y proporciona las credenciales de conexión a esos usuarios. Para obtener más información, consulte Gestión de usuarios y permisos.

Nota

A menos que se haga referencia explícita a algún otro tipo de administrador, el uso de administrator o de admin en esta sección hace referencia al administrador de JupyterHub, jupyterhub.

Acceso a JupyterHub

Acceda a JupyterHub a través del explorador para los clusters de Big Data Service 3.0.26 o anteriores. Se accede a JupyterHub desde un explorador una vez que se han cumplido los requisitos.
  1. Abra una ventana del explorador.
  2. Introduzca una URL con el siguiente formato:
    https://<node_ip_address>:8000

    Ejemplo:

    https://192.0.2.0:8000
  3. Conéctese con sus credenciales.
    Si no es un usuario administrador: regístrese desde la página Registrarse. Un usuario administrador debe autorizar al nuevo usuario registrado. Después de la autorización, el usuario puede conectarse.

También puede acceder al enlace JupyterHub desde la página de detalles del cluster en URL de cluster.

También puede crear un equilibrador de carga para proporcionar un front-end seguro para acceder a los servicios, incluido JupyterHub. Consulte Connecting to Services on a Cluster Using Load Balancer.

Generación de blocs de notas

Generación de Notebooks en un cluster de HA

Se deben cumplir los requisitos para que el usuario intente generar blocs de notas.

  1. Acceda a JupyterHub.
  2. Conéctese con las credenciales de administración. La autorización solo funciona si el usuario está presente en el host de Linux. JupyterHub busca el usuario en el host de Linux al intentar generar el servidor del bloc de notas.
  3. Se le redirigirá a una página de opciones de servidor en la que debe solicitar un ticket de Kerberos. Este ticket se puede solicitar mediante el principal de Kerberos y el archivo keytab, o la contraseña de Kerberos. El administrador del cluster puede proporcionar el principal de Kerberos y el archivo keytab, o la contraseña de Kerberos.

    El ticket de Kerberos es necesario para obtener acceso a los directorios de HDFS y otros servicios de big data que desea utilizar.

Generación de Notebooks en un cluster sin HA

Se deben cumplir los requisitos para que el usuario intente generar blocs de notas.

  1. Acceda a JupyterHub.
  2. Conéctese con las credenciales de administración. La autorización solo funciona si el usuario está presente en el host de Linux. JupyterHub busca el usuario en el host de Linux al intentar generar el servidor del bloc de notas.

Gestionar JupyterHub

Un usuario JupyterHub admin puede realizar las siguientes tareas para gestionar blocs de notas en JupyterHub en nodos ODH 1.x de Big Data Service 3.0.26 o anteriores.

Configuración de JupyterHub mediante el explorador

Como admin, puede configurar JupyterHub.

Nota

Configure JupyterHub mediante el explorador para clusters de Big Data Service 3.0.26 o anteriores.
  1. Conéctese como usuario opc al nodo de utilidad donde está instalado JupyterHub (el segundo nodo de utilidad de un cluster de HA [alta disponibilidad] o el primer y único nodo de utilidad de un cluster sin HA).
  2. Utilice sudo para gestionar las configuraciones de JupyterHub que se almacenan en /opt/jupyterhub/jupyterhub_config.py.
    Por ejemplo, para cambiar el número de puerto de JupyterHub, ejecute los siguientes comandos
    vi /opt/jupyterhub/jupyterhub_config.py
    # search for c.JupyterHub.bind_url and edit the port number and save
    sudo systemctl restart jupyterhub.service
    sudo systemctl status jupyterhub.service
Parada e inicio de JupyterHub mediante el explorador
Nota

Pare o inicie JupyterHub mediante el explorador de clusters de Big Data Service 3.0.26 o anteriores.

Como admin, puede parar o desactivar la aplicación para que no consuma recursos como, por ejemplo, la memoria. Reiniciar también puede ayudar con problemas o comportamientos inesperados.

  1. Conéctese como usuario opc al nodo de utilidad donde está instalado JupyterHub (el segundo nodo de utilidad de un cluster de HA [alta disponibilidad] o el primer y único nodo de utilidad de un cluster sin HA).
  2. Utilice sudo para iniciar, parar o reiniciar JupyterHub.
    sudo systemctl start jupyterhub.service
    sudo systemctl stop jupyterhub.service
    sudo systemctl restart jupyterhub.service
    sudo systemctl status jupyterhub.service
Gestión de límites del bloc de notas

Como administrador, puede limitar el número de servidores de blocs de notas activos del cluster de Big Data Service.

Por defecto, el número de servidores de blocs de notas activos está definido como el doble del número de OCPU en el nodo. El límite de OCPU por defecto es tres, y el límite de memoria por defecto es de 2 G. La configuración por defecto para el mínimo de blocs de notas activos es 10, y el máximo de blocs de notas activos es 80.
  1. Conéctese como usuario opc al nodo de utilidad donde está instalado JupyterHub (el segundo nodo de utilidad de un cluster de HA [alta disponibilidad] o el primer y único nodo de utilidad de un cluster sin HA).
  2. Utilice sudo para editar las configuraciones de JupyterHub almacenadas en /opt/jupyterhub/jupyterhub_config.py.
    Ejemplo:
    c.JupyterHub.active_server_limit = 10
    c.Spawner.cpu_limit = 3
    c.Spawner.mem_limit = '2G'
Actualización del gestor de contenido del bloc de notas
Actualización del gestor de contenido de HDFS

Por defecto, los blocs de notas se almacenan en el directorio de HDFS de un cluster.

Debe tener acceso al directorio de HDFS hdfs:///user/<username>/. Los blocs de notas se guardan en hdfs:///user/<username>/notebooks/.

  1. Conéctese como usuario opc al nodo de utilidad donde está instalado JupyterHub (el segundo nodo de utilidad de un cluster de HA [alta disponibilidad] o el primer y único nodo de utilidad de un cluster sin HA).
  2. Utilice sudo para gestionar las configuraciones de JupyterHub que se almacenan en /opt/jupyterhub/jupyterhub_config.py.
    c.Spawner.args = ['--ServerApp.contents_manager_class="hdfscm.HDFSContentsManager"']
  3. Utilice sudo para reiniciar JupyterHub.
    sudo systemctl restart jupyterhub.service
Actualización del gestor de contenido de Object Storage

Como usuario administrador, puede almacenar los blocs de notas de usuario individual en Object Storage en lugar de HDFS. Al cambiar el gestor de contenido de HDFS a Object Storage, los blocs de notas existentes no se copian en Object Storage. Los nuevos blocs de notas se guardan en Object Storage.

  1. Conéctese como usuario opc al nodo de utilidad donde está instalado JupyterHub (el segundo nodo de utilidad de un cluster de HA [alta disponibilidad] o el primer y único nodo de utilidad de un cluster sin HA).
  2. Utilice sudo para gestionar las configuraciones de JupyterHub que se almacenan en /opt/jupyterhub/jupyterhub_config.py. Consulte la sección sobre la generación de la clave secreta y la de acceso para obtener información sobre cómo generar las claves necesarias.
    c.Spawner.args = ['--ServerApp.contents_manager_class="s3contents.S3ContentsManager"', '--S3ContentsManager.bucket="<bucket-name>"', '--S3ContentsManager.access_key_id="<accesskey>"', '--S3ContentsManager.secret_access_key="<secret-key>"', '--S3ContentsManager.endpoint_url="https://<object-storage-endpoint>"', '--S3ContentsManager.region_name="<region>"','--ServerApp.root_dir=""']
  3. Utilice sudo para reiniciar JupyterHub.
    sudo systemctl restart jupyterhub.service

Integrar con Object Storage

Integre Spark con el almacenamiento de objetos para utilizarlo con clusters de Big Data Service.

En JupyterHub, para que Spark funcione con Object Storage, debe definir algunas propiedades del sistema y rellenarlas en las propiedades spark.driver.extraJavaOption y spark.executor.extraJavaOptions en las configuraciones de Spark.

Requisitos

Para integrar correctamente JupyterHub con Object Storage, debe:

  • Crear un cubo en Object Store para almacenar datos.
  • Crear una clave de API de Object Storage.
Recuperación de valores de propiedades del sistema

Las propiedades que debe definir en las configuraciones de Spark son:

  • TenantID
  • Userid
  • Fingerprint
  • PemFilePath
  • PassPhrase
  • Region

Recuperan los valores de estas propiedades:

  1. Abra el menú de navegación y seleccione Analytics & AI. En Lago de datos, seleccione Big Data Service.
  2. En la página de lista Clusters, seleccione el cluster con el que desea trabajar. Si necesita ayuda para buscar la página de lista o el cluster, consulte Lista de clusters en un compartimento.
  3. Para ver clusters en un compartimento diferente, utilice el filtro Compartimento para cambiar de compartimento.

    Debe tener permiso para trabajar en un compartimento para ver los recursos que contiene. Si no está seguro de qué compartimiento utilizar, póngase en contacto con un administrador. Para obtener más información, consulte Descripción de los compartimentos.

  4. En la página Detalles de cluster, en Recursos, seleccione Claves de API de Object Storage.
  5. En el menú Acciones (tres puntos) de la clave de API que desea ver, seleccione Ver archivo de configuración.

El archivo de configuración tiene todos los detalles de las propiedades del sistema, excepto la frase de contraseña. La frase de contraseña se especifica cuando se crea la clave de API de Object Storage. Debe recordar y utilizar la misma frase de contraseña.

Ejemplo: almacenamiento y lectura de datos de Object Storage en el núcleo de Python mediante pyspark
  1. Acceda a JupyterHub.
  2. Abra un nuevo bloc de notas.
  3. Copie y pegue los siguientes comandos para conectarse a Spark.
    import findspark
    findspark.init()
    import pyspark
  4. Copie y pegue los siguientes comandos para crear una sesión de Spark con las configuraciones especificadas. Cambie las variables por los valores de propiedades del sistema que ha recuperado antes.
    from pyspark.sql import SparkSession
    
    spark = SparkSession \
        .builder \
        .enableHiveSupport() \
        .config("spark.driver.extraJavaOptions", "-DBDS_OSS_CLIENT_REGION=<Region> -DBDS_OSS_CLIENT_AUTH_TENANTID=<TenantId> -DBDS_OSS_CLIENT_AUTH_USERID=<UserId> -DBDS_OSS_CLIENT_AUTH_FINGERPRINT=<FingerPrint> -DBDS_OSS_CLIENT_AUTH_PEMFILEPATH=<PemFile> -DBDS_OSS_CLIENT_AUTH_PASSPHRASE=<PassPhrase>")\
        .config("spark.executor.extraJavaOptions" , "-DBDS_OSS_CLIENT_REGION=<Region> -DBDS_OSS_CLIENT_AUTH_TENANTID=<TenantId> -DBDS_OSS_CLIENT_AUTH_USERID=<UserId> -DBDS_OSS_CLIENT_AUTH_FINGERPRINT=<FingerPrint> -DBDS_OSS_CLIENT_AUTH_PEMFILEPATH=<PemFile> -DBDS_OSS_CLIENT_AUTH_PASSPHRASE=<PassPhrase>")\
        .appName("<appname>") \
        .getOrCreate()
  5. Copie y pegue los siguientes comandos para crear el archivo y los directorios de Object Storage y almacenar datos en formato de Parquet.
    demoUri = "oci://<BucketName>@<Tenancy>/<DirectoriesAndSubDirectories>/"
    parquetTableUri = demoUri + "<fileName>"
    spark.range(10).repartition(1).write.mode("overwrite").format("parquet").save(parquetTableUri)
  6. Copie y pegue el siguiente comando para leer los datos de Object Storage.
    spark.read.format("parquet").load(parquetTableUri).show()
  7. Ejecute el bloc de notas con todos estos comandos.

    Acceso a Object Storage en Jupyter

Se mostrará la salida del código. Puede desplazarse hasta el cubo de Object Storage desde la consola y buscar el archivo creado en el cubo.

Gestión de usuarios y permisos

Utilice uno de los dos métodos de autenticación para autenticar usuarios en JupyterHub de modo que puedan crear blocs de notas y, si lo desea, administrar JupyterHub.

Por defecto, los clusters de ODH 1.x admiten la autenticación nativa. Sin embargo, la autenticación para JupyterHub y otros servicios de big data se deben manejar de forma diferente. Para generar blocs de notas de un solo usuario, el usuario que se conecta a JupyterHub debe estar presente en el host de Linux y debe tener permisos para escribir en el directorio raíz de HDFS. De lo contrario, el generador falla cuando se dispara el proceso de bloc de notas como usuario de Linux.

Para obtener información sobre la autenticación nativa, consulte Native Authentication.

Para obtener información sobre la autenticación LDAP para Big Data Service 3.0.26 o una versión anterior, consulte LDAP Authentication.

Autenticación Nativa

La autenticación nativa depende de la base de datos de usuarios JupyterHub para autenticar usuarios.

La autenticación nativa se aplica tanto a los clusters de HA como a los clusters sin HA. Consulte la sección sobre el autenticador nativo para obtener más información sobre el autenticador nativo.

Requisitos para autorizar a un usuario en un cluster de HA

Estos requisitos se deben cumplir para autorizar a un usuario en un cluster de HA de Big Data Service mediante autenticación nativa.

  1. El usuario debe existir en el host de Linux. Ejecute el siguiente comando para agregar un nuevo usuario de Linux en todos los nodos de un cluster.
    # Add linux user
    dcli -C "useradd -d /home/<username> -m -s /bin/bash <username>"
  2. Para iniciar un servidor de portátiles, un usuario debe proporcionar el principal y el archivo keytab path/password, así como solicitar un ticket de Kerberos desde la interfaz de JupyterHub. Para crear una tabla de claves, el administrador del cluster debe agregar el principal de Kerberos con una contraseña y un archivo keytab. Ejecute los siguientes comandos en el primer nodo maestro (mn0) del cluster.
    # Create a kdc principal with password or give access to existing keytabs.
    kadmin.local -q "addprinc <principalname>"
    Password Prompt: Enter passwrod
     
    # Create a kdc principal with keytab file or give access to existing keytabs.
    kadmin.local -q 'ktadd -k /etc/security/keytabs/<principal>.keytab principal'
  3. El nuevo usuario debe contar con los permisos de Ranger correctos para almacenar archivos en el directorio de HDFS hdfs:///users/<username> ya que los blocs de nota individuales se almacenan en /users/<username>/notebooks. El administrador del cluster puede agregar el permiso necesario desde la interfaz de Ranger abriendo la siguiente URL en un explorador web.
    https://<un0-host-ip>:6182
  4. El nuevo usuario debe tener los permisos correctos en Yarn, Hive y Object Storage para leer y escribir datos, y ejecutar trabajos de Spark. También puede utilizar la suplantación de Livy (ejecutar trabajos de Big Data Service como usuario Livy) sin obtener permisos explícitos en Spark, Yarn y otros servicios.
  5. Ejecute el siguiente comando para otorgar al nuevo usuario acceso al directorio de HDFS.
    # Give access to hdfs directory
    # kdc realm is by default BDSCLOUDSERVICE.ORACLE.COM
    kinit -kt /etc/security/keytabs/hdfs.headless.keytab hdfs-<clustername>@<kdc_realm> 
    sudo su hdfs -c "hdfs dfs -mkdir /user/<username>"
    sudo su hdfs -c "hdfs dfs -chown -R jupy5 /user/<username>"
Requisitos para Autorizar a un Usuario en un Cluster sin HA

Estos requisitos se deben cumplir para autorizar a un usuario en un cluster sin HA de Big Data Service mediante autenticación nativa.

  1. El usuario debe existir en el host de Linux. Ejecute el siguiente comando para agregar un nuevo usuario de Linux en todos los nodos de un cluster.
    # Add linux user
    dcli -C "useradd -d /home/<username> -m -s /bin/bash <username>"
  2. El nuevo usuario debe tener los permisos correctos para almacenar los archivos en el directorio de HDFS hdfs:///users/<username>. Ejecute el siguiente comando para otorgar al nuevo usuario acceso al directorio de HDFS.
    # Give access to hdfs directory
    sudo su hdfs -c "hdfs dfs -mkdir /user/<username>"
    sudo su hdfs -c "hdfs dfs -chown -R jupy5 /user/<username>"
Adición de un usuario administrador

Los usuarios administradores son los responsables de configurar y gestionar JupyterHub. Los usuarios administradores también son responsables de autorizar a los usuarios recién registrados en JupyterHub.

Antes de agregar un usuario administrador, se deben cumplir los requisitos de un cluster de HA o un cluster sin HA.

  1. Acceda a Apache Ambari.
  2. En la barra de herramientas lateral, en Servicios, seleccione JupyterHub.
  3. Seleccione Configuración y, a continuación, seleccione Configuraciones avanzadas.
  4. Seleccione Advanced jupyterhub-config.
  5. Agregue el usuario administrador a c.Authenticator.admin_users.
  6. Seleccione Guardar.
No es necesario que un usuario administrador del archivo de configuración JupyterHub tenga autorización explícita durante el inicio de sesión. Después de registrarse, puede conectarse directamente.
Adición de otros usuarios

Antes de agregar otros usuarios, se deben cumplir los requisitos para un cluster de Big Data Service.

  1. Acceda a JupyterHub.
  2. Regístrese para el nuevo usuario. Los usuarios no administradores necesitan una autorización explícita de los usuarios administradores.
  3. El usuario administrador debe conectarse a JupyterHub y desde la nueva opción de menú para autorizar a los usuarios conectados, debe autorizar al nuevo usuario.
    Captura de pantalla de la página Authorize Users en Jupyterhub
  4. El nuevo usuario ahora puede conectarse.
Supresión de Usuarios

Un usuario administrador puede suprimir usuarios JupyterHub.

  1. Acceda a JupyterHub.
  2. Abra Archivo > HubControlPanel.
  3. Vaya a la página Authorize Users.
  4. Suprima los usuarios que desea eliminar.
Autenticación de LDAP

Puede utilizar la autenticación LDAP mediante un explorador para clusters de ODH 1.x de Big Data Service 3.0.26 o anteriores.

Integración con Trino

Requisitos
  • Trino se debe instalar y configurar en el cluster de Big Data Service.
  • Instale el siguiente módulo de Python en el nodo JupyterHub (un1 para HA / un0 para cluster sin HA)
    Nota

    Ignore este paso si el módulo Trino-Python ya está presente en el nodo.
    python3.6 -m pip install trino[sqlalchemy]
     
    Offline Installation:
    Download the required python module in any machine where we have internet access
    Example:
    python3 -m pip download trino[sqlalchemy] -d /tmp/package
    Copy the above folder content to the offline node & install the package
    python3 -m pip install ./package/*
     
    Note : trino.sqlalchemy is compatible with the latest 1.3.x and 1.4.x SQLAlchemy versions. 
    BDS cluster node comes with python3.6 and SQLAlchemy-1.4.46 by default.
Integración con el cluster de HA de Big Data Service

Si el Trino-Ranger-Plugin está activado, asegúrese de agregar el usuario keytab proporcionado en las respectivas políticas de Trino Ranger. Consulte Integración de Trino con Ranger.

De manera predeterminada, Trino utiliza el nombre principal de Kerberos completo como usuario. Por lo tanto, al agregar/actualizar políticas de trino-ranger, debe utilizar el nombre principal de Kerberos completo como nombre de usuario.

Para el siguiente ejemplo de código, utilice jupyterhub@BDSCLOUDSERVICE.ORACLE.COM como usuario en las políticas de trino-ranger.

Nota

Si Trino-Ranger-Plugin está activado, asegúrese de agregar el usuario keytab proporcionado en las políticas de Trino Ranger respectivas. Para obtener más información, consulte Enabling Ranger for Trino.

Proporcione permisos de Ranger para JupyterHub a las siguientes políticas:

  • all - catalog, schema, table, column
  • all - function
  1. Abra una ventana del explorador.
  2. Introduzca una URL con el siguiente formato:
    https://<node_ip_address>:8000

    Por ejemplo:

    https://192.0.2.0:8000
  3. Conéctese con sus credenciales. Consulte JupyterHub Default Credentials.
  4. Introduzca el Principio y la Tabla de claves.
  5. Abra el bloc de notas Phython 3.
  6. Crear motor con Trino:
    from sqlalchemy import create_engine
    from sqlalchemy.schema import Table, MetaData
    from sqlalchemy.sql.expression import select, text
    from trino.auth import KerberosAuthentication
    from subprocess import Popen, PIPE
    import pandas as pd
     
    # Provide user specific keytab_path and principal. If user wants to run queries 
    with different keytab then user can update below keytab_path & user_principal 
    else #user can use same keytab_path, principal that is used while starting the 
    notebook session.
    #Refer below sample code
     
    keytab_path='/etc/security/keytabs/jupyterhub.keytab'
    user_principal='jupyterhub@BDSCLOUDSERVICE.ORACLE.COM'
    # Cert path is required for SSL.
    cert_path= '/etc/security/serverKeys/oraclerootCA.crt'
    # trino url = 'trino://<trino-coordinator>:<port>'
    trino_url='trino://trinohamn0.sub03011425120.hubvcn.oraclevcn.com:7778'
     
     
    # This is optional step, required only if user wants to run queries with different keytab.
     
    kinit_args = [ '/usr/bin/kinit', '-kt', keytab_path, user_principal]
    subp = Popen(kinit_args, stdin=PIPE, stdout=PIPE, stderr=PIPE)
    subp.wait()
       
    engine = create_engine(
        trino_url,
        connect_args={
            "auth": KerberosAuthentication(service_name="trino", principal=user_principal, ca_bundle=cert_path),
            "http_scheme": "https",
            "verify": True
        }
    )
  7. Ejecute la consulta:
    query = "select custkey, name, phone, acctbal from tpch.sf1.customer limit 10"
    df = pd.read_sql(query, engine)
    print(df)
Integración con un cluster sin HA de Big Data Service
  1. Abra una ventana del explorador.
  2. Introduzca una URL con el siguiente formato:
    https://<node_ip_address>:8000

    Por ejemplo:

    https://192.0.2.0:8000
  3. Conéctese con sus credenciales. Consulte JupyterHub Credenciales por Defecto.
  4. Abra el bloc de notas Phython 3.
  5. Crear motor con Trino:
    from sqlalchemy import create_engine
    from sqlalchemy.schema import Table, MetaData
    from sqlalchemy.sql.expression import select, text
    import pandas as pd
     
    # trino url = 'trino://trino@<trino-coordinator>:<port>'
    trino_url='trino://trino@trinohamn0.sub03011425120.hubvcn.oraclevcn.com:8285'
     
    engine = create_engine(trino_url)
  6. Ejecute la consulta:
    query = "select custkey, name, phone, acctbal from tpch.sf1.customer limit 10"
    df = pd.read_sql(query, engine)
    print(df)