Segredos

  • Artigo

Segredo é um par de chave-valor que armazena o material secreto, com um nome de chave exclusivo dentro de um escopo de segredos. Cada escopo é limitado a 1000 segredos. O tamanho máximo permitido para o valor do segredo é de 128 KB.

Consulte também a API de Segredos.

Criar um segredo

Os nomes secretos não diferenciam maiúsculas de minúsculas.

O método usado para criar um segredo depende do fato de você estar usando um escopo com suporte do Azure Key Vault ou um escopo com suporte do Databricks.

Criar um segredo em um escopo com suporte do Azure Key Vault

Para criar um segredo no Azure Key Vault, use a API REST Set Secret do Azure ou a interface do usuário do portal do Azure.

Azure Key Vault

Criar um segredo em um escopo com suporte do Databricks

Para criar um segredo em um escopo com suporte do Databricks usando a CLI do Databricks (versão 0.205 e superior):

databricks secrets put-secret --json '{
  "scope": "<scope-name>",
  "key": "<key-name>",
  "string_value": "<secret>"
}'

Se você estiver criando um segredo de várias linhas, poderá passar o segredo usando a entrada padrão. Por exemplo:

(cat << EOF
this
is
a
multi
line
secret
EOF
) | databricks secrets put-secret <secret_scope> <secret_key>

Você também pode fornecer um segredo de um arquivo. Para obter mais informações sobre como gravar segredos, consulte O que é a CLI do Databricks?.

Listar segredos

Para listar segredos em um determinado escopo:

databricks secrets list-secrets <scope-name>

A resposta exibe informações de metadados sobre os segredos, como os nomes de chave de segredos. Use o utilitário Secrets (dbutils.secrets) em um notebook ou trabalho para listar esses metadados. Por exemplo:

dbutils.secrets.list('my-scope')

Ler um segredo

Crie segredos usando a API REST ou a CLI, mas use o utilitário Secrets (dbutils.secrets) em um notebook ou trabalho para ler um segredo.

Excluir um segredo

Para excluir um segredo de um escopo com a CLI do Databricks:

databricks secrets delete-secret <scope-name> <key-name>

Você também pode usar a API de Segredos.

Para excluir um segredo de um escopo com suporte do Azure Key Vault, use a API REST do Azure SetSecret ou interface do usuário do portal do Azure.

Usar um segredo em uma propriedade de configuração ou variável de ambiente do Spark

Importante

Esse recurso está em uma versão prévia.

Observação

Disponível no Databricks Runtime 6.4 com suporte estendido e superior.

Você pode referenciar um segredo em uma propriedade de configuração ou variável de ambiente do Spark. Os segredos recuperados são editados da saída do notebook e dos logs do driver e do executor do Spark.

Importante

Lembre-se das seguintes implicações de segurança ao referenciar segredos em uma propriedade de configuração ou variável de ambiente do Spark:

  • Se o controle de acesso à tabela não estiver habilitado em um cluster, qualquer usuário com permissões Pode Anexar a em um cluster ou com permissões de Execução em um notebook poderá ler as propriedades de configuração do Spark de dentro do notebook. Isso inclui usuários que não têm permissão direta para ler um segredo. O Databricks recomenda habilitar o controle de acesso à tabela em todos os clusters ou gerenciar o acesso a segredos usando escopos de segredos.

  • Mesmo quando o controle de acesso à tabela está habilitado, os usuários com permissões Pode Anexar a em um cluster ou permissões de Execução em um notebook podem ler variáveis de ambiente de cluster de dentro do notebook. O Databricks não recomenda armazenar segredos em variáveis de ambiente de cluster se elas não estiverem disponíveis para todos os usuários no cluster.

  • Os segredos não são removidos do log de driver stdout e fluxos stderr do Spark. Para proteger dados confidenciais, por padrão, os logs do driver Spark só podem ser visualizados por usuários com a permissão PODE GERENCIAR em clusters de trabalho, de modo de acesso de usuário único e de modo de acesso compartilhado. Para permitir que usuários com a permissão PODE ANEXAR A ou PODE REINICIAR visualizem os logs nesses clusters, defina a seguinte propriedade de configuração do Spark na configuração do cluster: spark.databricks.acl.needAdminPermissionToViewLogs false.

    Em clusters do modo de acesso compartilhado sem isolamento, os logs do driver Spark podem ser visualizados por usuários com a permissão PODE ANEXAR A ou PODE GERENCIAR. Para limitar quem pode ler os logs apenas aos usuários com a permissão PODE GERENCIAR, defina spark.databricks.acl.needAdminPermissionToViewLogs como true.

Requisitos e limitações

