Com construir el fitxer ACA

Introducció

Dins el sistema d’Integració Contínua, el SIC proporciona un servei mitjançant el qual es poden generar automàticament pipelines de construcció i desplegament d’aplicacions, amb el treball col·laboratiu dels proveïdors d’aplicacions i d’infraestructures i sense la intervenció de l’equip del SIC.

En aquest article ens centrarem exclusivament en explicar com preparar l’arxiu ACA (Arxiu de Configuració d’Aplicacions). Si voleu més informació sobre el funcionament d’aquest servei, els requeriments que cal acomplir i altres, podeu consultar la secció Autoservei de pipelines on s’explica de forma detallada.

Configuració

El proveïdor d’aplicacions haurà de configurar l’arxiu /sic/aca.yml dins del repositori del projecte (a nivell de carpeta del projecte). Es tracta d’un arxiu de text en format YAML en el que a continuació definirem la informació que cal emplenar.

Versió

Caldrà indicar la versió de l’arxiu que, per tant, segueix un versionatge diferent al de l’aplicació ja que cada increment de versió es correspondrà amb canvis en les especificacions de construcció i/o desplegament. El seu valor ha de seguir el format estàndard: <versioMajor>.<versioMenor>.<pegat>.

version: x.y.z

Paràmetres

Opcionalment es poden definir paràmetres que permeten aplicar substitucions, de forma que allà on aparegui ${nom_param} se substituirà pel valor valor_param. Són útils per a dotar de més llegibilitat a l’arxiu de configuració i encapsular dades repetibles.

parameters:
  - name: nom_param1
    value: valor_param1
  - name: nom_param2
    value: valor_param2

build:
  steps:
    - id: step01
      position: 1
      tool: maven_3.6
      jdk: JDK 11-openjdk
      parameters: ${nom_param1}

Recursos

Caldrà definir els recursos dins l’entitat resources. Hi ha tres tipus de recursos:

• Entorns (environments)
• Infraestructures (infrastructures)
• Artefactes (artifacts)

Entorns

Es tracta de definir els entorns de desplegament, incloent el seu ordre i la modalitat de desplegament aplicada.

resources:
  environments:
    - id: int
      environment: int
      position: 1
      deploymentType: DELEGATED
    - id: pre
      environment: pre
      position: 2
      deploymentType: SEMIAUTOMATIC
    - id: pro
      environment: pro
      position: 3
      deploymentType: SEMIAUTOMATIC

Es relacionaran les denominacions d’infraestructures indicades pel proveïdor:

• Element o tipologia (element)
• Entorns (environments)
• Identificador del proveïdor (provider)

resources:
  (...)
  infrastructures:
    - id: 9999_apache
      element: apache
      environments:
        - environment: int
          vars:
        - environment: pre
          vars:
        - environment: pro
          vars:
      provider: cpd9
    - id: 9999_tomcat
      element: tomcat
      environments:
        - environment: int
          vars:
        - environment: pre
          vars:
        - environment: pro
          vars:
      provider: cpd9

Només si cal enviar variables d’entorn requerides per al desplegament a les infraestructures, s’haurà d’emplenar la secció vars:

resources:
  (...)
  infrastructures:
    - id: 9999_tomcat
      element: tomcat
      environments:
        - environment: int
          vars:
        - environment: pre
          vars:
        - environment: pro
          vars:
      provider: cpd9

La propietat element suporta el següent conjunt de tipus de servidors:

La propietat provider suporta el següent conjunt de valors:

El darrer element de la secció es centra en la definició de quins artefactes genera el procés de construcció i on s’ubicaran aquests.

resources:
  (...)
  artifacts:
    - id: artifact01
      artifactType: static
      path: target/nom_artefacte01.zip
    - id: artifact02
      artifactType: dynamic
      path: target/nom_artefacte02.war

En aquest cas, la propietat id simplement s’utilitzarà per a referenciar l’artefacte en la definició dels passos de desplegament. La propietat artifactType suporta el següent conjunt de valors:

Exemple d’artefacte de BBDD:

resources:
  (...)
  artifacts:
    - id: artifact03
      artifactType: plans
      path: sql/plans.xml

Procés de construcció

Caldrà definir tots els passos del procés i la seva ordenació en el que s’anomenen build steps. La definició es basa en una sèrie de tools predefinides. A més, els atributs dels passos de construcció varien en funció del seu tipus.

