Azure Service Fabric CLI

Artikel
10/15/2024

Bei der Azure Service Fabric-Befehlszeilenschnittstelle (CLI) handelt es sich um ein Befehlszeilen-Hilfsprogramm zum Interagieren mit und Verwalten von Service Fabric-Entitäten. Für die Service Fabric CLI ist die Verwendung mit Windows- oder mit Linux-Clustern möglich. Die Service Fabric CLI wird auf allen Plattformen ausgeführt, die Python unterstützen.

Wichtig

Es gibt zwei CLI-Hilfsprogramme, die für die Interaktion mit Service Fabric verwendet werden. Die Azure CLI wird zum Verwalten von Azure-Ressourcen verwendet, z.B. für einen in Azure gehosteten Service Fabric-Cluster. Die Service Fabric CLI wird verwendet, um eine direkte Verbindung mit dem Service Fabric-Cluster herzustellen (unabhängig vom Host-Ort) und den Cluster, Anwendungen und Dienste zu verwalten.

Voraussetzungen

Stellen Sie vor der Installation sicher, dass in Ihrer Umgebung Python und pip installiert sind. Weitere Informationen finden Sie in der Schnellstartdokumentation zu pip und der offiziellen Python-Installationsdokumentation.

Die CLI unterstützt die Python-Versionen 2.7, 3.6 und höher, wobei Python 3.x empfohlen wird.

Service Fabric-Ziellaufzeit

Die Service Fabric-Befehlszeilenschnittstelle ist zur Unterstützung der neuesten Laufzeitversion des Service Fabric SDK gedacht. Die folgende Tabelle gibt Aufschluss darüber, welche Version der Befehlszeilenschnittstelle Sie installieren sollten:

CLI-Version	Unterstützte Laufzeitversion
Neueste (~= 10)	Neueste (~= 7.1)
9.0.0	7.1
8.0.0	6,5
7.1.0	6.4
6.0.0	6.3
5.0.0	6.2
4.0.0	6.1
3.0.0	6.0
1.1.0	5.6, 5.7

Sie können optional eine zu installierende Zielversion der Befehlszeilenschnittstelle angeben, indem Sie den Befehl pip install mit dem Suffix ==<version> versehen. Die Syntax für Version 1.1.0 lautet beispielsweise wie folgt:

pip install -I sfctl==1.1.0

Ersetzen Sie den folgenden Befehl vom Typ pip install bei Bedarf durch den zuvor genannten Befehl.

Weitere Informationen zu Service Fabric-CLI-Releases finden Sie in der GitHub-Dokumentation.

Installieren von pip, Python und der Service Fabric CLI

Es gibt viele Möglichkeiten, pip und Python auf Ihrer Plattform zu installieren. Im Anschluss sind einige Schritte aufgeführt, mit denen Sie gängige Betriebssysteme schnell mit Python 3 und pip einrichten können.

Windows

Verwenden Sie für Windows 10, Windows Server 2016 und Windows Server 2012 R2 die offizielle Standardanleitung für die Installation. Mit dem Python-Installationsprogramm wird standardmäßig auch pip installiert.

Gehen Sie auf die offizielle Python-Download-Seite und laden Sie die neueste Version von Python 3.x herunter.
Starten Sie das Installationsprogramm.
Wählen Sie am unteren Ende der Eingabeaufforderung Python 3.x zu PATH hinzufügen.
Wählen Sie Jetzt installieren, und schließen Sie die Installation ab.

Sie können nun ein neues Befehlsfenster öffnen und die Version von Python und PIP abrufen.

python --version
pip --version

Führen Sie dann den folgenden Befehl aus, um die Azure Service Fabric-CLI (sfctl) zu installieren und die CLI-Hilfeseite anzuzeigen:

pip install sfctl
sfctl -h

Ubuntu und Windows-Subsystem für Linux

Führen Sie zum Installieren der Service Fabric-Befehlszeilenschnittstelle die folgenden Befehle aus:

sudo apt-get install python3
sudo apt-get install python3-pip
pip3 install sfctl

Die Installation können Sie anschließend mit Folgendem testen:

sfctl -h

Es kann vorkommen, dass ein Fehler aufgrund eines nicht gefundenen Befehls auftritt:

sfctl: command not found

Vergewissern Sie sich in diesem Fall, dass über $PATH auf ~/.local/bin zugegriffen werden kann:

export PATH=$PATH:~/.local/bin
echo "export PATH=$PATH:~/.local/bin" >> .shellrc

Sollte die Installation im Windows-Subsystem für Linux aufgrund falscher Ordnerberechtigungen nicht erfolgreich sein, muss der Vorgang unter Umständen mit erhöhten Berechtigungen wiederholt werden:

sudo pip3 install sfctl

Red Hat Enterprise Linux 7.4 (Unterstützung der Service Fabric-Vorschauversion)

Führen Sie zum Installieren der Service Fabric-Befehlszeilenschnittstelle unter Red Hat die folgenden Befehle aus:

sudo yum install -y python38
sudo yum install python38-setuptools
sudo easy_install-3.4 pip
sudo pip3 install sfctl

Sie können die Schritte im Abschnitt Ubuntu und Windows-Subsystem für Linux durchführen, um die Installation zu testen.

MacOS

Für MacOS empfehlen wir Ihnen die Nutzung des HomeBrew-Paket-Managers. Wenn HomeBrew nicht bereits installiert ist, können Sie die Installation mit dem folgenden Befehl durchführen:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Installieren Sie dann vom Terminal aus das neueste Python 3.x, pip und die Service Fabric CLI, indem Sie die folgenden Befehle ausführen:

