Acest exemplu conține un cod ca exemplu de structurare a configuraților Terraform pentru o infrastructură de dimensiuni mici, unde nu există dependențe externe.

Acest exemplu conține un cod ca exemplu de structurare a configuraților Terraform pentru o infrastructură de dimensiuni medii care folosește:

• 2 conturi AWS

• 2 medii de lucru separate (prod și stage care nu au procese comune). Fiecare mediu de lucru există într-un cont AWS separat

• Fiecare mediu de lucru folosește aceeași versiune a unui modul intern modules/network provenind din aceeași sursă locală (local directory)

Terraform este unul din cele mai puternice (poate chiar cel mai puternic) instrumente și unul din cele mai folosite pentru a defini infrastructura ca și cod. Le permite dezvoltatorilor să facă o mulțime de lucruri și nu îi împiedică să facă lucruri în moduri care vor fi greu de susținut sau de integrat în viitor.

Este posibil ca unele informații descrise în această carte să nu pară cele mai bune practici. Știu acest lucru și pentru a ajuta cititorii să separe cele mai bune practici stabilite de ceea ce este doar un alt mod de a face lucrurile într-un anumit fel, folosesc uneori indicii pentru a oferi context și pictograme pentru a specifica nivelul de maturitate pentru fiecare subsecțiune legată de cele mai bune practici.

Câțiva ani mai târziu, a fost actualizată cu mai multe bune practici disponibile cu Terraform 1.0. În cele din urmă, această carte ar trebui să conțină cele mai multe dintre cele mai bune practici și recomandări indiscutabile pentru utilizatorii Terraform.

Sponsori

Traduceri

Contactați-mă dacă doriți să ajutați la traducerea acestei cărți în alte limbi.

Contribuții

Îmi doresc întotdeauna să primesc feedback și să actualizez această carte pe măsură ce comunitatea se maturizează și noi idei sunt implementate și verificate în timp.

Autori

Licență

Această lucrare este licențiată sub Apache 2 License. Consultați LICENSE pentru detalii complete.

Autorii și colaboratorii la acest conținut nu pot garanta valabilitatea informațiilor găsite aici. Vă rugăm să vă asigurați că înțelegeți că informațiile furnizate aici sunt furnizate în mod liber și că nu este creat niciun fel de acord sau contract între dvs. și orice persoană asociată cu acest conținut sau proiect. Autorii și colaboratorii nu își asumă și nu își declină nicio responsabilitate față de orice parte pentru orice pierdere, daune sau întrerupere cauzată de erori sau omisiuni în informațiile conținute în, asociate cu sau legate de acest conținut, indiferent dacă astfel de erori sau omisiuni rezultă din neglijență, accident sau orice altă cauză.

Copyright © 2018-2023 Anton Babenko.

Întrebările legate de structura codului Terraform sunt de departe cele mai frecvente în comunitate. La un moment dat, toată lumea s-a gândit la cea mai bună structură de cod pentru proiect.

Cum ar trebui să-mi structurez configurațiile Terraform?

Aceasta este una dintre întrebările pentru care există o mulțime de soluții și este foarte greu să dai sfaturi universale, așa că este util să începem prin a înțelege cu ce avem de-a face.

• Care este complexitatea proiectului?

  • Numărul de resurse aferente

  • Numărul de furnizori Terraform (vezi nota de mai jos despre „furnizorii logici”)

• Cât de des se schimbă infrastructura proiectului?

  • De la o dată pe lună/săptămână/zi

  • La continuu (de fiecare dată când există un nou commit)

• Tirggeri pentru schimbari in cod? Permiteți serverului CI să actualizeze Git repository atunci când este construit un nou artefact?

  • Doar dezvoltatorii pot face push în repository-ul de infrastructură

  • Toată lumea poate propune o schimbare la orice, deschizând un PR (inclusiv activități automate care rulează pe serverul CI)

• Ce platformă de implementare sau serviciu de implementare utilizați?

  • AWS CodeDeploy, Kubernetes, sau OpenShift au nevoie de o abordare ușor diferită

• Cum sunt grupate mediile?

  • După mediu, regiune, proiect

Introducere în structurarea fișierelor de configurație Terraform

Punerea întregului cod în main.tf este o idee bună atunci când începeți sau scrieți un exemplu de cod. În toate celelalte cazuri, va fi mai bine să aveți mai multe fișiere împărțite logic astfel:

