Zelfstudie: Implementeren in een Service Fabric-cluster

In deze zelfstudie worden verschillende mogelijke manieren besproken om uw Jenkins-omgeving in te stellen, evenals verschillende manieren om uw toepassing te implementeren in een Service Fabric-cluster nadat deze is gebouwd. Volg deze algemene stappen om Jenkins te configureren, wijzigingen op te halen uit GitHub, uw toepassing te bouwen en te implementeren in uw cluster:

1. Zorg ervoor dat u de vereisten installeert.
2. Volg vervolgens de stappen in een van deze secties om Jenkins in te stellen:
   • Jenkins instellen in een Service Fabric-cluster,
   • Jenkins instellen buiten een Service Fabric-cluster of
   • Installeer de Service Fabric-invoegtoepassing in een bestaande Jenkins-omgeving.
3. Nadat u Jenkins hebt ingesteld, volgt u de stappen in Create and configure a Jenkins job to set up GitHub to set up GitHub to trigger Jenkins when changes to your application and to configure your Jenkins job pipeline through the build step to pull the changes from GitHub and build your application.
4. Ten slotte configureert u de Jenkins-taak na de build-stap om uw toepassing te implementeren in uw Service Fabric-cluster. Er zijn twee manieren om Jenkins te configureren voor het implementeren van uw toepassing in een cluster:
   • Voor ontwikkel- en testomgevingen gebruikt u Implementatie configureren met behulp van clusterbeheereindpunt. Deze methode is de eenvoudigste implementatiemethode die moet worden ingesteld.
   • Voor productieomgevingen gebruikt u Implementatie configureren met behulp van Azure-referenties. Microsoft raadt deze methode aan voor productieomgevingen, omdat u met Azure-referenties de toegang kunt beperken die een Jenkins-taak heeft tot uw Azure-resources.

Vereisten

• Zorg ervoor dat Git lokaal is geïnstalleerd. U kunt de juiste Git-versie installeren vanaf de git-downloadpagina op basis van uw besturingssysteem. Als u nog niet eerder met Git werkt, vindt u hier meer informatie over in de Git-documentatie.
• In dit artikel wordt het Voorbeeld aan de slag met Service Fabric op GitHub gebruikt: https://github.com/Azure-Samples/service-fabric-java-getting-started voor het bouwen en implementeren van de toepassing. U kunt deze opslagplaats splitsen om mee te volgen, of gebruik uw eigen GitHub-project met een wijziging in de instructies.

De Service Fabric-invoegtoepassing installeren in een bestaande Jenkins-omgeving

Als u de Service Fabric-invoegtoepassing toevoegt aan een bestaande Jenkins-omgeving, moet u de volgende stappen uitvoeren:

• Service Fabric CLI (sfctl). Installeer de CLI op systeemniveau in plaats van op gebruikersniveau, zodat Jenkins CLI-opdrachten kan uitvoeren.
• Als u Java-toepassingen wilt implementeren, installeert u zowel Gradle als Open JDK 8.0.
• Als u .NET Core 2.0-toepassingen wilt implementeren, installeert u de .NET Core 2.0 SDK.

Nadat u de vereiste vereisten voor uw omgeving hebt geïnstalleerd, kunt u zoeken naar de Azure Service Fabric-invoegtoepassing in Jenkins Marketplace en deze installeren.

Nadat u de invoegtoepassing hebt geïnstalleerd, gaat u verder met het maken en configureren van een Jenkins-taak.

Jenkins instellen in een Service Fabric-cluster

U kunt Jenkins instellen binnen of buiten een Service Fabric-cluster. In de volgende secties ziet u hoe u deze instelt in een cluster terwijl u een Azure-opslagaccount gebruikt om de status van het containerexemplaren op te slaan.