Es contemplen les següents tecnologies:

• Node
• Java
• .NET
• Compressió (zip, unzip)
• BBDD
• Docker Image

build:
  steps:
    - id: bs001
      position: 1
      tool: maven_3.6
      jdk: JDK 11-openjdk
      parameters: package -Dmaven.test.skip=true
      generates:
        - artifact01

build:
  steps:
    - id: bs001
      position: 1
      tool: nodejs_18_LTS
      parameters: install --scripts-prepend-node-path true
    - id: bs002
      position: 2
      tool: nodejs_18_LTS
      parameters: run-script build --scripts-prepend-node-path true
      generates:
        - artifact01

L’eina que s’utilizarà per a la construcció serà Npm i no caldrà que s’indiqui en els parameters d’execució doncs aquesta vindrà donada. Opcionalment, es podrà indicar la propietat executionDir per a indicar que la construcció cal executar-la en una ruta específica (per defecte, a l’arrel del projecte). La resta d’eines de cicle de vida (tals com bower, gulp i grunt) s’han d’incloure amb l’aplicació per a què el SIC les utilitzi per a la seva construcció. Pel que fa a Angular, framework de frontend recomanat per Arquitectura CTTI i el CS Canigó, l’aplicació haurà de definir la versió de ng (Angular-cli) a utilitzar per a la seva construcció.

build:
  steps:
    - id: bs001
      position: 1
      tool: maven_3.6
      jdk: JDK 11-openjdk
      parameters: package -Dmaven.test.skip=true
      generates:
        - artifact01
        - artifact02

No caldrà que s’indiqui la comanda mvn en els parameters d’execució doncs aquesta vindrà donada per l’eina. Opcionalment, es podrà indicar la propietat executionDir per a indicar que la construcció cal executar-la en una ruta específica (per defecte, a l’arrel del projecte).

build:
  steps:
    - id: bs001
      position: 1
      tool: MSBuild_15
      executionDir: src
      restoreParameters: app.sln /// .<path>packages.config -PackagesDirectory ./packages
      buildParameters:
         - msbuild_parameter_1
         - msbuild_parameter_2
         - msbuild_parameter_3
      generates:
        - artifact01

No caldrà que s’indiqui la comanda en el restore/build_parameters d’execució doncs aquesta vindrà donada per l’eina de restore (Nuget) i build (MSBuild) respectivament. Opcionalment, es podrà indicar la propietat executionDir per a indicar que la construcció cal executar-la en una ruta específica (per defecte, a l’arrel del projecte).

build:
  steps:
    - id: bs001
      position: 1
      tool: command
      executionDir: dist
      parameters: zip -r artefacte.zip
      generates:
        - artifact01

Caldrà que s’indiqui la comanda zip o unzip en els parameters d’execució per a especificar el tipus d’acció a realitzar.

build:
 steps:
    - id: bs001
      position: 1
      tool: bbdd
      generates:
        - artifact01

build:
 steps:
    - id: bs001
      position: 1
      tool: docker
      dockerImageName: repo/image:tag
      parameters: mvn clean package -Dmaven.test.skip=true
      generates:
        - artifact01

On:

• dockerImageName: nom de la imatge al catàleg d’imatges del SIC. Es composa pel repositori, el nom de la imatge i l’etiqueta de versió (tag). Per exemple: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk.
• parameters: comanda específica a executar dins de la imatge per a la construcció de l’artefacte. En aquest cas no vindrà donada.

build:
 steps:
    - id: bs001
      position: 1
      tool: docker
      dockerfilePath: /app/docker
      dockerfileName: DockerFile
      parameters: mvn clean package -Dmaven.test.skip=true
      generates:
        - artifact01

On:

• dockerfilePath: ruta del fitxer DockerFile al codi font del projecte per a la construcció de la imatge.
• dockerfileName: ficher DockerFile al codi font del projecte per a la construcció de la imatge.
• parameters: comanda específica a executar dins de la imatge per a la construcció de l’artefacte. En aquest cas no vindrà donada.

Anàlisi estàtic de codi

