CLI do Azure Service Fabric

A interface de linha de comandos (CLI) do Azure Service Fabric é um utilitário de linha de comandos para interagir e gerir entidades do Service Fabric. A CLI do Service Fabric pode ser utilizada com clusters do Windows ou do Linux. A CLI do Service Fabric é executada em qualquer plataforma onde o Python seja suportado.

Pré-requisitos

Antes da instalação, certifique-se de que o seu ambiente tem o Python e o pip instalados. Para obter mais informações, veja a documentação de início rápido do pipe a documentação de instalação do Python oficial.

A CLI suporta Python versões 2.7 e 3.6+, com Python 3.x recomendado.

Runtime de destino do Service Fabric

A CLI do Service Fabric destina-se a suportar a versão de runtime mais recente do Service Fabric SDK. Utilize a tabela seguinte para determinar qual a versão da CLI a instalar:

Opcionalmente, pode especificar uma versão de destino da CLI a instalar ao colocar no comando pip install o sufixo ==<version>. Por exemplo, para a versão 1.1.0, a sintaxe seria:

pip install -I sfctl==1.1.0

Substitua o comando pip install seguinte pelo comando mencionado anteriormente, quando necessário.

Para obter mais informações sobre versões da CLI do Service Fabric, veja a Documentação do GitHub.

Instalar o pip, o Python e a CLI do Service Fabric

Existem muitas formas de instalar o pip e o Python na sua plataforma. Seguem-se alguns passos para configurar rapidamente os principais sistemas operativos com o Python 3 e o pip.

Windows

Para Windows 10, Windows Server 2016 e Windows Server 2012 R2, utilize as instruções de instalação oficiais padrão. O instalador do Python também instala o pip por predefinição.

1. Vá para a página oficial de downloads do Python e faça o download da versão mais recente do Python 3.x.

2. Inicie o instalador.

3. Na parte inferior do prompt, selecione Adicionar Python 3.x ao PATH.

4. Selecione Instalar Agora e conclua a instalação.

Agora, pode abrir uma janela de comandos nova e obter a versão, quer do Python, quer do pip.

python --version
pip --version

Em seguida, execute o seguinte comando para instalar a CLI do Azure Service Fabric (sfctl) e exibir a página de ajuda da CLI:

pip install sfctl
sfctl -h

Ubuntu e subsistema Windows para Linux

Para instalar a CLI do Service Fabric, execute os seguintes comandos:

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

Em seguida, pode testar a instalação com:

sfctl -h

Se receber um erro de comando não encontrado, como:

sfctl: command not found

Certifique-se de que ~/.local/bin está acessível a partir de $PATH:

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

Se a instalação no subsistema Windows para Linux falhar com permissões de pasta incorretas, pode ser necessário tentar novamente com permissões elevadas:

sudo pip3 install sfctl

Red Hat Enterprise Linux 7.4 (suporte de pré-visualização do Service Fabric)

Para instalar a CLI do Service Fabric no Red Hat, execute os seguintes comandos:

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

Para testar a instalação, você pode consultar as etapas mencionadas na seção Ubuntu e Windows subsystem for Linux

MacOS

Para MacOS, recomendamos utilizar o Gestor de pacotes HomeBrew. Se o HomeBrew ainda não estiver instalado, execute o comando seguinte para o instalar:

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

Em seguida, a partir do terminal, instale o Python 3.x, pip e a CLI do Service Fabric mais recentes executando os seguintes comandos:

brew install python3
pip3 install sfctl
sfctl -h

Sintaxe da CLI

Aos comandos é sempre adicionado o prefixo sfctl. Para obter informações gerais sobre todos os comandos que pode utilizar, utilize sfctl -h. Para obter ajuda com comandos individuais, utilize sfctl <command> -h.

Os comandos seguem uma estrutura repetível, com o destino do comando antes do verbo ou da ação.

sfctl <object> <action>

Neste exemplo, <object> é o destino de <action>.

Selecionar um cluster

Antes de executar qualquer operação, tem de selecionar um cluster ao qual se deve ligar. Por exemplo, para selecionar e ligar ao cluster com o nome testcluster.com, execute o comando seguinte:

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

O ponto final do cluster tem de ter o prefixo http ou https. Tem de incluir a porta para o gateway HTTP. A porta e o endereço são os mesmos que o URL do Service Fabric Explorer.

Para os clusters que estão protegidos por um certificado, pode especificar um certificado PEM codificado. O certificado pode ser especificado como um ficheiro individual ou como um certificado e par de chaves. Se for um certificado autoassinado que não esteja assinado por uma AC, pode transmitir a opção --no-verify para ignorar a verificação de AC.

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

Para obter mais informações, veja Connect to a secure Azure Service Fabric cluster (Ligar a um cluster do Azure Service Fabric seguro).

Operações básicas

As informações de ligação do cluster estão presentes em diferentes sessões da CLI do Service Fabric. Depois de selecionar um cluster do Service Fabric, pode executar qualquer comando do Service Fabric no mesmo.

Por exemplo, para obter o estado de funcionamento do cluster do Service Fabric, utilize o comando seguinte:

sfctl cluster health

O comando resulta na seguinte saída:

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

Sugestões e resolução de problemas

Seguem-se algumas sugestões e dicas para resolver problemas comuns.

Converter um certificado no formato PFX em PEM

A CLI do Service Fabric suporta ficheiros de certificados de cliente como PEM (extensão .pem). Se utilizar ficheiros PFX do Windows, tem de converter esses certificados no formato PEM. Para converter um ficheiro PFX para ficheiro PEM, utilize o comando seguinte:

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

Da mesma forma, para converter um ficheiro PEM num ficheiro PFX, pode utilizar o seguinte comando (não é fornecida qualquer palavra-passe aqui):

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

Para obter mais informações, veja a documentação de OpenSSL.

Problemas de ligação

Algumas operações poderão gerar a mensagem seguinte:

Failed to establish a new connection

Verifique se o ponto final do cluster especificado está disponível e à escuta. Confirme, também, se a IU do Service Fabric Explorer está disponível no anfitrião e na porta. Para atualizar o ponto final, utilize sfctl cluster select.

Registos detalhados

Muitas vezes, os registos detalhados são úteis para depurar ou comunicar problemas. O --debug sinalizador aumenta a detalhamento da saída.

Ajuda de comandos e sintaxe

Para obter ajuda com um comando específico ou um grupo de comandos, utilize o sinalizador -h.

sfctl application -h

Segue-se outro exemplo:

sfctl application create -h

Atualizar a CLI do Service Fabric

Para atualizar a CLI do Service Fabric, execute os seguintes comandos (substitua pip por pip3 consoante o que tiver escolhido durante a instalação original):

pip uninstall sfctl
pip install sfctl

Próximos passos

• Implementar uma aplicação com a CLI do Azure Service Fabric
• Introdução ao Service Fabric no Linux