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.

Format i ubicació

El proveïdor d’aplicacions haurà de configurar l’arxiu /sic/aca.yml dins del repositori del projecte (al primer nivell de carpeta). Es tracta d’un arxiu de text en format YAML en el que cal indicar tota la informació necessària per a la construcció i desplegament de l’aplicació o component.

Configuració

L’arxiu ha de tenir la següent estructura general:

version
info
global-env
components:
  - custom-builder
    build
    deployment
notifications

version

Caldrà indicar la versió de l’arxiu ACA. Aquesta versió segueix un versionat diferent del de l’aplicació o component, ja que els dos primers dígits (versió major i minor) es correspondran amb la versió de la definició de l’esquema que descriu l’estructura i les restriccions de contingut del fitxer (yml schema version); i el tercer dígit (versió pegat) es correspondrà amb la versió del fitxer de configuració. El seu valor ha de seguir el format estàndard: <versioMajor>.<versioMenor>.<pegat> i la versió actual és:

version: 2.0.0

info

Aquest element contindrà informació general del component:

info:
  version
  description

info.version

Versió funcional de l’aplicació o component que ha d’acomplir l’Estàndard de versions. Per exemple:

info:
  version: 1.0.0

NOTA: Si es vol automatitzar la versió es pot optar per eliminar aquest element i fer ús del descriptor sic.yml.
Per a més informació: Howto automatitzar el descriptor sic.yml.

info.description

Descripció de l’aplicació o component. Es tracta d’un camp de lliure contingut. Per exemple:

info:
  description: Backend de l'aplicació de Gestió de Continguts CTTI

global-env

Relació de variables globals necessàries per a l’execució de la pipeline. Les variables requerides en cada cas dependran de les necessitats de desplegament aplicant els següents criteris:

Per a aquest tipus de desplegament no cal informar la secció de build perquè es recupera un producte ja empaquetat externament, i tampoc caldrà indicar l’atribut info.version perquè no es farà cap mena de gestió de tags al projecte.

On:

• En el cas de Maven s’executarà la comanda mvn deploy ${PUBLISH_PARAMS} per la qual cosa haurem d’indicar la ruta del fitxer pom.xml. Per exemple: PUBLISH_PARAMS: -f ./pom.xml.

• En el cas de Npm s’executarà la comanda npm publish ${PUBLISH_PARAMS} per la qual cosa haurem d’indicar la ruta de la llibreria. Per exemple: PUBLISH_PARAMS: ./dist/lib.

En qualsevol dels casos, es podran indicar paràmetres addicionals per a cada cas particular. La informació interna s’afegirà automàticament a la comanda.

