Usando JupyterHub no Big Data Service 3.0.26 ou Anterior

Use JupyterHub para gerenciar notebooks ODH 1.x do Big Data Service 3.0.26 ou anterior para grupos de usuários.

Pré-requisitos

Para que JupyterHub possa ser acessado em um browser, um administrador deve:

  • Disponibilizar o nó para conexões de entrada dos usuários. O endereço IP privado do nó precisa ser mapeado para um endereço IP público. Como alternativa, o cluster pode ser configurado para usar um bastion host ou o Oracle FastConnect. Consulte Conexão com Nós do Cluster com Endereços IP Privados.
  • Abra a porta 8000 no nó configurando as regras de entrada na lista de segurança de rede. Consulte Definindo Regras de Segurança.

JupyterHub Credenciais Padrão

As credenciais de acesso do administrador padrão para JupyterHub no Big Data Service 3.0.21 e versões anteriores são:

  • Nome de usuário: jupyterhub
  • Senha: A senha de administrador do Apache Ambari. Esta é a senha admin do cluster especificada durante a criação do cluster.
  • Nome principal do cluster HA: jupyterhub
  • Keytab do cluster HA: /etc/security/keytabs/jupyterhub.keytab

As credenciais de acesso do administrador padrão para JupyterHub no Big Data Service 3.0.22 a 3.0.26 são:

  • Nome de usuário: jupyterhub
  • Senha: A senha de administrador do Apache Ambari. Esta é a senha admin do cluster especificada durante a criação do cluster.
  • Nome principal do cluster HA: jupyterhub/<FQDN-OF-UN1-Hostname>
  • Keytab do cluster HA: /etc/security/keytabs/jupyterhub.keytab
    Por exemplo:
    Principal name for HA cluster: jupyterhub/pkbdsv2un1.rgroverprdpub1.rgroverprd.oraclevcn.com
              Keytab for HA cluster: /etc/security/keytabs/jupyterhub.keytab 

O administrador cria usuários adicionais e suas credenciais de acesso e fornece as credenciais de acesso a esses usuários. Para obter mais informações, consulte Gerenciar Usuários e Permissões.

Observação

A menos que seja explicitamente especificado como algum outro tipo de administrador, o uso de administrator ou admin em toda essa seção se refere ao administrador do JupyterHub, jupyterhub.

Acessando o JupyterHub

Acesse JupyterHub por meio do browser para clusters do Big Data Service 3.0.26 ou anteriores. O JupyterHub é acessado em um browser depois que os pré-requisitos são atendidos.
  1. Abra uma janela do browser.
  2. Informe um URL no seguinte formato:
    https://<node_ip_address>:8000

    Por exemplo:

    https://192.0.2.0:8000
  3. Acesse com suas credenciais.
    Se você for um usuário não administrador: Inscreva-se na página Inscrição. Um usuário administrador deve autorizar o novo usuário inscrito. Após a autorização, o usuário pode acessar.

Como alternativa, você pode acessar o link JupyterHub na página de detalhes do Cluster em URLs do Cluster.

Você também pode criar um Balanceador de Carga para fornecer um front-end seguro para acessar serviços, incluindo JupyterHub. Consulte Estabelecendo Conexão com Serviços em um Cluster com o Balanceador de Carga.

Criando Notebooks

Criando Notebooks em um cluster HA

Os pré-requisitos devem ser atendidos pelos usuários que estão tentando criar notebooks.

  1. Acesse JupyterHub.
  2. Acesse com credenciais administrativas. A autorização só funcionará se o usuário estiver presente no host do Linux. O JupyterHub procura o usuário no host do Linux enquanto tenta gerar o servidor de notebook.
  3. Você será redirecionado para uma página Opções do Servidor, na qual deverá solicitar um ticket do Kerberos. Esse ticket pode ser solicitado usando o principal do Kerberos e o arquivo keytab ou a senha do Kerberos. O administrador do cluster pode fornecer o principal do Kerberos e o arquivo keytab ou a senha do Kerberos.

    O ticket do Kerberos é necessário para ter acesso nos diretórios HDFS e em outros serviços do big data que você deseja usar.

