Scriptactie ontwikkelen met HDInsight

  • Artikel

Meer informatie over het aanpassen van uw HDInsight-cluster met behulp van Bash-scripts. Scriptacties zijn een manier om HDInsight aan te passen tijdens of na het maken van een cluster.

Wat zijn scriptacties?

Scriptacties zijn Bash-scripts die in Azure worden uitgevoerd op de clusterknooppunten om configuratiewijzigingen aan te brengen of software te installeren. Een scriptactie wordt uitgevoerd als hoofdmap en biedt volledige toegangsrechten tot de clusterknooppunten.

Scriptacties kunnen worden toegepast via de volgende methoden:

Gebruik deze methode om een script toe te passen... Tijdens het maken van het cluster... Op een actief cluster...
Azure Portal ✓ ✓
Azure PowerShell ✓ ✓
Klassieke versie van Azure-CLI   ✓
HDInsight .NET SDK ✓ ✓
Azure Resource Manager-sjabloon ✓  

Zie HDInsight-clusters aanpassen met scriptacties voor meer informatie over het gebruik van deze methoden om scriptacties toe te passen.

Best practices voor het ontwikkelen van scripts

Wanneer u een aangepast script voor een HDInsight-cluster ontwikkelt, zijn er verschillende aanbevolen procedures om rekening mee te houden:

Belangrijk

Scriptacties moeten binnen 60 minuten zijn voltooid, anders mislukt het proces. Tijdens het inrichten van knooppunten wordt het script gelijktijdig uitgevoerd met andere installatie- en configuratieprocessen. Concurrentie voor resources zoals CPU-tijd of netwerkbandbreedte kan ertoe leiden dat het script langer duurt dan in uw ontwikkelomgeving.

De Apache Hadoop-versie targeten

Voor verschillende versies van HDInsight zijn verschillende versies van Hadoop-services en -onderdelen geïnstalleerd. Als uw script een specifieke versie van een service of onderdeel verwacht, moet u het script alleen gebruiken met de versie van HDInsight die de vereiste onderdelen bevat. U kunt informatie vinden over onderdeelversies die zijn opgenomen in HDInsight met behulp van het document over hdinsight-onderdelenversies .

De versie van het besturingssysteem controleren

Verschillende versies van HDInsight zijn afhankelijk van specifieke versies van Ubuntu. Er kunnen verschillen zijn tussen besturingssysteemversies die u in uw script moet controleren. Mogelijk moet u bijvoorbeeld een binair bestand installeren dat is gekoppeld aan de versie van Ubuntu.

Als u de versie van het besturingssysteem wilt controleren, gebruikt u lsb_release. Het volgende script laat bijvoorbeeld zien hoe u naar een specifiek tar-bestand verwijst, afhankelijk van de versie van het besturingssysteem:

OS_VERSION=$(lsb_release -sr)
if [[ $OS_VERSION == 14* ]]; then
    echo "OS version is $OS_VERSION. Using hue-binaries-14-04."
    HUE_TARFILE=hue-binaries-14-04.tgz
elif [[ $OS_VERSION == 16* ]]; then
    echo "OS version is $OS_VERSION. Using hue-binaries-16-04."
    HUE_TARFILE=hue-binaries-16-04.tgz
fi

Doel van de versie van het besturingssysteem

HDInsight is gebaseerd op de Ubuntu Linux-distributie. Verschillende versies van HDInsight zijn afhankelijk van verschillende versies van Ubuntu, waardoor het gedrag van uw script kan veranderen. HDInsight 3.4 en eerder zijn bijvoorbeeld gebaseerd op Ubuntu-versies die gebruikmaken van Upstart. Versies 3.5 en hoger zijn gebaseerd op Ubuntu 16.04, dat gebruikmaakt van Systemd. Systemd en Upstart zijn afhankelijk van verschillende opdrachten, dus uw script moet worden geschreven om met beide te werken.

Een ander belangrijk verschil tussen HDInsight 3.4 en 3.5 is dat JAVA_HOME nu naar Java 8 verwijst. De volgende code laat zien hoe u kunt bepalen of het script wordt uitgevoerd op Ubuntu 14 of 16:

OS_VERSION=$(lsb_release -sr)
if [[ $OS_VERSION == 14* ]]; then
    echo "OS version is $OS_VERSION. Using hue-binaries-14-04."
    HUE_TARFILE=hue-binaries-14-04.tgz
elif [[ $OS_VERSION == 16* ]]; then
    echo "OS version is $OS_VERSION. Using hue-binaries-16-04."
    HUE_TARFILE=hue-binaries-16-04.tgz
