Guia de referència IaC

1. Introducció

Aquesta guia recull, en un únic document, tot el que un equip/lot d’aplicació ha de tenir en compte quan ha de preparar i desplegar infraestructura com a codi (IaC) amb Terraform a la plataforma SIC+ del CTTI. Cobreix de manera transversal:

• El punt de partida amb les plantilles oficials.
• L’estructura obligatòria del projecte.
• Les convencions de nomenclatura, etiquetatge i compliment de polítiques.
• Les bones pràctiques de codi Terraform.
• La gestió de mòduls compartits, secrets i certificats.
• L’estimació de costos i les còpies de seguretat.
• Els requisits per fer ús de CloudOps.
• El flux de treball end-to-end de CI/CD amb GHEC.

L’objectiu és que un proveïdor que ha de desplegar una arquitectura (per exemple sobre AWS) tingui una visió global i sàpiga a quina documentació de detall ha d’anar a aprofundir per cada punt.

Tot el codi i els workflows viuen a GitHub Enterprise Cloud (GHEC): https://ctti.ghe.com/enterprises/ctti. L’usuari ha d’estar donat d’alta i autenticat per accedir-hi.

2. Punt de partida: plantilles oficials

El CTTI manté un conjunt de plantilles Terraform d’exemple per a cadascun dels hiperescalars suportats. No són plantilles tancades ni d’ús obligatori cas a cas, sinó una base de la qual partir: cobreixen els arquetips d’arquitectura aprovats i més freqüents al CTTI (CaaS sobre contenidors, FaaS amb funcions, contingut estàtic…), ja venen alineades amb els estàndards interns i incorporen els mòduls propis de l’organització. La recomanació és sempre partir d’una d’aquestes plantilles i adaptar-la a les necessitats concretes de l’aplicació, afegint, eliminant o modificant components segons calgui, en lloc de començar de zero.

Cada plantilla evoluciona amb el temps i les release notes documenten les noves funcionalitats incorporades, els canvis de mòduls i els ajustos de compliment. És recomanable revisar-les abans de partir d’una plantilla per conèixer-ne les capacitats actuals (per exemple, l’extracció dinàmica d’etiquetatge des de SSM Parameter Store, els mòduls de Private Endpoints amb registre DNS automàtic, els mòduls amb suport dinàmic i parametrització ampliada, etc.).

📖 Detall i release notes: Plantilles IaC

3. Estructura del projecte

Els workflows de CI/CD de SIC+ esperen una estructura de directoris amb dos blocs diferenciats:

• La carpeta env/ i els noms dels entorns (dev, pre, pro) són imprescindibles i s’han de respectar de manera estricta perquè els pipelines funcionin: cada stage del CI/CD treballa amb la carpeta corresponent a l’entorn segons la branca en què s’està actuant, i si els noms no coincideixen el workflow no localitzarà el codi a executar.
• La carpeta modules/ és recomanada quan l’aplicació vol definir mòduls Terraform locals propis del repositori (veure secció 7); si no se’n preveuen, no cal incloure-la.

root
├── env
│   ├── pro
│   │   ├── backend.tf
│   │   ├── *.tf
│   │   └── variables.tf
│   ├── pre
│   │   └── ...
│   └── dev
│       └── ...
└── modules
    ├── db
    │   ├── main.tf
    │   ├── outputs.tf
    │   └── variables.tf
    ├── container-registry
    │   └── ...
    └── ...

Els workflows mapen branca ↔ entorn ↔ carpeta:

• branca develop → carpeta env/dev
• branca release → carpeta env/pre
• branca master → carpeta env/pro

📖 Detall: Requeriments IaC § Estructura de projecte

4. Configuració base de Terraform

4.1 Backend

L’estat de Terraform es guarda en un Storage Account d’Azure (centralitzat, un per aplicació, amb un Container per entorn). Cal declarar el backend de manera buida — el workflow de CD el configura dinàmicament:

terraform {
  backend "azurerm" {}
}

provider "azurerm" {
  features {}
}

4.2 Providers: fixar versions i tags per defecte

• Fixar la versió del provider explícitament per evitar actualitzacions involuntàries que introdueixin incompatibilitats.
• Definir default_tags al provider perquè tots els recursos heretin l’etiquetatge comú.
• En cas necessari, configurar múltiples providers amb àlies (p. ex. per desplegar a us-east-1 recursos que ho requereixen, com WAFv2 associat a CloudFront).

4.3 Plataformes de contenidors: ignore_changes per a la imatge

