Tutorial: Implantar em um cluster do Service Fabric

  • Artigo

Este tutorial aborda várias maneiras de configurar o ambiente do Jenkins e diferentes maneiras de implantar seu aplicativo em um cluster do Service Fabric, depois que ele for criado. Siga estas etapas gerais para configurar o Jenkins, extrair as alterações do GitHub, criar seu aplicativo e implantá-lo no cluster com êxito:

  1. Instale os Pré-requisitos.
  2. Em seguida, siga as etapas em uma destas seções para configurar o Jenkins:
  3. Depois de configurar o Jenkins, siga as etapas em Criar e configurar um trabalho do Jenkins a fim de configurar o GitHub para disparar o Jenkins quando forem feitas alterações ao seu aplicativo e para configurar o pipeline de trabalho do Jenkins usando a etapa de compilação para extrair as alterações do GitHub e criar seu aplicativo.
  4. Por fim, configure a etapa de pós-compilação do trabalho do Jenkins para implantar seu aplicativo no cluster do Service Fabric. Há duas maneiras de configurar o Jenkins para implantar seu aplicativo em um cluster:

Pré-requisitos

Instalar o plug-in do Service Fabric em um ambiente do Jenkins existente

Se você estiver adicionando o plug-in do Service Fabric em um ambiente do Jenkins existente, será necessário executar as seguintes etapas:

Depois de instalar os pré-requisitos necessários para o ambiente, procure o plug-in do Azure Service Fabric no marketplace do Jenkins e instale-o.

Depois de instalar o plug-in, vá para Criar e configurar um trabalho do Jenkins.

Configurar o Jenkins em um cluster do Service Fabric

Você pode configurar o Jenkins dentro ou fora de um cluster do Service Fabric. As próximas seções mostram como configurá-lo em um cluster usando uma conta de armazenamento do Azure para salvar o estado da instância do contêiner.

  1. Verifique se você tem um cluster Linux do Service Fabric com o Docker instalado. Os clusters do Service Fabric em execução no Azure já têm o Docker instalado. Se você estiver executando o cluster localmente (ambiente de desenvolvimento OneBox), verifique se o Docker está instalado em sua máquina com o docker info comando. Se não estiver instalado, instale-o usando os seguintes comandos:

    sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh

    Observação

    Verifique se a porta 8081 foi especificada como um ponto de extremidade personalizado no cluster. Se você estiver usando um cluster local, verifique se a porta 8081 está aberta no computador host e se ele tem um endereço IP público.

  2. Clone o aplicativo usando os seguintes comandos:

    git clone https://github.com/suhuruli/jenkins-container-application.git
