Tutorial: Implantar em um cluster do Service Fabric

  • Artigo

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

  1. Certifique-se de instalar 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 Jenkins para configurar o GitHub para acionar o Jenkins quando forem feitas alterações em seu aplicativo e para configurar seu pipeline de trabalho do Jenkins através da etapa de compilação para extrair as alterações do GitHub e construir seu aplicativo.
  4. Por fim, configure a etapa pós-compilação do trabalho Jenkins para implantar seu aplicativo no cluster do Service Fabric. Há duas maneiras de configurar o Jenkins para implantar seu aplicativo em um cluster:
    • Para ambientes de desenvolvimento e teste, use Configurar implantação usando o ponto de extremidade de gerenciamento de cluster. Esse método é o método de implantação mais simples de configurar.
    • Para ambientes de produção, use Configurar implantação usando credenciais do Azure. A Microsoft recomenda esse método para ambientes de produção porque com as credenciais do Azure você pode limitar o acesso que um trabalho Jenkins tem aos seus recursos do Azure.

Pré-requisitos

  • Verifique se o Git está instalado localmente. Você pode instalar a versão apropriada do Git na página de downloads do Git com base no seu sistema operacional. Se você é novo no Git, saiba mais sobre ele na documentação do Git.
  • Este artigo usa o Exemplo de Introdução do Service Fabric no GitHub: https://github.com/Azure-Samples/service-fabric-java-getting-started para que o aplicativo seja criado e implantado. Você pode bifurcar este repositório para acompanhar ou, com alguma modificação nas instruções, usar seu próprio projeto GitHub.

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

Se você estiver adicionando o plug-in do Service Fabric a um ambiente Jenkins existente, precisará executar as seguintes etapas:

  • CLI do Service Fabric (sfctl). Instale a CLI no nível do sistema em vez de no nível do usuário, para que Jenkins possa executar comandos da CLI.
  • Para implantar aplicativos Java, instale o Gradle e o Open JDK 8.0.
  • Para implantar aplicativos do .NET Core 2.0, instale o SDK do .NET Core 2.0.

Depois de instalar os pré-requisitos necessários para seu ambiente, você pode pesquisar o plug-in do Azure Service Fabric no mercado Jenkins e instalá-lo.

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

Configurar o Jenkins num cluster do Service Fabric

Pode configurar o Jenkins dentro ou fora de um cluster do Service Fabric. As seções a seguir mostram como configurá-lo dentro de um cluster ao usar uma conta de armazenamento do Azure para salvar o estado da instância do contêiner.

  1. Certifique-se de ter 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

    Nota

    Verifique se a porta 8081 está especificada como um ponto de extremidade personalizado no cluster. Se você estiver usando um cluster local, verifique se a porta 8081 está aberta na máquina host e se ela tem um endereço IP voltado para o 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. Persista o estado do contêiner Jenkins em um compartilhamento de arquivos:

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

    2. Crie um compartilhamento de arquivos na conta de armazenamento com um nome como sfjenkins.

    3. Clique em Connect para o compartilhamento de arquivos e observe os valores que ele exibe em Conectando do Linux, o valor deve ser semelhante ao abaixo:

      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

    Nota

    Para montar compartilhamentos cifs, você precisa ter o pacote cifs-utils instalado nos nós do cluster.

  4. Atualize os valores de espaço reservado setupentrypoint.sh no script com os detalhes do azure-storage na etapa 2.

    vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
    • Substitua [REMOTE_FILE_SHARE_LOCATION] pelo valor //sfjenkinsstorage1.file.core.windows.net/sfjenkins da saída da conexão na 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. Apenas cluster seguro:

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

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

    Além disso, adicione as seguintes linhas sob a marca ApplicationManifest (raiz) 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 de 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 obtém o certificado no formato PEM. Se o seu certificado estiver no formato PFX, você pode usar o seguinte comando 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

    Instala o contentor do Jenkins no cluster e pode ser monitorizado com o Service Fabric Explorer.

    Nota

    Pode levar alguns minutos para que a imagem do Jenkins seja baixada no cluster.

  7. A partir do browser, aceda a http://PublicIPorFQDN:8081. Fornece o caminho da palavra-passe de administrador inicial necessária para iniciar sessão.

  8. Observe o Service Fabric Explorer para determinar em qual nó o contêiner Jenkins está sendo executado. Inicie sessão no Secure Shell (SSH) neste nó.

    ssh user@PublicIPorFQDN -p [port]

  9. Obtenha o ID de instância do contentor com docker ps -a.

  10. Secure Shell (SSH) entre no contêiner e cole o caminho que lhe foi mostrado no portal Jenkins. Por exemplo, se no portal ele mostra 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 instalar, marque a caixa de seleção Nenhum e clique em instalar.

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

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