brew install python3
pip3 install sfctl
sfctl -h

CLI-Syntax

Die Befehle verfügen immer über das Präfix sfctl. Allgemeine Informationen zu allen Befehlen, die Sie nutzen können, erhalten Sie mit sfctl -h. Hilfe zu einem einzelnen Befehl erhalten Sie mit sfctl <command> -h.

Befehle folgen einer wiederholbaren Struktur. Dabei steht das Ziel des Befehls vor dem Verb oder der Aktion.

sfctl <object> <action>

In diesem Beispiel ist <object> das Ziel für <action>.

Auswählen eines Clusters

Bevor Sie Vorgänge durchführen, müssen Sie einen Cluster auswählen, mit dem die Verbindung hergestellt wird. Führen Sie beispielsweise den folgenden Befehl aus, um den Cluster testcluster.com auszuwählen und eine Verbindung damit herzustellen:

Warnung

Vermeiden Sie die Verwendung von ungeschützten Service Fabric-Clustern in einer Produktionsumgebung.

sfctl cluster select --endpoint http://testcluster.com:19080

Der Clusterendpunkt muss das Präfix http oder https aufweisen. Er muss den Port für das HTTP-Gateway enthalten. Der Port und die Adresse entsprechen der Service Fabric Explorer-URL.

Für Cluster, die mit einem Zertifikat gesichert sind, können Sie ein PEM-codiertes Zertifikat angeben. Das Zertifikat kann als eine einzelne Datei oder als Zertifikat und Schlüsselpaar angegeben werden. Handelt es sich um ein selbstsigniertes Zertifikat, das nicht von einer Zertifizierungsstelle signiert wurde, können Sie die Option --no-verify übergeben, um die Überprüfung der Zertifizierungsstelle zu umgehen.

sfctl cluster select --endpoint https://testsecurecluster.com:19080 --pem ./client.pem --no-verify

Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einem sicheren Cluster.

Einfache Vorgänge

Informationen zur Clusterverbindung werden über mehrere Service Fabric CLI-Sitzungen hinweg beibehalten. Nach dem Auswählen eines Service Fabric-Clusters können Sie im Cluster einen beliebigen Service Fabric-Befehl ausführen.

Verwenden Sie beispielsweise den folgenden Befehl, um den Integritätsstatus des Service Fabric-Clusters abzurufen:

sfctl cluster health

Mit diesem Befehl wird die folgende Ausgabe zurückgegeben:

{
  "aggregatedHealthState": "Ok",
  "applicationHealthStates": [
    {
      "aggregatedHealthState": "Ok",
      "name": "fabric:/System"
    }
  ],
  "healthEvents": [],
  "nodeHealthStates": [
    {
      "aggregatedHealthState": "Ok",
      "id": {
        "id": "66aa824a642124089ee474b398d06a57"
      },
      "name": "_Test_0"
    }
  ],
  "unhealthyEvaluations": []
}

Tipps und Problembehandlung

Hier sind einige Vorschläge und Tipps zum Beheben von allgemeinen Problemen angegeben.

Konvertieren eines Zertifikats aus dem PFX- in das PEM-Format

Die Service Fabric-Befehlszeilenschnittstelle unterstützt clientseitige Zertifikate als PEM-Dateien (Erweiterung „.pem“). Bei Verwendung von PFX-Dateien in Windows müssen Sie diese Zertifikate in das PEM-Format konvertieren. Mit dem folgenden Befehl konvertieren Sie eine PFX-Datei in eine PEM-Datei:

openssl pkcs12 -in certificate.pfx -out mycert.pem -nodes

Wenn Sie eine PFX-Datei in eine PEM-Datei konvertieren möchten, können Sie den folgenden Befehl verwenden. (Hier wird kein Kennwort angegeben.)

openssl  pkcs12 -export -out Certificates.pfx -inkey Certificates.pem -in Certificates.pem -passout pass:''

Weitere Informationen finden Sie in der OpenSSL-Dokumentation.

Verbindungsprobleme

Für einige Vorgänge wird unter Umständen die folgende Meldung generiert:

Failed to establish a new connection

Stellen Sie sicher, dass der angegebene Clusterendpunkt verfügbar ist und lauscht. Überprüfen Sie auch, ob die Service Fabric Explorer-Benutzeroberfläche unter diesem Host und Port verfügbar ist. Verwenden Sie sfctl cluster select, um den Endpunkt zu aktualisieren.

Detaillierte Protokolle

Detaillierte Protokolle sind häufig hilfreich, wenn Sie das Debuggen durchführen oder ein Problem melden. Mit dem --debug-Flag wird die Ausführlichkeit der Ausgabe erhöht.

Befehle – Hilfe und Syntax

Verwenden Sie das -h-Flag, um Hilfe zu einem bestimmten Befehl oder einer Gruppe von Befehlen zu erhalten.

sfctl application -h

Hier ist ein weiteres Beispiel angegeben:

sfctl application create -h

Aktualisieren der Service Fabric-Befehlszeilenschnittstelle

Führen Sie zum Aktualisieren der Service Fabric-Befehlszeilenschnittstelle die folgenden Befehle aus, und ersetzen Sie dabei pip durch pip3 (abhängig von der getroffenen Auswahl bei der ursprünglichen Installation):

pip uninstall sfctl
pip install sfctl

Freigeben über