cd jenkins-container-application

  3. Mantenha o estado do contêiner Jenkins em um compartilhamento de arquivos:

    1. Crie uma conta de armazenamento do Azure na mesma região do que o seu cluster com um nome como sfjenkinsstorage1.

    2. Crie um Compartilhamento de Arquivos na Conta de Armazenamento com um nome como sfjenkins.

    3. Clique em Conectar no compartilhamento de arquivos e observe os valores exibidos em Conectando por meio do Linux, o valor deve ser semelhantes a este:

      sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777

    Observação

    Para montar compartilhamentos de cifs, é necessário ter o pacote cifs-utils instalado nos nós do cluster.

  4. Atualize os valores de espaço reservado no script setupentrypoint.sh com os detalhes do armazenamento do Azure da etapa 2.

    vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
    • Substitua [REMOTE_FILE_SHARE_LOCATION] pelo valor //sfjenkinsstorage1.file.core.windows.net/sfjenkins do resultado da conexão da etapa 2 acima.
    • Substitua [FILE_SHARE_CONNECT_OPTIONS_STRING] pelo valor vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 da etapa 2 acima.

  5. Somente cluster seguro:

    Para configurar a implantação de aplicativos em um cluster seguro do Jenkins, o certificado deve ser acessível dentro do contêiner do Jenkins. No arquivo ApplicationManifest.xml, na marca ContainerHostPolicies, adicione essa referência de certificado e atualize o valor da impressão digital com o do certificado de cluster.

    <CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>

    Além disso, adicione as seguintes linhas na marca (raiz) ApplicationManifest no arquivo ApplicationManifest.xml e atualize o valor de impressão digital com o do certificado de cluster.

    <Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates>

  6. Conecte-se ao cluster e instale o aplicativo contêiner.

    Cluster seguro

    sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh

    O comando anterior usa o certificado no formato PEM. Se o certificado estiver no formato PFX, use o comando a seguir para convertê-lo. Se o arquivo PFX não estiver protegido por senha, especifique o parâmetro passin como -passin pass:.

    openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>

    Cluster não seguro

    sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh

    Isso instala um contêiner Jenkins no cluster e pode ser monitorado usando o Service Fabric Explorer.

    Observação

    O download da imagem do Jenkins no cluster pode demorar alguns minutos.

  7. No navegador, acesse http://PublicIPorFQDN:8081. Ela fornece o caminho da senha de administrador inicial necessária para entrar.

  8. Examine o Service Fabric Explorer para determinar em qual nó o contêiner Jenkins está em execução. Entre com SSH (Secure Shell) neste nó.

    ssh user@PublicIPorFQDN -p [port]

  9. Obter a ID de instância do contêiner usando docker ps -a.

  10. Entre com SSH (Secure Shell) no contêiner e cole o caminho exibido no portal do Jenkins. Por exemplo, se o portal mostrar o caminho PATH_TO_INITIAL_ADMIN_PASSWORD, execute os seguintes comandos:

    docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell

    cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value

  11. Na página Introdução ao Jenkins, escolha a opção Selecionar plug-in para instalação, marque a caixa de seleção Nenhum e clique em Instalar.

  12. Crie um usuário ou selecione para continuar como um administrador.

Depois de configurar o Jenkins, vá para Criar e configurar um trabalho do Jenkins.

Configurar o Jenkins fora de um cluster do Service Fabric

Você pode configurar o Jenkins dentro ou fora de um cluster do Service Fabric. As seções a seguir mostram como configurá-lo fora de um cluster.

  1. Verifique se o Docker está instalado no computador executando docker info no terminal. A saída indica se o serviço do Docker está em execução.

  2. Se Docker não estiver instalado, execute os seguintes comandos:

    sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh

  3. Baixar a imagem de contêiner Jenkins do Service Fabric: docker pull rapatchi/jenkins:latest. Esta imagem é fornecida com o plug-in do Service Fabric no Jenkins pré-instalado.

  4. Executar a imagem de contêiner:docker run -itd -p 8080:8080 rapatchi/jenkins:latest

  5. Obter a ID de instância de imagem de contêiner. Você pode listar todos os contêineres do Docker com o comando docker ps –a

  6. Entre no portal do Jenkins usando as seguintes etapas:

    1. Entrar em um shell Jenkins no seu host. Use os quatro primeiros dígitos da ID do contêiner. Por exemplo, se a ID do contêiner for 2d24a73b5964, use 2d24.

      docker exec -it [first-four-digits-of-container-ID] /bin/bash

    2. No shell Jenkins, obtenha a senha de administrador para a instância do contêiner:

      cat /var/jenkins_home/secrets/initialAdminPassword

    3. Para entrar no painel do Jenkins, abra a seguinte URL em um navegador: http://<HOST-IP>:8080. Use a senha da etapa anterior para desbloquear o Jenkins.

    4. (Opcional.) Depois de entrar pela primeira vez, você pode criar sua própria conta de usuário e usá-la para as etapas a seguir, ou pode continuar a usar a conta de administrador. Se você criar um usuário, precisará continuar com ele.

  7. Configure o GitHub para trabalhar com o Jenkins usando as etapas em Gerando uma nova chave SSH e adicionando-a ao agente SSH.

    • Usar as instruções fornecidas no GitHub para gerar uma chave SSH e adicionar a chave SSH à conta do GitHub que está hospedando o repositório.

    • Execute os comandos mencionados no link anterior no shell Jenkins Docker (e não no host).

    • Para entrar no shell Jenkins do host, use o seguinte comando:

      docker exec -t -i [first-four-digits-of-container-ID] /bin/bash