1. Zorg ervoor dat u een Service Fabric Linux-cluster hebt waarop Docker is geïnstalleerd. Service Fabric-clusters die worden uitgevoerd in Azure, hebben Docker al geïnstalleerd. Als u het cluster lokaal uitvoert (OneBox-ontwikkelomgeving), controleert u of Docker is geïnstalleerd op uw computer met de docker info opdracht. Als deze niet is geïnstalleerd, installeert u deze met behulp van de volgende opdrachten:

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

   Notitie

   Zorg ervoor dat de 8081-poort is opgegeven als een aangepast eindpunt op het cluster. Als u een lokaal cluster gebruikt, moet u ervoor zorgen dat poort 8081 is geopend op de hostcomputer en dat deze een openbaar IP-adres heeft.

2. Kloon de toepassing met behulp van de volgende opdrachten:

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

3. De status van de Jenkins-container behouden in een bestandsshare:

   1. Maak een Azure-opslagaccount in dezelfde regio als uw cluster met een naam, zoals sfjenkinsstorage1.

   2. Maak een bestandsshare onder het opslagaccount met een naam zoals sfjenkins.

   3. Klik op Verbinding maken voor de bestandsshare en noteer de waarden die worden weergegeven onder Verbinding maken van Linux. De waarde moet er ongeveer als volgt uitzien:

      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
      

   Notitie

   Als u cifs-shares wilt koppelen, moet het cifs-utils-pakket zijn geïnstalleerd in de clusterknooppunten.

4. Werk de waarden van de tijdelijke aanduidingen in het setupentrypoint.sh script bij met de azure-storage-gegevens uit stap 2.

   vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
   

   • Vervang [REMOTE_FILE_SHARE_LOCATION] door de waarde //sfjenkinsstorage1.file.core.windows.net/sfjenkins uit de uitvoer van de verbinding in stap 2 hierboven.
   • Vervang [FILE_SHARE_CONNECT_OPTIONS_STRING] door de waarde vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 uit stap 2 hierboven.

5. Alleen beveiligd cluster:

   Als u de implementatie van toepassingen op een beveiligd cluster vanuit Jenkins wilt configureren, moet het clustercertificaat toegankelijk zijn binnen de Jenkins-container. Voeg in het ApplicationManifest.xml-bestand onder de tag ContainerHostPolicies deze certificaatreferentie toe en werk de vingerafdrukwaarde bij met die van het clustercertificaat.

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

   Voeg bovendien de volgende regels toe onder de tag ApplicationManifest (root) in het ApplicationManifest.xml-bestand en werk de vingerafdrukwaarde bij met die van het clustercertificaat.

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

6. Verbinding maken naar het cluster en installeer de containertoepassing.

   Beveiligd cluster

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

   Met de voorgaande opdracht wordt het certificaat in PEM-indeling gebruikt. Als uw certificaat de PFX-indeling heeft, kunt u de volgende opdracht gebruiken om het te converteren. Als uw PFX-bestand niet met een wachtwoord is beveiligd, geeft u de wachtwoordparameter op als -passin pass:.

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

   Onbeveiligd cluster

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

   Hiermee wordt een Jenkins-container in het cluster geïnstalleerd. Dit kan worden bewaakt met de Service Fabric Explorer.

   Notitie

   Het kan enkele minuten duren voordat de Jenkins-installatiekopieën op het cluster zijn gedownload.

7. Ga in uw browser naar http://PublicIPorFQDN:8081. Hier vindt u het pad naar het eerste beheerderswachtwoord dat nodig is om u aan te melden.

8. Bekijk Service Fabric Explorer om te bepalen op welk knooppunt de Jenkins-container wordt uitgevoerd. Meld u aan bij dit knooppunt met Secure Shell (SSH).

   ssh user@PublicIPorFQDN -p [port]
   

9. Haal de exemplaar-id van de container op met docker ps -a.

10. Meld u met Secure Shell (SSH) aan bij de container en plak het pad dat u hebt weergegeven in de Jenkins-portal. Als in de portal bijvoorbeeld het pad PATH_TO_INITIAL_ADMIN_PASSWORDwordt weergegeven, voert u de volgende opdrachten uit:

    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. Kies op de pagina Aan de slag met Jenkins de optie Invoegtoepassing selecteren om te installeren, schakel het selectievakje Geen in en klik op Installeren.