Criando Notebooks em um Cluster não HA

Os pré-requisitos devem ser atendidos pelos usuários que estão tentando criar notebooks.

  1. Acesse JupyterHub.
  2. Acesse com credenciais administrativas. A autorização só funcionará se o usuário estiver presente no host do Linux. O JupyterHub procura o usuário no host do Linux enquanto tenta gerar o servidor de notebook.

Gerenciar JupyterHub

Um usuário JupyterHub admin pode executar as seguintes tarefas para gerenciar notebooks em JupyterHub nos nós ODH 1.x do Big Data Service 3.0.26 ou anterior.

Configurando o JupyterHub por meio do Browser

Como admin, você pode configurar JupyterHub.

Observação

Configure JupyterHub por meio do browser para clusters do Big Data Service 3.0.26 ou anteriores.
  1. Estabeleça conexão como usuário opc com o nó do utilitário no qual JupyterHub está instalado (o segundo nó do utilitário de um cluster HA (altamente disponível) ou o primeiro e único nó do utilitário de um cluster não HA).
  2. Use sudo para gerenciar as configurações JupyterHub que são armazenadas em /opt/jupyterhub/jupyterhub_config.py.
    Por exemplo, para alterar o número da porta de JupyterHub, execute os comandos a seguir
    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
Parando e Iniciando o JupyterHub por meio do Browser
Observação

Interrompa ou inicie JupyterHub por meio do browser para clusters do Big Data Service 3.0.26 ou anteriores.

Como admin, você pode interromper ou desativar o aplicativo para que ele não consuma recursos, como memória. A reinicialização também pode ajudar com problemas ou comportamentos inesperados.

  1. Estabeleça conexão como usuário opc com o nó do utilitário no qual JupyterHub está instalado (o segundo nó do utilitário de um cluster HA (altamente disponível) ou o primeiro e único nó do utilitário de um cluster não HA).
  2. Use sudo para iniciar, interromper ou reiniciar JupyterHub.
    sudo systemctl start jupyterhub.service
    sudo systemctl stop jupyterhub.service
    sudo systemctl restart jupyterhub.service
    sudo systemctl status jupyterhub.service
Gerenciando Limites de Notebook

Como administrador, você pode limitar o número de servidores de notebook ativos no cluster do Big Data Service.

Por padrão, o número de servidores de notebook ativos é definido como o dobro do número de OCPUs no nó. O limite padrão de OCPUs é três e o limite de memória padrão é 2 G. As definições padrão para o mínimo de notebooks ativos é 10 e o máximo é 80.
  1. Estabeleça conexão como usuário opc com o nó do utilitário no qual JupyterHub está instalado (o segundo nó do utilitário de um cluster HA (altamente disponível) ou o primeiro e único nó do utilitário de um cluster não HA).
  2. Use sudo para editar as configurações JupyterHub armazenadas em /opt/jupyterhub/jupyterhub_config.py.
    Exemplo:
    c.JupyterHub.active_server_limit = 10
    c.Spawner.cpu_limit = 3
    c.Spawner.mem_limit = '2G'
Atualizando o Notebook Content Manager
Atualizando o HDFS Content Manager

Por padrão, os notebooks são armazenados no diretório HDFS de um cluster.

Você deve ter acesso ao diretório HDFS hdfs:///user/<username>/. Os notebooks são salvos em hdfs:///user/<username>/notebooks/.

  1. Estabeleça conexão como usuário opc com o nó do utilitário no qual JupyterHub está instalado (o segundo nó do utilitário de um cluster HA (altamente disponível) ou o primeiro e único nó do utilitário de um cluster não HA).
  2. Use sudo para gerenciar as configurações JupyterHub que são armazenadas em /opt/jupyterhub/jupyterhub_config.py.
    c.Spawner.args = ['--ServerApp.contents_manager_class="hdfscm.HDFSContentsManager"']
  3. Use sudo para reiniciar JupyterHub.
    sudo systemctl restart jupyterhub.service
