Pulumi Databricks provedor de recursos

important

Essa documentação foi descontinuada e pode não estar atualizada.

nota

Este artigo abrange o Pulumi, que é desenvolvido por terceiros. Para entrar em contato com o provedor, consulte o suporte da Pulumi.

Este artigo mostra como usar o Python e o Pulumi, uma plataforma de infraestrutura como código (IaC) de terceiros que permite criar, implantar e gerenciar Databricks recursos usando linguagens de programação, ferramentas e práticas de engenharia familiares. Embora este artigo mostre como usar Python e o provedor de recursos Pulumi Databricks, o Pulumi oferece suporte a outras linguagens além de Python para Databricks, incluindo TypeScript, JavaScript, Go e C#.

O provedor Pulumi Databricks recurso é baseado no provedorDatabricks Terraform. Para obter mais informações, consulte Terraform Cloud.

Requisitos

A Pulumi account. Inscreva-se no Pulumi, se o senhor ainda não tiver um Pulumi account. O Pulumi é gratuito para indivíduos e oferece um nível gratuito para equipes.
Python 3.6 ou superior. Para verificar se o senhor tem o site Python instalado, execute o comando python --version em seu terminal ou com PowerShell. Instale o Python, se o senhor ainda não o tiver instalado.

nota

Algumas instalações do Python podem exigir que o senhor use python3 em vez de python. Nesse caso, substitua python por python3 em todo este artigo.

O URL da instância do workspace do Databricks, por exemplo, https://1234567890123456.7.gcp.databricks.com.
Credenciais de acesso ao Databricks. Os projetos do Pulumi Databricks são compatíveis com os seguintes tipos de autenticação do Databricks:
- Databricks autenticação de tokens de acesso pessoal (databricks:authType pat)
Consulte Configuração no repositório do Pulumi Databricks no GitHub.

