Gerenciar clusters HDInsight usando a API REST do Apache Ambari

• Interface do usuário da Web
• REST API

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

O que é o Apache Ambari

O Apache Ambari simplifica o gerenciamento e monitoramento de clusters Hadoop fornecendo uma interface do usuário da Web fácil de usar com o suporte de suas APIs REST. Ambari é fornecido por padrão com os 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 deste artigo usam o shell do Bash no Windows 10. Confira o Guia de instalação do subsistema do Windows para Linux para o Windows 10 para conhecer as etapas de instalação. Outros shells do Unix também funcionarão. 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.

Base Uniform Resource Identifier para a API REST do Ambari

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

Autenticação

Conectar-se ao Ambari no HDInsight requer HTTPS. Use o nome da conta do administrador (o padrão é admin) e a senha fornecidos durante a criação do cluster.

Para clusters Enterprise Security Package, em vez de admin, use um nome de usuá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.

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

export password='PASSWORD'

B. PowerShell

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

Identificar o nome do cluster com grafia correta de maiúsculas e minúsculas

A capitalização real do nome do cluster pode ser diferente do esperado. As etapas a seguir mostram a grafia correta de maiúsculas e minúsculas real e, em seguida, a armazena 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

Analisar dados JSON

O exemplo a seguir usa jq ou ConvertFrom-Json para analisar o documento de resposta JSON e exibir apenas as informações health_report 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 do cluster

Você precisará saber o nome de domínio totalmente qualificado (FQDN) de um nó do cluster. Você pode recuperar facilmente o FQDN para 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 de cabeçalho

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ó 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 de nós de cluster

Os endereços IP retornados pelos exemplos nesta seção não estão diretamente acessíveis pela internet. Eles só são acessíveis 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, confira 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 de cluster. Uma vez que o FQDN, em seguida, você pode obter o endereço IP do host. Os exemplos a seguir primeiro consultam o Ambari para o FQDN de todos os nós de host. Em seguida, consultam o 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 do HDInsight devem usar uma conta do Armazenamento do Azure ou o Data Lake Storage 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 recuperar 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

Estes 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 exemplos a seguir:

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

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

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

  Para localizar o nome da conta do Data Lake Storage, use os exemplos a seguir:

  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 ao ACCOUNTNAME.azuredatalakestore.net, onde ACCOUNTNAME é o nome da conta do Data Lake Storage.

  Para localizar o diretório no Data Lake Storage que contém o armazenamento do cluster, use os exemplos a seguir:

  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 ao /clusters/CLUSTERNAME/. Esse valor é um caminho dentro da conta do Data Lake Storage. Esse caminho é a raiz do sistema de arquivos compatível com HDFS para o cluster.

Observação

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

Obter todas as configurações

Obtenha as configurações que estão disponíveis para o seu 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 que contém a configuração atual dos componentes instalados. Consulte o valor da marca. 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 você tem interesse. No exemplo a seguir, substitua INITIAL pelo valor 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 que contém a configuração atual do componente livy2-conf.

Atualizar configuração

1. Crie newconfig.json.
   Modifique e, em seguida, insira os comandos a seguir:

   • Substitua livy2-conf pelo novo componente.

   • Substitua INITIAL pelo valor real recuperado para tag de 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 o caminho real e a versão de 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
     

     O 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 que contém a cadeia de caracteres "version" e a data, que é armazenada em newtag.

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

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

   • Exclui os elementos href, version e Config, pois eles não são necessários para enviar uma nova configuração.

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

     Por fim, os dados são salvos no documento newconfig.json. A estrutura do documento deve ser semelhante a este exemplo:

     {
       "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. Edite newconfig.json.
   Abra o documento newconfig.json e modifique/adicione valores no objeto properties. O exemplo a seguir altera o valor de "livy.server.csrf_protection.enabled" desde "true" até "false".

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

   Quando terminar de fazer modificações, salve o arquivo.

3. Envie newconfig.json.
   Use os seguintes comandos para enviar a configuração atualizada ao 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 nesse documento deverá corresponder à versão enviada e o objeto configs conterá 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 precisa ser reiniciado para que a nova configuração entre 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 do 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 modo de manutenção

   Estes comandos enviam um documento JSON para o servidor que ativa o modo de manutenção. Você pode verificar se o serviço está em 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 do 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 valor href retornado por esse URI usa o endereço IP interno do nó de cluster. Para usá-lo de fora do cluster, substitua a parte 10.0.0.18:8080 pelo FQDN do cluster.

4. Verifique a solicitação.
   Edite o comando a seguir substituindo 29 pelo valor real de id retornado 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 do 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. Por fim, 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óximas etapas

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