Provedor de Databricks do Terraform CDK

Observação

Este artigo aborda o cloud Development Kit for Terraform (CDKTF), que não é fornecido nem suportado pelo Databricks. Para entrar em contato com o provedor, consulte a comunidade Terraform.

Este artigo mostra como usar Python ou TypeScript junto com o Provedor Terraform CDK Databricks e o cloud Development Kit para Terraform (CDKTF). O CDKTF é uma plataforma terceirizada de infraestrutura como código (IaC) que permite criar, aprimorar e gerenciar recursos do Databricks usando linguagens de programação, ferramentas e práticas de engenharia familiares. Embora este artigo mostre como usar Python e TypeScript, o CDKTF oferece suporte a linguagens adicionais, como Java, C# e Go.

O provedor Terraform CDK Databricks é baseado no provedor Databricks Terraform. Para obter mais informações, consulte Terraform Cloud. O CDKTF é baseado no AWS cloud Development Kit (AWS CDK).

Requisitos

Você deve ter um workspace do Databricks, pois este artigo aprimora recursos em um workspace existente.

Em sua máquina de desenvolvimento local, você deve ter o seguinte instalado:

  • Terraform, versão 1.1 ou superior. Para verificar se você possui o Terraform instalado e verificar a versão instalada, execute o comando terraform -v do seu terminal ou com o PowerShell. Instale o Terraform, caso ainda não o tenha instalado.

    terraform -v
    
  • Node.js, versão 16.13 ou superior e npm. Para verificar se você tem Node.js e npm instalados e para verificar as versões instaladas, execute os comandos node -v e npm -v. As versões mais recentes do Node.js já incluem npm. Instale Node.js e npm usando o Node Version Manager (nvm), se você não tiver Node.js e npm já instalados.

    node -v
    npm -v
    
  • A CLI do CDKTF. Para verificar se você possui o CDKTF CLI instalado e para verificar a versão instalada, execute o comando cdktf --version. Instale o CDKTF CLI usando npm, caso ainda não o tenha instalado.

    cdktf --version
    

    Dica

    Você também pode instalar o CDKTF CLI no macOS com o Homebrew. Consulte Instalar o CDKTF.

  • As ferramentas Runtime de linguagem apropriadas, como segue:

    Python versão 3.7 ou superior e pipenv versão 2021.5.29 ou superior. Para verificar se o senhor tem o Python e pipenv instalados e para verificar as versões instaladas, execute os comandos python --version e pipenv --version. Instale o Python e o pipenv, caso ainda não os tenha instalado.

    python --version
    pipenv --version
    

    TypeScript versão 4.4 ou superior. Para verificar se você possui o TypeScript instalado e a versão instalada, execute o comando tsc -v. Instale o TypeScript, caso ainda não o tenha instalado.

    tsc -v
    

    Instale o idioma Pré-requisitos.

  • Autenticação Databricks configurada para o tipo de autenticação compatível que você deseja usar. Consulte Autenticação na documentação do provedor Databricks Terraform.

Passo 1: Criar um projeto CDKTF

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

  1. Crie um diretório vazio para seu projeto CDKTF e, em seguida, alterne para ele. execute os seguintes comandos no seu terminal ou com o PowerShell:

    mkdir cdktf-demo
    cd cdktf-demo
    
    md cdktf-demo
    cd cdktf-demo
    
  2. Crie um projeto CDKTF executando o seguinte comando:

    cdktf init --template=python --local
    
    cdktf init --template=typescript --local
    
  3. Quando for solicitado um Nome de projeto, aceite o nome de projeto default de cdktf-demo pressionando Enter.

  4. Quando for solicitada uma descrição do projeto, aceite a descrição do projeto default pressionando Enter.

  5. Se solicitado Do you want to start from an existente Terraform project, digite N e pressione Enter.

  6. Se solicitado Deseja enviar relatórios de travamento para a equipe do CDKTF, digite n e pressione Enter.

O CDKTF cria os seguintes arquivos e subdiretórios em seu diretório cdktf-demo :

  • .gitignore, que é uma lista de arquivos e diretórios que o Git ignora se você quiser enviar este projeto para um repositório Git remoto.

  • cdktf.json, que contém definições de configuração para seu projeto CDKTF. Consulte Arquivo de configuração para obter mais informações sobre as definições de configuração.

  • help, que contém informações sobre alguns próximos passos que você pode seguir para trabalhar com seu projeto CDKTF.

  • main-test.py, que contém testes de unidade de suporte que você pode escrever para seu projeto CDKTF. Consulte Testes de unidade para obter mais informações sobre testes de unidade.

  • main.py, que contém o código Python que você escreve para seu projeto CDKTF.

  • Pipfile e Pipfile.lock, que gerenciam dependências de código para seu projeto CDKTF.

  • jest.config.js e um subdiretório __tests__ , que gerencia testes de unidade de suporte que você pode escrever para seu projeto CDKTF. Consulte Testes de unidade para obter mais informações sobre testes de unidade.

  • Um subdiretório node_modules , que contém dependências de código para seu projeto CDKTF.

  • .gitignore, que é uma lista de arquivos e diretórios que o Git ignora se você quiser enviar este projeto para um repositório Git remoto.

  • cdktf.json, que contém definições de configuração para seu projeto CDKTF. Consulte Arquivo de configuração para obter mais informações sobre as definições de configuração.

  • help, que contém informações sobre alguns próximos passos que você pode seguir para trabalhar com seu projeto CDKTF.

  • main.ts, que contém o código TypeScript que você escreve para seu projeto CDKTF.

  • .npmrc, package.json, package-lock.json, setup.js e tsconfig.json, que gerenciam dependências de código e outras configurações para seu projeto CDKTF.

