Configuração do JupyterLab

O chart tdp-jupyter empacota o JupyterHub 5.3.0 com integração Spark para o TDP no Kubernetes.

O que é o JupyterLab?

O JupyterLab é a interface interativa de notebooks do TDP Kubernetes — o ambiente onde analistas e engenheiros de dados escrevem e executam código diretamente no browser, organizam arquivos e exploram dados.

Quando um usuário faz login, o JupyterLab abre em um ambiente isolado: storage, memória e CPU próprios, sem interferência com outros usuários.

A principal diferença em relação a um Jupyter local é a integração com Apache Spark: os notebooks não executam Spark na máquina do usuário — eles se conectam ao cluster Spark TDP (tdp-spark) e distribuem o processamento pelos workers do cluster.

Como o JupyterLab funciona no TDP Kubernetes

O JupyterLab é servido pelo JupyterHub — o servidor multiusuário que orquestra o ciclo de vida dos ambientes no Kubernetes.

O JupyterHub é responsável por autenticação, criação e encerramento dos pods de usuário; o JupyterLab é a interface que o usuário vê e usa dentro de cada pod.

Em vez de cada analista instalar o Jupyter localmente, o JupyterHub centraliza tudo no cluster: cada login resulta em um pod Kubernetes dedicado com o ambiente JupyterLab isolado.

Para saber mais

Consulte JupyterLab — Conceitos para uma visão completa da ferramenta, sua arquitetura e funcionamento.

Componentes implantados

Componente	Descrição
Hub	Servidor central que gerencia autenticação e criação de ambientes
Proxy	Proxy reverso que roteia requisições para o ambiente de cada usuário
Single-user pods	Um pod Kubernetes por usuário logado, com o notebook e o kernel
Integração Spark	ConfigMap que aponta os notebooks para o master Spark do cluster

O modelo single-user

Cada vez que um usuário faz login, o Hub cria um Pod dedicado para ele no Kubernetes.

Quando o usuário termina e para o servidor, o Pod é encerrado (mas o storage persiste, se configurado com PVC).

Isso significa que você precisa dimensionar o cluster para o pico de usuários simultâneos.

Pré-requisitos

• Kubernetes 1.19+, Helm 3.2+
• Provisionador de PV
• Cluster Spark via chart tdp-spark (ou instalação compatível), quando usar integração Spark

Instalação (OCI)

Terminal input

helm install <release> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-jupyter \
  -n <namespace> --create-namespace

Parâmetros principais

Parâmetro	Descrição
tdp-jupyter.enabled	Habilitar JupyterHub
tdp-jupyter.hub.resources	CPU/memória do hub
tdp-jupyter.hub.config.JupyterHub.authenticator_class	Autenticação (padrão: dummy)
tdp-jupyter.singleuser.*	CPU/memória/storage do usuário
tdp-jupyter.proxy.service.*	Tipo de Service / NodePorts
TDPConfigurations.externalDatabase.*	PostgreSQL externo opcional
tdpSparkIntegration.enabled	Integração Spark

Integração Spark

tdpSparkIntegration:
  enabled: true
  configMap:
    sparkConfig:
      "spark.executor.instances": "2"
      "spark.executor.memory": "4g"
      "spark.executor.cores": "3"

tdp-spark:
  spark:
    worker:
      replicaCount: 2
      resources:
        limits:
          cpu: 4
          memory: 6Gi

Ajuste o master Spark (spark://...) e as políticas de rede conforme o namespace e o release reais do Spark no seu cluster; confira serviços e rótulos com kubectl get svc no ambiente alvo.

Banco externo (PostgreSQL)

TDPConfigurations:
  externalDatabase:
    enabled: true
    recreate: false
    externalSecret:
      releaseName: "<postgresql-release-name>"

tdp-jupyter:
  hub:
    db:
      type: postgres
      url: "postgresql://<db-user>@<postgresql-host>.<namespace>.svc.cluster.local:5432/<database>"
      password: null
      upgrade: false
    extraEnv:
      PGPASSWORD:
        valueFrom:
          secretKeyRef:
            name: "<jupyter-db-secret-name>"
            key: password

Service: NodePort / LoadBalancer / ClusterIP

NodePort (padrão): tdp-jupyter.proxy.service.type: NodePort e nodePorts conforme o arquivo de valores (veja helm show values).

LoadBalancer / ClusterIP: defina proxy.service.type como LoadBalancer ou ClusterIP, conforme a exposição desejada.

Storage

singleuser:
  storage:
    dynamic:
      storageClass: <storage-class>
    capacity: 5Gi

Políticas de rede

O chart expõe singleuser.networkPolicy com egress típico para o Spark e para armazenamento S3 — use como modelo e ajuste namespaceSelector, labels e portas ao seu cluster (não copie nomes de tenant/namespace de outro ambiente).

Acesso

NodePort

Terminal input

kubectl get nodes -o wide

Use http://<node-ip>:<http-nodeport> (porta conforme seus values).

Port-forward

Terminal input

kubectl port-forward -n <namespace> svc/<jupyter-proxy-service-name> 8080:80

Abra http://localhost:8080. O nome do Service costuma derivar do release (confira com kubectl get svc).

LoadBalancer

Terminal input

kubectl get svc -n <namespace>

Use o IP externo do Service do proxy quando aplicável.

Autenticação padrão

• Usuário: admin
• O chart define uma senha inicial de exemplo — altere obrigatoriamente em produção.

Segurança / LDAP

Consulte Segurança — JupyterLab.

Solução de problemas

Terminal input

kubectl -n <namespace> get pods -l app.kubernetes.io/instance=<release>
kubectl -n <namespace> logs -l app.kubernetes.io/component=hub
kubectl -n <namespace> logs -l app.kubernetes.io/component=proxy
kubectl -n <namespace> get pvc -l app.kubernetes.io/instance=<release>

Desinstalação

Terminal input

helm uninstall <release> -n <namespace>
kubectl delete configmap tdp-spark-jupyter-integration -n <namespace>

Para a lista completa de chaves, use helm show values na versão do chart que instalou.