Aquesta secció és opcional doncs, per defecte, tots els passos del procés i la seva ordenació vindrà determinada per la definició del procés de construcció. Així doncs, cada pas de construcció que impliqui l’enviament de codi font per al seu anàlisi esdevindrà automàticament en un pas d’enviament de codi i comprovació de les Quality Gates corresponents. No obstant, es permet redefinir el seu comportament tal com es descriu a continuació.

Activar o desactivar l’enviament de codi font i/o la comprovació de les regles establertes

Es proporcionen unes propietats que permeten a l’usuari desactivar l’enviament de codi font i/o la comprovació de les regles establertes a l’eina davant urgències que pugui tenir per a desplegar o altres problemàtiques que es necessiti temps per a acabar de resoldre. Són les següents:

• evalStaticCode: permet activar o desactivar l’etapa completa d’anàlisi estàtic de codi, per lo que no es realitzarà l’enviament del codi font ni, òbviament, es comprovarà l’acompliment de les regles establertes.

• checkQualityGates: permet activar o desactivar la comprovació de les Quality Gates, per lo que el sistema no aturarà la pipeline en detectar un error en l’acompliment de les regles establertes.

analysis:
  evalStaticCode: true
  checkQualityGates: false

Per defecte, aquests indicadors es consideren actius.

Redefinir el timeout aplicat

L’Oficina de Qualitat defineix un timeout estàndard per a tots els projectes però, en cas que aquest esdevingui excessiu o insuficient per a la finalització de la tasca d’anàlisi del codi font, l’usuari pot optar per redefinir-lo a nivell de projecte mitjançant la propietat aecStageTimeout indicada en unitats de segon.

analysis:
  aecStageTimeout: 20

Redefinir el sistema d’enviament de codi font

Es permet redefinir el comportament per defecte d’aquest procés en el que s’anomenen analysis steps quan es detecta la necessitat de fer ús d’una imatge Docker diferent a la de construcció, es necessita editar la comanda a executar o el directori d’execució. Cal, però, tenir present que només cal redefinir-ho per al pas de build en qüestió i la resta (si hi ha) seguiran comportant-se de forma estàndard.

El sistema es basa en una sèrie de tools predefinides que es descriuen a continuació:

• maven: pas d’anàlisi estàtic de codi mitjançant el SonarScanner per a projectes Maven.

• msbuild: pas d’anàlisi estàtic de codi mitjançant el SonarScanner per a projectes que utilitzen MSBuild.

• generic: pas d’anàlisi estàtic de codi mitjançant el client genèric de SonarScanner. Es tracta del client utilitzat per a projectes que utilitzen NPM, projectes PHP, PL/SQL i d’altres.

Per a més informació: https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-jenkins/.

Caldrà definir la propietat target indicant l’identificador del step de build associat que es vol sobreescriure, que obligatòriament ha de coincidir amb un identificador de build step que hem definit més amunt i que s’afegirà com a sufix en l’enviament del projecte al SonarQube.

Opcionalment es podran indicar les propietats:

• imageName: només per a fer ús d’una imatge Docker diferent a la imatge de construcció de l’artefacte i que ha d’estar disponible al Registre d’imatges

• commands: per a especificar la comanda que cal executar només si s’especifica una imageName. En el cas de maven serà necessari indicar els següents paràmetres per a evitar que es realitzi de nou la construcció i, per tant, l’execució del goal es limiti a la generació i enviament de l’informe al SonarQube: -Dmaven.main.skip=true -Dmaven.install.skip=true -Dmaven.test.skip=true -Dmaven.antrun.skip=true --no-transfer-progress --batch-mode

• executionDir: per a indicar que l’enviament cal executar-lo sobre una ruta específica (per defecte, a l’arrel del projecte)

Exemple:

analysis:
  evalStaticCode: true
  checkQualityGates: true
  steps:
    - id: an001
      tool: maven
      target: bs001
      imageName: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk
      commands: mvn -f app1/pom.xml sonar:sonar -Dmaven.main.skip=true -Dmaven.install.skip=true -Dmaven.test.skip=true -Dmaven.antrun.skip=true --no-transfer-progress --batch-mode
      executionDir: dir1
    - id: an002
      tool: maven
      target: bs002
      imageName: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk
      commands: mvn -f app2/pom.xml sonar:sonar -Dmaven.main.skip=true -Dmaven.install.skip=true -Dmaven.test.skip=true -Dmaven.antrun.skip=true --no-transfer-progress --batch-mode
      executionDir: dir2
    - id: an003
      tool: maven
      target: bs003
      imageName: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk
      commands: mvn -f app3/pom.xml sonar:sonar -Dmaven.main.skip=true -Dmaven.install.skip=true -Dmaven.test.skip=true -Dmaven.antrun.skip=true --no-transfer-progress --batch-mode
      executionDir: dir3