La versió del contenidor la desplega el workflow CD d’aplicació, no el d’infraestructura. Cal indicar al recurs corresponent que ignori els canvis d’imatge per evitar recreacions i drift:

• Azure Container Apps:

  lifecycle {
    ignore_changes = [template[0].container[0].image]
  }
  

• AWS ECS:

  track_latest = true
  

📖 Detall: Requeriments IaC § CI/CD · Bones pràctiques IaC

4.4 Infraestructura base preexistent al compte

Quan s’aprovisiona el compte d’un lot, l’organització desplega automàticament una sèrie de recursos catalogats com a infraestructura base: components de xarxa (VPC, subxarxes, zones DNS privades…), rols i polítiques IAM, claus KMS, buckets/Storage Accounts auxiliars (per exemple, l’ACOCLDSIC a AWS, utilitzat per al desplegament de funcions Lambda grans), etc.

És important conèixer que aquests recursos no els pot crear ni modificar el lot, però en moltes ocasions els codis Terraform d’aplicació els necessitaran referenciar (p. ex. desplegar serveis ECS dins una subxarxa privada existent).

La manera correcta de fer aquesta referència és sempre amb blocs data, mai amb identificadors hardcodejats. Així el codi queda independent dels canvis a la infraestructura base i resol els valors en temps d’execució.

5. Nomenclatura i etiquetatge

5.1 Nomenclatura global

Tots els recursos han de seguir el patró:

acr-env-typ-lll-<funcionalitat>-iii

Els codis de tipus de recurs (s3, ecs, ecr, lam, vpc, api, etc. a AWS; cap, acr, fun, key, etc. a Azure; run, arc, fun, etc. a GCP) estan tabulats per hiperescalar al document de requeriments.

5.2 Etiquetes obligatòries

Tots els recursos han de portar:

CodiAplicacio   Codi d'aplicació
CodiEntitat     Codi d'entitat
CodiInap        Acrònim
CodiJira        Codi de facturació
CodiServei      Codi d'infraestructura
Entorn          Entorn de desplegament

A partir de v2.2.0 de les plantilles AWS aquestes etiquetes s’extreuen dinàmicament des de SSM Parameter Store, de manera que ja no s’han de hardcodejar.

📖 Detall i taules completes: Requeriments IaC § Nomenclatura

6. Bones pràctiques de codi Terraform

Resum dels patrons que cal aplicar:

• Blocs data: mai hardcodejar ARNs, IDs ni atributs d’altres recursos — recuperar-los amb un bloc data (p. ex. data "aws_vpc", data "aws_subnets").
• Variables i tfvars: tot atribut modificable ha de tenir variable a variables.tf amb description, type, default i, preferiblement, validation. Usar auto.tfvars perquè es carreguin automàticament.
• locals: per a composicions repetides (noms segons naming convention, parseig de secrets, lògica intermèdia amb funcions de Terraform). Millora la llegibilitat i evita repetició.
• for_each per davant de count: count és numèric i recrea recursos en cascada si s’elimina un element del mig de la llista; for_each itera sobre map/set i no té aquest problema.
• Referències, no valors literals: cap atribut d’un altre recurs en text pla. Si l’ús de referències crea un cycle, replantejar l’arquitectura del codi.
• Dependències: posicionar els recursos en l’ordre en què es creen i usar depends_on explícit quan calgui forçar un ordre o per llegibilitat.
• Versionatge estricte: mai HEAD de branques, ni en providers, ni en mòduls, ni en plantilles. Tot fixat per tag o versió.

📖 Detall i exemples: Bones pràctiques IaC

7. Organització del codi en mòduls reutilitzables

A l’hora d’organitzar el codi en mòduls reutilitzables, un lot té tres fonts vàlides on consumir-los, no excloents entre si:

