Självstudie: Distribuera till ett Service Fabric-kluster

Artikel
06/08/2023

Den här självstudien beskriver flera möjliga sätt att konfigurera Jenkins-miljön och olika sätt att distribuera programmet till ett Service Fabric-kluster när det har skapats. Följ dessa allmänna steg för att konfigurera Jenkins, hämta ändringar från GitHub, skapa ditt program och distribuera det till klustret:

Se till att du installerar kraven.
Följ sedan stegen i något av de här avsnitten för att konfigurera Jenkins:
När du har konfigurerat Jenkins följer du stegen i Skapa och konfigurera ett Jenkins-jobb för att konfigurera GitHub för att utlösa Jenkins när ändringar görs i ditt program och för att konfigurera jenkins-jobbpipelinen genom byggsteget för att hämta ändringarna från GitHub och skapa ditt program.
Konfigurera slutligen Jenkins-jobbet efter kompileringssteget för att distribuera ditt program till Service Fabric-klustret. Det finns två sätt att konfigurera Jenkins för att distribuera ditt program till ett kluster:
- För utvecklings- och testmiljöer använder du Konfigurera distribution med klusterhanteringsslutpunkt. Den här metoden är den enklaste distributionsmetoden att konfigurera.
- För produktionsmiljöer använder du Konfigurera distribution med azure-autentiseringsuppgifter. Microsoft rekommenderar den här metoden för produktionsmiljöer eftersom du med Azure-autentiseringsuppgifter kan begränsa åtkomsten som ett Jenkins-jobb har till dina Azure-resurser.

Förutsättningar

Kontrollera att Git är installerat lokalt. Du kan installera lämplig Git-version från sidan Med Git-nedladdningar baserat på ditt operativsystem. Om du inte har använt Git tidigare kan du läsa mer om det i Git-dokumentationen.
Den här artikeln använder Service Fabric Getting Started-exemplet på GitHub: https://github.com/Azure-Samples/service-fabric-java-getting-started för att programmet ska kunna skapa och distribuera. Du kan förgrena den här lagringsplatsen för att följa med, eller, med vissa ändringar i instruktionerna, använda ditt eget GitHub-projekt.

Installera Service Fabric-plugin-programmet i en befintlig Jenkins-miljö

Om du lägger till Service Fabric-plugin-programmet i en befintlig Jenkins-miljö måste du göra följande:

Service Fabric CLI (sfctl). Installera CLI på systemnivå i stället för på användarnivå, så att Jenkins kan köra CLI-kommandon.
Om du vill distribuera Java-program installerar du både Gradle och Open JDK 8.0.
Om du vill distribuera .NET Core 2.0-program installerar du .NET Core 2.0 SDK.

När du har installerat de krav som krävs för din miljö kan du söka efter Azure Service Fabric-plugin-programmet på Jenkins Marketplace och installera det.

När du har installerat plugin-programmet går du vidare till Skapa och konfigurera ett Jenkins-jobb.

Konfigurera Jenkins i ett Service Fabric-kluster

Du kan konfigurera Jenkins i eller utanför ett Service Fabric-kluster. Följande avsnitt visar hur du konfigurerar det i ett kluster när du använder ett Azure-lagringskonto för att spara containerinstansens tillstånd.

Kontrollera att du har ett Service Fabric Linux-kluster med Docker installerat. Service Fabric-kluster som körs i Azure har redan Docker installerat. Om du kör klustret lokalt (OneBox-utvecklingsmiljö) kontrollerar du om Docker är installerat på datorn med docker info kommandot . Om den inte är installerad installerar du den med hjälp av följande kommandon:
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Kommentar

Kontrollera att 8081-porten har angetts som en anpassad slutpunkt i klustret. Om du använder ett lokalt kluster kontrollerar du att port 8081 är öppen på värddatorn och att den har en offentlig IP-adress.

Klona programmet med hjälp av följande kommandon:

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

Spara tillståndet för Jenkins-containern i en filresurs:
1. Skapa ett Azure Storage-konto i samma region som klustret med ett namn som sfjenkinsstorage1.
2. Skapa en filresurs under lagringskontot med ett namn som sfjenkins.
3. Klicka på Anslut för filresursen och notera de värden som visas under Anslut från Linux bör värdet se ut ungefär som det nedan:
```
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
```
Kommentar

