M03 — Azure Databricks Workspace + Cluster + Key Vault

Duração: 3h Pré-requisitos: M00–M02 concluídos. Storage com containers bronze/silver/gold e ao menos 1 arquivo no bronze. Objetivo: criar o workspace Databricks, um cluster Single Node barato, Key Vault com Secret Scope, e conectar Databricks ao seu ADLS via Service Principal — sem expor chaves.

Mapa do módulo

1. Criar Key Vault  ──►  2. Criar Service Principal (SP)
                                  │
                                  ▼
                          3. Dar ao SP RBAC "Storage Blob Data Contributor"
                                  │
                                  ▼
4. Guardar credenciais do SP no Key Vault
                                  │
                                  ▼
5. Criar Azure Databricks Workspace
                                  │
                                  ▼
6. Configurar Databricks CLI + Secret Scope → Key Vault
                                  │
                                  ▼
7. Criar Cluster Single Node + testar leitura do bronze

Parte 1 — Key Vault

Variáveis (continuação da trilha):

$PROJ = "de"; $INIC = "w"; $AMB = "dev"; $REGS = "brs"; $REG = "brazilsouth"
$RG = "rg-$PROJ-$AMB-$REGS"
$ST = "st$PROJ$INIC$AMB$REGS"
$KV = "kv-$PROJ-$INIC-$AMB"     # nome global; 3-24 chars
$DBW = "dbw-$PROJ-$AMB-$REGS"

Passo 1.1 — Criar Key Vault

az keyvault create `
  --name $KV `
  --resource-group $RG `
  --location $REG `
  --enable-rbac-authorization true `
  --tags projeto=$PROJ ambiente=$AMB trilha=azure-e2e

--enable-rbac-authorization true: ativa o modo moderno (RBAC). Não use o legado (access policies) em projetos novos.

Passo 1.2 — Dar a si mesmo permissão de escrever segredos

Pega seu objectId:

$ME = az ad signed-in-user show --query "id" -o tsv

Atribui role:

$KVID = az keyvault show -n $KV -g $RG --query "id" -o tsv
az role assignment create `
  --assignee-object-id $ME `
  --assignee-principal-type User `
  --role "Key Vault Secrets Officer" `
  --scope $KVID

Espera 1-2 min para a permissão propagar.

Parte 2 — Service Principal (SP) para o Databricks acessar o ADLS

Passo 2.1 — Criar o SP

$SP = az ad sp create-for-rbac `
  --name "sp-$PROJ-$AMB-databricks-adls" `
  --query "{appId:appId, password:password, tenant:tenant}" -o json | ConvertFrom-Json

$SP_APPID    = $SP.appId
$SP_SECRET   = $SP.password
$SP_TENANT   = $SP.tenant

Write-Output "App ID:  $SP_APPID"
Write-Output "Tenant:  $SP_TENANT"
# NUNCA imprima o secret em terminal compartilhado.

Passo 2.2 — Dar ao SP acesso ao Storage

$STID = az storage account show -n $ST -g $RG --query "id" -o tsv
az role assignment create `
  --assignee $SP_APPID `
  --role "Storage Blob Data Contributor" `
  --scope $STID

Em produção, prefira o role no container (<storageId>/blobServices/default/containers/silver) em vez do storage inteiro. Aqui simplificamos.

Passo 2.3 — Guardar credenciais no Key Vault

az keyvault secret set --vault-name $KV --name "sp-appid"    --value $SP_APPID
az keyvault secret set --vault-name $KV --name "sp-secret"   --value $SP_SECRET
az keyvault secret set --vault-name $KV --name "sp-tenant"   --value $SP_TENANT
az keyvault secret set --vault-name $KV --name "storage-account-name" --value $ST

Pronto. Esqueça $SP_SECRET na sua máquina (limpa a variável: Remove-Variable SP_SECRET). Daqui pra frente, Databricks lê do KV.

Parte 3 — Criar o Workspace Azure Databricks

Passo 3.1 — Via CLI

