Azure Service Fabric CLI

11.2.1 · active · verified Thu Apr 16

sfctl is the Azure Service Fabric command-line interface, a powerful utility for interacting with and managing Service Fabric clusters, applications, and services. It provides a comprehensive set of commands for development, deployment, and operational tasks. The library maintains an active release cadence, with updates often aligning with new Service Fabric runtime versions to ensure compatibility and leverage new features. The current version is 11.2.1.

Common errors

```
sfctl: command not found
```
cause The `sfctl` executable is not in your system's PATH, or the installation failed.

fix Ensure `pip install sfctl` completed successfully. Verify Python's script directory (e.g., `~/.local/bin` on Linux/macOS, `Scripts` in Python install dir on Windows) is in your system's PATH environment variable. Reinstall `sfctl` if necessary.
```
UserWarning: sfctl has version "X.Y.Z" which does not match the cluster version "A.B.C.D". See https://learn.microsoft.com/azure/service-fabric/service-fabric-cli#service-fabric-target-runtime for version compatibility. Upgrade to a compatible version for the best experience.
```
cause Your installed sfctl version is not compatible with the connected Service Fabric cluster's runtime version.

fix Upgrade your Service Fabric cluster, downgrade `sfctl` using `pip install sfctl==<compatible-version>`, or upgrade `sfctl` using `pip install --upgrade sfctl` to match your cluster. Always consult the official compatibility documentation.
```
msrest.exceptions.ClientRequestError: Error occurred in request., ConnectionError: HTTPSConnectionPool(host='yourcluster.region.cloudapp.azure.com', port=19080): Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1018)')))
```
cause sfctl failed to verify the SSL certificate of the cluster endpoint, often due to self-signed certificates or incorrect certificate configuration.

fix For non-production/testing, add `--no-verify` to your `sfctl cluster select` command (e.g., `sfctl cluster select --endpoint https://... --pem ./client.pem --no-verify`). For production, import the cluster's certificate into your client machine's trusted root certification authorities store, or ensure you are using correctly issued certificates.
```
msrest.exceptions.ClientRequestError: Error occurred in request., ConnectionError: HTTPSConnectionPool(host='yourcluster.endpoint', port=19080): Max retries exceeded
```
cause The sfctl command could not establish a connection to the Service Fabric cluster, possibly due to incorrect endpoint, network issues, or cluster unavailability/firewall restrictions.

fix Verify the cluster endpoint URL and port are correct. Ensure the cluster is running and accessible from your machine (check network connectivity and firewall rules). For local clusters, confirm `http://localhost:19080` is the correct endpoint.
```
403 Client Error: Client certificate required for url: https://yourcluster.endpoint:19080/ImageStore/...
```
cause During application upload, the cluster requires a client certificate for authentication, which was either not provided or is invalid.

fix Ensure your `sfctl cluster select` command correctly specifies the client certificate (e.g., `--pem ./client.pem` or `--cert ./client.crt --key ./client.key`) before attempting application upload. Verify the certificate is valid and has permissions to interact with the image store.

Warnings

breaking sfctl versions are tightly coupled with Azure Service Fabric runtime versions. Incompatible versions can lead to errors or unexpected behavior. Starting with v7.0.0, sfctl includes a compatibility check, but manual verification is recommended.
Fix: Always use a version of sfctl compatible with your Service Fabric cluster runtime. Refer to the official Service Fabric CLI documentation for the recommended compatibility matrix. Upgrade both sfctl and your cluster if encountering compatibility warnings.
gotcha Connecting to secure Service Fabric clusters, especially those with self-signed certificates, often results in SSL/TLS errors. While `--no-verify` can bypass certificate validation, it is insecure and should be avoided in production.
Fix: For self-signed certificates, ensure the certificate is correctly installed in your operating system's trusted root store. For secure clusters, specify the correct `--pem` or `--cert` and `--key` arguments. Avoid `--no-verify` in production.
breaking Application upload operations (e.g., `sfctl application upload`) can sometimes experience timeouts or '403 Client Error: Client certificate required' even when other commands work. This was particularly noted in older versions.
Fix: Increase the default timeout using the `--timeout` parameter for large application packages. Ensure the client certificate is correctly configured and accessible to sfctl. For large packages, consider using the `--show-progress` option.
deprecated Support for Python 2.7 has been deprecated. The library now officially requires Python 3.8 or newer. Using older Python versions will lead to installation and runtime errors.
Fix: Upgrade your Python environment to version 3.8 or higher. Use `pip install sfctl` with a compatible Python 3 interpreter.

Install

pip install sfctl Install sfctl

Quickstart

After installation, use `sfctl -h` to see available commands. The first step is typically to connect to a Service Fabric cluster using `sfctl cluster select`. For secure clusters, you'll need to provide certificate paths (PEM or cert/key pair) and potentially use `--no-verify` for self-signed certificates, though this is not recommended for production environments.

# Install sfctl (if not already installed)
pip install sfctl

# Display help for sfctl commands
sfctl -h

# Connect to a Service Fabric cluster (example for a local cluster)
# Replace with your cluster endpoint and certificate details for secure/remote clusters
sfctl cluster select --endpoint http://localhost:19080

# Check the health of the connected cluster
sfctl cluster health

# List all applications in the cluster
sfctl application list

view raw JSON →