Hooks σε Charts

Το Helm παρέχει έναν μηχανισμό hook που επιτρέπει στους δημιουργούς charts να παρεμβαίνουν σε συγκεκριμένα σημεία του κύκλου ζωής ενός release. Για παράδειγμα, μπορείτε να χρησιμοποιήσετε hooks για να:

• Φορτώσετε ένα ConfigMap ή Secret κατά την εγκατάσταση πριν φορτωθούν τυχόν άλλα charts.
• Εκτελέσετε ένα Job για δημιουργία αντιγράφου ασφαλείας μιας βάσης δεδομένων πριν από την εγκατάσταση ενός νέου chart, και στη συνέχεια εκτελέσετε ένα δεύτερο job μετά την αναβάθμιση για να επαναφέρετε τα δεδομένα.
• Εκτελέσετε ένα Job πριν από τη διαγραφή ενός release για να αφαιρέσετε ομαλά μια υπηρεσία από την εναλλαγή πριν την αφαιρέσετε.

Τα hooks λειτουργούν όπως τα κανονικά templates, αλλά έχουν ειδικά annotations που αναγκάζουν το Helm να τα χειρίζεται διαφορετικά. Σε αυτήν την ενότητα καλύπτουμε το βασικό μοτίβο χρήσης για τα hooks.

Τα Διαθέσιμα Hooks

Ορίζονται τα ακόλουθα hooks:

Τιμή Annotation	Περιγραφή
pre-install	Εκτελείται μετά την απόδοση των templates, αλλά πριν τη δημιουργία οποιουδήποτε πόρου στο Kubernetes
post-install	Εκτελείται μετά τη φόρτωση όλων των πόρων στο Kubernetes
pre-delete	Εκτελείται σε αίτημα διαγραφής πριν τη διαγραφή οποιουδήποτε πόρου από το Kubernetes
post-delete	Εκτελείται σε αίτημα διαγραφής αφού διαγραφούν όλοι οι πόροι του release
pre-upgrade	Εκτελείται σε αίτημα αναβάθμισης μετά την απόδοση των templates, αλλά πριν ενημερωθεί οποιοσδήποτε πόρος
post-upgrade	Εκτελείται σε αίτημα αναβάθμισης μετά την αναβάθμιση όλων των πόρων
pre-rollback	Εκτελείται σε αίτημα rollback μετά την απόδοση των templates, αλλά πριν γίνει rollback οποιουδήποτε πόρου
post-rollback	Εκτελείται σε αίτημα rollback αφού τροποποιηθούν όλοι οι πόροι
test	Εκτελείται όταν καλείται η υποεντολή test του Helm (δείτε την τεκμηρίωση test)

Σημείωση: το hook crd-install έχει καταργηθεί υπέρ του φακέλου crds/ στο Helm 3.

Hooks και ο Κύκλος Ζωής του Release

Τα hooks σας επιτρέπουν, ως δημιουργό chart, να εκτελείτε λειτουργίες σε στρατηγικά σημεία του κύκλου ζωής ενός release. Για παράδειγμα, σκεφτείτε τον κύκλο ζωής για ένα helm install. Από προεπιλογή, ο κύκλος ζωής είναι ο εξής:

1. Ο χρήστης εκτελεί helm install foo
2. Καλείται το API εγκατάστασης της βιβλιοθήκης Helm
3. Μετά από ορισμένες επαληθεύσεις, η βιβλιοθήκη αποδίδει τα templates του foo
4. Η βιβλιοθήκη φορτώνει τους προκύπτοντες πόρους στο Kubernetes
5. Η βιβλιοθήκη επιστρέφει το αντικείμενο release (και άλλα δεδομένα) στον client
6. Ο client τερματίζει

Το Helm ορίζει δύο hooks για τον κύκλο ζωής install: pre-install και post-install. Αν ο δημιουργός του chart foo υλοποιήσει και τα δύο hooks, ο κύκλος ζωής τροποποιείται ως εξής:

1. Ο χρήστης εκτελεί helm install foo
2. Καλείται το API εγκατάστασης της βιβλιοθήκης Helm
3. Εγκαθίστανται τα CRDs στον φάκελο crds/
4. Μετά από ορισμένες επαληθεύσεις, η βιβλιοθήκη αποδίδει τα templates του foo
5. Η βιβλιοθήκη προετοιμάζεται να εκτελέσει τα hooks pre-install (φορτώνοντας τους πόρους hook στο Kubernetes)
6. Η βιβλιοθήκη ταξινομεί τα hooks κατά βάρος (αναθέτοντας βάρος 0 από προεπιλογή), κατά τύπο πόρου και τέλος κατά όνομα σε αύξουσα σειρά.
7. Η βιβλιοθήκη φορτώνει πρώτα το hook με το μικρότερο βάρος (αρνητικό προς θετικό)
8. Η βιβλιοθήκη περιμένει μέχρι το hook να είναι "Ready" (εκτός από τα CRDs)
9. Η βιβλιοθήκη φορτώνει τους προκύπτοντες πόρους στο Kubernetes. Σημειώστε ότι αν έχει οριστεί η σημαία --wait, η βιβλιοθήκη θα περιμένει μέχρι όλοι οι πόροι να βρίσκονται σε κατάσταση ready και δεν θα εκτελέσει το hook post-install μέχρι να είναι έτοιμοι.
10. Η βιβλιοθήκη εκτελεί το hook post-install (φορτώνοντας τους πόρους hook)
11. Η βιβλιοθήκη περιμένει μέχρι το hook να είναι "Ready"
12. Η βιβλιοθήκη επιστρέφει το αντικείμενο release (και άλλα δεδομένα) στον client
13. Ο client τερματίζει

Τι σημαίνει να περιμένουμε μέχρι ένα hook να είναι ready; Αυτό εξαρτάται από τον πόρο που δηλώνεται στο hook. Αν ο πόρος είναι τύπου Job ή Pod, το Helm θα περιμένει μέχρι να ολοκληρωθεί επιτυχώς. Και αν το hook αποτύχει, το release θα αποτύχει. Αυτή είναι μια blocking λειτουργία, επομένως ο client του Helm θα παραμείνει σε αναμονή κατά την εκτέλεση του Job.

Για όλους τους άλλους τύπους, μόλις το Kubernetes σημειώσει τον πόρο ως φορτωμένο (προστέθηκε ή ενημερώθηκε), ο πόρος θεωρείται "Ready". Όταν πολλοί πόροι δηλώνονται σε ένα hook, οι πόροι εκτελούνται διαδοχικά. Αν έχουν βάρη hook (δείτε παρακάτω), εκτελούνται με σειρά βάρους. Από το Helm 3.2.0, οι πόροι hook με το ίδιο βάρος εγκαθίστανται με την ίδια σειρά όπως οι κανονικοί πόροι που δεν είναι hook. Διαφορετικά, η σειρά δεν είναι εγγυημένη. (Στο Helm 2.3.0 και μετά, ταξινομούνται αλφαβητικά. Αυτή η συμπεριφορά, ωστόσο, δεν θεωρείται δεσμευτική και μπορεί να αλλάξει στο μέλλον.) Θεωρείται καλή πρακτική να προσθέτετε ένα βάρος hook και να το ορίζετε σε 0 αν το βάρος δεν είναι σημαντικό.

Οι πόροι hook δεν διαχειρίζονται μαζί με τα αντίστοιχα releases

Οι πόροι που δημιουργεί ένα hook δεν παρακολουθούνται ούτε διαχειρίζονται ως μέρος του release προς το παρόν. Μόλις το Helm επαληθεύσει ότι το hook έχει φτάσει στην κατάσταση ready, θα αφήσει τον πόρο hook ως έχει. Η συλλογή απορριμμάτων των πόρων hook όταν διαγράφεται το αντίστοιχο release μπορεί να προστεθεί στο Helm 3 στο μέλλον, επομένως οποιοιδήποτε πόροι hook που δεν πρέπει ποτέ να διαγραφούν θα πρέπει να φέρουν το annotation helm.sh/resource-policy: keep.