As etapas a seguir mostram como criar um projeto do Pulumi Databricks com Python. Para obter um tutorial de uma perspectiva puramente voltada para o provedor de nuvem, consulte Começar com o Google Cloud na documentação do Pulumi. Para obter um tutorial de uma perspectiva que prioriza a linguagem de programação, consulte Python, Node.js (JavaScript, TypeScript), Go e .NET (C#, VB, F#) na documentação do Pulumi.

Etapa 1: Crie um projeto Pulumi

Nesta passo, em sua máquina de desenvolvimento local, você configura a estrutura de diretórios necessária para um projeto Pulumi. Em seguida, você cria seu projeto Pulumi dentro dessa estrutura de diretório.

No terminal ou com o PowerShell, crie um diretório vazio e mude para ele, por exemplo:

Unix, Linux, and macOS
Windows

Bash
mkdir pulumi-demo
cd pulumi-demo

PowerShell

md pulumi-demo
cd pulumi-demo

Instale o Pulumi executando o seguinte comando, dependendo do seu sistema operacional:

Unix, Linux
MacOS
Windows

Install Pulumi on Unix or Linux by using curl:

Bash
curl -fsSL https://get.pulumi.com | sh

Install Pulumi on macOS by using Homebrew:

Bash
brew install pulumi/tap/pulumi

Install Pulumi on Windows by using PowerShell with elevated permissions through the Chocolatey package manager:

PowerShell

choco install pulumi

Para opções alternativas de instalação do Pulumi, consulte download e instalação na documentação do Pulumi. 3. Crie um projeto básico do Python Pulumi executando o seguinte comando:

Bash

pulumi new python

dica

O senhor também pode criar um projeto Pulumi a partir do seu Pulumi account on-line (Projects > Create project ). No entanto, não há um projeto padrão para Databricks.

Se solicitado, pressione Enter key e, em seguida, use o navegador da Web para fazer login no Pulumi account on-line, caso ainda não tenha feito login. Depois de fazer login, retorne ao terminal ou ao PowerShell.
Quando for solicitado um nome de projeto , aceite o nome de projeto default de pulumi-demo pressionando Enter .
Quando for solicitada uma descrição do projeto , digite A demo Python Pulumi Databricks project e pressione Enter .
Quando for solicitado um nome de pilha , aceite o nome de pilha default de dev pressionando Enter . O Pulumi cria os seguintes arquivos e subdiretórios em seu diretório pulumi-demo:
- Pulumi.yaml, que é uma lista de configurações para seu projeto Pulumi.
- __main__.pyque contém o código Python que o senhor escreve para o seu projeto Pulumi.
- requirements.txtque é uma lista de suporte ao pacote de código Python que o Pulumi instala para o seu projeto.
- .gitignoreque é uma lista de arquivos e diretórios que o Git ignora se o senhor quiser enviar esse projeto para um repositório Git remoto.
- O subdiretório venv contém o código do ambiente virtual Python de suporte que o Pulumi utiliza para seu projeto.
Execute uma implementação inicial da pilha dev do seu projeto executando o seguinte comando:
Bash
```
pulumi up
```
Quando solicitado a realizar essa atualização, pressione a seta para cima key para navegar até yes e, em seguida, pressione Enter .
Copie o link view Live que aparece e cole-o na barra de endereços do navegador da Web, que o levará ao Pulumi account on-line. Os detalhes da atividade da pilha dev para seu projeto pulumi-demo aparecem. Não há muito o que ver neste momento, pois ainda não há nenhum recurso em sua pilha. O senhor cria esses recursos na próxima etapa.

Etapa 2: Criar Databricks recurso

Nesta passo, você usa o provedor de recursos Pulumi Databricks para criar, em seu workspace Databricks existente, um Notebook e um Job para executar esse Notebook.

No arquivo __main.py__ que o Pulumi gerou, use seu editor de texto preferido ou ambiente de desenvolvimento integrado (IDE) para inserir o código a seguir. Este código declara o Pulumi Databricks Notebook e Job e suas configurações:

Python
"""A Python Pulumi program"""

import pulumi
from pulumi_databricks import *
from base64 import b64encode

# Get the authenticated user's workspace home directory path and email address.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/getcurrentuser
user_home_path     = get_current_user().home
user_email_address = get_current_user().user_name

# Define the name prefix to prepend to the resource names that are created
# for the Notebook and Job resources. To do this, you can use a Pulumi
# configuration value instead of hard-coding the name prefix in this file.
#
# To set a Pulumi configuration value, run the following command, which sets
# a "resource-prefix" configuration value to "pulumi-demo" in the
# associated "Pulumi.<stack-name>.yaml" configuration file:
#
# pulumi config set resource-prefix "pulumi-demo"
#
# For more information about defining and retrieving hard-coded values, see
# https://www.pulumi.com/docs/intro/concepts/config
config = pulumi.config.Config()
resource_prefix = config.require('resource-prefix')

# Define cluster resource settings.
node_type = config.require('node-type')

# Create a Notebook resource.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/notebook
# This example adds a single cell to the notebook, which is constructed from
# a single base64-encoded string. In practice, you would replace this:
#
# language       = "PYTHON",
# content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
#
# With this:
#
# source         = "path/to/local/my-notebook.py"
#
# To provide more notebook content easier and faster. Also, the notebook's language
# is automatically detected. If you specify a notebook path, be sure that it does
# not end in .ipynb, as Pulumi relies on the workspace import API, which doesn't
# rely on any specific extensions such as .ipynb in the notebook path.
notebook = Notebook(
  resource_name  = f"{resource_prefix}-notebook",
  path           = f"{user_home_path}/Pulumi/{resource_prefix}-notebook.py",
  language       = 'PYTHON',
  content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
)

# Export the URL of the Notebook, so that you can easily browse to it later.
# See https://www.pulumi.com/docs/intro/concepts/stack/#outputs
pulumi.export('Notebook URL', notebook.url)

# Create a Job resource.
# See https://www.pulumi.com/registry/packages/databricks/api-docs/job
# This job uses the most recent Databricks Runtime long-term support (LTS)
# runtime programmatic version ID at the time this article was first published,
# which is 14.3.x-scala2.12. You can replace this with a later version.
job = Job(
  resource_name = f"{resource_prefix}-job",
  name = f"{resource_prefix}-job",
  tasks = [
    JobTaskArgs(
      task_key = f"{resource_prefix}-task",
      new_cluster   = JobNewClusterArgs(
        num_workers   = 1,
        spark_version = "14.3.x-scala2.12",
        node_type_id  = node_type
      ),
      notebook_task = JobNotebookTaskArgs(
        notebook_path = f"{user_home_path}/Pulumi/{resource_prefix}-notebook.py"
      )
    )
  ],
  email_notifications = JobEmailNotificationsArgs(
    on_successes = [ user_email_address ],
    on_failures  = [ user_email_address ]
  )
)

# Export the URL of the Job, so that you can easily browse to it later.
# See https://www.pulumi.com/docs/intro/concepts/stack/#outputs
pulumi.export('Job URL', job.url)

Defina um valor de configuração chamado resource-prefix e defina-o como o valor hard-coded pulumi-demo, executando o seguinte comando. O Pulumi usa esse valor de configuração para nomear o Notebook e o Job:
Bash
```
pulumi config set resource-prefix "pulumi-demo"
```
O Pulumi cria um arquivo chamado Pulumi.dev.yaml no mesmo diretório do arquivo __main__.py e adiciona o seguinte código a esse arquivo YAML:
YAML
```
config:
  pulumi-demo:resource_prefix: pulumi-demo
```
O uso de valores de configuração permite que seu código seja mais modular e reutilizável. Agora, outra pessoa pode reutilizar seu arquivo __main__.py e definir um valor diferente para a variável resource_prefix sem alterar o conteúdo do arquivo __main__.py.
Defina um valor de configuração chamado node-type e defina-o como o seguinte valor codificado, executando o seguinte comando. O Pulumi usa esse valor de configuração para determinar o tipo de clustering no qual o trabalho é executado.
Bash
```
pulumi config set node-type "n1-standard-4"
```
O conteúdo do arquivo Pulumi.dev.yaml agora tem a seguinte aparência:
YAML
```
config:
  pulumi-demo:node-type: n1-standard-4
  pulumi-demo:resource-prefix: pulumi-demo
```
Para permitir que o Pulumi se autentique com seu Databricks workspace, defina os valores de configuração específicos do Databricks executando o comando relacionado. Por exemplo, para autenticação de tokens de acesso pessoal Databricks, execute o seguinte comando. Nesses comandos:
- Substitua <workspace-instance-url> pelo URL da instância do workspace, por exemplo, https://1234567890123456.7.gcp.databricks.com.
- Substitua <access-token> pelo valor de seus tokens de acesso. Certifique-se de especificar a opção --secret. Isso instrui o Pulumi a criptografar seus tokens de acesso como uma prática recomendada de segurança.

nota

Por default, o Pulumi usa uma criptografia por pilha key gerenciada pelo serviço Pulumi e um salt por valor para criptografar valores. Para usar um provedor de criptografia alternativo, consulte Configurando a criptografia de segredos na documentação do Pulumi.

Bash
pulumi config set databricks:host "<workspace-instance-url>"
pulumi config set databricks:token "<access-token>" --secret

O conteúdo do arquivo Pulumi.dev.yaml agora tem a seguinte aparência:

YAML
config:
  databricks:host: <your-workspace-instance-url>
  databricks:token:
    secure: <an-encrypted-version-of-your-access-token>
  pulumi-demo:node-type: n1-standard-4
  pulumi-demo:resource_prefix: pulumi-demo

Para usar um tipo de autenticação diferente do Databricks, consulte os Requisitos. Consulte também Configuration (Configuração ) no repositório do Pulumi Databricks no GitHub.

Etapa 3: implantado o recurso

Nesta etapa, o senhor ativa um Python ambiente virtual que o Pulumi fornece para o seu projeto como parte da execução do Python padrão de projeto Pulumi. Esse ambiente virtual ajuda a garantir que o senhor esteja usando a versão correta do Python, do Pulumi e do provedor de recursos do Pulumi Databricks juntos. Há várias estruturas de ambiente virtual Python disponíveis, como venv, virtualenv e pipenv. Este artigo e o projeto Pulumi Python padrão usam venv. venv já está incluído no Python. Para obter mais informações, consulte Criação de ambientes virtuais.

Ative o ambiente virtual Python executando o seguinte comando no diretório pulumi-demo, dependendo do sistema operacional e do tipo de shell:

Plataforma	Shell	comando para ativar o ambiente virtual
Unix, Linux, macOS	bash/zsh	`source venv/bin/activate`
	peixe	`source venv/bin/activate.fish`
	csh/tcsh	`source venv/bin/activate.csh`
	Núcleo do PowerShell	`venv/bin/Activate.ps1`
Windows	cmd.exe	`venv\Scripts\activate.bat`
	PowerShell	`venv\Scripts\Activate.ps1`

Instale o provedor de recursos Pulumi Databricks do Python pacote Index (PyPI ) em seu ambiente virtual executando o seguinte comando:
Bash
```
pip install pulumi-databricks
```

nota

Algumas instalações do pip podem exigir que você use pip3 em vez de pip. Se for o caso, substitua pip por pip3 em todo este artigo.

Visualize o recurso que o Pulumi criará executando o seguinte comando:
Bash
```
pulumi preview
```
Se houver algum erro relatado, corrija-o e execute o comando novamente.

Para view um relatório detalhado em seu Pulumi account on-line sobre o que o Pulumi fará, copie o link view Live que aparece e cole-o na barra de endereços do navegador da Web.
Crie e implante o recurso em seu site Databricks workspace executando o seguinte comando:
Bash
```
pulumi up
```
Quando solicitado a realizar essa atualização, pressione a seta para cima key para navegar até yes e, em seguida, pressione Enter . Se houver algum erro relatado, corrija-o e execute o comando novamente.
Para view um relatório detalhado em seu Pulumi account on-line sobre o que o Pulumi fez, copie o link view Live exibido e cole-o na barra de endereços do navegador da Web.

Etapa 4: Interagir com o recurso

Nesta passo, você executa o Job em seu workspace do Databricks, que executa o Notebook especificado.

Para view o Notebook que o Job executará em seu workspace, copie o link do URLNotebook que aparece e cole-o na barra de endereços do seu navegador da Web.
Para acessar view o Job que executa o Notebook em seu workspace, copie o link do URLJob que aparece e cole-o na barra de endereços do navegador da Web.
Para executar o trabalho, clique no botão executar agora na página do trabalho.
Depois que o trabalho terminar de ser executado, para view os resultados da execução do trabalho, na lista Execução concluída (últimos 60 dias) na página do trabalho, clique na entrada de tempo mais recente na coluna de tempo inicial . O painel Output mostra o resultado da execução do código do Notebook, que imprime os números de 1 a 10.

(Opcional) Etapa 5: fazer alterações em um recurso

Nesta passo opcional, você altera o código do Notebook, reimplementa o Notebook alterado e, em seguida, usa o Job para executar novamente o Notebook alterado.

Se o senhor não quiser fazer nenhuma alteração no Notebook, pule para a Etapa 6: Limpeza.

De volta ao arquivo __main.py__, altere esta linha de código:

Python
content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")

Para isso, e depois salve o arquivo:

Python
  content_base64 = b64encode(b'''
data = [
         { "Category": 'A', "ID": 1, "Value": 121.44 },
         { "Category": 'B', "ID": 2, "Value": 300.01 },
         { "Category": 'C', "ID": 3, "Value": 10.99 },
         { "Category": 'E', "ID": 4, "Value": 33.87}
       ]

df = spark.createDataFrame(data)

display(df)
''').decode("UTF-8")

Essa alteração instrui o Notebook a imprimir o conteúdo do site DataFrame especificado em vez dos números de 1 a 10.

nota

Certifique-se de que as linhas de código que começam com data e terminam com ''').decode("UTF-8") estejam alinhadas com a borda do seu editor de código. Caso contrário, o Pulumi inserirá espaços em branco adicionais no Notebook, o que pode fazer com que o novo código Python falhe na execução.

Opcionalmente, visualize o recurso que o Pulumi alterará executando o seguinte comando:
Bash
```
pulumi preview
```
Se houver algum erro relatado, corrija-o e execute o comando novamente.

Para view um relatório detalhado em seu Pulumi account on-line sobre o que o Pulumi fará, copie o link view Live que aparece e cole-o na barra de endereços do navegador da Web.
Implemente a alteração do recurso em seu site Databricks workspace executando o seguinte comando:
Bash
```
pulumi up
```
Quando solicitado a realizar essa atualização, pressione a seta para cima key para navegar até yes e, em seguida, pressione Enter . Se houver algum erro relatado, corrija-o e execute o comando novamente.
Para view um relatório detalhado em seu Pulumi account on-line sobre o que o Pulumi fez, copie o link view Live exibido e cole-o na barra de endereços do navegador da Web.
Para view o Notebook alterado em seu workspace, copie o link do URLNotebook que aparece e cole-o na barra de endereços do navegador da Web.
Para executar novamente o Job com o Notebook alterado, copie o link Job URL que aparece e cole-o na barra de endereços do navegador da Web. Em seguida, clique no botão executar agora na página do trabalho.
Depois que o trabalho terminar de ser executado, para view os resultados da execução do trabalho, na lista Execução concluída (últimos 60 dias) na página do trabalho, clique na entrada de tempo mais recente na coluna de tempo inicial . O painel Output (Saída ) mostra o resultado da execução do código do Notebook, que imprime o conteúdo do site DataFrame especificado.

Etapa 6: Limpar

Nesta passo, você instrui Pulumi a remover o Notebook e Job de seu workspace Databricks, bem como remover o projeto pulumi-demo e sua pilha dev de sua account Pulumi online.

Remova o recurso do site Databricks workspace executando o seguinte comando:
Bash
```
pulumi destroy
```
Quando solicitado a realizar essa remoção, pressione a seta para cima key para navegar até yes e, em seguida, pressione Enter .
Remova o projeto Pulumi pulumi-demo e sua pilha dev do seu Pulumi account on-line executando o seguinte comando:
Bash
```
pulumi stack rm dev
```
Quando solicitado a realizar essa remoção, digite dev e pressione Enter .
Para desativar o ambiente virtual venv Python, execute o seguinte comando:
Bash
```
deactivate
```

Testando

O senhor pode testar seu projeto Pulumi antes de implantá-lo. Consulte Testando os programas Pulumi na documentação do Pulumi.

Para testes de unidade de Pythonprojetos Pulumi baseados em, o senhor pode escrever e executar testes de unidade usando Python a estrutura de teste unittest do junto com o namespace pulumi.runtime do pacote Pulumi. Para executar testes com recurso simulado, o senhor substitui as chamadas para o Pulumi (e para Databricks) por mocks. Consulte os programas de teste unitário Pulumi na documentação do Pulumi.

O arquivo de exemplo a seguir, denominado infra.py, simula uma implementação do Notebook e do Job declarados no arquivo main.py deste artigo. Os testes de unidade neste exemplo verificam se o conteúdo codificado em Base64 do Notebook, o nome do Job e o destinatário email para a execução bem-sucedida do Job retornam os valores esperados. Dessa forma, somente essas propriedades relacionadas são simuladas aqui com valores de exemplo. Além disso, os valores de propriedade de recurso necessários sempre devem ser fornecidos, mesmo que o senhor não planeje usá-los em seus testes de unidade. Neste exemplo, esses valores obrigatórios são definidos como valores my-mock- aleatórios e esses valores não são testados.

Python
# infra.py

from pulumi_databricks import (
  Notebook,
  Job,
  JobEmailNotificationsArgs
)

notebook = Notebook(
  resource_name  = 'my-mock-notebook-resource-name',
  path           = 'my-mock-notebook-path',
  content_base64 = 'ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp'
)

job = Job(
  resource_name = 'my-mock-job-resource-name',
  name          = 'pulumi-demo-job',
  email_notifications = JobEmailNotificationsArgs(
    on_successes = [ 'someone@example.com' ]
  )
)

O arquivo de exemplo test_main.py a seguir testa se as propriedades relacionadas retornam seus valores esperados.

Python
# test_main.py

import pulumi
from pulumi_databricks import *
import unittest
import infra

# Set up mocking.
class MyMocks(pulumi.runtime.Mocks):
  def new_resource(self, type_, name, inputs, provider, id_):
    return [name + '_id', inputs]

  def call(self, token, args, provider):
    return {}

pulumi.runtime.set_mocks(MyMocks())

class TestNotebookAndJob(unittest.TestCase):
  @pulumi.runtime.test
  def test_notebook(self):
    def check_notebook_content_base64(args):
      content_base64 = args
      # Does the notebook's Base64-encoded content match the expected value?
      self.assertIn('ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp', content_base64)

    # Pass the mocked notebook's content_base64 property value to the test.
    return pulumi.Output.all(infra.notebook.content_base64).apply(check_notebook_content_base64)

  @pulumi.runtime.test
  def test_job(self):
    def check_job_name_and_email_onsuccesses(args):
      name, email_notifications = args
      # Does the job's name match the expected value?
      self.assertIn('pulumi-demo-job', name)
      # Does the email address for successful job runs match the expected value?
      self.assertIn('someone@example.com', email_notifications['on_successes'])

    # Pass into the test the mocked job's property values for the job's name
    # and the job's email address for successful runs.
    return pulumi.Output.all(
      infra.job.name,
      infra.job.email_notifications
    ).apply(check_job_name_and_email_onsuccesses)

Para executar esses testes e exibir seus resultados, execute o seguinte comando no diretório raiz do projeto Pulumi:

Python
python -m unittest

Para obter informações sobre outros tipos de testes que o senhor pode executar, consulte os artigos a seguir na documentação do Pulumi:

Requisitos​

Etapa 1: Crie um projeto Pulumi​

Etapa 2: Criar Databricks recurso​

Etapa 3: implantado o recurso​

Etapa 4: Interagir com o recurso​

(Opcional) Etapa 5: fazer alterações em um recurso​

Etapa 6: Limpar​

Testando​

Mais recurso​

Requisitos

Etapa 1: Crie um projeto Pulumi

Etapa 2: Criar Databricks recurso

Etapa 3: implantado o recurso

Etapa 4: Interagir com o recurso

(Opcional) Etapa 5: fazer alterações em um recurso

Etapa 6: Limpar

Testando

Mais recurso