Παράρτημα: Τεχνικές YAML

Το μεγαλύτερο μέρος αυτού του οδηγού επικεντρώθηκε στη συγγραφή της γλώσσας template. Εδώ, θα εξετάσουμε τη μορφή YAML. Η YAML έχει κάποια χρήσιμα χαρακτηριστικά που εμείς, ως συγγραφείς template, μπορούμε να χρησιμοποιήσουμε για να κάνουμε τα templates μας λιγότερο επιρρεπή σε σφάλματα και ευκολότερα στην ανάγνωση.

Βαθμωτά και Συλλογές

Σύμφωνα με την προδιαγραφή YAML, υπάρχουν δύο τύποι συλλογών και πολλοί βαθμωτοί τύποι.

Οι δύο τύποι συλλογών είναι maps και sequences:

map:
  one: 1
  two: 2
  three: 3

sequence:
  - one
  - two
  - three

Οι βαθμωτές τιμές είναι μεμονωμένες τιμές (σε αντίθεση με τις συλλογές)

Βαθμωτοί Τύποι στην YAML

Στη διάλεκτο YAML του Helm, ο βαθμωτός τύπος δεδομένων μιας τιμής καθορίζεται από ένα πολύπλοκο σύνολο κανόνων, συμπεριλαμβανομένου του Kubernetes schema για ορισμούς πόρων. Αλλά κατά τη συναγωγή τύπων, οι παρακάτω κανόνες τείνουν να ισχύουν.

Εάν ένας ακέραιος ή αριθμός κινητής υποδιαστολής είναι bare word (χωρίς εισαγωγικά), τυπικά αντιμετωπίζεται ως αριθμητικός τύπος:

count: 1
size: 2.34

Αλλά αν βρίσκονται σε εισαγωγικά, αντιμετωπίζονται ως strings:

count: "1" # <-- string, not int
size: '2.34' # <-- string, not float

Το ίδιο ισχύει για τα booleans:

isGood: true   # bool
answer: "true" # string

Η λέξη για μια κενή τιμή είναι null (όχι nil).

Σημειώστε ότι το port: "80" είναι έγκυρη YAML, και θα περάσει τόσο από τη μηχανή template όσο και από τον parser της YAML, αλλά θα αποτύχει αν το Kubernetes αναμένει το port να είναι ακέραιος.

Σε ορισμένες περιπτώσεις, μπορείτε να επιβάλετε μια συγκεκριμένη συναγωγή τύπου χρησιμοποιώντας YAML node tags:

coffee: "yes, please"
age: !!str 21
port: !!int "80"

Στο παραπάνω, το !!str λέει στον parser ότι το age είναι string, ακόμα κι αν μοιάζει με int. Και το port αντιμετωπίζεται ως int, παρόλο που βρίσκεται σε εισαγωγικά.

Strings στην YAML

Πολλά από τα δεδομένα που τοποθετούμε σε έγγραφα YAML είναι strings. Η YAML έχει περισσότερους από έναν τρόπους για να αναπαραστήσει ένα string. Αυτή η ενότητα εξηγεί τους τρόπους και επιδεικνύει πώς να χρησιμοποιήσετε κάποιους από αυτούς.

Υπάρχουν τρεις "inline" τρόποι για να δηλώσετε ένα string:

way1: bare words
way2: "double-quoted strings"
way3: 'single-quoted strings'

Όλα τα inline styles πρέπει να είναι σε μία γραμμή.

• Τα bare words είναι χωρίς εισαγωγικά και δεν γίνεται escape. Για αυτόν τον λόγο, πρέπει να προσέχετε ποιους χαρακτήρες χρησιμοποιείτε.
• Τα double-quoted strings μπορούν να έχουν συγκεκριμένους χαρακτήρες με escape χρησιμοποιώντας \. Για παράδειγμα "\"Hello\", she said". Μπορείτε να κάνετε escape τις αλλαγές γραμμής με \n.
• Τα single-quoted strings είναι "literal" strings, και δεν χρησιμοποιούν το \ για escape χαρακτήρων. Η μόνη escape sequence είναι '', που αποκωδικοποιείται ως ένα μόνο '.

Εκτός από τα strings μιας γραμμής, μπορείτε να δηλώσετε strings πολλών γραμμών:

coffee: |
  Latte
  Cappuccino
  Espresso

Το παραπάνω θα αντιμετωπίσει την τιμή του coffee ως ένα μόνο string ισοδύναμο με Latte\nCappuccino\nEspresso\n.

Σημειώστε ότι η πρώτη γραμμή μετά το | πρέπει να έχει σωστή εσοχή. Έτσι μπορούμε να σπάσουμε το παραπάνω παράδειγμα κάνοντας αυτό:

coffee: |
         Latte
  Cappuccino
  Espresso