Configurar o Jenkins fora de um cluster do Service Fabric

Pode configurar o Jenkins dentro ou fora de um cluster do Service Fabric. As secções seguintes mostram como configurá-lo fora de um cluster.

  1. Certifique-se de que o Docker está instalado na sua máquina executando docker info no terminal. A saída indica se o serviço Docker está em execução.

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

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

  3. Extraia a imagem do contentor do Jenkins do Service Fabric: docker pull rapatchi/jenkins:latest. Esta imagem vem com o plug-in Jenkins do Service Fabric pré-instalado.

  4. Execute a imagem do contentor:docker run -itd -p 8080:8080 rapatchi/jenkins:latest

  5. Obtenha o ID da instância de imagem do contentor. Pode listar todos os contentores de Docker com o comando docker ps –a

  6. Entre no portal Jenkins com as seguintes etapas:

    1. Inicie sessão num shell Jenkins a partir do seu anfitrião. Use os primeiros quatro dígitos do ID do contêiner. Por exemplo, se o ID do contêiner for 2d24a73b5964, use 2d24.

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

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

      cat /var/jenkins_home/secrets/initialAdminPassword

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

    4. (Opcional.) Depois de iniciar sessão pela primeira vez, pode criar a sua própria conta de utilizador e utilizá-la para os passos seguintes ou pode continuar a utilizar a conta de administrador. Se você criar um usuário, precisará continuar com esse usuário.

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

    • Utilize as instruções fornecidas pelo GitHub para gerar a chave SSH e adicioná-la à conta GitHub que está a alojar o repositório.

    • Execute os comandos mencionados na ligação anterior na shell Docker do Jenkins (e não no seu anfitrião).

    • Para iniciar sessão na shell do Jenkins a partir do seu anfitrião, utilize o seguinte comando:

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

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

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