Atualizando o Object Storage Content Manager

Como usuário administrador, você pode armazenar os notebooks de usuários individuais no Object Storage, em vez de no HDFS. Quando você altera o gerenciador de conteúdo do HDFS para o Object Storage, os notebooks existentes não são copiados para o Object Storage. Os novos notebooks são salvos no Object Storage.

  1. Estabeleça conexão como usuário opc com o nó do utilitário no qual JupyterHub está instalado (o segundo nó do utilitário de um cluster HA (altamente disponível) ou o primeiro e único nó do utilitário de um cluster não HA).
  2. Use sudo para gerenciar as configurações JupyterHub que são armazenadas em /opt/jupyterhub/jupyterhub_config.py. Consulte gerar acesso e chave secreta para saber como gerar as chaves obrigatórias.
    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. Use sudo para reiniciar JupyterHub.
    sudo systemctl restart jupyterhub.service

Integrar com o Object Storage

Integre o Spark ao Object Storage para uso com clusters do Big Data Service.

Em JupyterHub, para que o Spark funcione com o Object Storage, defina algumas propriedades do sistema e preencha-as nas configurações do Spark spark.driver.extraJavaOption e spark.executor.extraJavaOptions.

Pré-requisitos

Para poder integrar com sucesso JupyterHub com o Object Storage, você deverá:

  • Criar um bucket no Object Store para armazenar dados.
  • Criar uma chave de API do Object Storage.
Recuperando Valores de Propriedades do Sistema

As propriedades que você deve definir nas configurações do Spark são:

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

Para recuperar os valores dessas propriedades:

  1. Abra o menu de navegação e selecione Análise e IA. Em Data Lake, selecione Big Data Service.
  2. Na página da lista Clusters, selecione o cluster com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista ou o cluster, consulte Listando Clusters em um Compartimento.
  3. Para exibir clusters em outro compartimento, use o filtro Compartimento para alternar compartimentos.

    Você deve ter permissão para trabalhar em um compartimento para ver os recursos nele. Se você não tiver certeza sobre qual compartimento usar, entre em contato com um administrador. Para obter mais informações consulte Noções Básicas de Compartimentos.

  4. Na página de detalhes do Cluster, em Recursos, selecione Chaves de API do serviço Object Storage.
  5. No menu Ações (três pontos) da chave de API que você deseja exibir, selecione Exibir arquivo de configuração.

O arquivo de configuração tem todos os detalhes de propriedades do sistema, exceto a frase-senha. A frase-senha é especificada ao criar a chave da API do Object Storage e você deve lembrar e usar a mesma frase-senha.

Exemplo: Armazenando e Lendo Dados do Armazenamento de Objetos no Kernel Python Usando o pyspark
  1. Acesse JupyterHub.
  2. Abra um novo notebook.
  3. Copie e cole os comandos a seguir para estabelecer conexão com o Spark.
    import findspark
    findspark.init()
    import pyspark
  4. Copie e cole os comandos a seguir para criar uma sessão no Spark com as configurações especificadas. Substitua as variáveis pelos valores de propriedades do sistema recuperados anteriormente.
    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 e cole os comandos a seguir para criar os diretórios e o arquivo do Object Storage e armazenar dados no Formato Parquet.
    demoUri = "oci://<BucketName>@<Tenancy>/<DirectoriesAndSubDirectories>/"
    parquetTableUri = demoUri + "<fileName>"
    spark.range(10).repartition(1).write.mode("overwrite").format("parquet").save(parquetTableUri)
  6. Copie e cole o comando a seguir para ler os dados do Object Storage.
    spark.read.format("parquet").load(parquetTableUri).show()
  7. Execute o notebook com todos esses comandos.

    Acessar o Object Storage no Jupyter