Επειδή το Latte έχει λανθασμένη εσοχή, θα λάβουμε ένα σφάλμα όπως αυτό:

Error parsing file: error converting YAML to JSON: yaml: line 7: did not find expected key

Στα templates, είναι μερικές φορές πιο ασφαλές να βάλετε μια ψεύτικη "πρώτη γραμμή" περιεχομένου σε ένα έγγραφο πολλών γραμμών για προστασία από το παραπάνω σφάλμα:

coffee: |
  # Commented first line
         Latte
  Cappuccino
  Espresso

Σημειώστε ότι οτιδήποτε είναι αυτή η πρώτη γραμμή, θα διατηρηθεί στην έξοδο του string. Έτσι αν, για παράδειγμα, χρησιμοποιείτε αυτή την τεχνική για να εισάγετε τα περιεχόμενα ενός αρχείου σε ένα ConfigMap, το σχόλιο πρέπει να είναι του τύπου που αναμένεται από ό,τι διαβάζει αυτή την καταχώρηση.

Έλεγχος Κενών σε Strings Πολλών Γραμμών

Στο παραπάνω παράδειγμα, χρησιμοποιήσαμε το | για να υποδείξουμε ένα string πολλών γραμμών. Αλλά παρατηρήστε ότι το περιεχόμενο του string μας ακολουθούνταν από ένα τελικό \n. Αν θέλουμε ο επεξεργαστής YAML να αφαιρέσει αυτή την τελική αλλαγή γραμμής, μπορούμε να προσθέσουμε ένα - μετά το |:

coffee: |-
  Latte
  Cappuccino
  Espresso

Τώρα η τιμή του coffee θα είναι: Latte\nCappuccino\nEspresso (χωρίς τελικό \n).

Άλλες φορές, μπορεί να θέλουμε να διατηρηθούν όλα τα κενά στο τέλος. Μπορούμε να το κάνουμε αυτό με τη σημειογραφία |+:

coffee: |+
  Latte
  Cappuccino
  Espresso


another: value

Τώρα η τιμή του coffee θα είναι Latte\nCappuccino\nEspresso\n\n\n.

Η εσοχή μέσα σε ένα text block διατηρείται, και έχει ως αποτέλεσμα τη διατήρηση των αλλαγών γραμμής επίσης:

coffee: |-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

Στην παραπάνω περίπτωση, το coffee θα είναι Latte\n 12 oz\n 16 oz\nCappuccino\nEspresso.

Εσοχή και Templates

Όταν γράφετε templates, μπορεί να θέλετε να εισάγετε τα περιεχόμενα ενός αρχείου στο template. Όπως είδαμε σε προηγούμενα κεφάλαια, υπάρχουν δύο τρόποι για να το κάνετε αυτό:

• Χρησιμοποιήστε {{ .Files.Get "FILENAME" }} για να λάβετε τα περιεχόμενα ενός αρχείου στο chart.
• Χρησιμοποιήστε {{ include "TEMPLATE" . }} για να κάνετε render ένα template και στη συνέχεια να τοποθετήσετε τα περιεχόμενά του στο chart.

Όταν εισάγετε αρχεία στην YAML, είναι καλό να κατανοήσετε τους κανόνες πολλών γραμμών παραπάνω. Συχνά, ο ευκολότερος τρόπος για να εισάγετε ένα στατικό αρχείο είναι να κάνετε κάτι σαν αυτό:

myfile: |
{{ .Files.Get "myfile.txt" | indent 2 }}

Σημειώστε πώς κάνουμε την εσοχή παραπάνω: το indent 2 λέει στη μηχανή template να προσθέσει εσοχή δύο κενών σε κάθε γραμμή του "myfile.txt". Σημειώστε ότι δεν βάζουμε εσοχή σε εκείνη τη γραμμή του template. Αυτό γιατί αν το κάναμε, το περιεχόμενο του αρχείου της πρώτης γραμμής θα είχε διπλή εσοχή.

Αναδιπλούμενα Strings Πολλών Γραμμών

Μερικές φορές θέλετε να αναπαραστήσετε ένα string στην YAML σας με πολλές γραμμές, αλλά θέλετε να αντιμετωπιστεί ως μία μακριά γραμμή όταν ερμηνεύεται. Αυτό ονομάζεται "folding". Για να δηλώσετε ένα folded block, χρησιμοποιήστε > αντί για |:

coffee: >
  Latte
  Cappuccino
  Espresso

Η τιμή του coffee παραπάνω θα είναι Latte Cappuccino Espresso\n. Σημειώστε ότι όλες εκτός από την τελευταία αλλαγή γραμμής θα μετατραπούν σε κενά. Μπορείτε να συνδυάσετε τους ελέγχους whitespace με τον δείκτη folded text, οπότε το >- θα αντικαταστήσει ή θα αφαιρέσει όλες τις αλλαγές γραμμής.