Passo 2: Definir recursos

Nesta passo, você usará o provedor Terraform CDK Databricks para definir um Notebook e um Job para executar esse Notebook.

  1. Instale as dependências do projeto da seguinte maneira:

    Usando pipenv, instale em seu projeto CDKTF o Provedor Terraform CDK Databricks para gerar recursos Databricks. Para fazer isso, execute o seguinte:

    pipenv install cdktf-cdktf-provider-databricks
    

    Usando npm (para TypeScript), instale em seu projeto CDKTF o Provedor Terraform CDK Databricks para gerar recursos Databricks. Instale também as definições de TypeScript para o pacote Node.js para usar a classe Buffer para escrever código no Notebook. Para fazer isso, execute o seguinte:

    npm install @cdktf/provider-databricks --force
    npm install --save-dev @types/node
    
  2. Substitua o conteúdo do arquivo main.py (para Python) ou do arquivo main.ts (para TypeScript) pelo código a seguir. Este código autentica o CDKTF com seu workspace do Databricks e, em seguida, gera um Notebook junto com um Job para executar o Notebook. Para view a documentação de sintaxe para este código, consulte a referência de construção do provedor Terraform CDK Databricks para Python ou TypeScript.

    #!/usr/bin/env python
    from unicodedata import name
    from constructs import Construct
    from cdktf import App, TerraformStack, TerraformOutput
    from cdktf_cdktf_provider_databricks import *
    import vars
    from base64 import b64encode
    
    class MyStack(TerraformStack):
      def __init__(self, scope: Construct, ns: str):
        super().__init__(scope, ns)
    
        DatabricksProvider(
          scope = self,
          id    = "databricksAuth"
        )
    
        current_user = DataDatabricksCurrentUser(
          scope     = self,
          id_       = "currentUser"
        )
    
        # Define the notebook.
        notebook = Notebook(
          scope          = self,
          id_            = "notebook",
          path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
          language       = "PYTHON",
          content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
        )
    
        # Define the job to run the notebook.
        job = Job(
          scope = self,
          id_   = "job",
          name  = f"{vars.resource_prefix}-job",
          new_cluster = JobNewCluster(
            num_workers   = vars.num_workers,
            spark_version = vars.spark_version,
            node_type_id  = vars.node_type_id
          ),
          notebook_task = JobNotebookTask(
            notebook_path = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py"
          ),
          email_notifications = JobEmailNotifications(
            on_success = [ current_user.user_name ],
            on_failure = [ current_user.user_name ]
          )
        )
    
        # Output the notebook and job URLs.
        TerraformOutput(
          scope = self,
          id    = "Notebook URL",
          value = notebook.url
        )
    
        TerraformOutput(
          scope = self,
          id    = "Job URL",
          value = job.url
        )
    
    app = App()
    MyStack(app, "cdktf-python")
    
    app.synth()
    
    import { Construct } from "constructs";
    import { App, TerraformOutput, TerraformStack } from "cdktf";
    import { DatabricksProvider, DataDatabricksCurrentUser, Notebook, Job } from "@cdktf/provider-databricks";
    import * as vars from "./vars";
    
    class MyStack extends TerraformStack {
      constructor(scope: Construct, name: string) {
        super(scope, name);
    
        new DatabricksProvider(this, "databricksAuth", {})
    
        const currentUser = new DataDatabricksCurrentUser(this, "currentUser", {});
    
        // Define the notebook.
        const notebook = new Notebook(this, "notebook", {
          path: `${currentUser.home}/CDKTF/${vars.resourcePrefix}-notebook.py`,
          language: "PYTHON",
          contentBase64: Buffer.from("display(spark.range(10))", "utf8").toString("base64")
        });
    
        // Define the job to run the notebook.
        const job = new Job(this, "job", {
          name: `${vars.resourcePrefix}-job`,
          newCluster: {
            numWorkers: vars.numWorkers,
            sparkVersion: vars.sparkVersion,
            nodeTypeId: vars.nodeTypeId
          },
          notebookTask: {
            notebookPath: `${currentUser.home}/CDKTF/${vars.resourcePrefix}-notebook.py`
          },
          emailNotifications: {
            onSuccess: [ currentUser.userName ],
            onFailure: [ currentUser.userName ]
          }
        });
    
        // Output the notebook and job URLs.
        new TerraformOutput(this, "Notebook URL", {
          value: notebook.url
        });
    
        new TerraformOutput(this, "Job URL", {
          value: job.url
        });
      }
    }
    
    const app = new App();
    new MyStack(app, "cdktf-demo");
    app.synth();
    
  3. Crie um arquivo chamado vars.py (para Python) ou vars.ts (para TypeScript) no mesmo diretório que main.py (para Python) ou main.ts (para TypeScript). Substitua os valores a seguir por seus próprios valores para especificar um prefixo de recurso e configurações clusters , como o número de worker, stringsde versão do tempo de execução do Spark e tipo de nó.

    #!/usr/bin/env python
    resource_prefix = "cdktf-demo"
    num_workers     = 1
    spark_version   = "10.4.x-scala2.12"
    node_type_id    = "n1-standard-4"
    
    export const resourcePrefix = "cdktf-demo"
    export const numWorkers     = 1
    export const sparkVersion   = "10.4.x-scala2.12"
    export const nodeTypeId     = "n1-standard-4"
    