fi
...
if [[ $OS_VERSION == 16* ]]; then
    echo "Using systemd configuration"
    systemctl daemon-reload
    systemctl stop webwasb.service    
    systemctl start webwasb.service
else
    echo "Using upstart configuration"
    initctl reload-configuration
    stop webwasb
    start webwasb
fi
...
if [[ $OS_VERSION == 14* ]]; then
    export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
elif [[ $OS_VERSION == 16* ]]; then
    export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
fi

U vindt het volledige script met deze fragmenten op https://hdiconfigactions.blob.core.windows.net/linuxhueconfigactionv02/install-hue-uber-v02.sh.

Zie het document hdinsight-onderdeelversie voor de versie van Ubuntu die wordt gebruikt door HDInsight.

Zie Systemd voor upstartgebruikers voor meer informatie over de verschillen tussen Systemd en Upstart.

Stabiele koppelingen naar scriptresources bieden

Het script en de bijbehorende resources moeten beschikbaar blijven gedurende de levensduur van het cluster. Deze resources zijn vereist als er nieuwe knooppunten aan het cluster worden toegevoegd tijdens schaalbewerkingen.

De best practice is om alles in een Azure Storage-account in uw abonnement te downloaden en te archiveren.

Belangrijk

Het gebruikte opslagaccount moet het standaardopslagaccount voor het cluster zijn of een openbare container met het kenmerk Alleen-lezen in een ander opslagaccount.

De voorbeelden van Microsoft worden bijvoorbeeld opgeslagen in het https://hdiconfigactions.blob.core.windows.net/ opslagaccount. Deze locatie is een openbare, alleen-lezen container die wordt onderhouden door het HDInsight-team.

Vooraf gecompileerde resources gebruiken

Vermijd bewerkingen die resources compileren op basis van broncode om de tijd te beperken die nodig zijn om het script uit te voeren. U kunt bijvoorbeeld vooraf resources compileren en opslaan in een Azure Storage-account-blob in hetzelfde datacenter als HDInsight.

Zorg ervoor dat het script voor clusteraanpassing idempotent is

Scripts moeten idempotent zijn. Als het script meerdere keren wordt uitgevoerd, moet het cluster elke keer dezelfde status krijgen.

Een script dat configuratiebestanden wijzigt, mag bijvoorbeeld geen dubbele vermeldingen toevoegen als deze meerdere keren wordt uitgevoerd.

Hoge beschikbaarheid van de clusterarchitectuur garanderen

HDInsight-clusters op basis van Linux bieden twee hoofdknooppunten die actief zijn in het cluster en scriptacties worden uitgevoerd op beide knooppunten. Als de onderdelen die u installeert slechts één hoofdknooppunt verwachten, installeert u de onderdelen niet op beide hoofdknooppunten.

Belangrijk

Services die als onderdeel van HDInsight worden geleverd, zijn ontworpen om indien nodig een failover uit te voeren tussen de twee hoofdknooppunten. Deze functionaliteit wordt niet uitgebreid naar aangepaste onderdelen die zijn geïnstalleerd via scriptacties. Als u hoge beschikbaarheid voor aangepaste onderdelen nodig hebt, moet u uw eigen failovermechanisme implementeren.

De aangepaste onderdelen configureren voor het gebruik van Azure Blob Storage

Onderdelen die u op het cluster installeert, hebben mogelijk een standaardconfiguratie die gebruikmaakt van HDFS-opslag (Apache Hadoop Distributed File System). HDInsight gebruikt Azure Storage of Data Lake Storage als standaardopslag. Beide bieden een HDFS-compatibel bestandssysteem dat gegevens persistent maakt, zelfs als het cluster wordt verwijderd. Mogelijk moet u onderdelen die u installeert configureren om WASB of ADL te gebruiken in plaats van HDFS.

Voor de meeste bewerkingen hoeft u het bestandssysteem niet op te geven. Met het volgende kopieert u bijvoorbeeld het bestand hadoop-common.jar van het lokale bestandssysteem naar de clusteropslag:

hdfs dfs -put /usr/hdp/current/hadoop-client/hadoop-common.jar /example/jars/

In dit voorbeeld maakt de hdfs opdracht transparant gebruik van de standaardclusteropslag. Voor sommige bewerkingen moet u mogelijk de URI opgeven. Bijvoorbeeld adl:///example/jars voor Azure Data Lake Storage Gen1, abfs:///example/jars voor Data Lake Storage Gen2 of wasb:///example/jars voor Azure Storage.