• main.tf - apelați module, informații locale și surse de date pentru a crea toate resursele

• variables.tf - conține declarații ale variabilelor utilizate în main.tf

• outputs.tf - conține rezultate din resursele create înmain.tf

• versions.tf - conține cerințele de versiune pentru Terraform și furnizori

Cum să ne gândim la structura fișierelor de configurație Terraform?

Recomandări uzuale pentru structurarea codului

• Este mai ușor și mai rapid să lucrezi cu un număr mai mic de resurse

  • terraform plan șiterraform apply ambele fac apeluri API în cloud pentru a verifica starea resurselor

  • Dacă aveți întreaga infrastructură într-o singură compoziție de infrastructură, acest lucru poate dura ceva timp

• O rază de impact este mai mică, cu mai puține resurse

  • Izolarea resurselor care nu depind unele de altele prin plasarea lor în compoziții separate reduce riscul în cazul în care ceva nu merge bine

• Începeți proiectul folosind remote state deoarece:

  • Laptopul nu este un loc bun pentru stocarea stării infrastructurii

  • Gestionarea unui fișiertfstate în git este un coșmar

  • Mai târziu, când straturile de infrastructură vor începe să crească în mai multe direcții (număr de dependențe sau resurse), va fi mai ușor să țineți lucrurile sub control

• • La fel ca în cazul codului procedural, codul Terraform ar trebui scris pentru ca oamenii să-l citească mai întâi, consecvența va ajuta atunci când vor avea loc schimbări peste șase luni

  • Este posibil să mutați resurse în fișierul de stare Terraform, dar poate fi mai greu de făcut dacă aveți o structură și o denumire inconsecventă

• Păstrați modulele de resurse cât mai simple posibil

• Nu puneți simplu text (hardcoded) valorile care pot fi transmise ca variabile sau descoperite folosind surse de date

• Utilizați surse de date șiterraform_remote_state în special ca legatură între modulele de infrastructură din cadrul compoziției

În această carte, exemplele de proiecte sunt grupate în funcție de complexitate - de la infrastructuri mici la infrastructuri foarte mari. Această separare nu este strictă, așa că verificați și alte structuri.

Orchestrarea modulelor și compozițiilor de infrastructură

A avea o infrastructură mică înseamnă că există un număr mic de dependențe și puține resurse. Pe măsură ce proiectul crește, necesitatea de a înlănțui execuția configurațiilor Terraform, conectarea diferitelor module de infrastructură și transmiterea valorilor într-o compoziție, devine evidentă.

Există cel puțin 5 grupuri distincte de soluții de orchestrare pe care dezvoltatorii le folosesc:

1. Doar Terraform. Foarte simplu, dezvoltatorii trebuie să cunoască doar Terraform pentru a duce treaba la bun sfârșit.

2. Terragrunt. Instrument de orchestrare pur, care poate fi folosit pentru a orchestra întreaga infrastructură, precum și pentru a gestiona dependențe. Terragrunt operează cu module de infrastructură și compoziții în mod nativ, astfel încât reduce duplicarea codului.

3. Scripturi interne. Adesea, acest lucru se întâmplă ca punct de plecare către orchestrare și înainte de a descoperi Terragrunt.

4. Instrument de automatizare Ansible sau altceva asemănător. Utilizat de obicei atunci când Terraform este adoptat după Ansible sau când Ansible UI este utilizat în mod activ.

Având în vedere acest lucru, această carte trece în revistă primele două dintre aceste structuri de proiect, doar Terraform și Terragrunt.

Structuri de cod Terraform

Structuri de cod Terragrunt

Documentație

Documentație generată automat

Cu configurații Terraform pre-commit poate fi folosit pentru a formata și valida codul, precum și pentru a actualiza documentația.

terraform-docs

@todo: Versiuni ale modulelor de documente, release, acțiuni GH

Resurse

Acest capitol descrie conceptele cheie folosite în această carte.

Resurse

Resursele sunt, de exemplu, aws_vpc, aws_db_instance, etc. O resursă aparține unui furnizor (provider), acceptă argumente, întoarce atribute și are cicluri de viață. O resursă poate fi creată, preluată, actualizată și ștearsă.

Modulul de resurse

Modulul de infrastructură

