Gerenciar clusters HDInsight usando a API REST do Apache Ambari

• Interface do usuário da Web
• API REST

Saiba como usar a API REST do Apache Ambari para gerenciar e monitorar clusters Apache Hadoop no Azure HDInsight.

O que é Apache Ambari

O Apache Ambari simplifica o gerenciamento e o monitoramento de clusters Hadoop fornecendo uma interface do usuário da Web fácil de usar apoiada por suas APIs REST. O Ambari é fornecido por padrão com clusters HDInsight baseados em Linux.

Pré-requisitos

• Um cluster Hadoop no HDInsight. Consulte Introdução ao HDInsight no Linux.

• Bash no Ubuntu no Windows 10. Os exemplos neste artigo usam o shell Bash no Windows 10. Consulte o Guia de Instalação do Subsistema Windows para Linux para Windows 10 para obter as etapas de instalação. Outros shells Unix também funcionam. Os exemplos, com algumas pequenas modificações, podem funcionar em um prompt de comando do Windows. Ou você pode usar o Windows PowerShell.

• jq, um processador JSON de linha de comando. Consulte https://stedolan.github.io/jq/.

• Windows PowerShell. Ou você pode usar o Bash.

Identificador de recurso uniforme de base para a API REST do Ambari

O URI (Uniform Resource Identifier) base para a API REST do Ambari no HDInsight é https://CLUSTERNAME.azurehdinsight.net/api/v1/clusters/CLUSTERNAME, onde CLUSTERNAME é o nome do cluster. Os nomes de cluster em URIs diferenciam maiúsculas de minúsculas. Embora o nome do cluster na parte FQDN (nome de domínio totalmente qualificado) do URI (CLUSTERNAME.azurehdinsight.net) não diferencie maiúsculas de minúsculas, outras ocorrências no URI diferenciam maiúsculas de minúsculas.

Autenticação

A conexão com o Ambari no HDInsight requer HTTPS. Use o nome da conta de administrador (o padrão é admin) e a senha fornecida durante a criação do cluster.

Para clusters do Enterprise Security Package, em vez de , use um nome de adminusuário totalmente qualificado como username@domain.onmicrosoft.com.

Exemplos

Configuração (Preservar credenciais)

Preserve suas credenciais para evitar reinseri-las para cada exemplo. O nome do cluster é preservado em uma etapa separada.

A. Bash
Edite o script substituindo PASSWORD pela sua senha real. Em seguida, digite o comando.

export password='PASSWORD'

B. PowerShell

$creds = Get-Credential -UserName "admin" -Message "Enter the HDInsight login"

Identificar corretamente o nome do cluster com caixa

O invólucro real do nome do cluster pode ser diferente do esperado. As etapas a seguir mostram o invólucro real e, em seguida, armazená-lo em uma variável para todos os exemplos posteriores.

Edite os scripts para substituir CLUSTERNAME pelo nome do cluster. Em seguida, digite o comando. (O nome do cluster para o FQDN não diferencia maiúsculas de minúsculas.)

export clusterName=$(curl -u admin:$password -sS -G "https://CLUSTERNAME.azurehdinsight.net/api/v1/clusters" | jq -r '.items[].Clusters.cluster_name')
echo $clusterName