1. Mòduls locals al propi repositori d’aplicació — definits dins la carpeta modules/ de l’estructura del projecte, per a peces específiques de l’aplicació.
2. Mòduls compartits del lot — quan el mòdul té sentit que s’utilitzi a més d’una aplicació del mateix lot AMxx (veure 7.1).
3. Mòduls oficials de tercers — provinents del registre públic de Terraform o repositoris públics. Només són acceptats els mòduls oficials (mantinguts pel propi proveïdor o per HashiCorp, com terraform-aws-modules/*, hashicorp/*, etc.); queden descartats els mòduls de comunitat sense garantia de manteniment.

En tots tres casos cal aplicar les mateixes regles: referenciar sempre per tag/versió concreta (mai HEAD ni una branca) i revisar el compliment de polítiques del codi resultant.

7.1 Mòduls compartits entre aplicacions del mateix lot

Cada lot AMxx disposa automàticament d’un repositori per a mòduls Terraform compartits entre les seves aplicacions:

https://ctti.ghe.com/ctti-dev/iac-terraform-modules-amXX_YY

Els equips (-maintain, -write, -read) hereten els mateixos rols que als repositoris d’aplicació. El versionatge i coordinació del codi és responsabilitat dels arquitectes del lot.

Format de referència:

module "ecr_repo" {
  source = "ctti.ghe.com/ctti-dev/iac-terraform-modules-amXX_YY.git//carpeta?ref=v1.0.3"
  ...
}

On carpeta és el subdirectori del mòdul i ?ref=v1.0.3 el tag. Sempre referenciar per tag, mai contra una branca.

📖 Detall: Codi IaC compartit)

8. Gestió de secrets i certificats

Dues estratègies segons l’origen del valor:

8.1 Secrets autogenerats (gestionats per Terraform)

Per a secrets que neixen amb la infraestructura, generar-los amb random_password o aprofitar els que generen automàticament alguns serveis (p. ex. primary_access_key d’un Azure Cognitive Account), i pujar-los directament al servei de secrets corresponent (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Mai en text pla en tfvars ni en codi.

8.2 Secrets i certificats preexistents (gestionats per CloudOps)

Per a secrets/certificats que ja existeixen o que han de pujar-se manualment, no es fan per consola ni per Terraform — s’usa la plataforma CloudOps (workflows GitHub Actions als repositoris <codi-app>-<acrònim>-cloudops-<hiperescalar>):

1. Obrir Issue al repo CloudOps amb el template corresponent (pujada / modificació / esborrament).
2. Omplir el formulari amb les dades del secret/certificat.
3. El workflow executa l’operació de forma traçable.
4. Verificar el resultat per consola (només lectura).

Des de Terraform, els secrets/certificats gestionats per CloudOps es referencien per data:

• Si només cal l’ARN/ID (típic en certificats per a un ALB, Front Door, etc.): data "aws_secretsmanager_secret", data "azurerm_key_vault_certificate", etc.
• Si cal el valor com a paràmetre d’un altre recurs (p. ex. password d’un SQL Server): data "azurerm_key_vault_secret" i accedir a .value.

📖 Detall: Gestió de secrets i certificats

9. Compliment de polítiques i seguretat

Al workflow de CI on PR s’executa un stage de Scan check que valida el codi contra les polítiques de Checkov del CTTI:

• Repositori de polítiques: ctti-arq/ghec-checkov-policies
• Les PR no es poden mergear si el Scan check no passa.

Cal revisar i auditar regularment el compliment, i integrar la gestió de polítiques en el flux normal de treball — no tractar-les com una darrera barrera.

10. Estimació de costos amb Cloudability Governance

Des de v2.2.0 de les plantilles AWS (incorporant-se a Azure/GCP), el workflow de CI on PR executa l’acció ctti-actions/cloudability-governance@v1, que:

1. Llegeix el tfplan.json generat al pas anterior.
2. Llegeix opcionalment un fitxer usage.yaml que descriu el consum esperat (transferència, hores, requests…) — millora la precisió.
3. Publica un comentari al PR amb el cost estimat, recursos suportats, no suportats i recomanacions.

El fitxer usage.yaml ha de viure dins de env/dev/, env/pre/ o env/pro/ segons l’entorn. Format simplificat:

version: "0.1"
resource_usage:
  aws_instance.example_ec2_instance:
    count: 1
    term_type: "compute_savings_plan"
    purchase_option: "partial_upfront"
    lease_contract_length: "3yr"

L’eina suporta gran varietat de recursos: compute (EC2, launch templates), bases de dades (RDS, Aurora, DynamoDB, ElastiCache, Redshift), storage (EBS, FSx, S3), missatgeria (SNS, SQS), serverless (Lambda), big data (EMR), event processing, monitoring, KMS i networking. Per a recursos no suportats l’eina els llistarà al comentari sense incloure’ls a l’estimació.

📖 Detall i llistat complet: Estimació de costos amb Cloudability Governance

11. Backups (específic AWS)

Per incloure recursos en els plans de còpia de seguretat centralitzats de l’organització cal:

1. Encriptar el recurs amb la KMS del compte (creada com a infraestructura base de l’aplicació, recuperable amb un bloc data).
2. Etiquetar amb la freqüència/retenció desitjada:

   Freqüència	Valor etiqueta
   Diària	diaria
   Setmanal bàsica	semanal-bas
   Setmanal avançada	semanal-av
   Mensual	mensual
   Anual bàsica	anual-bas
   Anual avançada	anual-av

Les plantilles AWS (notablement a partir de v1.2.0) ja incorporen exemples per a Aurora i DynamoDB.

📖 Detall: Requeriments IaC § Backups

12. CloudOps i prerequisits a nivell de Terraform

Les operacions sobre recursos ja desplegats (parades i arrencades programades, execució de comandes contra instàncies o contenidors, rotació de certificats, pujada o modificació de secrets preexistents, etc.) no es realitzen des de Terraform sinó a través de CloudOps — una plataforma de workflows GitHub Actions específica per a aquest tipus de tasques operatives, ja referenciada parcialment en el punt 8 per al cas dels secrets.

És important saber que alguns d’aquests workflows requereixen que la infraestructura s’hagi desplegat amb configuració específica a nivell de Terraform perquè CloudOps hi pugui actuar (p. ex. habilitar Execute Command en serveis ECS, configurar agent i rol SSM en instàncies EC2, permetre l’accés del rol de CloudOps a Log Groups encriptats, instal·lar utilitats concretes a la imatge de contenidor, etc.). Per això, quan es planifica l’arquitectura, val la pena revisar la documentació de CloudOps i de requeriments d’IaC per identificar quins prerequisits cal aplicar al codi des de l’inici.

💡 Les plantilles oficials del CTTI (per exemple template-fargate a AWS) ja incorporen el codi necessari per complir amb els prerequisits CloudOps més habituals.

📖 Detall: Requeriments IaC § CloudOps · Plataforma CloudOps

13. Flux de treball end-to-end (CI/CD)

El model és GitFlow + Pull Requests + Semantic Versioning 2.0, amb les branques mapejades a entorns:

Què fan els workflows

• Infra CI on PR (automàtic en obrir PR): format scan + scan check (polítiques Checkov) + Cloudability cost estimation + terraform plan + emmagatzematge del plan a un Storage Account d’Azure.
• Infra CI on Commit (automàtic en fer merge): tagging del repositori.
• Infra CD Apply (manual, sota demanda): recupera el plan emmagatzemat pel tag, crea CRQ a ITSM (per a Pre/Pro), executa el terraform apply, etiqueta el repositori per a propòsits de rollback.

Inputs del CD Apply manual

Cada execució demana:

• Branch del workflow: develop / release / master.
• Infra Version: el tag exacte del plan a desplegar (p. ex. 1.0.1-RC).
• Env to apply the terraform plan: entorn destí (dev / pre / pro).
• ITSM ID Change Coordinator: ID per crear la CRQ.

💡 Si l’aplicació no té entorn de desenvolupament, l’estratègia és integrar directament a release sense passar per develop.

📖 Detall: Exemple e2e Infra

14. Resum del recorregut per a un proveïdor que arrenca

Per a un lot que ha de muntar una arquitectura — per exemple a AWS — el camí recomanat és:

1. Accedir a GHEC i validar permisos del team (-maintain / -write / -read) al repositori d’aplicació i al repo de mòduls compartits del lot.
2. Triar la plantilla de iac-aws-templates que millor s’adapti (template-fargate, template-apprunner, template-apigateway) en la versió més recent estable, i copiar-ne el contingut respectant l’estructura env/ + modules/.
3. Personalitzar les variables (acronimapp, region_code, entorn…) i adaptar els blocs data als recursos existents al compte (VPC, subnets, KMS, certificats…).
4. Aplicar la nomenclatura i etiquetatge obligatoris (a partir de plantilles v2.2.0 AWS, l’etiquetatge ja s’extreu de SSM Parameter Store).
5. Identificar els secrets/certificats preexistents i preparar la sol·licitud de pujada via CloudOps; per a secrets nous, generar-los amb random_password i pujar-los directament des de Terraform.
6. Crear o referenciar els mòduls compartits del lot (iac-terraform-modules-amXX_YY) per a codi reutilitzable.
7. Crear el fitxer usage.yaml per cada entorn per millorar la precisió de l’estimació de costos.
8. Obrir PR a develop → revisar resultats de format, polítiques i cost al comentari del PR.
9. Aprovar i mergear → executar Infra CD Apply manualment per a Dev.
10. Promoure a release (Pre) i a master (Pro) seguint el mateix patró, amb la CRQ d’ITSM corresponent.

Annex: índex de documents de referència