A saída do código é exibida. Você pode navegar até o bucket do Object Storage na Console e localizar o arquivo criado no bucket.

Gerenciar Usuários e Permissões

Use um dos dois métodos de autenticação para autenticar usuários em JupyterHub para que eles possam criar notebooks e, opcionalmente, administrar JupyterHub.

Por padrão, os clusters ODH 1.x suportam autenticação nativa. Mas a autenticação para JupyterHub e outros serviços big data deve ser tratada de forma diferente. Para gerar notebooks de usuário único, o usuário que faz log-in em JupyterHub precisa estar presente no host do Linux e precisa ter permissões para gravar no diretório raiz do HDFS. Caso contrário, o criador falhará porque o processo de notebook é acionado como usuário do Linux.

Para obter informações sobre autenticação nativa, consulte Autenticação Nativa.

Para obter informações sobre autenticação LDAP para o Big Data Service 3.0.26 ou anterior, consulte Autenticação LDAP.

Autenticação nativa

A autenticação nativa depende do banco de dados do usuário JupyterHub para autenticar usuários.

A autenticação nativa se aplica a clusters HA e não HA. Consulte autenticador nativo para obter detalhes sobre o autenticador nativo.

Pré-requisitos para Autorizar um Usuário em um Cluster HA

Esses pré-requisitos devem ser atendidos para autorizar um usuário em um cluster HA do Big Data Service usando a autenticação nativa.

  1. O usuário deve existir no host do Linux. Execute o comando a seguir para adicionar um novo usuário do Linux em todos os nós de um cluster.
    # Add linux user
    dcli -C "useradd -d /home/<username> -m -s /bin/bash <username>"
  2. Para iniciar um servidor de notebook, um usuário deve fornecer o principal e o arquivo keytab path/password e solicitar um ticket do Kerberos na interface do JupyterHub. Para criar um keytab, o administrador do cluster deve adicionar o principal do Kerberos com uma senha e com um arquivo keytab. Execute os comandos a seguir no primeiro nó principal (mn0) do 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. O novo usuário deve possuir permissões corretas do Ranger para armazenar arquivos no diretório HDFS hdfs:///users/<username>, pois os notebooks individuais são armazenados em /users/<username>/notebooks. O administrador do cluster pode adicionar a permissão necessária na interface do Ranger abrindo o seguinte URL em um browser.
    https://<un0-host-ip>:6182
  4. O novo usuário deve ter permissões corretas no Yarn, Hive e Object Storage para ler e gravar dados e executar jobs do Spark. O usuário pode usar a personificação do Livy (executar jobs do Big Data Service como usuário do Livy) sem obter permissões explícitas no Spark, Yarn e em outros serviços.
  5. Execute o comando a seguir para conceder ao novo usuário acesso ao diretório 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>"
Pré-requisitos para Autorizar um Usuário em um Cluster não HA

Esses pré-requisitos devem ser atendidos para autorizar um usuário em um cluster não HA do Big Data Service usando a autenticação nativa.

  1. O usuário deve existir no host do Linux. Execute o comando a seguir para adicionar um novo usuário do Linux em todos os nós de um cluster.
    # Add linux user
    dcli -C "useradd -d /home/<username> -m -s /bin/bash <username>"
  2. O novo usuário deverá ter permissões corretas para armazenar arquivos no diretório hdfs:///users/<username> do HDFS. Execute o comando a seguir para conceder ao novo usuário acesso ao diretório 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>"
Adicionando um Usuário Administrador

Os usuários administradores são responsáveis por configurar e gerenciar JupyterHub. Os usuários administradores também são responsáveis por autorizar usuários recém-inscritos em JupyterHub.

