Azure Service Fabric CLIAzure Service Fabric CLI

Azure Service Fabric 命令列介面 (CLI) 是一個命令列公用程式,用於操作和管理 Azure Service Fabric 實體。The Azure Service Fabric command-line interface (CLI) is a command-line utility for interacting with and managing Service Fabric entities. Service Fabric CLI 可以搭配 Windows 或 Linux 叢集使用。The Service Fabric CLI can be used with either Windows or Linux clusters. Service Fabric CLI 可在支援 Python 的任何平台上執行。The Service Fabric CLI runs on any platform where Python is supported.

重要

有兩個 CLI 公用程式用來與 Service Fabric 互動。There are two CLI utilities used to interact with Service Fabric. Azure CLI 用來管理 Azure 資源,例如 Azure 託管的 Service Fabric 叢集。Azure CLI is used to manage Azure resources, such as an Azure-hosted Service Fabric cluster. Service Fabric CLI 用來直接連線到 Service Fabric 叢集 (不論裝載於何處) 及管理叢集、應用程式和服務。Service Fabric CLI is used to directly connect to the Service Fabric cluster (regardless of where it's hosted) and manage the cluster, applications, and services.

必要條件Prerequisites

安裝之前,請確定您的環境已安裝 Python 和 pip。Prior to installation, make sure your environment has both Python and pip installed. 如需詳細資訊,請參閱 pip 快速入門文件和正式的 Python 安裝文件For more information, see the pip quickstart documentation and the official Python installation documentation.

CLI 支援 Python 2.7、3.5、3.6 和 3.7 版。The CLI supports Python versions 2.7, 3.5, 3.6, and 3.7. Python 3.x 是建議版本,因為 Python 2.7 的支援達到即將結束。Python 3.x is the recommended version, since Python 2.7 will reach end of support soon.

Service Fabric 目標執行階段Service Fabric target runtime

Service Fabric CLI 旨在支援 Service Fabric SDK 的最新執行階段版本。The Service Fabric CLI is meant to support the latest runtime version of the Service Fabric SDK. 使用下表來判斷要安裝的 CLI 版本:Use the following table to determine which version of CLI to install:

CLI 版本CLI version 支援的執行階段版本supported runtime version
最新 (~=7)Latest (~=7) 最新 (~=6.4)Latest (~=6.4)
6.0.06.0.0 6.36.3
5.0.05.0.0 6.26.2
4.0.04.0.0 6.16.1
3.0.03.0.0 6.06.0
1.1.01.1.0 5.6, 5.75.6, 5.7

您可以選擇性地指定要安裝的 CLI 目標版本,方法是在 pip install 命令加上尾碼 ==<version>You can optionally specify a target version of the CLI to install by suffixing the pip install command with ==<version>. 例如,1.1.0 版的語法為:For example, for version 1.1.0 the syntax would be:

pip install -I sfctl==1.1.0

在必要時,將下列 pip install 命令取代為先前所述的命令。Replace the following pip install command with the previously mentioned command when necessary.

如需 Service Fabric CLI 版本的詳細資訊,請參閱 GitHub 文件For more information on Service Fabric CLI releases, see the GitHub documentation.

安裝 pip、Python 和 Service Fabric CLIInstall pip, Python, and the Service Fabric CLI

有許多方法可在您的平台上安裝 pip 和 Python。There are many ways to install pip and Python on your platform. 以下這些步驟可以使用 Python 3 與 pip 快速設定主要作業系統。Here are some steps to get major operating systems set up quickly with Python 3 and pip.

WindowsWindows

針對 Windows 10、Windows Server 2016 和 Windows Server 2012 R2,請使用標準官方安裝指示。For Windows 10, Windows Server 2016, and Windows Server 2012 R2, use the standard official installation instructions. Python 安裝程式預設也會安裝 pip。The Python installer also installs pip by default.

  1. 前往官方 Python 下載頁面並下載最新版的 Python 3.7。Go to the official Python downloads page, and download the latest release of Python 3.7.

  2. 開始安裝程式。Start the installer.

  3. 在提示字元的底部,選取 [將 Python 3.7 新增至路徑] 。At the bottom of the prompt, select Add Python 3.7 to PATH.

  4. 選取 [立即安裝] ,並完成安裝。Select Install Now, and finish the installation.

現在您可以開啟新的命令視窗,並取得 Python 和 pip 的版本。Now you can open a new command window and get the version of both Python and pip.

python --version
pip --version

然後執行下列命令來安裝 Azure Service Fabric CLI (sfctl) 及檢視 CLI 說明頁面:Then run the following command to install the Azure Service Fabric CLI (sfctl) and view the CLI help page:

pip install sfctl
sfctl -h

適用於 Linux 的 Ubuntu 和 Windows 子系統Ubuntu and Windows subsystem for Linux

若要安裝 Service Fabric CLI,請執行下列命令:To install the Service Fabric CLI, run the following commands:

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

然後您可以測試安裝:Then you can test the installation with:

sfctl -h

如果您收到找不到命令這類的錯誤:If you receive a command not found error such as:

sfctl: command not found

請確定可從 $PATH 存取 ~/.local/binBe sure that ~/.local/bin is accessible from the $PATH:

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

如果使用不正確的資料夾權限在適用於 Linux 的 Windows 子系統上安裝失敗,可能需要以提高的權限再試一次:If the installation on Windows subsystem for Linux fails with incorrect folder permissions, it may be necessary to try again with elevated permissions:

sudo pip3 install sfctl

Red Hat Enterprise Linux 7.4 (Service Fabric 預覽支援)Red Hat Enterprise Linux 7.4 (Service Fabric preview support)

若要在 Red Hat 上安裝 Service Fabric CLI,請執行下列命令:To install Service Fabric CLI on Red Hat, run the following commands:

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

若要測試安裝,您可以參考適用於 Linux 的 Ubuntu 和 Windows 子系統一節中所述的步驟For testing the installation, you can refer to the steps mentioned in Ubuntu and Windows subsystem for Linux section

MacOSMacOS

對於 MacOS,建議使用 HomeBrew 套件管理員For MacOS, we recommend that you use the HomeBrew package manager. 如果尚未安裝 HomeBrew,可執行下列命令來加以安裝:If HomeBrew is not already installed, install it by running the following command:

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

然後從終端機安裝 Python 3.7、pip 和 Service Fabric CLI,方法是執行下列命令:Then from the terminal, install Python 3.7, pip, and the Service Fabric CLI by running the following commands:

brew install python3
pip3 install sfctl
sfctl -h

CLI 語法CLI syntax

命令前面一律會加上 sfctlCommands are always prefixed with sfctl. 如需有關所有可用命令的一般資訊,請使用 sfctl -hFor general information about all the commands you can use, use sfctl -h. 如需單一命令的說明,請使用 sfctl <command> -hFor help with a single command, use sfctl <command> -h.

命令會遵循可重複的結構,而命令的目標前面會加上動詞命令或動作。Commands follow a repeatable structure, with the target of the command preceding the verb or the action.

sfctl <object> <action>

在此範例中,<object><action> 的目標。In this example, <object> is the target for <action>.

選取叢集Select a cluster

在您執行任何作業之前,必須選取要連線的叢集。Before you perform any operations, you must select a cluster to connect to. 例如,若要選取並連線到名為 testcluster.com 的叢集,請執行下列命令:For example, to select and connect to the cluster with the name testcluster.com, run the following command:

警告

請勿於生產環境中使用不安全的 Service Fabric 叢集。Do not use unsecured Service Fabric clusters in a production environment.

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

叢集端點前面必須加上 httphttpsThe cluster endpoint must be prefixed by http or https. 它必須包含 HTTP 閘道的連接埠。It must include the port for the HTTP gateway. 此連接埠和位址等同於 Service Fabric Explorer URL。The port and address are the same as the Service Fabric Explorer URL.

對於使用憑證保護的叢集,您可以指定 PEM 編碼的憑證。For clusters that are secured with a certificate, you can specify a PEM-encoded certificate. 此憑證可以指定為單一檔案或憑證和金鑰組。The certificate can be specified as a single file or as a cert and a key pair. 若自我簽署憑證不是由 CA 所簽署,您可傳遞 --no-verify 選項以略過 CA 驗證。If it is a self-signed certificate that is not CA signed, you can pass the --no-verify option to bypass CA verification.

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

如需詳細資訊,請參閱連線到 Azure Service Fabric 叢集For more information, see Connect to a secure Azure Service Fabric cluster.

基本作業Basic operations

叢集連線資訊會跨多個 Service Fabric CLI 工作階段保存。Cluster connection information persists across multiple Service Fabric CLI sessions. 選取 Service Fabric 叢集後,您可以在此叢集上執行任何 Service Fabric 命令。After you select a Service Fabric cluster, you can run any Service Fabric command on the cluster.

例如,若要取得 Service Fabric 叢集健康情況,請使用下列命令:For example, to get the Service Fabric cluster health state, use the following command:

sfctl cluster health

此命令會導致下列輸出:The command results in the following output:

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

秘訣與疑難排解Tips and troubleshooting

以下是用於解決一般問題的某些建議和秘訣。Here are some suggestions and tips for solving common problems.

將憑證從 PFX 轉換為 PEM 格式Convert a certificate from PFX to PEM format

Service Fabric CLI 支援以 PEM (.pem 副檔名) 檔案作為用戶端憑證。The Service Fabric CLI supports client-side certificates as PEM (.pem extension) files. 如果您從 Windows 使用 PFX 檔案,則必須將這些憑證轉換成 PEM 格式。If you use PFX files from Windows, you must convert those certificates to PEM format. 若要將 PFX 檔案轉換為 PEM 檔案,請使用下列命令︰To convert a PFX file to a PEM file, use the following command:

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

同樣地,若要從 PEM 檔案轉換為 PFX 檔案,您可以使用下列命令 (在此處未提供任何密碼):Similarly, to convert from a PEM file to a PFX file, you can use the following command (no password is being provided here):

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

如需詳細資訊,請參閱 OpenSSL 文件For more information, see the OpenSSL documentation.

連線問題Connection problems

某些作業可能會產生下列訊息:Some operations might generate the following message:

Failed to establish a new connection

確認指定的叢集端點可以使用且正在接聽。Verify that the specified cluster endpoint is available and listening. 另外確認 Service Fabric Explorer 的 UI 可在該主機和連接埠上使用。Also, verify that the Service Fabric Explorer UI is available at that host and port. 若要更新端點,請使用 sfctl cluster selectTo update the endpoint, use sfctl cluster select.

詳細記錄Detailed logs

當您偵錯或回報問題時,詳細記錄通常很有幫助。Detailed logs often are helpful when you debug or report a problem. --debug 旗標可增加輸出的詳細程度。The --debug flag increases the verbosity of the output.

命令的說明和語法Command help and syntax

如需特定命令或一組命令的說明,請使用 -h 旗標。For help with a specific command or a group of commands, use the -h flag.

sfctl application -h

以下是另一個範例︰Here is another example:

sfctl application create -h

更新 Service Fabric CLIUpdating the Service Fabric CLI

若要更新 Service Fabric CLI,請執行下列命令 (以 pip3 取代 pip,取決於您在原始安裝期間的選擇):To update the Service Fabric CLI, run the following commands (replace pip with pip3 depending on what you chose during your original install):

pip uninstall sfctl
pip install sfctl

後續步驟Next steps