Procés de desplegament

Caldrà definir tots els passos del procés i la seva ordenació en el que s’anomenen deploy steps. La definició es basa en una sèrie de tipologies predefinides anomenades type. A continuació es descriuen els diferents tipus de desplegament que es poden configurar.

Estàndard (predefined)

Pas de desplegament en el que se li indica l’artefacte a desplegar i l’identificador d’infraestructura destí (cas estàndard). Exemple:

deploy:
  steps:
    - id: dp001
      position: 1
      type: predefined
      destination: 9999_tomcat
      artifact: artifact01

Llibreria (library)

Pas de publicació de llibreries al Nexus, en el que se li indica l’eina de desplegament tool seguint el mateix patró que el Procés de construcció. No obstant això, en aquest cas, aquesta propietat només serà requerida si cal fer ús d’una imatge docker del catàleg diferent de la utilitzada en la construcció. En cas de no ser necessari, serà suficient fer referència a l’artifact en qüestió i el sistema aprofitarà la mateixa imatge de la construcció.

Exemple especificant la tool i la jdk:

deploy:
  steps:
    - id: ds001
      position: 1
      type: library
      tool: maven_3.6
      jdk: JDK 11-openjdk
      parameters: deploy -f pom.xml

Exemple sense indicar la tool i referenciant a un artifact generat a la construcció (build.steps[].generates) per a fer ús de la mateixa imatge de construcció. En cas d’indicar simultàniament l’eina i l’artefacte, el sistema utilitzarà la imatge associada a la tool indicada ignorant la propietat artifact:

deploy:
  steps:
    - id: ds001
      position: 1
      type: library
      parameters: deploy -f pom.xml
      artifact: artifact01

Exemple utilitzant imatge docker específica del catàleg:

deploy:
  steps:
    - id: ds001
      position: 1
      type: library
      tool: docker
      dockerImageName: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk
      parameters: mvn deploy -f pom.xml

Exemple amb diversos parameters:

deploy:
  steps:
    - id: ds001
      position: 1
      type: library
      tool: docker
      dockerImageName: gencat-sic-builders/mvn-builder:1.0-3.6-11-openjdk
      parameters:
       -  mvn deploy -f app1/pom.xml
       -  mvn deploy -f app2/pom.xml
       -  mvn deploy -f app3/pom.xml

Exemple mitjançant MSBuild (en aquest cas sí serà necessari indicar la destination per a extreure el node provider en el que cal realitzar el pas):

deploy:
  steps:
    - id: ds001
      position: 1
      type: library
      tool: MSBuild_15
      parameters: push .\\app.nupkg
      destination: cpdx_nexus_xxxx

En qualsevol cas, opcionalment es podrà indicar la propietat executionDir per a indicar que la construcció cal executar-la en una ruta específica (per defecte, a l’arrel del projecte).

Finalment, caldrà indicar les adreces de correu electrònic on es notificarà d’accions manuals en espera i resultats de l’execució:

notificationRecipients:
    - usuari1@domini
    - usuari2@domini

Validació

Està previst implementar un sistema de validació que comprovi el format, el contingut i les referències del fitxer ACA en fer la pujada al Sistema de Custòdia de Codi. Fins aleshores, recomanem fer una validació mínima del fitxer utilitzant eines online de validació disponibles com YAML Validator.

Exemples

A continuació s’adjunten exemples de casos d’ús:

• Maven - Nexus (llibreria)
• Maven - Weblogic
  
• Maven - Nexus & Weblogic
  
• Npm - Nexus (llibreria)
• Npm - Apache
• .NET - Nexus (llibreria)
• .NET
• PHP
• Oracle Apex o migracions de BBDD
• Docker Image
• Docker Custom Image
• Docker Custom Image - Nexus (llibreria)
• Maven Code Analysis Redefined

Si voleu més informació podeu consultar la secció de Guies.
Si teniu qualsevol dubte o problema podeu revisar les Preguntes Freqüents o utilitzar els canals de Suport.