# Identify properly cased cluster name
$resp = Invoke-WebRequest -Uri "https://CLUSTERNAME.azurehdinsight.net/api/v1/clusters" `
    -Credential $creds -UseBasicParsing
$clusterName = (ConvertFrom-Json $resp.Content).items.Clusters.cluster_name;

# Show cluster name
$clusterName

Análise de dados JSON

O exemplo a seguir usa jq ou ConvertFrom-Json para analisar o documento de resposta JSON e exibir apenas as health_report informações dos resultados.

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName" \
| jq '.Clusters.health_report'

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.Clusters.health_report

Obter o FQDN de nós de cluster

Talvez seja necessário saber o nome de domínio totalmente qualificado (FQDN) de um nó de cluster. Você pode recuperar facilmente o FQDN para os vários nós no cluster usando os seguintes exemplos:

Todos os nós

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/hosts" \
| jq -r '.items[].Hosts.host_name'

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/hosts" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.items.Hosts.host_name

Nós principais

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/HDFS/components/NAMENODE" \
| jq -r '.host_components[].HostRoles.host_name'

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/HDFS/components/NAMENODE" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.host_components.HostRoles.host_name

Nós de trabalho

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/HDFS/components/DATANODE" \
| jq -r '.host_components[].HostRoles.host_name'

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/HDFS/components/DATANODE" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.host_components.HostRoles.host_name

Nós do Zookeeper

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/ZOOKEEPER/components/ZOOKEEPER_SERVER" \
| jq -r ".host_components[].HostRoles.host_name"

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/ZOOKEEPER/components/ZOOKEEPER_SERVER" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.host_components.HostRoles.host_name

Obter o endereço IP interno dos nós de cluster

Os endereços IP retornados pelos exemplos nesta seção não são diretamente acessíveis pela Internet. Eles só podem ser acessados na Rede Virtual do Azure que contém o cluster HDInsight.

Para obter mais informações sobre como trabalhar com o HDInsight e redes virtuais, consulte Planejar uma rede virtual para o HDInsight.

Para localizar o endereço IP, você deve saber o FQDN (nome de domínio totalmente qualificado) interno dos nós do cluster. Depois de ter o FQDN, você pode obter o endereço IP do host. Os exemplos a seguir consultam primeiro Ambari para o FQDN de todos os nós host. Em seguida, consulta Ambari para o endereço IP de cada host.

for HOSTNAME in $(curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/hosts" | jq -r '.items[].Hosts.host_name')
do
    IP=$(curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/hosts/$HOSTNAME" | jq -r '.Hosts.ip')
  echo "$HOSTNAME <--> $IP"
done

$uri = "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/hosts" 
$resp = Invoke-WebRequest -Uri $uri -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
foreach($item in $respObj.items) {
    $hostName = [string]$item.Hosts.host_name
    $hostInfoResp = Invoke-WebRequest -Uri "$uri/$hostName" `
        -Credential $creds -UseBasicParsing
    $hostInfoObj = ConvertFrom-Json $hostInfoResp
    $hostIp = $hostInfoObj.Hosts.ip
    "$hostName <--> $hostIp"
}

Obter o armazenamento padrão

Os clusters HDInsight devem usar uma Conta de Armazenamento do Azure ou Armazenamento Data Lake como o armazenamento padrão. Você pode usar o Ambari para recuperar essas informações após a criação do cluster. Por exemplo, se você quiser ler/gravar dados no contêiner fora do HDInsight.

Os exemplos a seguir recuperam a configuração de armazenamento padrão do cluster:

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" \
| jq -r '.items[].configurations[].properties["fs.defaultFS"] | select(. != null)'

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" `
    -Credential $creds -UseBasicParsing
$respObj = ConvertFrom-Json $resp.Content
$respObj.items.configurations.properties.'fs.defaultFS'

Importante

Esses exemplos retornam a primeira configuração aplicada ao servidor (service_config_version=1) que contém essas informações. Se você recuperar um valor que foi modificado após a criação do cluster, talvez seja necessário listar as versões de configuração e recuperar a mais recente.

O valor de retorno é semelhante a um dos seguintes exemplos:

• wasbs://CONTAINER@ACCOUNTNAME.blob.core.windows.net - Esse valor indica que o cluster está usando uma conta de Armazenamento do Azure para armazenamento padrão. O ACCOUNTNAME valor é o nome da conta de armazenamento. A CONTAINER parte é o nome do contêiner de blob na conta de armazenamento. O contêiner é a raiz do armazenamento compatível com HDFS para o cluster.