Informatie schrijven naar STDOUT en STDERR

HDInsight registreert scriptuitvoer die is geschreven naar STDOUT en STDERR. U kunt deze informatie bekijken met behulp van de Ambari-webgebruikersinterface.

Notitie

Apache Ambari is alleen beschikbaar als het cluster is gemaakt. Als u een scriptactie gebruikt tijdens het maken van een cluster en het maken mislukt, raadpleegt u Problemen met scriptacties oplossen voor andere manieren om toegang te krijgen tot vastgelegde gegevens.

De meeste hulpprogramma's en installatiepakketten schrijven al informatie naar STDOUT en STDERR, maar u kunt extra logboekregistratie toevoegen. Als u tekst naar STDOUT wilt verzenden, gebruikt u echo. Bijvoorbeeld:

echo "Getting ready to install Foo"

echo Standaard wordt de tekenreeks naar STDOUT verzonden. Als u deze wilt doorsturen naar STDERR, voegt u vóór echotoe>&2. Bijvoorbeeld:

>&2 echo "An error occurred installing Foo"

Hierdoor wordt informatie die naar STDOUT is geschreven, omgeleid naar STDERR (2). Zie voor meer informatie over IO-omleiding https://www.tldp.org/LDP/abs/html/io-redirection.html.

Zie Problemen met scriptacties oplossen voor meer informatie over het weergeven van informatie die is vastgelegd door scriptacties.

Bestanden opslaan als ASCII met LF-regeleinden

Bash-scripts moeten worden opgeslagen als ASCII-indeling, met regels die worden beëindigd door LF. Bestanden die zijn opgeslagen als UTF-8 of CRLF gebruiken als het einde van de regel, kunnen mislukken met de volgende fout:

$'\r': command not found
line 1: #!/usr/bin/env: No such file or directory

Logica voor opnieuw proberen gebruiken om tijdelijke fouten te herstellen

Bij het downloaden van bestanden, het installeren van pakketten met apt-get of andere acties waarmee gegevens via internet worden verzonden, kan de actie mislukken vanwege tijdelijke netwerkfouten. De externe resource waarmee u communiceert, kan bijvoorbeeld een failover uitvoeren naar een back-upknooppunt.

Als u uw script tolerant wilt maken voor tijdelijke fouten, kunt u logica voor opnieuw proberen implementeren. De volgende functie laat zien hoe u logica voor opnieuw proberen implementeert. De bewerking wordt drie keer opnieuw uitgevoerd voordat deze mislukt.

#retry
MAXATTEMPTS=3

retry() {
    local -r CMD="$@"
    local -i ATTMEPTNUM=1
    local -i RETRYINTERVAL=2

    until $CMD
    do
        if (( ATTMEPTNUM == MAXATTEMPTS ))
        then
                echo "Attempt $ATTMEPTNUM failed. no more attempts left."
                return 1
        else
                echo "Attempt $ATTMEPTNUM failed! Retrying in $RETRYINTERVAL seconds..."
                sleep $(( RETRYINTERVAL ))
                ATTMEPTNUM=$ATTMEPTNUM+1
        fi
    done
}

In de volgende voorbeelden ziet u hoe u deze functie gebruikt.

retry ls -ltr foo

retry wget -O ./tmpfile.sh https://hdiconfigactions.blob.core.windows.net/linuxhueconfigactionv02/install-hue-uber-v02.sh

Helpermethoden voor aangepaste scripts

Hulpmethoden voor scriptacties zijn hulpprogramma's die u kunt gebruiken tijdens het schrijven van aangepaste scripts. Deze methoden zijn opgenomen in het https://hdiconfigactions.blob.core.windows.net/linuxconfigactionmodulev01/HDInsightUtilities-v01.sh script. Gebruik het volgende om ze te downloaden en te gebruiken als onderdeel van uw script:

# Import the helper method module.
wget -O /tmp/HDInsightUtilities-v01.sh -q https://hdiconfigactions.blob.core.windows.net/linuxconfigactionmodulev01/HDInsightUtilities-v01.sh && source /tmp/HDInsightUtilities-v01.sh && rm -f /tmp/HDInsightUtilities-v01.sh

De volgende helpers zijn beschikbaar voor gebruik in uw script:

Helpergebruik Beschrijving
download_file SOURCEURL DESTFILEPATH [OVERWRITE] Hiermee downloadt u een bestand van de bron-URI naar het opgegeven bestandspad. Standaard wordt een bestaand bestand niet overschreven.
untar_file TARFILE DESTDIR Extraheert een tar-bestand (met behulp van -xf) naar de doelmap.
test_is_headnode Als het script is uitgevoerd op een clusterhoofdknooppunt, retourneer dan 1; anders 0.
test_is_datanode Als het huidige knooppunt een gegevensknooppunt (werkrol) is, retourneert u een 1; anders 0.
test_is_first_datanode Als het huidige knooppunt het eerste gegevensknooppunt (werkrol) is (workernode0 genoemd), retourneert u een 1; anders 0.
get_headnodes Retourneer de volledig gekwalificeerde domeinnaam van de hoofdknooppunten in het cluster. Namen zijn door komma's gescheiden. Er wordt een lege tekenreeks geretourneerd bij fout.
get_primary_headnode Hiermee haalt u de volledig gekwalificeerde domeinnaam van het primaire hoofdknooppunt op. Er wordt een lege tekenreeks geretourneerd bij fout.
get_secondary_headnode Hiermee haalt u de volledig gekwalificeerde domeinnaam van het secundaire hoofdknooppunt op. Er wordt een lege tekenreeks geretourneerd bij fout.
get_primary_headnode_number Hiermee haalt u het numerieke achtervoegsel van het primaire hoofdknooppunt op. Er wordt een lege tekenreeks geretourneerd bij fout.
get_secondary_headnode_number Hiermee haalt u het numerieke achtervoegsel van het secundaire hoofdknooppunt op. Er wordt een lege tekenreeks geretourneerd bij fout.

Algemene gebruikspatronen

Deze sectie bevat richtlijnen voor het implementeren van enkele van de algemene gebruikspatronen die u kunt tegenkomen tijdens het schrijven van uw eigen aangepaste script.

Parameters doorgeven aan een script

In sommige gevallen zijn voor uw script mogelijk parameters vereist. Mogelijk hebt u bijvoorbeeld het beheerderswachtwoord voor het cluster nodig wanneer u de Ambari REST API gebruikt.

Parameters die aan het script worden doorgegeven, worden positionele parameters genoemd en worden toegewezen aan $1 voor de eerste parameter, $2 voor de tweede, enzovoort. $0 bevat de naam van het script zelf.

