Kom igång med Jenkins Configuration as Code

Jenkins Configuration as Code är äntligen här. I det här blogginlägget går jag igenom hur du konverterar en befintlig Jenkins-instans till JCasC och hur du börjar från grunden. Nu kör vi!

Vad är Jenkins Configuration as Code (JCasC)?

JCasC är ett Jenkins-plugin som gör att du kan lagra och underhålla din Jenkins-konfiguration i en YAML-fil. Jag beskrev de främsta fördelarna i ett tidigare blogginlägg: Jenkins Configuration as Code - Automatisera en automatiseringsserver.

Installation

Scenario 1: Börja från grunden med Docker

För att visa hur du börjar från grunden med Docker använder jag vårt GitHub-repository Praqma/praqma-jenkins-casc. Det innehåller en Dockerfile och docker-compose.yml som är redo att användas. Du kan använda dina egna images eller forka våra och använda dem.

Låt oss titta på innehållet i repot: Först ut är master/Dockerfile. Den bygger på Docker-imagen praqma/jenkins4casc:1.0, som i sin tur bygger på den officiella Jenkins-imagen för Docker. JCasC är förinstallerat och Setup Wizard är inaktiverad, så din container är redo att användas när du startar den.

FROM praqma/jenkins4casc:1.0LABEL maintainer="man@praqma.net"COPY plugins_extra.txt /usr/share/jenkins/ref/plugins_extra.txtARG JAVA_OPTSRUN xargs /usr/local/bin/install-plugins.sh < /usr/share/jenkins/ref/plugins_extra.txt

Därefter kommer filen master/plugins_extra.txt, som innehåller en lista över pluginer som förinstalleras på Jenkins-instansen. Om du vill att din instans ska innehålla fler pluginer lägger du till dem här.

Sedan finns filen docker-compose.yml, som används för att starta containern. Den är värd att titta närmare på:

version: '3.3'services:  jenkins:    build: #TODO: Once plugin installation is handled through c-as-c this can be removed and replaced with 'image'.      context: ./master    ports:      - 80:8080      - 50000:50000    volumes:      - jenkins_home:/var/jenkins_home      - ./jenkins.yaml:/var/jenkins_home/jenkins.yaml    secrets:      - github  #Github username with password as an example.  Purpose here is to have a user with write-access for special cases.  Like the git-publisher.      - adminpw  #Initial administrator user password.  Added for debugging purposes.  Should be removed prior to go-live.      - agent_private_key #ssh private key for connecting ssh slaves    environment:      - CASC_JENKINS_CONFIG=/var/jenkins_home/jenkins.yaml #Use a github repo.  Be aware that the raw content is cached, so it can take a couple of minutes to take effectsecrets: #Be careful with newlines in your secrets, make sure to remove them before running docker-compose up.  github:    file: /var/deploy/secrets/github  adminpw:    file: /var/deploy/secrets/adminpw  agent_private_key: #This should point to the private key you want your jenkins master to use when connecting to slaves.  So in AWS for example this would be your .pem file    file: ~/.ssh/id_rsavolumes:  jenkins_home:

Jenkins-konfigurationsfilen jenkins.yaml mappas till /var/jenkins_home/jenkins.yaml (rad 12), och miljövariabeln CASC_JENKINS_CONFIG sätts så att den pekar på vår nyligen mappade konfigurationsfil (rad 18). Toppen! Nu har JCasC-pluginet åtkomst till vår Jenkins-konfigurationsfil och vet var den finns.

Docker secrets deklareras också (rad 19+), vilket gör att vi kan skicka in känsliga data som inloggningsuppgifter och SSH-nycklar. Du behöver anpassa dem så att de pekar på de secrets du vill skicka in.

Om du vill återskapa min konfiguration behöver du lägga SSH-nyckeln du vill använda i ~/.ssh/id_rsa samt två textfiler som innehåller ett lösenord på:/var/deploy/secrets/github/var/deploy/secrets/adminpw

Om du väljer att ändra definitionerna av secrets måste du även uppdatera hur secrets skickas in (rad 13+).

Nu är du redo att gå vidare till nästa avsnitt.

Obs! Textfiler som innehåller ett lösenord ska bara innehålla en enda rad. Var uppmärksam på redigerare, som Atom, som automatiskt lägger till en avslutande radbrytning när du sparar en fil.