Om du vill montera cifs-resurser måste du ha cifs-utils-paketet installerat i klusternoderna.
Uppdatera platshållarvärdena i skriptet setupentrypoint.sh med azure-storage-informationen från steg 2.
```
vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
```
- Ersätt [REMOTE_FILE_SHARE_LOCATION] med värdet //sfjenkinsstorage1.file.core.windows.net/sfjenkins från utdata från anslutningen i steg 2 ovan.
- Ersätt [FILE_SHARE_CONNECT_OPTIONS_STRING] med värdet vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 från steg 2 ovan.
Endast säkert kluster:

För att konfigurera distributionen av program på ett säkert kluster från Jenkins måste klustercertifikatet vara tillgängligt i Jenkins-containern. I filen ApplicationManifest.xml lägger du till certifikatreferensen under taggen ContainerHostPolicies och uppdaterar tumavtrycksvärdet med klustercertifikatets värde.
```
<CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>
```
Lägg dessutom till följande rader under taggen ApplicationManifest (rot) i filen ApplicationManifest.xml och uppdatera tumavtrycksvärdet med värdet för klustercertifikatet.
```
<Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates> 
```
Anslut till klustret och installera containerprogrammet.

Skyddat kluster
```
sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh
```
Föregående kommando tar certifikatet i PEM-format. Om certifikatet är i PFX-format kan du använda följande kommando för att konvertera det. Om PFX-filen inte är lösenordsskyddad anger du parametern passin som -passin pass:.
```
openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>
```
Osäkert kluster
```
sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh
```
Detta installerar en Jenkins-container på klustret och kan övervakas med Service Fabric Explorer.

Kommentar

Det kan ta några minuter innan Jenkins-avbildningen laddas ned i klustret.
Gå till http://PublicIPorFQDN:8081 i webbläsaren. På sidan visas sökvägen till det ursprungliga administratörslösenordet som krävs för att logga in.
Titta på Service Fabric Explorer för att avgöra på vilken nod Jenkins-containern körs. Secure Shell (SSH) loggar in på den här noden.
```
ssh user@PublicIPorFQDN -p [port]
```
Hämta containerns instans-ID med docker ps -a.
Secure Shell (SSH) loggar in på containern och klistrar in sökvägen som du visades på Jenkins-portalen. Om den till exempel visar sökvägen PATH_TO_INITIAL_ADMIN_PASSWORDi portalen kör du följande kommandon:
```
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
```
På sidan Komma igång med Jenkins väljer du alternativet Välj plugin-program för att installera, markerar kryssrutan Ingen och klickar på Installera.
Skapa en användare eller välj för att fortsätta som administratör.

När du har konfigurerat Jenkins går du vidare till Skapa och konfigurera ett Jenkins-jobb.

Konfigurera Jenkins utanför ett Service Fabric-kluster

Du kan konfigurera Jenkins i eller utanför ett Service Fabric-kluster. I följande avsnitt visas hur du konfigurerar Jenkins utanför ett kluster.

Kontrollera att Docker är installerat på datorn genom att köra docker info i terminalen. Utdata anger om Docker-tjänsten körs.

Om Docker inte är installerat kör du följande kommandon:

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

