Azure Service Fabric CLIAzure Service Fabric CLI

Azure Service Fabric 命令行接口 (CLI) 是一个命令行实用程序,用于与 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.

Important

可以使用两个 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

pip install 命令添加 ==<version> 后缀即可选择性地指定要安装的 CLI 的目标版本。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
sudo yum install -y epel-release
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

命令始终以 sfctl 为前缀。Commands 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:

Warning

请勿将不安全的 Service Fabric 群集用在生产环境中。Do not use unsecured Service Fabric clusters in a production environment.

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

群集终结点必须以 httphttps 为前缀。The 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,请运行以下命令(根据在原始安装期间所选的内容将 pip 替换为 pip3):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