Σημειώστε ότι στη σύνταξη folding, η εσοχή κειμένου θα προκαλέσει τη διατήρηση των γραμμών.

coffee: >-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

Το παραπάνω θα παράγει Latte\n 12 oz\n 16 oz\nCappuccino Espresso. Σημειώστε ότι τόσο τα κενά όσο και οι αλλαγές γραμμής εξακολουθούν να υπάρχουν.

Ενσωμάτωση Πολλαπλών Εγγράφων σε Ένα Αρχείο

Είναι δυνατό να τοποθετήσετε περισσότερα από ένα έγγραφα YAML σε ένα μόνο αρχείο. Αυτό γίνεται προτάσσοντας ένα νέο έγγραφο με --- και τερματίζοντας το έγγραφο με ...

---
document: 1
...
---
document: 2
...

Σε πολλές περιπτώσεις, είτε το --- είτε το ... μπορεί να παραλειφθεί.

Ορισμένα αρχεία στο Helm δεν μπορούν να περιέχουν περισσότερα από ένα έγγραφα. Αν, για παράδειγμα, παρέχεται περισσότερο από ένα έγγραφο μέσα σε ένα αρχείο values.yaml, μόνο το πρώτο θα χρησιμοποιηθεί.

Τα αρχεία template, ωστόσο, μπορεί να έχουν περισσότερα από ένα έγγραφα. Όταν συμβαίνει αυτό, το αρχείο (και όλα τα έγγραφά του) αντιμετωπίζεται ως ένα αντικείμενο κατά το rendering του template. Αλλά στη συνέχεια η προκύπτουσα YAML διαχωρίζεται σε πολλαπλά έγγραφα πριν τροφοδοτηθεί στο Kubernetes.

Συνιστούμε να χρησιμοποιείτε πολλαπλά έγγραφα ανά αρχείο μόνο όταν είναι απολύτως απαραίτητο. Η ύπαρξη πολλαπλών εγγράφων σε ένα αρχείο μπορεί να είναι δύσκολη στην αποσφαλμάτωση.

Η YAML είναι Υπερσύνολο της JSON

Επειδή η YAML είναι υπερσύνολο της JSON, κάθε έγκυρο έγγραφο JSON θα πρέπει να είναι έγκυρη YAML.

{
  "coffee": "yes, please",
  "coffees": [
    "Latte", "Cappuccino", "Espresso"
  ]
}

Το παραπάνω είναι ένας άλλος τρόπος αναπαράστασης αυτού:

coffee: yes, please
coffees:
- Latte
- Cappuccino
- Espresso

Και τα δύο μπορούν να αναμειχθούν (με προσοχή):

coffee: "yes, please"
coffees: [ "Latte", "Cappuccino", "Espresso"]

Και τα τρία πρέπει να αναλυθούν στην ίδια εσωτερική αναπαράσταση.

Ενώ αυτό σημαίνει ότι αρχεία όπως το values.yaml μπορούν να περιέχουν δεδομένα JSON, το Helm δεν αντιμετωπίζει την επέκταση αρχείου .json ως έγκυρο επίθημα.

YAML Anchors

Η προδιαγραφή YAML παρέχει έναν τρόπο για να αποθηκεύσετε μια αναφορά σε μια τιμή, και αργότερα να αναφερθείτε σε αυτή την τιμή μέσω αναφοράς. Η YAML αναφέρεται σε αυτό ως "anchoring":

coffee: "yes, please"
favorite: &favoriteCoffee "Cappuccino"
coffees:
  - Latte
  - *favoriteCoffee
  - Espresso

Στο παραπάνω, το &favoriteCoffee ορίζει μια αναφορά στο Cappuccino. Αργότερα, αυτή η αναφορά χρησιμοποιείται ως *favoriteCoffee. Έτσι το coffees γίνεται Latte, Cappuccino, Espresso.

Ενώ υπάρχουν μερικές περιπτώσεις όπου τα anchors είναι χρήσιμα, υπάρχει μια πτυχή τους που μπορεί να προκαλέσει ανεπαίσθητα σφάλματα: Την πρώτη φορά που η YAML καταναλώνεται, η αναφορά επεκτείνεται και στη συνέχεια απορρίπτεται.

Έτσι αν αποκωδικοποιούσαμε και στη συνέχεια επανακωδικοποιούσαμε το παραπάνω παράδειγμα, η προκύπτουσα YAML θα ήταν:

coffee: yes, please
favorite: Cappuccino
coffees:
- Latte
- Cappuccino
- Espresso

Επειδή το Helm και το Kubernetes συχνά διαβάζουν, τροποποιούν και στη συνέχεια ξαναγράφουν αρχεία YAML, τα anchors θα χαθούν.