az databricks workspace create `
  --resource-group $RG `
  --name $DBW `
  --location $REG `
  --sku premium `
  --tags projeto=$PROJ ambiente=$AMB trilha=azure-e2e

SKU:

standard — limita features.
premium — habilita Unity Catalog, Table ACL, Secret Scopes backed by Key Vault. Use sempre Premium.
trial — 14 dias premium grátis. Free tier inclui isto uma vez.

Provisioning leva ~5 min.

Validar:

az databricks workspace show -g $RG -n $DBW --query "{name:name, state:provisioningState, url:workspaceUrl}" -o table

Esperado:

Name              State      Url
----------------  ---------  ----------------------------------------------------
dbw-de-dev-brs    Succeeded  adb-xxxxxxxxxxxxxxxx.xx.azuredatabricks.net

Salva a URL:

$DBWURL = "https://" + (az databricks workspace show -g $RG -n $DBW --query "workspaceUrl" -o tsv)
Write-Output "Abra: $DBWURL"

Passo 3.2 — Abrir o workspace pela primeira vez

Acesse $DBWURL (já estará logado via SSO da sua conta Azure).
Pop-up “Try Premium for free” → confirme.
Confira na home se está em eastus2 ou brazilsouth (no canto inferior).

Parte 4 — Databricks CLI + autenticação

Passo 4.1 — Gerar Personal Access Token (PAT)

No workspace web:

Canto superior direito → seu e-mail → User Settings.
Aba Developer → Access tokens → Generate new token.
Comentário: cli-localhost-dev. Vida útil: 90 dias.
Copie o token agora (não verá de novo).

Passo 4.2 — Configurar CLI

databricks configure --host $DBWURL --token
# cola o token quando pedir

Validar:

databricks current-user me

Deve retornar seu e-mail.

Lista clusters (vazio agora):

databricks clusters list

Parte 5 — Secret Scope vinculado ao Key Vault

No Databricks, segredos vivem em Secret Scopes. Podem ser:

Databricks-backed: scope nativo, mais simples.
Azure Key Vault-backed: aponta para um KV → segredos centralizados, só dá pra criar via UI.

Passo 5.1 — Criar scope KV-backed (via UI obrigatório)

Abra https://<workspace-url>#secrets/createScope (URL “escondida” do Databricks).
Scope name: kv.
Manage Principal: All Users (em dev).
DNS Name: cole https://<KV>.vault.azure.net/ (mostre com az keyvault show -n $KV -g $RG --query properties.vaultUri -o tsv).
Resource ID: cole o output de az keyvault show -n $KV -g $RG --query id -o tsv.
Create.

Passo 5.2 — Validar via CLI

databricks secrets list-scopes

Esperado:

Name  Backend Type
----  ------------
kv    AZURE_KEYVAULT

Listar os segredos visíveis (via scope, não dá pra ler o valor — só usar dentro do notebook):

databricks secrets list-secrets kv

Esperado: sp-appid, sp-secret, sp-tenant, storage-account-name.

Parte 6 — Criar Cluster Single Node (barato)

Para a trilha, Single Node (driver-only, sem workers) é mais que suficiente e custa ~USD 0.30/h. Cluster com workers vem só no M08 / case real.

Passo 6.1 — JSON do cluster

Crie cluster-single.json:

{
  "cluster_name": "dev-single-node",
  "spark_version": "15.4.x-scala2.12",
  "node_type_id": "Standard_DS3_v2",
  "num_workers": 0,
  "autotermination_minutes": 20,
  "data_security_mode": "SINGLE_USER",
  "single_user_name": "SEU_EMAIL_AQUI@dominio.com",
  "custom_tags": {
    "ResourceClass": "SingleNode",
    "projeto": "de",
    "ambiente": "dev",
    "trilha": "azure-e2e"
  },
  "spark_conf": {
    "spark.databricks.cluster.profile": "singleNode",
    "spark.master": "local[*, 4]"
  }
}

autotermination_minutes: 20 = se você fechar o notebook, em 20 min o cluster apaga. Critical pra não queimar crédito.

data_security_mode: SINGLE_USER = obrigatório para usar Unity Catalog (M06).

Passo 6.2 — Criar

databricks clusters create --json @cluster-single.json

Aguarde ~3-5 min (databricks clusters list).

Parte 7 — Primeiro notebook + leitura do ADLS

Passo 7.1 — Importar notebook

Crie 01_test_adls.py na sua máquina:

# Databricks notebook source
# MAGIC %md # Teste de conexão ADLS via Service Principal

# COMMAND ----------

# Lê credenciais do Key Vault via Secret Scope
sp_appid  = dbutils.secrets.get("kv", "sp-appid")
sp_secret = dbutils.secrets.get("kv", "sp-secret")
sp_tenant = dbutils.secrets.get("kv", "sp-tenant")
storage   = dbutils.secrets.get("kv", "storage-account-name")

# COMMAND ----------

# Configura OAuth2 para o storage
endpoint = f"fs.azure.account.oauth2.client.endpoint.{storage}.dfs.core.windows.net"
spark.conf.set(f"fs.azure.account.auth.type.{storage}.dfs.core.windows.net", "OAuth")
spark.conf.set(f"fs.azure.account.oauth.provider.type.{storage}.dfs.core.windows.net",
               "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set(f"fs.azure.account.oauth2.client.id.{storage}.dfs.core.windows.net", sp_appid)
spark.conf.set(f"fs.azure.account.oauth2.client.secret.{storage}.dfs.core.windows.net", sp_secret)
spark.conf.set(endpoint, f"https://login.microsoftonline.com/{sp_tenant}/oauth2/token")

# COMMAND ----------

bronze_root = f"abfss://bronze@{storage}.dfs.core.windows.net/"
display(dbutils.fs.ls(bronze_root))

# COMMAND ----------

# Lê o parquet que você subiu no M02
df = spark.read.parquet(
    f"{bronze_root}source=nyctaxi/dataset=yellow/year=2024/month=01/"
)
print(f"Linhas: {df.count():,}")
df.printSchema()
display(df.limit(5))

Passo 7.2 — Importar pro workspace

databricks workspace import 01_test_adls.py /Users/SEU_EMAIL/01_test_adls --language PYTHON --format SOURCE

Passo 7.3 — Rodar

Abra o workspace web → navega até o notebook.
Topo direito → Attach → escolhe dev-single-node.
Run all.

Esperado: lista de pastas no Bronze, e contagem ~3 milhões de linhas (NYC taxi Jan/2024).

Se der erro AuthenticationFailed na leitura → role do SP não propagou. Espere 2 min e rode de novo.

Parte 8 — Boas práticas que viram costume

Custom tags no cluster

Sempre marque com projeto, ambiente, responsavel. Em prod, faturamento depende disso.

Pools (opcional, mas vale ler)

Cluster Pool = “máquinas pré-aquecidas”. Reduz tempo de start de 5 min → 30 seg. Cobra só quando em uso. Para a trilha não precisa, mas conhecer cai em entrevista.

Init scripts

Scripts shell que rodam no boot do cluster (instalar libs custom, configs JVM). Em Unity Catalog clusters Single User, init scripts precisam estar em Volume (M06) ou em workspace files.

Pegadinhas

SKU standard no workspace → não consegue criar Secret Scope KV-backed. Sempre premium.
Secret Scope KV-backed criado mas databricks secrets list-scopes mostra “AZURE_KEYVAULT” e list-secrets vazio → sua identidade Azure não tem permissão de listar segredos no KV. Adicione role “Key Vault Reader” + “Key Vault Secrets User” na sua identidade no KV.
AuthenticationFailed ao ler o storage → 1) role não propagou; 2) você pegou o client secret errado; 3) confundiu App ID com Object ID (são diferentes!).
Cluster fica em Pending por 10+ min → cota da subscription (free tier limita vCPUs). Vá em Subscription → Usage + quotas e veja Standard DSv2 Family vCPUs.
Esqueceu autotermination_minutes → cluster fica ligado 24h, queima USD 7/dia. Sempre defina.

Snippets úteis

Parar cluster manualmente:

$CID = databricks clusters list --output json | ConvertFrom-Json | Where-Object { $_.cluster_name -eq "dev-single-node" } | Select-Object -ExpandProperty cluster_id
databricks clusters delete --cluster-id $CID    # "delete" significa terminar; pode religar depois

Logs do cluster:

databricks clusters events --cluster-id $CID

Checklist de saída

Workspace Databricks Premium criado e acessível.
Key Vault com 4 segredos (sp-appid, sp-secret, sp-tenant, storage-account-name).
Secret Scope kv (AZURE_KEYVAULT) listado em databricks secrets list-scopes.
Cluster Single Node criado, com autotermination_minutes: 20.
Notebook 01_test_adls roda do início ao fim sem erro e mostra 5 linhas do dataset.
Cluster está terminado agora (Network → Compute → ícone de “stopped”). Sem cluster aceso de graça.

→ M04 — Primeiro notebook Spark + Delta (Bronze → Silver)