Πρακτικά, αυτό σημαίνει ότι αν δημιουργήσετε πόρους σε ένα hook, δεν μπορείτε να βασιστείτε στο helm uninstall για να αφαιρέσει τους πόρους. Για να καταστρέψετε τέτοιους πόρους, πρέπει είτε να προσθέσετε ένα προσαρμοσμένο annotation helm.sh/hook-delete-policy στο αρχείο template του hook, είτε να ορίσετε το πεδίο time to live (TTL - χρόνος ζωής) Job.

Συγγραφή ενός Hook

Τα hooks είναι απλά αρχεία manifest του Kubernetes με ειδικά annotations στην ενότητα metadata. Επειδή είναι αρχεία template, μπορείτε να χρησιμοποιήσετε όλες τις κανονικές δυνατότητες template, συμπεριλαμβανομένης της ανάγνωσης .Values, .Release και .Template.

Για παράδειγμα, αυτό το template, αποθηκευμένο στο templates/post-install-job.yaml, δηλώνει ένα job που θα εκτελεστεί στο post-install:

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}"
  labels:
    app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
    app.kubernetes.io/instance: {{ .Release.Name | quote }}
    app.kubernetes.io/version: {{ .Chart.AppVersion }}
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  annotations:
    # This is what defines this resource as a hook. Without this line, the
    # job is considered part of the release.
    "helm.sh/hook": post-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    metadata:
      name: "{{ .Release.Name }}"
      labels:
        app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
        app.kubernetes.io/instance: {{ .Release.Name | quote }}
        helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
    spec:
      restartPolicy: Never
      containers:
      - name: post-install-job
        image: "alpine:3.3"
        command: ["/bin/sleep","{{ default "10" .Values.sleepyTime }}"]

Αυτό που κάνει αυτό το template να είναι hook είναι το annotation:

annotations:
  "helm.sh/hook": post-install

Ένας πόρος μπορεί να υλοποιήσει πολλαπλά hooks:

annotations:
  "helm.sh/hook": post-install,post-upgrade

Ομοίως, δεν υπάρχει όριο στον αριθμό των διαφορετικών πόρων που μπορούν να υλοποιήσουν ένα συγκεκριμένο hook. Για παράδειγμα, μπορείτε να δηλώσετε τόσο ένα secret όσο και ένα config map ως hook pre-install.

Όταν τα subcharts δηλώνουν hooks, αυτά αξιολογούνται επίσης. Δεν υπάρχει τρόπος για ένα chart ανώτερου επιπέδου να απενεργοποιήσει τα hooks που δηλώνονται από τα subcharts.

Είναι δυνατός ο ορισμός ενός βάρους για ένα hook που θα βοηθήσει στη δημιουργία μιας καθορισμένης σειράς εκτέλεσης. Τα βάρη ορίζονται χρησιμοποιώντας το ακόλουθο annotation:

annotations:
  "helm.sh/hook-weight": "5"

Τα βάρη hook μπορούν να είναι θετικοί ή αρνητικοί αριθμοί αλλά πρέπει να αναπαρίστανται ως strings. Όταν το Helm ξεκινά τον κύκλο εκτέλεσης των hooks ενός συγκεκριμένου τύπου, θα ταξινομήσει αυτά τα hooks σε αύξουσα σειρά.

Πολιτικές διαγραφής hook

Είναι δυνατός ο ορισμός πολιτικών που καθορίζουν πότε θα διαγραφούν οι αντίστοιχοι πόροι hook. Οι πολιτικές διαγραφής hook ορίζονται χρησιμοποιώντας το ακόλουθο annotation:

annotations:
  "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

Μπορείτε να επιλέξετε μία ή περισσότερες καθορισμένες τιμές annotation:

Τιμή Annotation	Περιγραφή
before-hook-creation	Διαγράφει τον προηγούμενο πόρο πριν εκκινηθεί ένα νέο hook (προεπιλογή)
hook-succeeded	Διαγράφει τον πόρο μετά την επιτυχή εκτέλεση του hook
hook-failed	Διαγράφει τον πόρο αν το hook απέτυχε κατά την εκτέλεση

Αν δεν καθοριστεί annotation πολιτικής διαγραφής hook, εφαρμόζεται η συμπεριφορά before-hook-creation από προεπιλογή.