Criar e configurar uma tarefa do Jenkins

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

  1. No painel Jenkins, clique em Novo Item.

  2. Introduza um nome para o item (por exemplo, MyJob). Selecione free-style project (projeto de estilo livre) e clique em OK.

  3. A página Configuração do trabalho é aberta. (Para aceder à configuração a partir do painel Jenkins, clique no trabalho e, em seguida, clique em Configurar).

  4. Na guia Geral, marque a caixa para o projeto GitHub e especifique a URL do projeto GitHub. Este URL aloja a aplicação Java do Service Fabric que pretende integrar no fluxo de integração contínua do Jenkins e implementaçã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 o URL do repositório que aloja a aplicação Java do Service Fabric que quer integrar no 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 seu repositório GitHub para falar com Jenkins:

    1. Na página do repositório do 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. Introduza o URL do webhook do Jenkins (por predefinição, deve ser http://<PublicIPorFQDN>:8081/github-webhook/). Clique em add/update service (adicionar/atualizar serviço).

    4. É enviado um evento de teste para a instância do Jenkins. Deverá ver uma verificação a verde através do webhook do GitHub, e o seu projeto será compilado.

  7. Na guia Build Triggers no Jenkins, selecione qual opção de compilação você deseja. Neste exemplo, você deseja acionar uma compilação sempre que um push para o repositório acontecer, portanto, selecione gatilho de gancho do GitHub para sondagem GITScm. (Anteriormente, esta opção era denominada Build when a change is pushed to GitHub [Compilar quando é enviada uma alteração para o GitHub]).

  8. Na guia Build, siga um destes procedimentos, dependendo se você está criando um aplicativo Java ou um aplicativo .NET Core:

    • Para aplicações Java: Na lista suspensa Adicionar etapa de construção, selecione Invocar script Gradle. Clique em Advanced (Avançado). No menu avançado, especifique o caminho para o script de construção raiz para seu aplicativo. Este obtém o build.gradle a partir do caminho especificado e funciona em conformidade. Para o aplicativo ActorCounter, isso é: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.

      Ação de Compilação do Jenkins do Service Fabric

    • Para aplicativos .NET Core: na lista suspensa Adicionar etapa de compilação, selecione Executar Shell. Na caixa de comando exibida, o diretório primeiro precisa ser alterado para o caminho onde o build.sh arquivo está localizado. Uma vez que o diretório tenha sido alterado, o build.sh script pode ser executado para construir 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 de Serviço de Contador com um nome de trabalho 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, você precisa do local do certificado desse cluster em seu contêiner Jenkins. Escolha uma das seguintes opções, dependendo se o contêiner Jenkins está sendo executado dentro ou fora do cluster e anote o local do certificado de cluster:

    • Para Jenkins em execução dentro do 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 Jenkins em execução fora do cluster: Siga estas etapas para copiar o certificado de cluster para seu contêiner:

      1. O seu certificado deve estar em formato PEM. Se você não tiver um arquivo PEM, poderá criar um a partir do arquivo PFX do certificado. Se o seu ficheiro PFX não estiver protegido por palavra-passe, execute o seguinte comando a partir do seu anfitrião:

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

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

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

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

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

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

Você está quase terminado! Mantenha a vaga de Jenkins aberta. A única tarefa restante é configurar as etapas pós-compilação para implantar seu aplicativo no cluster do Service Fabric:

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

Para ambientes de desenvolvimento e teste, você pode usar o ponto de extremidade de gerenciamento de cluster para implantar seu aplicativo. Configurar a ação pós-compilação com o ponto de extremidade de gerenciamento de cluster para implantar seu aplicativo requer a menor quantidade de configuração. Se você estiver implantando em um ambiente de produção, pule 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 Jenkins, clique na guia Ações pós-compilação.

  2. No menu pendente Post-Build Actions (Ações de Pós-compilação), selecione Deploy Service Fabric Project (Implementar 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. Para Host de Gerenciamento, insira o ponto de extremidade de conexão para seu cluster, por exemplo {your-cluster}.eastus.cloudapp.azure.com.

  5. Para Client Key e Client Cert, insira o local do arquivo PEM em seu contêiner Jenkins, por exemplo /var/jenkins_home/clustercert.pem. (Você copiou o local do certificado na última etapa do Criar e configurar um trabalho Jenkins.)

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

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

  7. Clique em Verificar configuração. Na verificação bem-sucedida, clique em Salvar. Seu pipeline de trabalho Jenkins agora está totalmente configurado. Pule para as próximas etapas para testar sua implantação.

Configurar a implantação usando credenciais do Azure

Para ambientes de produção, é altamente recomendável configurar uma credencial do Azure para implantar seu aplicativo. Esta seção mostra como configurar uma entidade de serviço do Microsoft Entra para usar 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 Jenkins.

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

  1. Para criar uma entidade de serviço do Microsoft Entra e atribuir-lhe permissões na sua subscrição do Azure, siga os passos em Utilizar o portal para criar uma entidade de serviço e aplicação Microsoft Entra. Preste atenção ao seguinte:

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

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

  3. No menu pendente Post-Build Actions (Ações de Pós-compilação), selecione Deploy Service Fabric Project (Implementar Projeto do Service Fabric).

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

  5. No Provedor de Credenciais Jenkins, selecione Entidade de Serviço do Microsoft Azure na lista suspensa Tipo .

  6. Use os valores salvos ao configurar 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 você usa para selecionar a credencial no 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.

    O Service Fabric Jenkins insere credenciais do Azure

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

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

  10. Na lista suspensa do Service Fabric, selecione o cluster no qual você deseja implantar o aplicativo.

  11. Para Client Key e Client Cert, insira o local do arquivo PEM em seu contêiner Jenkins. Por exemplo, /var/jenkins_home/clustercert.pem.

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

  13. Clique em Verificar configuração. Na verificação bem-sucedida, clique em Salvar. Seu pipeline de trabalho Jenkins agora está totalmente configurado. Continue para Próximas etapas para testar sua implantação.

Solução de problemas do plug-in Jenkins

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

Ideias para experimentar

O GitHub e o Jenkins estão agora configurados. Considere fazer alguma alteração de exemplo no reliable-services-actor-sample/Actors/ActorCounter projeto em sua bifurcação do repositório, https://github.com/Azure-Samples/service-fabric-java-getting-started. Envie suas alterações para a ramificação remota master (ou qualquer ramificação com a qual você tenha configurado para trabalhar). Isto aciona a tarefa MyJob do Jenkins, que configurou. Ele busca as alterações do GitHub, as cria e implanta o aplicativo no cluster especificado em ações pós-compilação.

Próximos passos

Jenkins no Azure