Values

Αυτό το μέρος του Οδηγού Βέλτιστων Πρακτικών καλύπτει τη χρήση των values. Σε αυτόν τον τομέα του οδηγού, παρέχουμε συστάσεις σχετικά με τον τρόπο που θα πρέπει να δομείτε και να χρησιμοποιείτε τα values, με έμφαση στο σχεδιασμό του αρχείου values.yaml ενός chart.

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

Τα ονόματα των μεταβλητών θα πρέπει να ξεκινούν με πεζό γράμμα, και οι λέξεις θα πρέπει να διαχωρίζονται με camelcase:

Σωστό:

chicken: true
chickenNoodleSoup: true

Λάθος:

Chicken: true  # initial caps may conflict with built-ins
chicken-noodle-soup: true # do not use hyphens in the name

Σημειώστε ότι όλες οι ενσωματωμένες μεταβλητές του Helm ξεκινούν με κεφαλαίο γράμμα για να διακρίνονται εύκολα από τα values που ορίζει ο χρήστης: .Release.Name, .Capabilities.KubeVersion.

Επίπεδα ή Ένθετα Values

Το YAML είναι μια ευέλικτη μορφή, και τα values μπορούν να είναι βαθιά ένθετα ή επίπεδα.

Ένθετα:

server:
  name: nginx
  port: 80

Επίπεδα:

serverName: nginx
serverPort: 80

Στις περισσότερες περιπτώσεις, τα επίπεδα values είναι προτιμότερα από τα ένθετα. Ο λόγος είναι ότι είναι απλούστερα τόσο για τους developers των templates όσο και για τους χρήστες.

Για βέλτιστη ασφάλεια, ένα ένθετο value πρέπει να ελέγχεται σε κάθε επίπεδο:

{{ if .Values.server }}
  {{ default "none" .Values.server.name }}
{{ end }}

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

{{ default "none" .Values.serverName }}

Όταν υπάρχει μεγάλος αριθμός σχετικών μεταβλητών, και τουλάχιστον μία από αυτές είναι υποχρεωτική, μπορούν να χρησιμοποιηθούν ένθετα values για βελτίωση της αναγνωσιμότητας.

Διευκρινίστε τους Τύπους

Οι κανόνες μετατροπής τύπων του YAML είναι μερικές φορές απροσδόκητοι. Για παράδειγμα, το foo: false δεν είναι το ίδιο με το foo: "false". Μεγάλοι ακέραιοι αριθμοί όπως το foo: 12345678 μπορεί να μετατραπούν σε επιστημονική σημειογραφία σε ορισμένες περιπτώσεις.

Ο ευκολότερος τρόπος να αποφύγετε σφάλματα μετατροπής τύπων είναι να είστε σαφείς με τα strings και να αφήνετε τα υπόλοιπα ως έχουν. Ή, με λίγα λόγια, βάζετε όλα τα strings σε εισαγωγικά.

Συχνά, για να αποφευχθούν προβλήματα με τη μετατροπή ακεραίων, είναι προτιμότερο να αποθηκεύετε τους ακέραιους ως strings, και να χρησιμοποιείτε το {{ int $value }} στο template για μετατροπή από string σε ακέραιο.

Στις περισσότερες περιπτώσεις, οι ρητές ετικέτες τύπων αναγνωρίζονται σωστά, οπότε το foo: !!string 1234 θα αντιμετωπίσει το 1234 ως string. Ωστόσο, ο YAML parser καταναλώνει τις ετικέτες, οπότε οι πληροφορίες τύπου χάνονται μετά από μία ανάλυση.

Σκεφτείτε πώς θα Χρησιμοποιήσουν οι Χρήστες τα Values

Υπάρχουν τρεις πιθανές πηγές για τα values:

• Το αρχείο values.yaml του chart
• Ένα αρχείο values που παρέχεται με τις εντολές helm install -f ή helm upgrade -f
• Τα values που περνούν μέσω του flag --set ή --set-string στις εντολές helm install ή helm upgrade

Κατά το σχεδιασμό της δομής των values σας, έχετε υπόψη ότι οι χρήστες του chart μπορεί να θέλουν να τα παρακάμψουν είτε μέσω του flag -f είτε με την επιλογή --set.

Δεδομένου ότι το --set έχει περιορισμένη εκφραστικότητα, η πρώτη κατευθυντήρια γραμμή για τη συγγραφή του αρχείου values.yaml είναι να το κάνετε εύκολο να παρακαμφθεί από το --set.

Για αυτόν τον λόγο, είναι συχνά καλύτερο να δομείτε το αρχείο values χρησιμοποιώντας maps.

Δύσκολο στη χρήση με --set:

servers:
  - name: foo
    port: 80
  - name: bar
    port: 81

Το παραπάνω δεν μπορεί να εκφραστεί με --set στο Helm <=2.4. Στο Helm 2.5, η πρόσβαση στο port του foo είναι --set servers[0].port=80. Όχι μόνο είναι δυσκολότερο για τον χρήστη να το βρει, αλλά είναι επιρρεπές σε σφάλματα αν αργότερα αλλάξει η σειρά των servers.

Εύκολο στη χρήση:

servers:
  foo:
    port: 80
  bar:
    port: 81

Η πρόσβαση στο port του foo είναι πολύ πιο προφανής: --set servers.foo.port=80.

Τεκμηρίωση του values.yaml

Κάθε ορισμένη ιδιότητα στο values.yaml θα πρέπει να τεκμηριώνεται. Το σχόλιο τεκμηρίωσης θα πρέπει να ξεκινά με το όνομα της ιδιότητας που περιγράφει και στη συνέχεια να δίνει τουλάχιστον μια πρόταση περιγραφής.

Λάθος:

# the host name for the webserver \{#the-host-name-for-the-webserver}
serverHost: example
serverPort: 9191

Σωστό:

# serverHost is the host name for the webserver \{#serverhost-is-the-host-name-for-the-webserver}
serverHost: example
# serverPort is the HTTP listener port for the webserver \{#serverport-is-the-http-listener-port-for-the-webserver}
serverPort: 9191

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