Hämta containeravbildningen för Service Fabric Jenkins:docker pull rapatchi/jenkins:latest. Den här avbildningen levereras med Service Fabric Jenkins-plugin-programmet förinstallerat.
Kör containeravbildningen: docker run -itd -p 8080:8080 rapatchi/jenkins:latest
Hämta ID:t för containeravbildningsinstansen. Du kan visa en lista med alla Docker-containrar med hjälp av kommandot docker ps –a
Logga in på Jenkins-portalen med följande steg:
1. Logga in på ett Jenkins-gränssnitt från värden. Använd de första fyra siffrorna i container-ID:t. Om container-ID:t till exempel är 2d24a73b5964använder du 2d24.
```
docker exec -it [first-four-digits-of-container-ID] /bin/bash
```
2. Hämta administratörslösenordet för containerinstansen från Jenkins-gränssnittet:
```
cat /var/jenkins_home/secrets/initialAdminPassword
```
3. Om du vill logga in på Jenkins-instrumentpanelen öppnar du följande URL i en webbläsare: http://<HOST-IP>:8080. Använd lösenordet från föregående steg för att låsa upp Jenkins.
4. (Valfritt.) När du har loggat in för första gången kan du skapa ett eget användarkonto och använda det för följande steg, eller så kan du fortsätta att använda administratörskontot. Om du skapar en användare måste du fortsätta med den användaren.
Konfigurera GitHub så att det fungerar med Jenkins genom att följa stegen i Generera en ny SSH-nyckel och lägga till den i SSH-agenten.
- Följ instruktionerna från GitHub för att skapa SSH-nyckeln och lägga till SSH-nyckeln på det GitHub-konto som är (blir) värd för databasen.
- Kör de kommandon som nämns i länken ovan i Jenkins Docker-gränssnittet (och inte på värden).
- Om du vill logga in till Jenkins-gränssnittet från värden ska du använda följande kommando:
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash
```

Kontrollera att klustret eller datorn där Jenkins-containeravbildningen finns har en offentlig IP-adress. Detta gör att Jenkins-instansen kan ta emot meddelanden från GitHub.

När du har konfigurerat Jenkins fortsätter du till nästa avsnitt, Skapa och konfigurera ett Jenkins-jobb.

Skapa och konfigurera ett Jenkins-jobb

Stegen i det här avsnittet visar hur du konfigurerar ett Jenkins-jobb för att svara på ändringar i en GitHub-lagringsplats, hämta ändringarna och skapa dem. I slutet av det här avsnittet dirigeras du till de sista stegen för att konfigurera jobbet för att distribuera ditt program baserat på om du distribuerar till en utvecklings-/testmiljö eller till en produktionsmiljö.

Klicka på Nytt objekt på Jenkins-instrumentpanelen.
Ange ett namn (till exempel MyJob). Välj free-style project (freestyle-projekt) och klicka på OK.
Sidan Jobbkonfiguration öppnas. (Om du vill komma till konfigurationen från Jenkins-instrumentpanelen klickar du på jobbet och klickar sedan på Konfigurera).
På fliken Allmänt markerar du kryssrutan för GitHub-projektet och anger din GitHub-projekt-URL. Den här URL:en är värd för det Service Fabric Java-program som du vill integrera med Jenkins CI/CD-flödet (t.ex. https://github.com/{your-github-account}/service-fabric-java-getting-started).
På fliken Hantering av källkod väljer du Git. Ange URL för databasen som är värd för det Service Fabric Java-program som du vill integrera med Jenkins CI/CD-flödet (t.ex. https://github.com/{your-github-account}/service-fabric-java-getting-started). Du kan också ange vilken gren som ska skapas (till exempel /master).
Konfigurera din GitHub-lagringsplats så att den kommunicerar med Jenkins:
1. På din GitHub-lagringsplats går du till Inställningar> Integrationer och tjänster.
2. Välj Lägg till tjänst, skriv Jenkins och välj plugin-programmet Jenkins-GitHub.
3. Ange din Jenkins-webhooksadress (som standard ska den vara http://<PublicIPorFQDN>:8081/github-webhook/). Klicka på Lägg till/Uppdatera tjänsten.
4. En testhändelse skickas till Jenkins-instansen. Du bör se en grön bock vid webhooken i GitHub och projektet skapas.
På fliken Build Triggers (Skapa utlösare) i Jenkins väljer du vilket byggalternativ du vill använda. I det här exemplet vill du utlösa en version när en push-överföring till lagringsplatsen sker, så välj GitHub-hookutlösare för GITScm-avsökning. (Tidigare hette det här alternativet Build when a change is pushed to GitHub) (Bygg när en ändring skickas till GitHub).
På fliken Skapa gör du något av följande beroende på om du skapar ett Java-program eller ett .NET Core-program:
- För Java-program: I listrutan Lägg till byggsteg väljer du Anropa Gradle-skript. Klicka på Avancerad. I den avancerade menyn anger du sökvägen till rotversionsskriptet för ditt program. Då hämtas build.gradle från den angivna sökvägen och fungerar på motsvarande sätt. För ActorCounter-programmet är detta: ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.
- För .NET Core-program: I listrutan Lägg till byggsteg väljer du Kör gränssnitt. I kommandorutan som visas måste katalogen först ändras till sökvägen där build.sh filen finns. När katalogen har ändrats kan skriptet build.sh köras för att skapa programmet.
```
cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh
```
  Följande skärmbild visar ett exempel på de kommandon som används för att skapa counter service-exemplet med jenkins-jobbnamnet CounterServiceApplication.
För att konfigurera Jenkins för att distribuera din app till ett Service Fabric-kluster i åtgärderna efter bygget behöver du platsen för klustrets certifikat i Jenkins-containern. Välj något av följande beroende på om Jenkins-containern körs i eller utanför klustret och notera platsen för klustercertifikatet:
- För Jenkins som körs i klustret: Sökvägen till certifikatet kan hittas genom att upprepa värdet för Certificates_JenkinsOnSF_Code_MyCert_PEM miljövariabeln inifrån containern.
```
echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
```
- För Jenkins som körs utanför klustret: Följ dessa steg för att kopiera klustercertifikatet till containern:
  1. Certifikatet måste vara i PEM-format. Om du inte har någon PEM-fil kan du skapa en från PFX-certifikatfilen. Om PFX-filen inte är lösenordsskyddad kör du följande kommando från värden:
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:
```
    Om PFX-filen är lösenordsskyddad tar du med lösenordet i parametern -passin . Till exempel:
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>
```
  2. Kör från värden för att hämta container-ID:t för Jenkins-containern docker ps .
  3. Kopiera PEM-filen till containern med följande Docker-kommando:
```
docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home
```

Du är nästan klar! Håll Jenkins-jobbet öppet. Den enda återstående uppgiften är att konfigurera stegen efter bygget för att distribuera programmet till Service Fabric-klustret:

Om du vill distribuera till en utvecklings- eller testmiljö följer du stegen i Konfigurera distribution med hjälp av klusterhanteringsslutpunkten.
Om du vill distribuera till en produktionsmiljö följer du stegen i Konfigurera distribution med azure-autentiseringsuppgifter.

Konfigurera distribution med klusterhanteringsslutpunkt

För utvecklings- och testmiljöer kan du använda slutpunkten för klusterhantering för att distribuera ditt program. Att konfigurera åtgärden efter bygget med klusterhanteringsslutpunkten för att distribuera ditt program kräver minst mängd konfiguration. Om du distribuerar till en produktionsmiljö går du vidare till Konfigurera distribution med Azure-autentiseringsuppgifter för att konfigurera ett Microsoft Entra-tjänsthuvudnamn som ska användas under distributionen.

I Jenkins-jobbet klickar du på fliken Åtgärder efter bygget .
I listrutan Post-Build Actions (Åtgärder efter skapandet) väljer du Deploy Service Fabric Project (Distribuera Service Fabric-projekt).
Under Service Fabric Cluster Configuration (Konfiguration av Service Fabric-kluster) väljer du alternativknappen Fyll i service fabric-hanteringsslutpunktens slutpunkt .
För Hanteringsvärd anger du anslutningsslutpunkten för klustret, till exempel {your-cluster}.eastus.cloudapp.azure.com.
För Klientnyckel och Klientcertifikat anger du platsen för PEM-filen i Jenkins-containern, till exempel /var/jenkins_home/clustercert.pem. (Du kopierade certifikatets plats det sista steget iSkapa och konfigurera ett Jenkins-jobb.)
Under Programkonfiguration konfigurerar du fälten Programnamn, Programtyp och (relativ) sökväg till programmanifest .
Klicka på Verifiera konfiguration. Klicka på Spara när verifieringen har slutförts. Jenkins-jobbpipelinen är nu helt konfigurerad. Gå vidare till Nästa steg för att testa distributionen.

Konfigurera distribution med azure-autentiseringsuppgifter

För produktionsmiljöer rekommenderar vi starkt att du konfigurerar en Azure-autentiseringsuppgift för att distribuera ditt program. Det här avsnittet visar hur du konfigurerar ett Microsoft Entra-tjänsthuvudnamn som ska användas för att distribuera ditt program i åtgärden efter bygget. Du kan tilldela tjänsthuvudnamn till roller i din katalog för att begränsa behörigheterna för Jenkins-jobbet.

För utvecklings- och testmiljöer kan du konfigurera antingen Azure-autentiseringsuppgifter eller slutpunkten för klusterhantering för att distribuera ditt program. Mer information om hur du konfigurerar en slutpunkt för klusterhantering finns i Konfigurera distribution med klusterhanteringsslutpunkt.

Om du vill skapa ett Huvudnamn för Microsoft Entra-tjänsten och tilldela den behörigheter i din Azure-prenumeration följer du stegen i Använd portalen för att skapa ett Microsoft Entra-program och tjänstens huvudnamn. Var uppmärksam på följande:
- När du följer stegen i avsnittet måste du kopiera och spara följande värden: program-ID, programnyckel, katalog-ID (klient-ID) och prenumerations-ID. Du behöver dem för att konfigurera Azure-autentiseringsuppgifterna i Jenkins.
- Om du inte har de behörigheter som krävs för din katalog måste du be en administratör att antingen bevilja dig behörigheterna eller skapa tjänstens huvudnamn åt dig, eller så måste du konfigurera hanteringsslutpunkten för klustret i Post-Build Actions för ditt jobb i Jenkins.
- I avsnittet Skapa ett Microsoft Entra-program kan du ange valfri välformulerad URL för inloggnings-URL:en.
- I avsnittet Tilldela program till en roll kan du tilldela programmet rollen Läsare i resursgruppen för klustret.
Gå tillbaka till Jenkins-jobbet och klicka på fliken Åtgärder efter bygget.
I listrutan Post-Build Actions (Åtgärder efter skapandet) väljer du Deploy Service Fabric Project (Distribuera Service Fabric-projekt).
Under Konfiguration av Service Fabric-kluster klickar du på Välj Service Fabric-klustret. Klicka på Lägg till bredvid Azure-autentiseringsuppgifter. Klicka på Jenkins för att välja Provider för Jenkins-autentiseringsuppgifter.
I Jenkins-autentiseringsuppgifter väljer du Microsoft Azure-tjänstens huvudnamn i listrutan Typ .
Använd de värden som du sparade när du konfigurerade tjänstens huvudnamn i steg 1 för att ange följande fält:
- Klient-ID: Program-ID
- Klienthemlighet: Programnyckel
- Klientorganisations-ID: Katalog-ID
- Prenumerations-ID: Prenumerations-ID
Ange ett beskrivande ID som du använder för att välja autentiseringsuppgifterna i Jenkins och en kort beskrivning. Klicka sedan på Verifiera tjänstens huvudnamn. Om verifieringen lyckas klickar du på Lägg till.
Under Konfiguration av Service Fabric-kluster kontrollerar du att dina nya autentiseringsuppgifter har valts för Azure-autentiseringsuppgifter.
I listrutan Resursgrupp väljer du resursgruppen för klustret som du vill distribuera programmet till.
I listrutan Service Fabric väljer du det kluster som du vill distribuera programmet till.
För Klientnyckel och Klientcertifikat anger du platsen för PEM-filen i Jenkins-containern. Till exempel /var/jenkins_home/clustercert.pem.
Under Programkonfiguration konfigurerar du fälten Programnamn, Programtyp och (relativ) sökväg till programmanifest .
Klicka på Verifiera konfiguration. Klicka på Spara när verifieringen har slutförts. Jenkins-jobbpipelinen är nu helt konfigurerad. Fortsätt till Nästa steg för att testa distributionen.

Felsökning av Jenkins-plugin-programmet

Om du stöter på buggar med Jenkins-plugin-programmet kan du ange ett problem i Jenkins JIRA för den specifika komponenten.

Idéer att prova

GitHub och Jenkins har nu konfigurerats. Överväg att göra några exempeländringar i reliable-services-actor-sample/Actors/ActorCounter projektet i din förgrening av lagringsplatsen, https://github.com/Azure-Samples/service-fabric-java-getting-started. Skicka ändringarna till fjärrgrenen master (eller någon gren som du har konfigurerat att arbeta med). Detta utlöser Jenkins-jobbet (MyJob) som du konfigurerade. Den hämtar ändringarna från GitHub, skapar dem och distribuerar programmet till klustret som du angav i åtgärder efter bygget.

Nästa steg

Jenkins på Azure