Scenario 2: Kom igång med befintliga Jenkins-instanser

Det här avsnittet fokuserar på att introducera JCasC i en Jenkins-instans som redan körs, oavsett om den är nyinstallerad eller inte. Det borde vara självklart, men undvik att experimentera med din produktionsinstans utan att först testa dina konfigurationsändringar ordentligt.

Gå till Plugin Manager under Manage Jenkins för att installera pluginerna Configuration as Code och configuration-as-code-support. Du hittar dem under fliken Available. Använd filtret för enkelhetens skull, välj pluginerna och klicka på Install without restart.

När pluginerna har installerats kan du gå vidare till nästa avsnitt.

Konfiguration

Scenario 1 och 2: Inledande konfiguration

Hur du kör Jenkins påverkar inte hur din konfigurationsfil ser ut, så du kan använda samma fil för både Docker-baserade och klassiska Jenkins-instanser. Det enda kravet är att pluginerna du konfigurerar är installerade.

För Docker-baserade Jenkins-instanser kan du läsa avsnittet ”Scenario 1: Börja från grunden” ovan om hur du förinstallerar pluginer. För klassiska installationer utgår jag tills vidare från manuell installation. Configuration as Code kan hantera installation av pluginer, men det tar jag upp i ett separat blogginlägg.

Så här kan din allra första JCasC-konfigurationsfil se ut:

_jenkins.yaml_jenkins:  systemMessage: "Hello, world!"

Scenario 1: Använd din konfigurationsfil med Docker

I avsnittet ”Scenario 1: Börja från grunden” ovan visade jag hur filen docker-compose.yml anger jenkins.yaml som vår konfigurationsfil. Jag uppmuntrar dig att redigera den filen direkt. Börja antingen med grundexemplet ovan, skapa en egen konfiguration eller använd delar av min konfiguration. När du är nöjd med konfigurationsfilen startar du containern genom att köra:

docker-compose up –build

När containern är igång kan du komma åt din Jenkins-instans på localhost:8080.

Scenario 2: Använd din konfigurationsfil i en klassisk miljö

När du har installerat pluginet hittar du menyalternativet Configuration as Code under Manage Jenkins. Det är här du konfigurerar JCasC.

Under Configuration as Code ändrar du inställningen Path or URL så att den pekar på din Jenkins-konfigurationsfil och klickar på Apply new configuration. Klart! Och ingen omstart krävs!

Du kan stöta på följande fel: ”Configuration cannot be applied. File or URL cannot be parsed or does not exist”. Kontrollera i så fall att sökvägen är korrekt och att Jenkins-användaren har läsbehörighet.

Om du stöter på ett undantag eller följande fel: ”Invalid configuration elements for […]”, kunde Jenkins inte tolka din konfigurationsfil. Den innehåller sannolikt ett syntaxfel och är inte giltig YAML.

Scenario 1 och 2: Resurser för att utöka din konfiguration

Nu har du din ”Hello, world!”-konfiguration igång. Om det mot förmodan är all konfiguration du behöver kan du sluta läsa här. Annars fortsätter vi!

Till en början kan det vara svårt att veta vad du ska lägga till i YAML-filen och hur olika inställningar ska konfigureras, men det finns några resurser som kan hjälpa dig.

De som bidrar till pluginet har redan lagt till många exempel i JCasC GitHub repository. Det är ett bra ställe för att ta reda på hur du konfigurerar specifika plugin.

Under Manage Jenkins > Configuration as Code, längst ned på sidan, hittar du praktiska referenslänkar till både dokumentation och scheman som du kan använda för att validera din YAML-fil.

I vårt GitHub-repository Praqma/praqma-jenkins-casc hittar du ytterligare ett exempel på en konfigurationsfil, men den här kräver installation av olika plugin som listas i filen plugins_extra.txt.

Utöka konfigurationsfilen efter behov – se bara till att behålla en giltig hierarki för poster och, naturligtvis, giltig YAML-syntax.

Genomgång av exempel

I det här avsnittet förklarar jag innehållet i min Jenkins-konfigurationsfil från GitHub-repositoryt Praqma/praqma-jenkins-casc.