Antes de adicionar um usuário administrador, os pré-requisitos devem ser atendidos para um cluster HA ou cluster não HA.

  1. Acesse o Apache Ambari.
  2. Na barra de ferramentas lateral, em Serviços, selecione JupyterHub.
  3. Selecione Configurações e, em seguida, Configurações Avançadas.
  4. Selecione Advanced jupyterhub-config.
  5. Adicione o usuário administrador a c.Authenticator.admin_users.
  6. Selecione Salvar.
Um usuário administrador no arquivo de configuração JupyterHub não precisa ter autorização explícita durante o acesso. Após a inscrição, você pode entrar diretamente.
Adicionando Outros Usuários

Antes de adicionar outros usuários, os pré-requisitos devem ser atendidos para um cluster do Big Data Service.

  1. Acesse JupyterHub.
  2. Inscreva-se para o novo usuário. Usuários não administradores precisam de autorização explícita dos usuários administradores.
  3. O usuário administrador deve acessar JupyterHub e na nova opção de menu para autorizar usuários conectados e o novo usuário.
    Captura de tela da página Autorizar Usuários no Jupyterhub
  4. O novo usuário agora pode acessar.
Deletando Usuários

Um usuário administrador pode excluir usuários JupyterHub.

  1. Acesse JupyterHub.
  2. Abra Arquivo > HubControlPanel.
  3. Navegue até a página Autorizar Usuários.
  4. Exclua os usuários que você deseja remover.
Autenticação LDAP LDAP

Você pode usar a autenticação LDAP por meio de um browser para clusters ODH 1.x do Big Data Service 3.0.26 ou anteriores.

Integre com o Trino

Pré-requisitos
  • O Trino deve ser instalado e configurado no cluster do Big Data Service.
  • Instale o seguinte módulo Python no nó JupyterHub (un1 para HA / un0 para cluster não HA)
    Observação

    Ignore esta etapa se o módulo Trino-Python já estiver presente no nó.
    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.
Integração com o Cluster HA do Big Data Service

Se o Trino-Ranger-Plugin estiver ativado, certifique-se de adicionar o usuário do keytab fornecido nas respectivas políticas do Trino Ranger. Consulte Integrando o Trino ao Ranger.

Por padrão, o Trino usa o nome principal completo do Kerberos como usuário. Portanto, ao adicionar/atualizar políticas de trino-ranger, você deve usar o nome principal completo do Kerberos como nome de usuário.

Para a amostra de código a seguir, use jupyterhub@BDSCLOUDSERVICE.ORACLE.COM como usuário nas políticas trino-ranger.

Observação

Se o Trino-Ranger-Plugin estiver ativado, certifique-se de adicionar o usuário keytab fornecido nas respectivas políticas do Trino Ranger. Para obter mais detalhes, consulte Ativando o Ranger para Trino.

Forneça permissões do Ranger para JupyterHub às seguintes políticas:

  • all - catalog, schema, table, column
  • all - function
  1. Abra uma janela do browser.
  2. Informe um URL no seguinte formato:
    https://<node_ip_address>:8000

    Por exemplo:

    https://192.0.2.0:8000
  3. Acesse com suas credenciais. Consulte JupyterHub Credenciais Padrão.
  4. Informe o Princípio e o Keytab.
  5. Abra o notebook Phython 3.
  6. Criar motor com 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. Executar a consulta:
    query = "select custkey, name, phone, acctbal from tpch.sf1.customer limit 10"
    df = pd.read_sql(query, engine)
    print(df)
Integração com o cluster sem HA do Big Data Service
  1. Abra uma janela do browser.
  2. Informe um URL no seguinte formato:
    https://<node_ip_address>:8000

    Por exemplo:

    https://192.0.2.0:8000
  3. Acesse com suas credenciais. Consulte JupyterHub Credenciais Padrão.
  4. Abra o notebook Phython 3.
  5. Criar motor com 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. Executar a consulta:
    query = "select custkey, name, phone, acctbal from tpch.sf1.customer limit 10"
    df = pd.read_sql(query, engine)
    print(df)