S’executarà la comanda dotnet nuget push ${ARTIFACT_PATH}/*.nupkg

En aquest cas, no serà necessari configurar cap directiva de build ni deployment.

Exemple de definició de variables per al desplegament a Openshift:

global-env:
  - CONTAINER_DOCKERFILE_PATH: Dockerfile
  - CONTAINER_IMAGE_NAME: petclinic-test-os
  - DEPLOYMENT_TYPE: DeploymentConfig

components[].custom-builder

Informació per a generar el contenidor que serà l’encarregat de construir l’aplicació o component. Només caldrà indicar aquesta secció en cas que l’aplicació o component no pugui fer ús del Registre d’imatges perquè disposa de requeriments propis. En aquest cas, l’element indicarà els diferents passos (steps) per a generar el contenidor, proporcionant informació sobre aquest (container) i les accions a executar (execution). Les imatges podran estendre del Registre d’imatges corporatiu.

components[].custom-builder.steps[].container

Informació per a construir la imatge del contenidor que s’encarregarà de la construcció de l’aplicació o component (custom builder). Caldrà afegir l’element local (local) indicant:

• name: nom que es desitja assignar a la imatge del contenidor

• path: ruta del Dockerfile de la imatge del contenidor

Per exemple:

components:
  - custom-builder:
      steps:
        - container:
            image:
              local:
                name: 7-768-arp-api-builder
                path: builds/Dockerfile

El nom de la imatge (name) serà referenciada des de la secció de construcció (build).

components[].build

Relació de passes (steps) per a la construcció del projecte segons la següent estructura:

components:
  - build:
      steps:
        - container
          execution

On:

• container: informació del contenidor encarregat de realitzar la construcció del projecte

• execution: informació de les comandes que cal executar per a la construcció del projecte

components[].build.steps[].container

Informació del contenidor encarregat de realitzar la construcció del projecte segons la següent estructura:

components:
  - build:
      steps:
        - container:
            image
            resources

On:

• image: informació de la imatge encarregada de realitzar la construcció del projecte

• resources: recursos a assignar per a la correcta construcció del projecte (CPU i memòria)

components[].build.steps[].container.image

Informació de la imatge a utilitzar per a la construcció del projecte segons la següent estructura.

components:
  - build:
      steps:
        - container:
            image:
              remote/local

La imatge pot ser de dos tipus:

• remote: si la imatge del contenidor constructor (builder) és una de les imatges proporcionades al Registre d’imatges corporatiu.

• local: si la imatge del contenidor constructor és pròpia (custom builder) creada en l’element components[].custom-builder.

components[].build.steps[].container.image.remote

Imatge i versió del contenidor constructor (builder) que cal utilitzar d’entre les disponibles al Registre d’imatges corporatiu.

Caldrà definir el nom de la imatge (name) segons la següent estructura:

components:
  - build:
      steps:
        - container:
            image:
              remote:
                name

components[].build.steps[].container.image.local

Imatge del contenidor constructor pròpia (custom builder) creada en l’element components[].custom-builder. Caldrà definir el nom de la imatge (name) segons la següent estructura:

components:
    build:
      steps:
        - container:
            image:
              local:
                name

components[].build.steps[].container.resources

Recursos de màquina necessaris per a que el contenidor pugui dur a terme la construcció del projecte. Es definiran els recursos de CPU i memòria del contenidor, tant de limits (recursos màxims) com de request (recursos mínims), segons la següent estructura:

components:
    build:
      steps:
        - container:
            resources:
              limits:
                cpu
                memory
              requests:
                cpu
                memory

On:

• cpu: recursos de CPU mesurats en unitats de CPU. 1 CPU equival a 1 vCPU/Core per a plataformes cloud i 1 hyperthread a plataformes on premise. Es permeten sol·licituds fraccionades, per tant, si especifiquem 0.5 equival a la meitat de CPU que un que demana 1 CPU. L’expressió 0.1 equival a l’expressió 100m, que es pot llegir com “cent milicpus” o com a “cent milicores”. Es recomana utilitzar la unitat “milicore” tenint en compte que no es permet una precisió major que 1m.

• memory: recursos de memòria mesurats en bytes. Podeu expressar la memòria amb un nombre sencer o com un nombre decimal fent ús d’aquests prefixos: G o M, o també podeu usar els equivalents en potencia de dos: Gi o Mi. Es recomana utilitzar la unitat “Mi”.

Per a més informació sobre l’administració de recursos: https://kubernetes.io/es/docs/concepts/configuration/manage-resources-containers/.

components[].build.steps[].execution

Relació de comandes (commands) que s’han d’executar al contenidor per a la construcció del projecte segons la següent estructura:

components:
    build:
      steps:
        - execution:
            commands

Exemple

Exemple de construcció d’una aplicació Maven 3.6 i Jdk 1.8:

components:
  - build:
      steps:
        - container:
            image:
              remote:
                name: registreimatges.sic.intranet.gencat.cat/gencat-sic-builders/mvn-builder:1.0-3.6-8
            resources:
              limits:
                cpu: 1000m
                memory: 1024Mi
              requests:
                cpu: 100m
                memory: 128Mi
          execution:
            commands:
              - mvn clean package -Dmaven.test.skip=true

components[].deployment

Informació sobre el repositori de codi font que conté els descriptors en format YML per al desplegament de l’aplicació a l’OpenShift i Kubernetes (scm), així com la relació d’entorns on es desplegarà l’aplicació (enviroments) segons la següent estructura:

components:
  - deployment:
      scm
      environments

On scm indica el repositori on es troben ubicats els orquestradors per a dur a terme el desplegament de l’aplicació.

components[].deployment.enviroments[]

Informació sobre els entorns (name) i les especificitats del desplegament sobre aquests, segons l’estructura següent:

components:
  - deployment:
      environments:
        - name
          deployment-type
          artifacts
          actions

On:

• name: nom de l’entorn on es desplegarà l’aplicació. Per exemple: “integration”, “preproduction” o “production”.

• deployment-type: únicament per a desplegaments on-premise, modalitat de desplegament aplicable. Possibles valors: delegated o semiautomatic

• artifacts: únicament per a desplegaments on-premise, llista d’artefactes que es desplegaran

• actions: únicament per a desplegaments al cloud, accions a realitzar per al desplegament de l’aplicació diferenciant entre: before-deploy, deploy i after-deploy

components[].deployment.enviroments[].artifacts[]

Únicament per a desplegaments on-premise, informació sobre els artefactes a desplegar indicant el seu: nom (name), ruta (path), tipus (type) i, en cas de desplegament en modalitat delegada, l’identificador de insfraestructura assignat ( infrastructure-id), segons l’estructura següent:

components:
  - deployment:
      environments:
        - name:
          deployment-type:
          artifacts:
            name:
            path:
            type:
            infrastructure-id:

On:

• name: nom de l’artefacte a desplegar

• path: (opcional) ruta de l’artefacte a partir de l’arrel del projecte utilitzant el caràcter separador “/”. Per defecte, “.”

• type: tipus d’artefacte a desplegar. Possibles valors: dynamic, static o bbdd

• infrastructure-id: únicament per al desplegament en modalitat delegada, identificador d’infraestructura proporcionat pel Cpd

Per exemple:

components:
  - deployment:
      environments:
        - name: integration
          deployment-type: delegated
          artifacts:
            - name: bbdd_INT.zip
              path: tmpBBDD
              type: bbdd
              infrastructure-id: id_cpdx_bbdd

Com es pot veure a l’exemple, en el cas de desplegaments de scripts de Base de Dades (type: bbdd) caldrà indicar el nom i ruta de l’artefacte preestablerts pel sistema:

• name: bbdd_${entorn fitxer plans.xml}

• path: tmpBBDD

components[].deployment.enviroments[].actions.before-deploy

Informació sobre el possible pas previ al desplegament before-deploy concebut per a poder dur a terme tasques que calgui executar abans del desplegament com, per exemple, modificar l’estat d’un API Gateway. Aquest pas és compatible únicament amb plataformes Openshift i Kubernetes segons la següent estructura:

components:
  - deployment:
      environments:
        - name
          actions:
            before-deploy:
              steps:
                - execution:
                    env

On caldrà indicar el detall de les execucions (execution) de cada pas (steps) a realitzar indicant les següents variables d’entorn:

Per exemple:

components:
  - deployment:
      environments:
        - name: preproduction
          actions:
            before-deploy:
              steps:
                - execution:
                    env:
                      - JOB_NAME_PREFIX: admin
                      - JOB_IMAGE: test-runjob:1.0
                      - JOB_WAIT: 60
                      - JOB_ENVS: TYPE=PREDEPLOY|KONG_ADMIN_URL=http://api-admin|ENDPOINTS=$(cat deploy.json)

components[].deployment.enviroments[].actions.deploy

Informació sobre el desplegament de l’aplicació deploy segons la següent estructura:

components:
  - deployment:
      environments:
        - name: preproduction
          actions:
            deploy:
              steps:
                - execution:
                    env

On caldrà indicar el detall de les execucions (execution) de cada pas (steps) a realitzar indicant les variables requerides en cada cas i que dependran de les necessitats de desplegament aplicant els següents criteris:

Per al desplegament a l’Openshift i Kubernetes IBMCloud i CaaS:

Per al desplegament a WebApp Azure:

Per al desplegament a l’Api Manager (API Connect v.5.2):

Per al desplegament a l’Api Manager (API Connect >= v.10):

Per al desplegament al CloudFoundry IBMCloud:

Per al desplegament On Premise:

Per exemple, per al desplegament a l’entorn de Preproducció a l’Openshift i Kubernetes:

components:
  - deployment:
      scm: git.intranet.gencat.cat/0192/orchestrators.git
      environments:
        - name: preproduction
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - DESCRIPTORS_PATH: deploys/PRE
                      - DEPLOYMENT_NAME: backend-deployment
                      - DEPLOYMENT_WAIT: 60

components[].deployment.enviroments[].actions.after-deploy

Informació sobre el possible pas posterior al desplegament after-deploy concebut per a poder dur a terme tasques que calgui executar després del desplegament com, per exemple, modificar l’estat d’un API Gateway. Aquest pas és compatible únicament amb plataformes Openshift i Kubernetes segons la següent estructura:

components:
  - deployment:
      environments:
        - name
          actions:
            after-deploy:
              steps:
                - execution:
                    env

On caldrà indicar el detall de les execucions (execution) de cada pas (steps) a realitzar indicant les següents variables d’entorn:

Per exemple:

components:
  - deployment:
      environments:
        - name: preproduction
          actions:
            after-deploy:
              steps:
                - execution:
                    env:
                      - JOB_NAME_PREFIX: admin
                      - JOB_IMAGE: test-runjob:1.0
                      - JOB_WAIT: 60
                      - JOB_ENVS: TYPE=POSTDEPLOY|KONG_ADMIN_URL=http://api-admin

notifications

Informació sobre el canal de notificació i destinataris davant accions manuals en espera i informació sobre resultats de les execucions. Actualment, el canal de notificació és mitjançant el correu electrònic, essent necessari indicar la relació de destinataris segons la següent estructura:

notifications:
  email:
    recipients:
      -

Per exemple:

notifications:
  email:
    recipients:
      - correu@domini.cat

Validació

Està previst implementar un sistema de validació que comprovi el format, el contingut i les referències del fitxer 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 dels diferents casos d’ús:

• Construcció aplicació Maven i desplegament al Kubernetes CaaS

• Construcció aplicació Maven i desplegament al CloudFoundry IBMCloud

• Construcció aplicació Node i desplegament a l’Openshift

• Construcció micro frontend Node i desplegament a l’Openshift

• Construcció aplicació Maven amb passes before/post-deploy i desplegament a l’Openshift

• Construcció aplicació .NET Core i desplegament al Kubernetes CaaS

• Desplegament Nginx a l’Openshift

• Desplegament producte Nginx extern a l’Openshift

• Desplegament aplicació al WebApp Azure

• Construcció aplicació PHP utilitzant imatge “custom Builder” i desplegament a l’Openshift

• Construcció aplicació Maven utilitzant imatge “custom Builder” i desplegament al Kubernetes IBMCloud

• Construcció aplicació Maven i desplegament On Premise

• Construcció aplicació MSBuild (Windows) i desplegament On Premise

• Desplegament d’scripts de bbdd en contenidors

• Desplegament d’scripts de bbdd On Premise

• Aplicació a desplegar a l’Api Manager (API Connect v.5.2)

• Aplicació a desplegar a l’Api Manager (API Connect >= v.10)

• Construcció i publicació de llibreria Maven al Nexus

• Construcció i publicació de llibreria Node al Nexus

• Construcció i publicació de llibreria .NET Core al Nexus

• Construcció i publicació de llibreria .NET Framework (MSBuild) al Nexus

• Construcció i publicació d’imatge pròpia al Registre corporatiu

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.