Passo 3: aprimorar os recursos

Nesta passo, você usa a CLI do CDKTF para aprimorar, em seu workspace Databricks existente, o Notebook definido e o Job para execução desse Notebook.

  1. Gere o código Terraform equivalente para seu projeto CDKTF. Para fazer isso, execute o comando cdktf synth .

    cdktf synth
    
  2. Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. execução o seguinte:

    cdktf diff
    
  3. aprimore o Notebook e Job executando o comando cdktf deploy.

    cdktf deploy
    
  4. Quando solicitado a Aprovar, pressione Enter. O Terraform cria e aprimorou o Notebook e Job em seu workspace.

Passo 4: Interagir com os recursos

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

  1. Para view o Notebook em que o Job será executado em seu workspace, copie o link do URLNotebook que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da web.

  2. Para view o Job que executa o Notebook em seu workspace, copie o link do URLJob que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da web.

  3. Para executar o Job, clique no botão Execution Now na página Job .

(Opcional) Passo 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.

Caso não queira fazer nenhuma alteração no Notebook, pule para o passo 6: Limpar.

  1. No arquivo main.py (para Python) ou no arquivo main.ts (para TypeScript), altere a declaração da variável notebook do seguinte:

        notebook = Notebook(
          scope          = self,
          id_            = "notebook",
          path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
          language       = "PYTHON",
          content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
        )
    
       const notebook = new Notebook(this, "notebook", {
          path: currentUser.home + "/CDKTF/" + vars.resourcePrefix + "-notebook.py",
          language: "PYTHON",
          contentBase64: Buffer.from("display(spark.range(10))", "utf8").toString("base64")
       });
    

    Para o seguinte:

        notebook = Notebook(
          scope          = self,
          id_            = "notebook",
          path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
          language       = "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")
        )
    
       const notebook = new Notebook(this, "notebook", {
          path: currentUser.home + "/CDKTF/" + vars.resourcePrefix + "-notebook.py",
          language: "PYTHON",
          contentBase64: Buffer.from(`
    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)`, "utf8").toString("base64")
       });
    

    Observação

    Certifique-se de que as linhas de código que começam e terminam com acentos graves (`) estejam niveladas com a borda do seu editor de código. Caso contrário, o Terraform inserirá espaços em branco no Notebook que podem fazer com que o novo código Python falhe na execução.

  2. Gere novamente o código Terraform equivalente para seu projeto CDKTF. Para fazer isso, execute o seguinte:

    cdktf synth
    
  3. Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. execução o seguinte:

    cdktf diff
    
  4. aprimore as alterações do Notebook executando o comando cdktf deploy.

    cdktf deploy
    
  5. Quando solicitado a Aprovar, pressione Enter. O Terraform altera o conteúdo do Notebook .

  6. Para view o Notebook alterado que o Job executará em seu workspace, refresh o Notebook que você abriu anteriormente ou copie o link do URLNotebook que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da web.

  7. Para view a Job que executa o Notebook alterado em seu workspace, refresh a Job que você abriu anteriormente ou copie o link da URLJob que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da web.

  8. Para executar o Job, clique no botão Execution Now na página Job .

Passo 6: Limpar

Nesta passo, você usa a CLI do CDKTF para remover o Notebook e Job do workspace do Databricks.

  1. Remova os recursos de seu workspace executando o comando cdktf destroy:

    cdktf destroy
    
  2. Quando solicitado a Aprovar, pressione Enter. O Terraform remove os recursos do seu workspace.