• abfs://CONTAINER@ACCOUNTNAME.dfs.core.windows.net - Esse valor indica que o cluster está usando o Azure Data Lake Storage Gen2 para armazenamento padrão. Os ACCOUNTNAME valores e CONTAINER têm os mesmos significados que para o Armazenamento do Azure mencionado anteriormente.

• adl://home - Esse valor indica que o cluster está usando o Azure Data Lake Storage Gen1 para armazenamento padrão.

  Para localizar o nome da conta do Armazenamento Data Lake, use os seguintes exemplos:

  curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" \
  | jq -r '.items[].configurations[].properties["dfs.adls.home.hostname"] | select(. != null)'
  

  $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" `
      -Credential $creds -UseBasicParsing
  $respObj = ConvertFrom-Json $resp.Content
  $respObj.items.configurations.properties.'dfs.adls.home.hostname'
  

  O valor de retorno é semelhante a ACCOUNTNAME.azuredatalakestore.net, onde ACCOUNTNAME é o nome da conta de armazenamento do Data Lake.

  Para localizar o diretório no Armazenamento Data Lake que contém o armazenamento para o cluster, use os seguintes exemplos:

  curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" \
  | jq -r '.items[].configurations[].properties["dfs.adls.home.mountpoint"] | select(. != null)'
  

  $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations/service_config_versions?service_name=HDFS&service_config_version=1" `
      -Credential $creds -UseBasicParsing
  $respObj = ConvertFrom-Json $resp.Content
  $respObj.items.configurations.properties.'dfs.adls.home.mountpoint'
  

  O valor de retorno é semelhante a /clusters/CLUSTERNAME/. Esse valor é um caminho dentro da conta de armazenamento Data Lake. Esse caminho é a raiz do sistema de arquivos compatível com HDFS para o cluster.

Nota

O cmdlet Get-AzHDInsightCluster fornecido pelo Azure PowerShell também retorna as informações de armazenamento para o cluster.

Obter todas as configurações

Obtenha as configurações disponíveis para o cluster.

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName?fields=Clusters/desired_configs"

$respObj = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName`?fields=Clusters/desired_configs" `
    -Credential $creds -UseBasicParsing
$respObj.Content

Este exemplo retorna um documento JSON contendo a configuração atual para componentes instalados. Veja o valor da tag . O exemplo a seguir é um trecho dos dados retornados de um tipo de cluster Spark.

"jupyter-site" : {
  "tag" : "INITIAL",
  "version" : 1
},
"livy2-client-conf" : {
  "tag" : "INITIAL",
  "version" : 1
},
"livy2-conf" : {
  "tag" : "INITIAL",
  "version" : 1
},

Obter configuração para componente específico

Obtenha a configuração para o componente em que está interessado. No exemplo a seguir, substitua INITIAL pelo valor da tag retornado da solicitação anterior.

curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations?type=livy2-conf&tag=INITIAL"

$resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations?type=livy2-conf&tag=INITIAL" `
    -Credential $creds -UseBasicParsing
$resp.Content

Este exemplo retorna um documento JSON contendo a configuração atual do livy2-conf componente.

Atualizar configuração

