Συμβάσεις ονοματοδοσίας

Γενικές συμβάσεις

Δεν θα πρέπει να υπάρχει κανένας λόγος να μην ακολουθείτε τουλάχιστον αυτές τις συμβάσεις :)

Προσέξτε ότι οι πραγματικοί πόροι του cloud συχνά έχουν περιορισμούς στα επιτρεπόμενα ονόματα. Ορισμένοι πόροι, για παράδειγμα, δεν μπορούν να περιέχουν παύλες, ενώ ορισμένοι πρέπει να είναι γραμμένοι με κεφαλαία γράμματα. Οι συμβάσεις σε αυτό το βιβλίο αναφέρονται στα ίδια τα ονόματα του Terraform.

1. Χρησιμοποιήστε _ (υπογράμμιση) αντί για - (παύλα) παντού (σε ονόματα πόρων, ονόματα πηγών δεδομένων, ονόματα μεταβλητών, εξόδους κλπ.).

2. Προτιμήστε να χρησιμοποιείτε πεζά γράμματα και αριθμούς (παρόλο που υποστηρίζεται το UTF-8).

Ορίσματα πηγής πόρων και δεδομένων

1. Μην επαναλαμβάνετε τον τύπο του πόρου στο όνομα του πόρου (ούτε μερικώς ούτε πλήρως):

`resource "aws_route_table" "public" {}`

`resource "aws_route_table" "public_route_table" {}`

`resource "aws_route_table" "public_aws_route_table" {}`

1. Το όνομα του πόρου θα πρέπει να ονομάζεται this εάν δεν υπάρχει πιο περιγραφικό και γενικό όνομα ή εάν η μονάδα πόρων δημιουργεί έναν μόνο πόρο αυτού του τύπου (π.χ. στη μονάδα AWS VPC υπάρχει ένας μόνο πόρος τύπου aws_nat_gateway και πολλαπλοί πόροι τύπου aws_route_table, οπότε το aws_nat_gateway θα πρέπει να ονομάζεται this και το aws_route_table θα πρέπει να έχει πιο περιγραφικά ονόματα - όπως private, public, database).

2. Χρησιμοποιείτε πάντα ουσιαστικά στον ενικό αριθμό για τα ονόματα.

3. Χρησιμοποιήστε - μέσα σε τιμές ορισμάτων και σε σημεία όπου η τιμή θα είναι εκτεθειμένη σε άνθρωπο (π.χ. μέσα στο όνομα DNS του RDS instance).

4. Συμπεριλάβετε το όρισμα count / for_each μέσα σε μπλοκ πόρων ή πηγής δεδομένων ως το πρώτο όρισμα στην κορυφή και διαχωρίστε το με νέα γραμμή μετά από αυτό.

5. Συμπεριλάβετε το όρισμα tags, εάν υποστηρίζεται από τον πόρο, ως το τελευταίο πραγματικό όρισμα, ακολουθούμενο από τα depends_on και lifecycle, εάν είναι απαραίτητο. Όλα αυτά θα πρέπει να διαχωρίζονται με μία κενή γραμμή.

6. Όταν χρησιμοποιείτε συνθήκες/conditions σε ένα argument count / for_each προτιμήστε boolean τιμές αντί να χρησιμοποιείτε length ή άλλες εκφράσεις.

Παραδείγματα κώδικα πόρου

Χρήση του count / for_each

main.tf

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
}

main.tf

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

  # ... remaining arguments omitted
}

Τοποθέτηση ετικετών/tags

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

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

  tags = {
    Name = "..."
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}   

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

  tags = "..."

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }

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

Συνθήκες σε count

outputs.tf

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
}

Μεταβλητές

1. Μην ανακαλύπτετε ξανά τον τροχό στις μονάδες πόρων: χρησιμοποιήστε το όνομα/name, την περιγραφή/description και την προεπιλεγμένη/default τιμή για τις μεταβλητές όπως ορίζονται στην ενότητα «Αναφορά ορίσματος» για τον πόρο με τον οποίο εργάζεστε.

2. Η υποστήριξη για επικύρωση σε μεταβλητές είναι μάλλον περιορισμένη (π.χ. δεν μπορεί να έχει πρόσβαση σε άλλες μεταβλητές ή να κάνει αναζητήσεις). Προγραμματίστε αναλόγως, διότι σε πολλές περιπτώσεις αυτή η λειτουργία είναι άχρηστη.