Un modul de infrastructură este o colecție de module de resurse, care în mod logic nu pot fi conectate, dar în situația actuală/proiectul/setarea servesc aceluiași scop. Acesta definește configurația pentru furnizori, care este transmisă modulelor de resurse din interior și resurselor. În mod normal, este limitat să funcționeze într-o singură entitate per separator logic (de exemplu, Regiune AWS, Proiect Google).

Compoziţia de infrastructură

Compoziţia este o colecție de module de infrastructură, care se pot întinde pe mai multe zone separate logic (de exemplu, regiuni AWS, mai multe conturi AWS). Compoziţia este utilizată pentru a descrie infrastructura completă necesară pentru întreaga organizație sau întreagul proiect.

O compoziţie este constituită din module de infrastructură, care sunt constituite din module de resurse, care implementează resurse individuale.

Sursa de date

Sursa de date efectuează o operație doar de citire și depinde de configurația furnizorului, este utilizată într-un modul de resurse și într-un modul de infrastructură.

Sursa de date terraform_remote_state acționează ca o legătură între module de nivel superior și compoziții.

Remote state

Provider, provisioner, etc

Providers, provisioners, și alți câțiva termeni sunt descriși foarte bine în documentația oficială și nu are rost să repet aici. După părerea mea, au puțin de-a face cu scrierea unor module bune de Terraform.

De ce atât de dificil?

Accesul la date între molecule (module de resurse și module de infrastructură) se realizează folosind datele de ieșire ale modulelor (outputs) și sursele de date (data sources).

Când puneți conceptele descrise mai sus în pseudo-relații, acestea pot arăta astfel:

Acest exemplu conține un cod ca exemplu de structurare a configuraților Terraform pentru o infrastructură de dimensiuni mari care folosește:

• 2 conturi AWS

• 2 regiuni

• 2 medii de lucru separate (prod și stage care nu au procese comune). Fiecare mediu de lucru există într-un cont AWS separat și conține resurse în două regiuni

• Fiecare mediu de lucru folosește aceeași versiune a unui modul intern modules/network provenind din aceeași sursă locală (local directory)

Care sunt instrumentele pe care ar trebui să le cunosc și pe care ar trebui să le folosesc?

Ar trebui specificate versiunile modulelor de resurse și infrastructură. Furnizorii de infrastructură (providers) ar trebui configurați în afara modulelor, dar numai în compoziție. Versiunea furnizorilor și cea a Terraform pot fi, de asemenea, blocate.

Există, de asemenea, un workshop pentru persoanele care doresc să exerseze lucrurile descrise în acest ghid.

Utilizați locals pentru a specifica dependențe explicite între resurse

Un mod util de a da un indiciu pentru Terraform că unele resurse ar trebui șterse înainte chiar și atunci când nu există nicio dependență directă în configurațiile Terraform.

Terraform 0.12 - Argumente obligatorii vs argumente opționale

1. Argumentul obligatoriu index_document trebuie setat, dacă var.website nu este o hartă (map) goală.

2. Argumentul opțional error_document poate fi omis.

Convenții generale

1. Folosiți _ (underscore) în loc de - (cratimă) peste tot (numele resurselor, numele surselor de date, numele variabilelor, outputs, etc).

2. De preferat să utilizați litere mici și cifre (chiar dacă UTF-8 este acceptat).

Argumentele resurselor și surselor de date

1. Nu repetați tipul de resursă în numele resursei (nu parțial, nici complet):

   resource "aws_route_table" "public" {}

   resource "aws_route_table" "public_route_table" {}

   resource "aws_route_table" "public_aws_route_table" {}

3. Folosiți întotdeauna substantive la singular pentru nume.

4. Folosiți - în interiorul valorilor argumentelor și în locurile în care valoarea va fi expusă unui om (ex.: în interiorul numelui DNS al instanței RDS).

5. Includeți argumentulcount / for_each în interiorul blocului de resurse sau sursă de date ca prim argument în partea de sus și separat prin linie nouă după acesta.

6. Includeți argumentul tags, dacă este suportat de resursă, ca ultimul argument real, urmat de depends_on și lifecycle, dacă este necesar. Toate acestea ar trebui separate printr-o singură linie goală.

7. Când folosiți condiții într-un argumentcount / for_each este de preferat să se folosească valori booleene în loc de length sau alte expresii.

Exemple de cod pentru resurse (resource)

Folosirea count / for_each