Waarden die als parameters aan het script zijn doorgegeven, moeten tussen enkele aanhalingstekens ('). Dit zorgt ervoor dat de doorgegeven waarde wordt behandeld als een letterlijke waarde.

Omgevingsvariabelen instellen

Het instellen van een omgevingsvariabele wordt uitgevoerd met de volgende instructie:

VARIABLENAME=value

In het voorgaande voorbeeld VARIABLENAME is de naam van de variabele. Gebruik $VARIABLENAMEvoor toegang tot de variabele . Als u bijvoorbeeld een waarde wilt toewijzen die wordt geleverd door een positionele parameter als een omgevingsvariabele met de naam PASSWORD, gebruikt u de volgende instructie:

PASSWORD=$1

Volgende toegang tot de informatie kan vervolgens worden gebruikt $PASSWORD.

Omgevingsvariabelen die in het script zijn ingesteld, bestaan alleen binnen het bereik van het script. In sommige gevallen moet u mogelijk systeembrede omgevingsvariabelen toevoegen die behouden blijven nadat het script is voltooid. Als u systeembrede omgevingsvariabelen wilt toevoegen, voegt u de variabele toe aan /etc/environment. Met de volgende instructie wordt bijvoorbeeld het volgende toegevoegd HADOOP_CONF_DIR:

echo "HADOOP_CONF_DIR=/etc/hadoop/conf" | sudo tee -a /etc/environment

Toegang tot locaties waar de aangepaste scripts zijn opgeslagen

Scripts die worden gebruikt om een cluster aan te passen, moeten worden opgeslagen op een van de volgende locaties:

  • Een Azure Storage-account dat is gekoppeld aan het cluster.

  • Een extra opslagaccount dat is gekoppeld aan het cluster.

  • Een openbaar leesbare URI. Bijvoorbeeld een URL naar gegevens die zijn opgeslagen in OneDrive, Dropbox of een andere bestandshostingservice.

  • Een Azure Data Lake Storage-account dat is gekoppeld aan het HDInsight-cluster. Zie Quickstart: Clusters instellen in HDInsight voor meer informatie over het gebruik van Azure Data Lake Storage met HDInsight.

    Notitie

    De service-principal die HDInsight gebruikt voor toegang tot Data Lake Storage leestoegang tot het script moet hebben.

Resources die door het script worden gebruikt, moeten ook openbaar beschikbaar zijn.

Het opslaan van de bestanden in een Azure Storage-account of Azure Data Lake Storage biedt snelle toegang, zowel binnen het Azure-netwerk.

Notitie

De URI-indeling die wordt gebruikt om naar het script te verwijzen, verschilt afhankelijk van de service die wordt gebruikt. Gebruik of wasbs://voor opslagaccounts die zijn gekoppeld aan het HDInsight-clusterwasb://. Voor openbaar leesbare URI's gebruikt u http:// of https://. Gebruik adl://voor Data Lake Storage .

Controlelijst voor het implementeren van een scriptactie

Dit zijn de stappen die u moet uitvoeren bij het voorbereiden van de implementatie van een script:

  • Plaats de bestanden met de aangepaste scripts op een plaats die toegankelijk is voor de clusterknooppunten tijdens de implementatie. Bijvoorbeeld de standaardopslag voor het cluster. Bestanden kunnen ook worden opgeslagen in openbaar leesbare hostingservices.
  • Controleer of het script idempotent is. Hierdoor kan het script meerdere keren op hetzelfde knooppunt worden uitgevoerd.
  • Gebruik een tijdelijke bestandsmap /tmp om de gedownloade bestanden te bewaren die door de scripts worden gebruikt en schoon ze vervolgens op nadat scripts zijn uitgevoerd.
  • Als instellingen op besturingssysteemniveau of configuratiebestanden van de Hadoop-service worden gewijzigd, kunt u HDInsight-services opnieuw starten.

Een scriptactie uitvoeren

U kunt scriptacties gebruiken om HDInsight-clusters aan te passen met behulp van de volgende methoden:

  • Azure Portal
  • Azure PowerShell
  • Azure Resource Manager-sjablonen
  • De HDInsight .NET SDK.

Zie Scriptactie gebruiken voor meer informatie over het gebruik van elke methode.

Aangepaste scriptvoorbeelden

Microsoft biedt voorbeeldscripts voor het installeren van onderdelen op een HDInsight-cluster. Zie Hue installeren en gebruiken op HDInsight-clusters als voorbeeldscriptactie.

Problemen oplossen

Hier volgen fouten die u kunt tegenkomen bij het gebruik van scripts die u hebt ontwikkeld:

Fout: $'\r': command not found. Soms gevolgd door syntax error: unexpected end of file.

Oorzaak: deze fout wordt veroorzaakt wanneer de regels in een script eindigen met CRLF. Unix-systemen verwachten alleen LF als het einde van de regel.

Dit probleem treedt meestal op wanneer het script is geschreven in een Windows-omgeving, omdat CRLF een veelvoorkomende regel is die eindigt voor veel teksteditors in Windows.

Oplossing: als het een optie in uw teksteditor is, selecteert u Unix-indeling of LF voor het einde van de regel. U kunt ook de volgende opdrachten op een Unix-systeem gebruiken om de CRLF te wijzigen in een LF:

Notitie

De volgende opdrachten zijn ongeveer gelijkwaardig omdat ze de CRLF-regeleinden moeten wijzigen in LF. Selecteer er een op basis van de hulpprogramma's die beschikbaar zijn op uw systeem.

Opdracht Opmerkingen
unix2dos -b INFILE Er wordt een back-up gemaakt van het oorspronkelijke bestand met een . BAK-extensie
tr -d '\r' < INFILE > OUTFILE OUTFILE bevat een versie met alleen LF-einden
perl -pi -e 's/\r\n/\n/g' INFILE Wijzigt het bestand rechtstreeks
sed 's/$'"/`echo \\\r`/" INFILE > OUTFILE OUTFILE bevat een versie met alleen LF-einden.

Fout: line 1: #!/usr/bin/env: No such file or directory.

Oorzaak: deze fout treedt op wanneer het script is opgeslagen als UTF-8 met een byteordermarkering (BOM).

Oplossing: sla het bestand op als ASCII of als UTF-8 zonder stuklijst. U kunt ook de volgende opdracht gebruiken op een Linux- of Unix-systeem om een bestand te maken zonder de stuklijst:

awk 'NR==1{sub(/^\xef\xbb\xbf/,"")}{print}' INFILE > OUTFILE

Vervang door INFILE het bestand dat de stuklijst bevat. OUTFILE moet een nieuwe bestandsnaam zijn, die het script zonder de stuklijst bevat.

Volgende stappen