Azure Service Fabric CLI

Article
07/14/2022

The Azure Service Fabric command-line interface (CLI) is a command-line utility for interacting with and managing Service Fabric entities. The Service Fabric CLI can be used with either Windows or Linux clusters. The Service Fabric CLI runs on any platform where Python is supported.

Important

There are two CLI utilities used to interact with Service Fabric. Azure CLI is used to manage Azure resources, such as an Azure-hosted Service Fabric cluster. 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

Prior to installation, make sure your environment has both Python and pip installed. For more information, see the pip quickstart documentation and the official Python installation documentation.

The CLI supports Python versions 2.7 and 3.6+, with Python 3.x recommended.

Service Fabric target runtime

The Service Fabric CLI is meant to support the latest runtime version of the Service Fabric SDK. Use the following table to determine which version of CLI to install:

CLI version	supported runtime version
Latest (~=10)	Latest (~=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

You can optionally specify a target version of the CLI to install by suffixing the pip install command with ==<version>. For example, for version 1.1.0 the syntax would be:

pip install -I sfctl==1.1.0

Replace the following pip install command with the previously mentioned command when necessary.

For more information on Service Fabric CLI releases, see the GitHub documentation.

Install pip, Python, and the Service Fabric CLI

There are many ways to install pip and Python on your platform. Here are some steps to get major operating systems set up quickly with Python 3 and pip.

Windows

For Windows 10, Windows Server 2016, and Windows Server 2012 R2, use the standard official installation instructions. The Python installer also installs pip by default.

Go to the official Python downloads page, and download the latest release of Python 3.x.
Start the installer.
At the bottom of the prompt, select Add Python 3.x to PATH.
Select Install Now, and finish the installation.

Now you can open a new command window and get the version of both Python and pip.

python --version
pip --version

Then run the following command to install the Azure Service Fabric CLI (sfctl) and view the CLI help page:

pip install sfctl
sfctl -h

Ubuntu and Windows subsystem for Linux

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

Be sure that ~/.local/bin is accessible from the $PATH:

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

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 preview support)

To install Service Fabric CLI on Red Hat, run the following commands:

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

For testing the installation, you can refer to the steps mentioned in Ubuntu and Windows subsystem for Linux section

MacOS

For MacOS, we recommend that you use the HomeBrew package manager. 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)"

Then from the terminal, install the latest Python 3.x, pip, and the Service Fabric CLI by running the following commands:

brew install python3
pip3 install sfctl
sfctl -h

CLI syntax

Commands are always prefixed with sfctl. For general information about all the commands you can use, use sfctl -h. For 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>

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. For example, to select and connect to the cluster with the name testcluster.com, run the following command:

Warning

Do not use unsecured Service Fabric clusters in a production environment.

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

The cluster endpoint must be prefixed by http or https. It must include the port for the HTTP gateway. The port and address are the same as the Service Fabric Explorer URL.

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. 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

For more information, see Connect to a secure Azure Service Fabric cluster.

Basic operations

Cluster connection information persists across multiple Service Fabric CLI sessions. After you select a Service Fabric cluster, you can run any Service Fabric command on the cluster.

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.

Convert a certificate from PFX to PEM format

The Service Fabric CLI supports client-side certificates as PEM (.pem extension) files. If you use PFX files from Windows, you must convert those certificates to PEM format. To convert a PFX file to a PEM file, use the following command:

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

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:''

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. Also, verify that the Service Fabric Explorer UI is available at that host and port. To update the endpoint, use sfctl cluster select.

Detailed logs

Detailed logs often are helpful when you debug or report a problem. The --debug flag increases the verbosity of the output.

Command help and syntax

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

Updating the Service Fabric CLI

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