1. Crie newconfig.json.
   Modifique e insira os comandos da seguinte maneira:

   • Substitua livy2-conf pelo novo componente.

   • Substitua INITIAL pelo valor real recuperado de tag Obter todas as configurações.

     A. Bash

     curl -u admin:$password -sS -G "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations?type=livy2-conf&tag=INITIAL" \
     | jq --arg newtag $(echo version$(date +%s%N)) '.items[] | del(.href, .version, .Config) | .tag |= $newtag | {"Clusters": {"desired_config": .}}' > newconfig.json
     

     B. PowerShell
     O script do PowerShell usa jq. Edite C:\HD\jq\jq-win64 abaixo para refletir seu caminho real e versão do jq.

     $epoch = Get-Date -Year 1970 -Month 1 -Day 1 -Hour 0 -Minute 0 -Second 0
     $now = Get-Date
     $unixTimeStamp = [math]::truncate($now.ToUniversalTime().Subtract($epoch).TotalMilliSeconds)
     $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/configurations?type=livy2-conf&tag=INITIAL" `
       -Credential $creds -UseBasicParsing
     $resp.Content | C:\HD\jq\jq-win64 --arg newtag "version$unixTimeStamp" '.items[] | del(.href, .version, .Config) | .tag |= $newtag | {"Clusters": {"desired_config": .}}' > newconfig.json
     

     Jq é usado para transformar os dados recuperados do HDInsight em um novo modelo de configuração. Especificamente, esses exemplos executam as seguintes ações:

   • Cria um valor exclusivo contendo a cadeia de caracteres "version" e a data, que é armazenada no newtag.

   • Cria um documento raiz para a nova configuração.

   • Obtém o conteúdo da .items[] matriz e o adiciona sob o elemento desired_config .

   • Exclui os hrefelementos , versione , pois Config esses elementos não são necessários para enviar uma nova configuração.

   • Adiciona um tag elemento com um valor de version#################. A parte numérica é baseada na data atual. Cada configuração deve ter uma tag exclusiva.

     Finalmente, os dados são salvos no newconfig.json documento. A estrutura do documento deve ser semelhante ao exemplo a seguir:

     {
       "Clusters": {
         "desired_config": {
           "tag": "version1552064778014",
           "type": "livy2-conf",
           "properties": {
             "livy.environment": "production",
             "livy.impersonation.enabled": "true",
             "livy.repl.enableHiveContext": "true",
             "livy.server.csrf_protection.enabled": "true",
               ....
           },
         },
       }
     }
     

2. Editar newconfig.json.
   Abra o newconfig.json documento e modifique/adicione valores no properties objeto. O exemplo a seguir altera o valor de "livy.server.csrf_protection.enabled" de de "true" para "false".

   "livy.server.csrf_protection.enabled": "false",
   

   Salve o arquivo assim que terminar de fazer modificações.

3. Submeter newconfig.json.
   Use os comandos a seguir para enviar a configuração atualizada para o Ambari.

   curl -u admin:$password -sS -H "X-Requested-By: ambari" -X PUT -d @newconfig.json "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName"
   

   $newConfig = Get-Content .\newconfig.json
   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName" `
       -Credential $creds -UseBasicParsing `
       -Method PUT `
       -Headers @{"X-Requested-By" = "ambari"} `
       -Body $newConfig
   $resp.Content
   

   Esses comandos enviam o conteúdo do arquivo newconfig.json para o cluster como a nova configuração. A solicitação retorna um documento JSON. O elemento versionTag neste documento deve corresponder à versão enviada e o objeto configs contém as alterações de configuração solicitadas.

Reiniciar um componente de serviço

Neste ponto, a interface do usuário da Web do Ambari indica que o serviço Spark precisa ser reiniciado antes que a nova configuração possa entrar em vigor. Use as etapas a seguir para reiniciar o serviço.

1. Use o seguinte para habilitar o modo de manutenção para o serviço Spark2:

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   -X PUT -d '{"RequestInfo": {"context": "turning on maintenance mode for SPARK2"},"Body": {"ServiceInfo": {"maintenance_state":"ON"}}}' \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2"
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" `
       -Credential $creds -UseBasicParsing `
       -Method PUT `
       -Headers @{"X-Requested-By" = "ambari"} `
       -Body '{"RequestInfo": {"context": "turning on maintenance mode for SPARK2"},"Body": {"ServiceInfo": {"maintenance_state":"ON"}}}'
   

2. Verificar o modo de manutenção

   Esses comandos enviam um documento JSON para o servidor que ativa o modo de manutenção. Você pode verificar se o serviço está agora no modo de manutenção usando a seguinte solicitação:

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" \
   | jq .ServiceInfo.maintenance_state
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" `
       -Credential $creds -UseBasicParsing
   $respObj = ConvertFrom-Json $resp.Content
   $respObj.ServiceInfo.maintenance_state
   

   O valor de retorno é ON.