jenkins:  systemMessage: "Welcome to the demo setup for Jenkins Configuration as Code plugin.  For more information look in the official repo with our demo setup: https://github.com/Praqma/praqma-jenkins-casc"  agentProtocols:    - "JNLP4-connect"  securityRealm:    local:      allowsSignup: false      users:       - id: demoAdmin         password: ${adminpw:-passw0rd}  authorizationStrategy:    globalMatrix:      grantedPermissions:        - "Overall/Read:anonymous"        - "Job/Read:anonymous"        - "View/Read:anonymous"        - "Overall/Administer:authenticated"  crumbIssuer: "standard"credentials:  system:    domainCredentials:      - credentials:          - usernamePassword:              scope:    SYSTEM              id:       github-user              username: ReleasePraqma              password: ${github}          - basicSSHUserPrivateKey:              scope: SYSTEM              id: agent-private-key              username: agentuser              passphrase:  ""              description: "ssh private key used to connect ssh slaves"              privateKeySource:                directEntry: # The key 'agent_private_key' resolved from a docker secret defined in docker-compose.yml                  privateKey: ${agent_private_key}

Viktigast av allt är att jag har konfigurerat en användare som jag alltid kan ansluta med. Jag lade bland annat till en lokal Security Realm med inaktiverad registrering och användaren ”demoAdmin”. För att konfigurera användarens lösenord expanderar jag en miljövariabel som skickas in som en Docker secret, eller som helt enkelt finns i miljön. Om miljövariabeln inte är tillgänglig används passw0rd som reserv.

Se alltid till att du har en användare konfigurerad, annars kan du låsa ute dig själv.

securityRealm:    local:      allowsSignup: false      users:       - id: demoAdmin         password: ${adminpw:-passw0rd}

Jag konfigurerade också en authorizationStrategy för att begränsa behörigheterna för anonyma användare.

authorizationStrategy:    globalMatrix:      grantedPermissions:        - "Overall/Read:anonymous"        - "Job/Read:anonymous"        - "View/Read:anonymous"        - "Overall/Administer:authenticated"

Nästa steg är att lägga till autentiseringsuppgifter. De används för autentisering mot andra applikationer, till exempel när du klonar Git-repositoryn i dina pipelines. Även här förlitar jag mig på Docker secrets och miljövariabler.

domainCredentials:      - credentials:          - usernamePassword:              scope:    SYSTEM              id:       github-user              username: ReleasePraqma              password: ${github}          - basicSSHUserPrivateKey:              scope: SYSTEM              id: agent-private-key              username: agentuser              passphrase:  ""              description: "ssh private key used to connect ssh slaves"              privateKeySource:                directEntry:                  privateKey: ${agent_private_key}

Rot-elementen tools och security innehåller också en del konfiguration. Det här är ett bra tillfälle att titta i dokumentationen för att se vilka underordnade element som kan konfigureras.

tool:  git:    installations:      - name: Default        home: "git"security:  remotingCLI:    enabled: false

Genom att läsa dokumentationen för elementet security kan vi se hur inställningen för remoting CLI konfigureras. Nedan hittar du respektive dokumentationssida för security och remoting CLI.

Du kanske märker att flera konfiguratorer hamnar under rotelementet unclassified. Bland de olika konfigurerbara elementen här anger jag Jenkins URL och administratörsadress.

unclassified:  location:    url: https://jenkins.company.com    adminAddress: support@company.net

Det finns många andra element att konfigurera, men låt oss anta att du är nöjd med konfigurationen. Nu tillämpar vi den!

Läs in ändrad konfiguration igen

För att tillämpa ändringar du har gjort i konfigurationsfilen går du tillbaka till sidan Configuration as Code under Manage Jenkins och klickar på Reload existing configuration. När sidan har uppdaterats har konfigurationen lästs in igen. Upprepa detta varje gång du redigerar konfigurationsfilen. Det går att automatisera, men det tar jag upp i ett framtida inlägg.

Avslutningsvis

Jag hoppas att du har tyckt att det varit roligt att komma i gång med JCasC. Det finns många fler konfigurerbara delar än de jag tog upp här, och pluginet Configuration as Code har en ljus framtid. Håll utkik efter fler inlägg om Jenkins Configuration as Code.

Sätt i gång och börja migrera din konfiguration till kod med JCasC!

Se den praktiska sessionen ”How to use Jenkins Configuration as Code” på Day of Jenkins