El Servei d’Integració Contínua és un servei a disposició dels proveïdors d’aplicacions per a automatitzar el desplegament de les aplicacions.
L’API Manager Corporatiu és una plataforma en modalitat SaaS basada en la solució IBM API Connect 10 Reserved Instance. Aquest servei permet gestionar el cicle de vida de les APIS de manera senzilla i segura amb l’objectiu de facilitar-ne tant la seva publicació com el seu consum.
L’organització de catàlegs, espais i productes és la següent:
privat-pre, public-pre, privat i public.Un cop fet el desenvolupament amb API Designer, caldrà exportar els yml de definició del producte i les seves APIS per a repositar-los al sistema de gestió de codi font (SCM - Source Code Management) del SIC d’acord amb les següents premisses:
Cada producte es correspondrà amb un projecte dins el codi de diàleg adient, de forma que tota la gestió posterior de pipelines i creació de peticions Remedy s’associïn a l’aplicació corresponent. Per aquest mateix motiu, no està contemplat la creació de subgrups de projectes, tot i que l’eina ho permeti.
Els projectes poden tenir tantes branques com siguin necessàries, però sempre s’haurà d’incloure la branca MASTER i el contingut d’aquesta branca serà amb el que treballaran les pipelines de desplegament per defecte. No obstant això, el sistema permetrà opcionalment desplegar el codi font associat a la branca EVOLUTIUS.
Aquest repositori no és un entorn de desenvolupament, per la qual cosa només les persones assignades com a Release Managers seran les encarregades de consolidar el codi i lliurar-lo. Aquest codi font ja haurà d’estar validat en entorns de desenvolupament i es lliurarà quan es decideixi distribuir als entorns dels serveis TIC centrals.
Les pipelines seran les encarregades de generar els TAGS de Release de codi corresponents tan bon punt es desplegui amb èxit a producció.
Per tal de configurar la integració al SIC, tots els projectes hauran de disposar de la carpeta /sic al primer nivell
de carpeta i, dins d’aquesta carpeta, caldrà crear l’arxiu de configuració aca.yml que proporcionarà la configuració necessària:
| Variable | Requerit | Descripció | Valor per defecte | Exemple |
|---|---|---|---|---|
| APIC_PRODUCT_FILE | No | Ruta i nom del fitxer descriptor per al desplegament de l’aplicació a l’Api Manager. La variable només serà requerida en cas que la ruta i/o nom del fitxer difereixi del suggerit | product.yml | - |
| APIC_TARGET_URL | Si | URL de destí de les APIs si és comuna a totes, tot i que pot conviure amb APIC_TARGET_URL_{N} per especificitats. | - | APIC_TARGET_URL: ‘https://backend/api’ |
| APIC_TARGET_URL_{N} | Si | URL de destí de les APIs si NO és comuna a totes les APIs permetent definir especificitats, tot i que pot conviure amb APIC_TARGET_URL global: - Format de la clau: APIC_TARGET_URL_{0-*9a-*zA-Z} - Format del valor: <api-file-name-with-extension>:<target-url> |
- | APIC_TARGET_URL_1: ‘api_1.0.0.yml:https://backend/api’ |
Per exemple:
version: 2.0.0 # aca schema version
info:
version: 1.0.1
description: APIM Demo Project
global-env:
- APIC_PRODUCT_FILE: 'product.yml'
components:
- deployment:
environments:
- name: privat_pre
actions:
deploy:
steps:
- execution:
env:
- APIC_TARGET_URL: 'https://common-backend/pre' # aplicable a totes les apis excepte API_C
- APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pre'
- name: public_pre
actions:
deploy:
steps:
- execution:
env:
- APIC_TARGET_URL: 'https://common-backend/pre' # aplicable a totes les apis excepte API_C
- APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pre'
- name: privat
actions:
deploy:
steps:
- execution:
env:
- APIC_TARGET_URL: 'https://common-backend/pro' # aplicable a totes les apis excepte API_C
- APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pro'
- name: public
actions:
deploy:
steps:
- execution:
env:
- APIC_TARGET_URL: 'https://common-backend/pro' # aplicable a totes les apis excepte API_C
- APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pro'
notifications:
email:
recipients:
- noreply@gencat.cat
On es pot comprovar que s’ha definit una target-url global i una d’específica per a l’API_C.
Per a més informació, podeu consultar: Com construir el fitxer ACA.
El SIC s’encarrega de la publicació i el desplegament automatitzat de les APIS, atorgant la màxima agilitat i autonomia als equips de desenvolupament. En aquest sentit, es proporciona un conjunt de pipelines que permeten gestionar el seu cicle de vida d’una forma estandarditzada:
1.1.0.1.1.0.1.1.0.1.1.0.1.1.0.Per a més informació, podeu consultar: Servei d’API Manager Corporatiu.
Cal tenir present que:
El SIC aplica una sèrie d’estàndards de nomenclatura amb l’objectiu de facilitar la identificació a simple vista de productes i APIs publicades per part dels subscriptors i, a més, mitigar el possible risc de solapament de recursos. Les regles de nomenclatura aplicades són les següents:
Productes:
name obligatori i immutable que es correspon amb el codi de diàleg, el caràcter separador “-” i el nom del projecte.
Per exemple: “0192-apim_demo_project”.title obligatori amb prefix de codi de diàleg, un espai en blanc i un text lliure. Per exemple: “0192 APIM Demo Project”.APIs:
x-ibm-name obligatori amb prefix de codi de diàleg, el caràcter separador ‘-’ i l’identificador de l’API.
Per exemple: “0192-api_a”.basePath inclou el codi de diàleg. Per exemple: “/0192/api_a”. Per tal de resoldre la crida al target-url
de l’aplicació, s’implementa un pas a l’Assembly que s’encarrega d’eliminar el codi de diàleg del requestPath.En qualsevol cas, si aquests criteris no s’acompleixen a la configuració del producte o les APIs, el SIC durà a terme els reemplaçaments necessaris per a assegurar la seva aplicació. Donat el nom del producte és immutable, aquest no es demana de cara a l’execució de les pipelines operatives de gestió del cicle de vida: DELETE, DEPRECATE, REPLACE, RETIRE i SUPERSEDE.
Amb l’objectiu de permetre l’aplicació de criteris de cerca sobre productes i APIs publicades als diferents catàlegs, el SIC s’encarrega de la injecció automàtica de dos nivells estàndards de categories per codi de diàleg i nom del projecte. Aquestes categories no invalidaran en cap cas les que es puguin haver indicat a la configuració, simplement s’afegiran si no hi són.
A continuació, es mostren exemples amb els criteris aplicats:
info:
version: 1.0.1
title: 0192 APIM Demo Project
name: 0192-apim_demo_project
categories:
- '0192'
- '0192/apim_demo_project'
swagger: "2.0"
info:
version: 1.0.1
title: 0192 APIM Demo Project Api_a
x-ibm-name: 0192-api_a
basePath: /0192/api_a
x-ibm-configuration:
...
categories:
- '0192'
- '0192/apim_demo_project'
- '0192/apim_demo_project/api_a'
...
El SIC aplica una sèrie de mecanismes de control i seguretat (snippets) que poden implicar canvis respecte a la definició inicial de productes i APIs realitzada pel proveïdor:
plans:
default-plan:
title: Default Plan
description: Default Plan
approval: true
rate-limits:
default:
value: 30/1second
hard-limit: true
burst-limits:
default:
value: 300/1second
authenticated:visibility:
view:
type: authenticated
orgs: []
tags: []
enabled: true
subscribe:
type: authenticated
orgs: []
tags: []
enabled: true
En cas d’autenticació IBM Default:
securityDefinitions:
clientID:
type: apiKey
in: header
name: X-IBM-Client-Id
security:
- clientID: []
En cas d’autenticació Gicar (entorn productiu):
securityDefinitions:
clientID:
type: apiKey
in: header
name: X-IBM-Client-Id
produccio-gicar:
type: oauth2
x-ibm-oauth-provider: pro-apic-keycloak-cpd4
flow: accessCode
authorizationUrl: >-
https://endpointma.autenticaciogicar4.extranet.gencat.cat/realms/gicarcpd4/protocol/openid-connect/auth
tokenUrl: >-
https://endpointma.autenticaciogicar4.extranet.gencat.cat/realms/gicarcpd4/protocol/openid-connect/token
scopes:
email: scope email
profile: scope profile
security:
- clientID: []
produccio-gicar:
- email
- profile
x-ibm-configuration.assembly.execute serà reemplaçada aplicant la configuració de target-url especificada al
fitxer aca.yml de forma que sigui possible dur a terme un desplegament multientorn, tenint en compte la regla de
nomenclatura aplicada al basePath.execute:
- gatewayscript:
title: gatewayscript
version: 2.0.0
description: Set new request path
source: |
const requestPath = context.get('request.path');
const newRequestPath = requestPath.replace(/^\/\d*\.*\d*/, "");
context.set('new.request.path', newRequestPath);
- invoke:
title: invoke
version: 2.0.0
verb: keep
target-url: '<replace_target_url>$(new.request.path)'
follow-redirects: false
timeout: 60
parameter-control:
type: blocklist
header-control:
type: blocklist
values:
- ^X-IBM-Client-Id$
inject-proxy-headers: true
Podeu descarregar el següent Projecte d’exemple, que mostra una configuració completa d’un producte.
Si teniu qualsevol dubte o problema podeu revisar les Preguntes Freqüents o utilitzar els canals de Suport.