3. Em seguida, use o seguinte para desativar o serviço Spark2:

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   -X PUT -d '{"RequestInfo":{"context":"_PARSE_.STOP.SPARK2","operation_level":{"level":"SERVICE","cluster_name":"CLUSTERNAME","service_name":"SPARK"}},"Body":{"ServiceInfo":{"state":"INSTALLED"}}}' \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2"
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" `
       -Credential $creds -UseBasicParsing `
       -Method PUT `
       -Headers @{"X-Requested-By" = "ambari"} `
       -Body '{"RequestInfo":{"context":"_PARSE_.STOP.SPARK2","operation_level":{"level":"SERVICE","cluster_name":"CLUSTERNAME","service_name":"SPARK"}},"Body":{"ServiceInfo":{"state":"INSTALLED"}}}'
   $resp.Content
   

   A resposta é semelhante ao seguinte exemplo:

   {
       "href" : "http://10.0.0.18:8080/api/v1/clusters/CLUSTERNAME/requests/29",
       "Requests" : {
           "id" : 29,
           "status" : "Accepted"
       }
   }
   

   Importante

   O href valor retornado por esse URI está usando o endereço IP interno do nó do cluster. Para usá-lo de fora do cluster, substitua a 10.0.0.18:8080 parte pelo FQDN do cluster.

4. Verifique a solicitação.
   Edite o comando abaixo substituindo 29 pelo valor real retornado id da etapa anterior. Os comandos a seguir recuperam o status da solicitação:

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/requests/29" \
   | jq .Requests.request_status
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/requests/29" `
       -Credential $creds -UseBasicParsing
   $respObj = ConvertFrom-Json $resp.Content
   $respObj.Requests.request_status
   

   Uma resposta de COMPLETED indica que a solicitação foi concluída.

5. Quando a solicitação anterior for concluída, use o seguinte para iniciar o serviço Spark2.

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   -X PUT -d '{"RequestInfo":{"context":"_PARSE_.START.SPARK2","operation_level":{"level":"SERVICE","cluster_name":"CLUSTERNAME","service_name":"SPARK"}},"Body":{"ServiceInfo":{"state":"STARTED"}}}' \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2"
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" `
       -Credential $creds -UseBasicParsing `
       -Method PUT `
       -Headers @{"X-Requested-By" = "ambari"} `
       -Body '{"RequestInfo":{"context":"_PARSE_.START.SPARK2","operation_level":{"level":"SERVICE","cluster_name":"CLUSTERNAME","service_name":"SPARK"}},"Body":{"ServiceInfo":{"state":"STARTED"}}}'
   $resp.Content
   

   O serviço agora está usando a nova configuração.

6. Finalmente, use o seguinte para desativar o modo de manutenção.

   curl -u admin:$password -sS -H "X-Requested-By: ambari" \
   -X PUT -d '{"RequestInfo": {"context": "turning off maintenance mode for SPARK2"},"Body": {"ServiceInfo": {"maintenance_state":"OFF"}}}' \
   "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2"
   

   $resp = Invoke-WebRequest -Uri "https://$clusterName.azurehdinsight.net/api/v1/clusters/$clusterName/services/SPARK2" `
       -Credential $creds -UseBasicParsing `
       -Method PUT `
       -Headers @{"X-Requested-By" = "ambari"} `
       -Body '{"RequestInfo": {"context": "turning off maintenance mode for SPARK2"},"Body": {"ServiceInfo": {"maintenance_state":"OFF"}}}'
   

Próximos passos

Para obter uma referência completa da API REST, consulte Apache Ambari API Reference V1. Consulte também, Autorizar usuários para exibições do Apache Ambari