resource "aws_route_table" "public" {
  count = 2

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

resource "aws_route_table" "private" {
  for_each = toset(["one", "two"])

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

resource "aws_route_table" "public" {
  vpc_id = "vpc-12345678"
  count  = 2

  # ... remaining arguments omitted
}

Folosirea tags

resource "aws_nat_gateway" "this" {
  count = 2

  allocation_id = "..."
  subnet_id     = "..."

  tags = {
    Name = "..."
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}   

resource "aws_nat_gateway" "this" {
  count = 2

  tags = "..."

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }

  allocation_id = "..."
  subnet_id     = "..."
}

Condiții în count

resource "aws_nat_gateway" "that" {    # Best
  count = var.create_public_subnets ? 1 : 0
}

resource "aws_nat_gateway" "this" {    # Good
  count = length(var.public_subnets) > 0 ? 1 : 0
}

Variabile

1. Nu reinventați roata în modulele de resurse: folosiți name, description, și valoarea default pentru variabile cum sunt definite în secțiunea "Argument Reference" (din documentația oficială Terraform) pentru resursa de care aveți nevoie.

2. Suportul pentru validarea variabilelor este destul de limitat (de exemplu, nu pot accesa alte variabile sau nu pot face căutări). Planificați în consecință, deoarece în multe cazuri această caracteristică este inutilă.

3. Utilizați forma de plural într-un nume de variabilă atunci când tipul este list(...) sau map(...).

4. Ordonați cheile într-un bloc de variabilă astfel: description , type, default, validation.

5. Includeți întotdeauna description pentru toate variabilele chiar dacă vi se pare că este evident ce fac (veți avea nevoie de această informație în viitor).

6. De preferință, alegeți folosirea unor tipuri simple (number, string, list(...), map(...), any) în loc de tipuri ca object() cu excepția cazului în care trebuie să aveți constrângeri stricte pentru fiecare cheie.

7. De preferință, alegeți folosirea tipurilor specifice, camap(map(string)) dacă toate elementele din map au același tip (ex.: string) sau pot fi convertite (ex.: tipul number poate fi convertit la tipul string).

8. Utilizați tipul any pentru a dezactiva validarea tipului începând de la o anumită adâncime sau atunci când mai multe tipuri ar trebui să fie acceptate.

9. Valoarea {} este uneori de tip map (hartă), dar alteori un obiect. Utilizați tomap(...) pentru a o face de tip map pentru că nu există nicio modalitate de a face un obiect.

Outputs

Faceți rezultatele (outputs) consistente și ușor de înțeles în afara domeniului de aplicare (atunci când un utilizator folosește un modul, ar trebui să fie evident care este tipul și atributul valorii returnate).

1. Numele rezultatului ar trebui să descrie proprietatea pe care o conține și să aibă o formă mai puțin liberă decât v-ați dori în mod normal

2. O structură bună pentru numele de ieșire arată ca {name}_{type}_{attribute} , unde:

   1. {name} este o resursă sau un nume de sursă de date fără prefix de furnizor. {name} pentru aws_subnet este subnet, pentruaws_vpc este vpc.

   2. {type} este un tip de sursă de resurse.

   3. {attribute} este un atribut returnat de rezultate (outputs).
5. Includeți întotdeauna description pentru toate rezultatele (outputs) chiar dacă vi se pare că este ceva evident.

6. Evitați setarea sensitive pentru argumente cu excepția cazului în care controlați pe deplin utilizarea acestui rezultat în toate locurile din toate modulele.

7. De preferință, alegețitry() (disponibil începând cu Terraform 0.13) în loc de element(concat(...)) (abordarea legacy folosită înainte de versiunea 0.13)

Exemple de cod pentru output

Returnați cel mult un ID al grupului de securitate:

output "security_group_id" {
  description = "The ID of the security group"
  value       = try(aws_security_group.this[0].id, aws_security_group.name_prefix[0].id, "")
}

Când aveți mai multe resurse de același tip, .this ar trebui să fie omis în numele ieșirii:

output "this_security_group_id" {
  description = "The ID of the security group"
  value       = element(concat(coalescelist(aws_security_group.this.*.id, aws_security_group.web.*.id), [""]), 0)
}

Folosiți numele la plural dacă valoarea returnată este o listă

output "rds_cluster_instance_endpoints" {
  description = "A list of all cluster instance endpoints"
  value       = aws_rds_cluster_instance.this.*.endpoint
}