12. Maak een gebruiker of selecteer deze om door te gaan als beheerder.

Nadat u Jenkins hebt ingesteld, gaat u verder met het maken en configureren van een Jenkins-taak.

Jenkins instellen buiten een Service Fabric-cluster

U kunt Jenkins instellen binnen of buiten een Service Fabric-cluster. In de volgende secties ziet u hoe u Jenkins instelt buiten een cluster.

1. Zorg ervoor dat Docker op uw computer is geïnstalleerd door deze uit te voeren docker info in de terminal. De uitvoer geeft aan of de Docker-service wordt uitgevoerd.

2. Als Docker niet is geïnstalleerd, voert u de volgende opdrachten uit:

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

3. Haal de Service Fabric Jenkins container-installatiekopie op: docker pull rapatchi/jenkins:latest. Deze installatiekopieën worden geleverd met de Jenkins-invoegtoepassing van Service Fabric die vooraf is geïnstalleerd.

4. Voer de installatiekopie van de container uit: docker run -itd -p 8080:8080 rapatchi/jenkins:latest

5. Haal de id op van het exemplaar van de installatiekopie van de container. U kunt een lijst van alle Docker-containers bekijken met de opdracht docker ps –a

6. Meld u aan bij de Jenkins-portal met de volgende stappen:

   1. Meld u aan bij een Jenkins-shell vanaf uw host. Gebruik de eerste vier cijfers van de container-id. Als de container-id bijvoorbeeld is 2d24a73b5964, gebruikt u 2d24.

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

   2. Haal vanuit de Jenkins-shell het beheerderswachtwoord voor uw containerinstantie op:

      cat /var/jenkins_home/secrets/initialAdminPassword
      

   3. Als u zich wilt aanmelden bij het Jenkins-dashboard, opent u de volgende URL in een webbrowser: http://<HOST-IP>:8080 Gebruik het wachtwoord uit de vorige stap om Jenkins te ontgrendelen.

   4. (Optioneel.) Nadat u zich voor de eerste keer hebt aangemeld, kunt u uw eigen gebruikersaccount maken en dat gebruiken voor de volgende stappen, of u kunt het beheerdersaccount blijven gebruiken. Als u een gebruiker maakt, moet u doorgaan met die gebruiker.

7. Stel GitHub in om met Jenkins te werken met behulp van de stappen in Het genereren van een nieuwe SSH-sleutel en het toevoegen aan de SSH-agent.

   • Volg de instructies van GitHub om de SSH-sleutel te genereren en deze toe te voegen aan het GitHub-account waarop de opslagplaats wordt gehost.

   • Voer de opdrachten die in de vorige koppeling zijn genoemd, uit in de Jenkins Docker-shell (en niet op uw host).

   • Gebruik de volgende opdracht om u vanaf uw host aan te melden bij de Jenkins-shell:

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

Zorg ervoor dat het cluster of de computer waarop de Jenkins-containerinstallatiekopie wordt gehost, een openbaar IP-adres heeft. Alleen zo kan het Jenkins-exemplaar meldingen ontvangen van GitHub.

Nadat u Jenkins hebt ingesteld, gaat u verder met de volgende sectie, maakt en configureert u een Jenkins-taak.

Een Jenkins-taak maken en configureren

De stappen in deze sectie laten zien hoe u een Jenkins-taak configureert om te reageren op wijzigingen in een GitHub-opslagplaats, de wijzigingen op te halen en deze te bouwen. Aan het einde van deze sectie wordt u omgeleid naar de laatste stappen om de taak te configureren om uw toepassing te implementeren op basis van of u implementeert in een ontwikkel-/testomgeving of in een productieomgeving.

1. Klik op het Jenkins-dashboard op Nieuw item.