Verifique se o cluster ou a máquina em que a imagem de contêiner Jenkins está hospedada tem um endereço IP público. Isso permite que a instância do Jenkins receba notificações do GitHub.

Depois de configurar o Jenkins, prossiga para a próxima seção, Criar e configurar um trabalho do Jenkins.

Criar e configurar um trabalho do Jenkins

As etapas nesta seção mostram como configurar um trabalho do Jenkins para responder a alterações em um repositório GitHub, como buscar essas alterações e como criá-las. No final desta seção, você será direcionado para as etapas finais a fim de configurar o trabalho para implantar no aplicativo de acordo com a natureza do ambiente, se desenvolvimento/teste ou produção.

  1. No painel do Jenkins, clique em Novo Item.

  2. Insira um nome de item (por exemplo, MyJob). Selecione projeto em estilo livree clique em OK.

  3. A página de configuração do trabalho é aberta. (Para obter a configuração do painel do Jenkins, clique no trabalho e em Configurar.)

  4. Na guia Geral, marque a caixa do projeto GitHub e especifique a URL do projeto GitHub. Essa URL hospeda o aplicativo Java do Service Fabric que você deseja integrar à integração contínua do Jenkins, no fluxo de implantação contínua (CI/CD) (por exemplo, https://github.com/{your-github-account}/service-fabric-java-getting-started).

  5. Na guia Gerenciamento de Código-Fonte, selecione Git. Especifique a URL do repositório que hospeda o aplicativo Java do Service Fabric que você deseja integrar ao fluxo CI/CD do Jenkins (por exemplo, https://github.com/{your-github-account}/service-fabric-java-getting-started). Você também pode especificar qual ramificação criar (por exemplo, /master).

  6. Configure o repositório GitHub para falar com o Jenkins:

    1. Na página repositório GitHub, vá para Configurações>Integrações e Serviços.

    2. Selecione Adicionar Serviço, digite Jenkins e selecione o plug-in Jenkins-GitHub.

    3. Insira a URL do webhook Jenkins (por padrão, ele deve ser http://<PublicIPorFQDN>:8081/github-webhook/). Clique em adicionar/atualizar serviço.

    4. Um evento de teste é enviado para a instância do Jenkins. Você verá uma marca de seleção verde ao lado do webhook no GitHub, e o projeto será criado.

  7. Na guia Build Triggers do Jenkins, selecione a opção de compilação desejada. Neste exemplo, você deseja disparar uma build sempre que ocorrer um envio por push para o repositório; para isso, selecione Gatilho de gancho GitHub para sondagem GITScm. (Anteriormente, essa opção se chamava Compilar quando uma alteração for enviada ao GitHub.)

  8. Na guia Criar, siga um destes procedimentos, dependendo de estar criando um aplicativo Java ou um aplicativo .NET Core:

    • Para aplicativos do Java: na lista suspensa Adicionar etapa de compilação, selecione Invocar Script Gradle. Clique em Avançado. No menu avançado, especifique o caminho do script de compilação da raiz para o aplicativo. Ele obtém o build.gradle no caminho especificado e funciona de maneira correspondente. Para o aplicativo ActorCounter, é: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.

      Ação Compilar do Jenkins no Service Fabric

    • Para aplicativos do .NET Core: na lista suspensa Adicionar etapa de compilação, selecione Executar Shell. Na caixa de comando que aparece, o diretório precisa primeiro ser alterado para o caminho em que o arquivo build.sh está localizado. Após a alteração no diretório, o script build.sh pode ser executado para criar o aplicativo.

      cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh

      A captura de tela a seguir mostra um exemplo dos comandos usados para criar o exemplo Counter Service com o nome de trabalho do Jenkins de CounterServiceApplication.

      Exemplo de comandos usados para criar o serviço

  9. Para configurar o Jenkins para implantar seu aplicativo em um cluster do Service Fabric nas ações pós-compilação, é necessário saber o local do certificado do cluster em seu contêiner do Jenkins. Escolha um dos seguintes, dependendo de o contêiner Jenkins estar em execução dentro ou fora do seu cluster e de acordo com o local do certificado de cluster:

    • Para o Jenkins em execução no cluster: o caminho para o certificado pode ser encontrado ecoando o valor da variável de ambiente Certificates_JenkinsOnSF_Code_MyCert_PEM de dentro do contêiner.

      echo $Certificates_JenkinsOnSF_Code_MyCert_PEM

    • Para o Jenkins em execução fora do cluster: siga estas etapas para copiar o certificado de cluster para o contêiner:

      1. O certificado deve estar no formato PEM. Se você não tiver um arquivo PEM, poderá criar um do arquivo PFX de certificado. Se o arquivo PFX não estiver protegido por senha, execute o seguinte comando no seu host:

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:

        Se o arquivo PFX estiver protegido por senha, inclua a senha no parâmetro -passin. Por exemplo:

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>

      2. para obter a ID do contêiner para seu contêiner do Jenkins, execute docker ps no host.

      3. Copie o arquivo PEM no seu contêiner com o seguinte comando do Docker:

        docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home

Está quase concluído! Mantenha o trabalho do Jenkins aberto. A única tarefa restante é configurar as etapas de pós-compilação para implantar seu aplicativo no cluster do Service Fabric:

Configurar a implantação usando o ponto de extremidade de gerenciamento do cluster

Para ambientes de desenvolvimento e teste, você pode usar o ponto de extremidade de gerenciamento do cluster para implantar o aplicativo. Configurar a ação de pós-compilação com o ponto de extremidade de gerenciamento do cluster para implantar o aplicativo exige o mínimo de configuração. Se você estiver implantando em um ambiente de produção, avance para Configurar a implantação usando credenciais do Azure para configurar uma entidade de serviço do Microsoft Entra a ser usada durante a implantação.

  1. No trabalho do Jenkins, clique na guia Ações de Pós-compilação.

  2. No menu suspenso Ações Pós-Compilação, selecione Implantar Projeto do Service Fabric.

  3. Em Configuração de Cluster do Service Fabric, selecione o botão de opção Preencher o Ponto de Extremidade de Gerenciamento do Service Fabric.

  4. Em Host de Gerenciamento, insira o ponto de extremidade de conexão do seu cluster; por exemplo, {your-cluster}.eastus.cloudapp.azure.com.

  5. Em Chave do Cliente e Certificado de Cliente, insira o local do arquivo PEM em seu contêiner do Jenkins; por exemplo, /var/jenkins_home/clustercert.pem. (Você copiou o local do certificado na última etapa de Criar e configurar um trabalho do Jenkins.)

  6. Em Configuração de Aplicativo, configure os campos Nome do Aplicativo, Tipo de Aplicativo e Caminho para o Manifesto do Aplicativo (relativo).

    Ação de pós-compilação do Service Fabric – configurar ponto de extremidade de gerenciamento

  7. Clique em Verificar Configuração. Quando a verificação tiver êxito, clique em Salvar. O pipeline de trabalho do Jenkins agora está totalmente configurado. Vá para Próximas etapas a fim de testar a implantação.

Configurar a implantação usando as credenciais do Azure

Para ambientes de produção, é recomendado configurar uma credencial do Azure para implantar seu aplicativo. Esta seção mostra como configurar uma entidade de serviço do Microsoft Entra a ser usada para implantar seu aplicativo na ação pós-compilação. Você pode atribuir entidades de serviço a funções em seu diretório para limitar as permissões do trabalho do Jenkins.

Para ambientes de desenvolvimento e teste, você pode configurar as credenciais do Azure ou o ponto de extremidade de gerenciamento do cluster para implantar seu aplicativo. Para obter detalhes sobre como configurar um ponto de extremidade de gerenciamento do cluster, confira Configurar a implantação usando o ponto de extremidade de gerenciamento do cluster.

  1. Para criar uma entidade de serviço do Microsoft Entra e atribuir-lhe permissões em sua assinatura do Azure, siga as etapas em Usar o portal para criar um aplicativo e uma entidade de serviço do Microsoft Entra. Preste atenção ao seguinte:

    • Ao seguir as etapas no tópico, não deixe de copiar e salvar os seguintes valores: ID do aplicativo, Chave de aplicativo, ID do diretório (ID do locatário) e ID da assinatura. Necessário para configurar as credenciais do Azure no Jenkins.
    • Se você não tiver as permissões necessárias em seu diretório, precisará pedir ao administrador para conceder as permissões ou criar a entidade de serviço, ou precisará configurar o ponto de extremidade de gerenciamento para o cluster nas Ações de Pós-Compilação relativo ao seu trabalho no Jenkins.
    • Na seção Criar um aplicativo do Microsoft Entra, você pode inserir qualquer URL bem formada para a URL de logon.
    • Na seção Atribuir aplicativo a uma Função, você pode atribuir ao aplicativo a função de Leitor no grupo de recursos para o cluster.

  2. De volta ao trabalho do Jenkins, clique na guia Ações de Pós-compilação.

  3. No menu suspenso Ações Pós-Compilação, selecione Implantar Projeto do Service Fabric.

  4. Em Configuração de Cluster do Service Fabric, clique em Selecionar o Cluster do Service Fabric. Clique em Adicionar lado das Credenciais do Azure. Clique em Jenkins para selecionar o provedor de credenciais do Jenkins.

  5. No provedor de credenciais do Jenkins, selecione Entidade de Serviço do Microsoft Azure no menu suspenso Tipo.

  6. Use os valores que você salvou ao definir a entidade de serviço na etapa 1 para definir os seguintes campos:

    • ID do cliente: ID do aplicativo
    • Segredo do cliente: chave do aplicativo
    • ID do locatário: ID do diretório
    • ID da assinatura: ID da assinatura

  7. Insira uma ID descritiva, que será usada para selecionar a credencial do Jenkins, e uma breve Descrição. Em seguida, clique em Verificar entidade de serviço. Se a verificação for bem-sucedida, clique em Adicionar.

    Jenkins do Service Fabric inserir credenciais do Azure

  8. De volta à opção Configuração de Cluster do Service Fabric, verifique se a nova credencial está selecionada em Credenciais do Azure.

  9. Na lista suspensa Grupo de Recursos, selecione o grupo de recursos do cluster em que você deseja implantar o aplicativo.

  10. Na lista suspensa Service Fabric, selecione o cluster em que você deseja implantar o aplicativo.

  11. Em Chave do Cliente e Certificado de Cliente, insira o local do arquivo PEM em seu contêiner do Jenkins. Por exemplo, /var/jenkins_home/clustercert.pem.

  12. Em Configuração de Aplicativo, configure os campos Nome do Aplicativo, Tipo de Aplicativo e Caminho para o Manifesto do Aplicativo (relativo). Ação de pós-build do Jenkins no Service Fabric – Configurar as credenciais do Azure

  13. Clique em Verificar Configuração. Quando a verificação tiver êxito, clique em Salvar. O pipeline de trabalho do Jenkins agora está totalmente configurado. Continue nas Próximas etapas a fim de testar a implantação.

Solução de problemas do plug-in do Jenkins

Se você encontrar bugs no plug-in do Jenkins, registre um problema no JIRA do Jenkins para o componente específico.

Ideias para experimentar

O GitHub e o Jenkins agora estão configurados. Considere fazer alguma alteração de exemplo no projeto reliable-services-actor-sample/Actors/ActorCounter na sua bifurcação do repositório, https://github.com/Azure-Samples/service-fabric-java-getting-started. Envie as alterações à ramificação master remota (ou a qualquer ramificação configurada para o trabalho) por push. Isso dispara o trabalho do Jenkins, MyJob, que você configurou. Ele busca as alterações do GitHub, compila-as e implanta o aplicativo no cluster especificado nas ações pós-compilação.

Próximas etapas

Jenkins no Azure