Os seguintes requisitos e limitações se aplicam à referência de segredos em propriedades de configuração e variáveis de ambiente do Spark:

  • Os proprietários do cluster devem ter a permissão CAN READ no escopo do segredo.
  • Somente os proprietários de cluster podem adicionar uma referência a um segredo em uma propriedade de configuração ou variável de ambiente do Spark e editar o escopo e o nome existentes. Os proprietários alteram um segredo usando a API de Segredos. Você deve reiniciar o cluster para buscar o segredo novamente.
  • Os usuários com a permissão CAN MANAGE no cluster podem excluir uma propriedade de segredo de configuração ou variável de ambiente do Spark.

Sintaxe para referenciar segredos em uma propriedade de configuração ou variável de ambiente do Spark

Você pode referenciar um segredo usando qualquer nome de variável válido ou propriedade de configuração do Spark. O Azure Databricks permite um comportamento especial para variáveis que referenciam segredos com base na sintaxe do valor que está sendo definido, e não no nome da variável.

A sintaxe da propriedade de configuração do Spark ou do valor da variável de ambiente deve ser {{secrets/<scope-name>/<secret-name>}}. O valor deve começar com {{secrets/ e terminar com }}.

As partes variáveis da propriedade de configuração ou da variável de ambiente do Spark são:

  • <scope-name>: o nome do escopo no qual o segredo está associado.
  • <secret-name>: o nome exclusivo do segredo no escopo.

Por exemplo, {{secrets/scope1/key1}}.

Observação

  • Não deve haver espaços entre os colchetes. Se houver espaços, eles serão tratados como parte do escopo ou do nome do segredo.

Referenciar um segredo com uma propriedade de configuração do Spark

Especifique uma referência a um segredo em uma propriedade de configuração do Spark no seguinte formato:

spark.<property-name> {{secrets/<scope-name>/<secret-name>}}

Qualquer configuração do Spark <property-name> pode fazer referência a um segredo. Cada propriedade de configuração do Spark pode referenciar apenas um segredo, mas você pode configurar várias propriedades do Spark para referenciar segredos.

Por exemplo:

Defina uma configuração do Spark para referenciar um segredo:

spark.password {{secrets/scope1/key1}}

Para buscar o segredo no notebook e usá-lo:

Python

spark.conf.get("spark.password")

SQL

SELECT ${spark.password};

Referenciar um segredo em uma variável de ambiente

Especifique um caminho secreto em uma variável de ambiente no seguinte formato:

<variable-name>={{secrets/<scope-name>/<secret-name>}}

Você pode usar qualquer nome de variável válido ao referenciar um segredo. O acesso a segredos referenciados em variáveis de ambiente é determinado pelas permissões do usuário que configurou o cluster. Os segredos armazenados em variáveis de ambiente são acessíveis por todos os usuários do cluster, mas são redigidos da exibição de texto não criptografado como segredos referenciados em outro lugar.

Variáveis de ambiente que fazem referência a segredos podem ser acessadas por meio de um script de inicialização com escopo de cluster. Confira como Definir e usar variáveis de ambiente com scripts de inicialização.

Por exemplo:

Defina uma variável de ambiente para referenciar um segredo:

SPARKPASSWORD={{secrets/scope1/key1}}

Para buscar o segredo em um script de inicialização, acesse $SPARKPASSWORD usando o seguinte padrão:

if [ -n "$SPARKPASSWORD" ]; then
  # code to use ${SPARKPASSWORD}
fi

Gerenciar permissões de segredos

Esta seção descreve como gerenciar o controle de acesso secreto usando O que é a CLI do Databricks? (versão 0.205 e superior). Você também pode usar a API de Segredos ou o provedor Terraform do Databricks. Para obter níveis de permissão de segredo, confira ACLs de segredo

Criar uma ACL de segredos

Para criar uma ACL secreta para um determinado escopo secreto usando a CLI do Databricks (herdada)

databricks secrets put-acl <scope-name> <principal> <permission>

Fazer uma solicitação Put para uma entidade de segurança que já tenha uma permissão aplicada substitui o nível de permissão existente.

O principal campo especifica uma entidade de segurança existente do Azure Databricks. Um usuário é especificado usando seu endereço de email, uma entidade de serviço usando o valor applicationId e um grupo usando o respectivo nome de grupo.

Exibir ACLs de segredo

Para exibir todas as ACLs de segredos de um determinado escopo de segredo:

databricks secrets list-acls <scope-name>

Para obter a ACL de segredos aplicada a uma entidade de segurança de um determinado escopo de segredo:

databricks secrets get-acl <scope-name> <principal>

Se não existir uma ACL para a entidade de segurança e o escopo especificados, essa solicitação falhará.

Excluir uma ACL de segredos

Para excluir a ACL de segredos aplicada a uma entidade de segurança de um determinado escopo de segredo:

databricks secrets delete-acl <scope-name> <principal>