2. Voer een itemnaam in (bijvoorbeeld MyJob). Selecteer free-style project en klik op OK.

3. De pagina Taakconfiguratie wordt geopend. (Als u de configuratie van het Jenkins-dashboard wilt openen, klikt u op de taak en klikt u vervolgens op Configureren).

4. Schakel op het tabblad Algemeen het selectievakje voor het GitHub-project in en geef de URL van uw GitHub-project op. Dit is de URL waarop de Service Fabric Java-toepassing wordt gehost die u wilt integreren met de CI-/CD-stroom van Jenkins (Continue integratie, Continue implementatie), bijvoorbeeld https://github.com/{your-github-account}/service-fabric-java-getting-started.

5. Selecteer Git op het tabblad Broncodebeheer. Geef de opslagplaats-URL op waarop de Service Fabric Java-toepassing wordt gehost die u wilt integreren met de CI-/CD-stroom van Jenkins, (bijvoorbeeld https://github.com/{your-github-account}/service-fabric-java-getting-started). U kunt ook opgeven welke vertakking moet worden gebouwd (bijvoorbeeld /master).

6. Configureer uw GitHub-opslagplaats om te communiceren met Jenkins:

   1. Ga op de pagina van uw GitHub-opslagplaats naar Instellingen> Integrations and Services.

   2. Selecteer Service toevoegen, typ Jenkins en selecteer de Jenkins-GitHub-invoegtoepassing.

   3. Geef de Jenkins-webhook-URL op (standaard is dit http://<PublicIPorFQDN>:8081/github-webhook/). Klik op add/update service.

   4. Er wordt een testgebeurtenis verzonden naar uw Jenkins-exemplaar. Er komt een groen vinkje bij de webhook te staan in GitHub en uw project wordt gemaakt.

7. Selecteer op het tabblad Build Triggers in Jenkins de gewenste build-optie. In dit voorbeeld wilt u een build activeren wanneer er een push naar de opslagplaats plaatsvindt, dus selecteer gitHub-hooktrigger voor GITScm-polling. (Voorheen heette deze optie Build when a change is pushed to GitHub.)

8. Voer op het tabblad Bouwen een van de volgende handelingen uit, afhankelijk van of u een Java-toepassing of een .NET Core-toepassing bouwt:

   • Voor Java-toepassingen: Selecteer Gradle Script aanroepen in de vervolgkeuzelijst Build-stap toevoegen. Klik op Geavanceerd. Geef in het geavanceerde menu het pad op naar het hoofdscript voor uw toepassing. Het haalt build.gradle op uit het opgegeven pad en werkt dienovereenkomstig. Voor de ActorCounter-toepassing is dit: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.

     

   • Voor .NET Core-toepassingen: selecteer In de vervolgkeuzelijst Build-stap toevoegen de optie Shell uitvoeren. In het opdrachtvak dat wordt weergegeven, moet de map eerst worden gewijzigd in het pad waar het build.sh bestand zich bevindt. Zodra de map is gewijzigd, kan het build.sh script worden uitgevoerd om de toepassing te bouwen.

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

     In de volgende schermopname ziet u een voorbeeld van de opdrachten die worden gebruikt om het voorbeeld van de tellerservice te bouwen met een Jenkins-taaknaam van CounterServiceApplication.

     

9. Als u Jenkins wilt configureren voor het implementeren van uw app in een Service Fabric-cluster in de post-buildacties, hebt u de locatie van het certificaat van dat cluster in uw Jenkins-container nodig. Kies een van de volgende opties, afhankelijk van of uw Jenkins-container binnen of buiten het cluster wordt uitgevoerd en noteer de locatie van het clustercertificaat:

   • Voor Jenkins die in uw cluster wordt uitgevoerd: het pad naar het certificaat vindt u door de waarde van de omgevingsvariabele Certificates_JenkinsOnSF_Code_MyCert_PEM vanuit de container te echoën.

     echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
     

   • Voor Jenkins die buiten uw cluster wordt uitgevoerd: volg deze stappen om het clustercertificaat naar uw container te kopiëren:

     1. Uw certificaat moet de PEM-indeling hebben. Als u geen PEM-bestand hebt, kunt u er een maken op basis van het PFX-certificaatbestand. Als uw PFX-bestand niet met een wachtwoord is beveiligd, voert u de volgende opdracht uit vanaf uw host:

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

        Als het PFX-bestand met een wachtwoord is beveiligd, neemt u het wachtwoord op in de -passin parameter. Voorbeeld:

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

     2. Als u de container-id voor uw Jenkins-container wilt ophalen, voert u deze uit docker ps vanaf uw host.

     3. Kopieer het PEM-bestand naar uw container met de volgende Docker-opdracht:

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

Je bent bijna klaar! Houd de Jenkins-taak open. De enige resterende taak is het configureren van de stappen na de build om uw toepassing te implementeren in uw Service Fabric-cluster:

• Als u wilt implementeren in een ontwikkel- of testomgeving, volgt u de stappen in Implementatie configureren met behulp van het eindpunt voor clusterbeheer.
• Als u wilt implementeren in een productieomgeving, volgt u de stappen in Implementatie configureren met behulp van Azure-referenties.

Implementatie configureren met clusterbeheereindpunt

Voor ontwikkel- en testomgevingen kunt u het eindpunt voor clusterbeheer gebruiken om uw toepassing te implementeren. Voor het configureren van de actie na de build met het eindpunt voor clusterbeheer om uw toepassing te implementeren, is de minste hoeveelheid installatie vereist. Als u implementeert in een productieomgeving, gaat u verder met het configureren van implementatie met behulp van Azure-referenties om een Microsoft Entra-service-principal te configureren die tijdens de implementatie moet worden gebruikt.

1. Klik in de Jenkins-taak op het tabblad Acties na maken.

2. Selecteer in de vervolgkeuzelijst Post-Build Actions de optie Post-Build Actions.

3. Selecteer onder Service Fabric-clusterconfiguratie het keuzerondje Service Fabric-beheereindpunt invullen.

4. Voer voor beheerhost het verbindingseindpunt voor uw cluster in, bijvoorbeeld{your-cluster}.eastus.cloudapp.azure.com.

5. Voer voor clientsleutel en clientcertificaat de locatie van het PEM-bestand in uw Jenkins-container in, bijvoorbeeld/var/jenkins_home/clustercert.pem. (U hebt de locatie van het certificaat gekopieerd in de laatste stap van Een Jenkins-taak maken en configureren.)

6. Configureer onder Toepassingsconfiguratie de toepassingsnaam, het toepassingstype en het (relatieve) pad naar de velden Toepassingsmanifest.

   

7. Klik op Configuratie controleren. Als de verificatie is geslaagd, klikt u op Opslaan. Uw Jenkins-taakpijplijn is nu volledig geconfigureerd. Ga verder met volgende stappen om uw implementatie te testen.

Implementatie configureren met behulp van Azure-referenties

Voor productieomgevingen wordt het configureren van een Azure-referentie voor het implementeren van uw toepassing sterk aanbevolen. In deze sectie wordt beschreven hoe u een Microsoft Entra-service-principal configureert voor het implementeren van uw toepassing in de actie na het bouwen. U kunt service-principals toewijzen aan rollen in uw directory om de machtigingen van de Jenkins-taak te beperken.

Voor ontwikkel- en testomgevingen kunt u Azure-referenties of het eindpunt voor clusterbeheer configureren om uw toepassing te implementeren. Zie Implementatie configureren met behulp van clusterbeheereindpunt voor meer informatie over het configureren van een eindpunt voor clusterbeheer.

1. Als u een Microsoft Entra-service-principal wilt maken en deze machtigingen wilt toewijzen in uw Azure-abonnement, volgt u de stappen in De portal gebruiken om een Microsoft Entra-toepassing en service-principal te maken. Let op het volgende:

   • Terwijl u de stappen in het onderwerp volgt, moet u de volgende waarden kopiëren en opslaan: toepassings-id, toepassingssleutel, map-id (tenant-id) en abonnements-id. U hebt ze nodig om de Azure-referenties in Jenkins te configureren.
   • Als u niet over de vereiste machtigingen voor uw directory beschikt, moet u een beheerder vragen om u de machtigingen te verlenen of de service-principal voor u te maken, of moet u het beheereindpunt voor uw cluster configureren in de acties na de build voor uw taak in Jenkins.
   • In de sectie Een Microsoft Entra-toepassing maken kunt u elke goed opgemaakte URL invoeren voor de aanmeldings-URL.
   • In de sectie Toewijzen aan een rol kunt u uw toepassing de rol Lezer toewijzen aan de resourcegroep voor uw cluster.

2. Klik in de Jenkins-taak op het tabblad Acties na de build.

3. Selecteer in de vervolgkeuzelijst Post-Build Actions de optie Post-Build Actions.

4. Klik onder Service Fabric-clusterconfiguratie op Het Service Fabric-cluster selecteren. Klik op Toevoegen naast Azure-referenties. Klik op Jenkins om de Jenkins-referentieprovider te selecteren.

5. Selecteer in de Jenkins Credentials Provider microsoft Azure-service-principal in de vervolgkeuzelijst Soort .

6. Gebruik de waarden die u hebt opgeslagen bij het instellen van uw service-principal in stap 1 om de volgende velden in te stellen:

   • Client-id: toepassings-id
   • Clientgeheim: toepassingssleutel
   • Tenant-id: Map-id
   • Abonnements-id: Abonnements-id

7. Voer een beschrijvende id in die u gebruikt om de referentie in Jenkins en een korte beschrijving te selecteren. Klik vervolgens op Service-principal controleren. Als de verificatie is geslaagd, klikt u op Toevoegen.

   

8. Controleer onder Service Fabric-clusterconfiguratie of uw nieuwe referentie is geselecteerd voor Azure-referenties.

9. Selecteer in de vervolgkeuzelijst Resourcegroep de resourcegroep van het cluster waarnaar u de toepassing wilt implementeren.

10. Selecteer in de vervolgkeuzelijst Service Fabric het cluster waarnaar u de toepassing wilt implementeren.

11. Voer voor clientsleutel en clientcertificaat de locatie van het PEM-bestand in uw Jenkins-container in. Bijvoorbeeld /var/jenkins_home/clustercert.pem.

12. Configureer onder Toepassingsconfiguratie de toepassingsnaam, het toepassingstype en het (relatieve) pad naar de velden Toepassingsmanifest.

13. Klik op Configuratie controleren. Als de verificatie is geslaagd, klikt u op Opslaan. Uw Jenkins-taakpijplijn is nu volledig geconfigureerd. Ga door naar Volgende stappen om uw implementatie te testen.

Problemen met de Jenkins-invoegtoepassing oplossen

Als er fouten optreden met de Jenkins-invoegtoepassing, kunt u een probleem indienen in de Jenkins JIRA voor het specifieke onderdeel.

Ideeën om te proberen

GitHub en Jenkins zijn nu geconfigureerd. Overweeg een voorbeeldwijziging aan te brengen in het reliable-services-actor-sample/Actors/ActorCounter project in uw fork van de opslagplaats. https://github.com/Azure-Samples/service-fabric-java-getting-started Push uw wijzigingen naar de externe master vertakking (of een vertakking waarmee u hebt geconfigureerd om mee te werken). Op die manier wordt de geconfigureerde Jenkins-taak MyJob geactiveerd. De wijzigingen worden opgehaald uit GitHub, worden gebouwd en de toepassing geïmplementeerd in het cluster dat u hebt opgegeven in acties na de build.

Volgende stappen

Jenkins op Azure