3. Χρησιμοποιήστε τον πληθυντικό αριθμό στο όνομα μιας μεταβλητής όταν ο τύπος είναι list(...) ή map(...).

4. Ταξινομήστε τα κλειδιά σε ένα μπλοκ μεταβλητών ως εξής: περιγραφή/description , τύπος/type, προεπιλογή/default, επικύρωση/validation.

5. Περιλαμβάνετε πάντα περιγραφή/description σε όλες τις μεταβλητές ακόμα και αν νομίζετε ότι είναι προφανές (θα σας χρειαστεί στο μέλλον).

6. Προτιμήστε τη χρήση απλών τύπων (number, string, list(...), map(...), any) έναντι ειδικών τύπων όπως object() εκτός αν χρειάζεται να έχετε αυστηρούς περιορισμούς σε κάθε κλειδί.

7. Χρησιμοποιήστε συγκεκριμένους τύπους όπως map(map(string)) αν όλα τα στοιχεία του map έχουν τον ίδιο τύπο (π.χ. string) ή μπορούν να μετατραπούν σε αυτόν (π.χ. ο τύπος number μπορεί να μετατραπεί σε string).

8. Χρησιμοποιήστε τύπο any για να απενεργοποιήσετε την επικύρωση τύπου ξεκινώντας από ένα συγκεκριμένο βάθος ή όταν πρέπει να υποστηρίζονται πολλαπλοί τύποι.

9. Η τιμή {} είναι μερικές φορές ένα map αλλά μερικές φορές ένα αντικείμενο. Χρησιμοποιήστε το tomap(....) για να φτιάξετε ένα map επειδή δεν υπάρχει τρόπος να φτιάξετε ένα αντικείμενο.

Outputs

Κάντε τα outputs συνεπή και κατανοητά εκτός του πεδίου εφαρμογής της (όταν ένας χρήστης χρησιμοποιεί μια μονάδα θα πρέπει να είναι προφανές τι τύπο και τι ιδιότητα έχει η τιμή που επιστρέφει).

1. Το όνομα του output θα πρέπει να περιγράφει την ιδιότητα που περιέχει και να είναι λιγότερο «ελεύθερο» από ό,τι θα θέλατε κανονικά.

2. Μια καλή δομή για το όνομα του output μοιάζει με {name}_{type}_{attribute} , όπου:

   1. {name} είναι ένα όνομα πόρου ή πηγής δεδομένων χωρίς πρόθεμα παρόχου. Το {name} για το aws_subnet είναι το subnet, για το aws_vpc είναι το vpc.

   2. {type} είναι ο τύπος μιας πηγής πόρων.

   3. {attribute} είναι ένα χαρακτηριστικό που επιστρέφεται από το output

   4. Δείτε παραδείγματα.

3. Εάν το output επιστρέφει μια τιμή με συναρτήσεις παρεμβολής/interpolation functions και πολλαπλούς πόρους, τα {name} και {type} εκεί θα πρέπει να είναι όσο το δυνατόν πιο γενικά (το this ως πρόθεμα θα πρέπει να παραλείπεται). Δείτε παράδειγμα.

4. Αν η επιστρεφόμενη τιμή είναι μια λίστα θα πρέπει να έχει όνομα στον πληθυντικό. Δείτε παράδειγμα.

5. Πάντα να περιλαμβάνετε περιγραφή/description για όλα τα outputs ακόμα και αν νομίζετε ότι είναι προφανής.

6. Αποφύγετε να ορίσετε ευαίσθητο/sensitive όρισμα εκτός αν ελέγχετε πλήρως τη χρήση αυτού του output σε όλα τα σημεία σε όλες τις μονάδες.

7. Προτιμήστε την try() (διαθέσιμη από το Terraform 0.13) έναντι της element(concat(...)) (παλαιότερη προσέγγιση για την έκδοση πριν την 0.13)

Παραδείγματα κώδικαoutput

Επιστρέψτε το πολύ ένα ID τoυ security group

outputs.tf

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, "")
}

Όταν υπάρχουν πολλαπλοί πόροι του ίδιου τύπου, το this θα πρέπει να παραλείπεται στο όνομα τoυ output:

outputs.tf

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)
}

Χρησιμοποιήστε όνομα πληθυντικού αν η τιμή που επιστρέφει είναι λίστα

outputs.tf

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