hull
hull-demo-1.31.2
Ce référentiel contient le graphique de la bibliothèque Hull Helm. Il est conçu pour faciliter la construction, le maintien et la configuration d'objets Kubernetes dans les graphiques de barre et peuvent être ajoutés à n'importe quel graphique de barre en tant qu'addon pour améliorer la fonctionnalité sans risque de briser les configurations de graphique de barre existantes.
Le graphique lui-même et toute la documentation qui y sont liés se trouve dans le dossier hull qui est le dossier racine du graphique de la barre de la bibliothèque de Hull.
Les schémas JSON de l'API Kubernetes sont stockés dans le dossier kubernetes-json-schema .
Vous trouverez ci-dessous les graphiques de coque README.md :
Les abstractions doivent être maintenues - Kelsey Hightower
Un aspect de conception majeur de Helm est qu'il oblige l'utilisateur à créer des abstractions individuelles de la configuration des applications Kubernetes. Pour chaque graphique de barre individuel qui est réalisé sous forme de modèles YAML dans un dossier Helm Charts /templates . Ces fichiers de modèle, contenant des blocs de code YAML Kubernetes YAML, contenant une part et des mappages de configuration personnalisés en utilisant des expressions de modèles GO, d'autre part, fournissent la colle entre la configuration de l'application via le fichier de configuration central values.yaml . On peut dire que cette approche de l'abstraction par application est bien adaptée pour créer des packages de configuration tailormade pour même les applications les plus spécialisées, mais a le coût d'avoir une grande surface pour des cas d'utilisation de l'emballage d'applications d'applications plus simples, récurrentes et standard. La création, le maintien et la compréhension (souvent) des abstractions introduites par les graphiques de barre - en particulier lorsqu'ils sont confrontés à un nombre élevé de graphiques de barre individuels provenant de diverses sources - peuvent devenir fastidieux et difficiles.
La principale caractéristique de la bibliothèque Hull est la possibilité de supprimer entièrement des fichiers de modèles YAML personnalisés à partir de workflows de graphique de barre et permettant ainsi de supprimer un niveau d'abstraction. À l'aide du graphique de la bibliothèque Hull, les objets Kubernetes, y compris toutes leurs propriétés, peuvent être spécifiés complètement et de manière transparente dans les values.yaml . Le graphique de la bibliothèque de Hull lui-même fournit la couche uniforme pour rationaliser la spécification, la configuration et le rendu des graphiques de barre pour y parvenir. Vous pouvez également le considérer comme une fine couche au-dessus de l'API de Kubernetes pour éviter l'intermédiaire entre le graphique de la barre et la configuration de l'objet API Kubernetes, tout en offrant une flexibilité lorsqu'elle est nécessaire pour personnaliser les options de configuration individuelles au lieu de vous obliger à ajouter chaque commutateur de configuration. manuellement aux modèles. La validation du schéma JSON basé sur la fonctionnalité de validation JSON Helm (via values.schema.json ) aide à écrire des objets conformes à l'API de Kubernetes dès le début lors de l'utilisation d'un IDE qui prend en charge la validation du schéma JSON en direct. Avantages supplémentaires (métadonnées d'objets héréditaires uniformes, inclusion simplifiée de configmaps / secrets, valeurs de référence dans les values.yaml , ...) sont disponibles avec la coque dont vous pouvez lire ci-dessous dans la vue d'ensemble des caractéristiques clés . Mais peut-être plus important encore, la bibliothèque de Hull peut être ajoutée en tant que dépendance à tout graphique de barre existant et être utilisée côte à côte sans casser les fonctionnalités des graphiques de barre existants, voir l'ajout du graphique de la bibliothèque de la coque à un graphique de barre pour plus d'informations. Et enfin, en étant un tableau de bibliothèque lui-même, tout fonctionne à 100% dans la fonctionnalité offerte par Helm - aucun outil supplémentaire n'est introduit ou impliqué.
Vos commentaires sur ce projet sont appréciés, veuillez donc commenter ou démarrer une discussion dans la section Issues ou créer des souhaits de fonctionnalités et des rapports de bogues. Merci!
L'idée du graphique de la bibliothèque de Hull est en partie inspirée par le concept de graphique de tête commun et pour tester
.
hull-demo Avant de plonger dans les détails de Hull, voici un premier aperçu de son fonctionnement. Vous pouvez simplement télécharger la dernière version du graphique hull-demo Helm à partir de la section des versions de cette page, il a tout botté pour tester la coque ou la création d'un nouveau graphique de barre basé sur Hull avec un minimum d'effort.
Le graphique hull-demo enveloppe une application fictive myapp avec un frontend et backend déploiement et paire de services. Il existe un fichier de configuration pour la configuration du serveur qui est monté sur les pods backend . Les pods frontend doivent connaître l'adresse du service backend via des variables environnementales. De plus, la configuration doit par défaut être facilement commutable à partir d'une configuration debug (en utilisant un Nodeport pour accéder au frontend) à une configuration de type production (en utilisant un service ClusterIp et une entrée).
Une structure par défaut nue pour capturer ces aspects peut ressembler à ceci (avec des commentaires de ligne supplémentaires pour l'explication):
hull : # HULL is configured via subchart key 'hull'
config : # chart setup takes place here for everything besides object definitions
specific : # central place for shared values specific to this chart
debug : true # a switch influencing creation of objects in this chart
application_version : v23.1 # a shared image tag for multiple container
myapp : # some exemplary configuration settings for the app, exposed here for transparency
rate_limit : 100
max_connections : 5
objects : # all objects to create are defined here
deployment : # create deployments
myapp-frontend : # the base part of the object name for frontend deployment
pod : # configure pod-related aspects
containers : # non-init containers
main : # one main container
image : # provide image reference
repository : mycompany/myapp-frontend # repository
tag : _HT*hull.config.specific.application_version # reference to central tag value above
ports : # exposed ports
http : # port name is http
containerPort : 80 # the port number
env : # environment variables
SERVER_HOSTNAME : # name of variable
value : _HT^myapp-backend # value is dynamically rendered reference to myapp-backend service name
SERVER_PORT : # name of variable
value : " 8080 " # backend service port
myapp-backend : # the base part of the object name for backend deployment
pod : # configure pod-related aspects
containers : # non-init containers
main : # one main container
image : # image reference
repository : mycompany/myapp-backend # repository
tag : _HT*hull.config.specific.application_version # reference to central tag value above
ports : # exposed ports
http : # port name is http
containerPort : 8080 # the port number
volumeMounts : # mounts of the container
appconfig : # context key is appconfig
name : myappconfig # the name needs to match a volume
mountPath : /etc/config/appconfig.json # mountPath
subPath : backend-appconfig.json # subPath
volumes : # volumes that may be mounted
myappconfig : # key matching a volumeMounts name
configMap : # configmap reference
name : myappconfig # the configmap to load, simply referenced by key name
configmap : # create configmaps
myappconfig : # the backend configuration
data : # data section
backend-appconfig.json : # key name is file name
serialization : toPrettyJson # serialize the dictionary content of inline to pretty Json
inline : # define the contents of the file as a dictionary for convenience
rate-limit : _HT*hull.config.specific.myapp.rate_limit
max-connections : _HT*hull.config.specific.myapp.max_connections
debug-log : _HT!{{ if _HT*hull.config.specific.debug }}true{{ else }}false{{ end }}
service : # create services
myapp-frontend : # frontend service, automatically matches pods with identical parent object's key name
ports : # definition of service ports
http : # http port for type=ClusterIP
enabled : _HT?not _HT*hull.config.specific.debug # bind rendering to debug: false condition, use embedded transformation to reference field
port : 80 # regular port
targetPort : http # targetPort setting
http_nodeport : # http port for type=NodePort
enabled : _HT?_HT*hull.config.specific.debug # bind rendering to debug: true condition
port : 80 # regular port
nodePort : 31111 # the node port
targetPort : http # targetPort setting
type : |- # dynamically switch type based on hull.config.specific.debug setting
_HT!
{{- if _HT*hull.config.specific.debug -}}
NodePort
{{- else -}}
ClusterIP
{{- end -}}
myapp-backend : # backend service, automatically matches pods with identical parent object's key name
ports : # definition of service ports
http : # http port
port : 8080 # regular port
targetPort : http # targetPort setting
type : ClusterIP # in cluster service
ingress : # create ingresses
myapp : # the central frontend ingress
enabled : _HT?not _HT*hull.config.specific.debug # rendering bound to debug: false
rules : # the ingress rules
myapp : # key-value dictionary of rules
host : SET_HOSTNAME_HERE # change the host at deployment time to actual one
http : # http settings
paths : # paths definition
standard : # a standard path definition
path : / # could be changed at deployment time
pathType : ImplementationSpecific # path type
backend : # backend config
service : # service targeted
name : myapp-frontend # key name suffices to reference service created in this chart
port : # target port
name : http # target port name Ceci est l'exemple constituant des values.yaml de hull-demo , si vous téléchargez la dernière version hull-demo et exécutez:
helm template hull-demo-<version>.tgz
il rend un ensemble d'objets basés sur values.yaml ci-dessus.
myapp-frontend qui a un jeu de tag d'image configuré de manière centralisée (par défaut v23.1 ), et des variables d'environnement pointant vers l'adresse du service de myapp-backendmyapp-backend qui a un jeu tag d'image configuré de manière centralisée (par défaut v23.1 ) et une configuration montée à partir de la configmap myappconfigmyappconfig configmap avec un fichier json qui est construit dynamiquement en incorporant les expressions de modèles et référencer les valeurs définies ailleurs dans values.yamlmyapp-backendmyapp-frontend dont la configuration du type et du port est la dépendance sur le commutateur debug central - soit tapez NodePort en mode de configuration debug ou tapez ClusterIP en combinaison avec une entrée myapp dans des configurations non-debugmyapp qui n'est rendu / créé en cas de debug: false valeur est définie Chaque aspect de cette configuration peut être modifié ou écrasé au moment du déploiement en utilisant values.yaml supplémentaires.yaml Files de superposition, par exemple:
debug par les paramètres debug: true ou debug: falsemyapp configmaps ( rate_limit et max_connections ) ou le remplacer complètement Tous les objets et la logique ont été créés avec moins d'une centaine de lignes de code de configuration global dans les values.yaml de hull-demo . Vous pouvez tester tous les aspects mentionnés ci-dessus ou simplement expérimenter en ajoutant helm template values.yaml supplémentaires. Pour bootstrap votre name graphique de barre, videz simplement Chart.yaml configuration values.yaml .
Il s'agit d'une première démo de la façon dont Hull pourrait être utilisé, mais il y a beaucoup plus de fonctionnalités et de cas d'utilisation pris en charge. Vérifiez les fonctionnalités clés et la documentation détaillée pour plus d'informations.
Comme indiqué ci-dessus, lorsqu'il est inclus dans un graphique de barre, le graphique de la bibliothèque de Hull peut reprendre le travail de rendu dynamiquement des objets Kubernetes à partir de leurs spécifications données du fichier values.yaml seul. Avec la construction d'objets YAML reportée aux fonctions de modèles GO de la bibliothèque Hull au lieu de modèles YAML personnalisés dans le dossier /templates vous pouvez appliquer de manière centralisée les meilleures pratiques:
Concentrez-vous sur ce qui est nécessaire pour spécifier des objets Kubernetes sans avoir à ajouter des modèles YAML individuels YAML à votre graphique. Cela supprime une source commune d'erreurs et de maintenance du flux de travail régulier de Helm. Pour que la sortie rendu de la coque soit conforme à la spécification de l'API Kubernetes, un grand nombre de tests unitaires valident la sortie rendu de la coque contre le schéma JSON de l'API Kubernetes.
Pour plus de détails, reportez-vous à la documentation sur la validation du schéma JSON.
Pour tous les types d'objets Kubernetes pris en charge par Hull, un accès de configuration complet aux propriétés des types d'objets Kubernetes est directement disponible . Cela soulage les responsables du diagramme de devoir ajouter des options de configuration manquantes une par une et les utilisateurs du graphique de la barre de fournir le graphique de la barre pour ajouter uniquement les propriétés dont ils ont besoin pour leur configuration. La mise à jour uniquement du graphique de la coque vers une version plus récente avec la version API Kubernetes correspondante est nécessaire pour activer la configuration des propriétés ajoutées aux objets Kubernetes en attendant dans les versions API plus récentes. Les graphiques de coque sont versés pour refléter les versions API Kubernetes minimales les prises en charge.
Pour plus de détails, reportez-vous à la documentation sur la vue d'ensemble de l'architecture.
L'interface unique de la bibliothèque Hull est utilisée pour créer et configurer des objets dans des graphiques pour le déploiement. Cela favorise la compréhension mutuelle des créateurs de graphiques / responsables et des consommateurs de la façon dont le graphique fonctionne réellement et de ce qu'il contient. Creuser dans le dossier /templates pour comprendre les implications des graphiques de barre n'est plus nécessaire. Pour éviter toute mauvaise configuration, l'interface de la bibliothèque - les values.yaml de la bibliothèque de coque - est entièrement validée par JSON. Lorsque vous utilisez un IDE prenant en charge la validation du schéma JSON en direct (par exemple VSCODE), vous pouvez obtenir des conseils IDE lors de la création des objets de coque. Avant le rendu, la conformité du schéma JSON est validée par la bibliothèque de Hull.
Pour plus de détails, reportez-vous à la documentation sur la validation du schéma JSON.
Les métadonnées uniformes et riches sont automatiquement attachées à tous les objets créés par la bibliothèque Hull.
Pour plus de détails sur l'écrasement des métadonnées, reportez-vous à l'exemple avancé ci-dessous.
Gestion flexible de la configmap et des entrées secrètes en choisissant entre la spécification en ligne du contenu dans values.yaml ou l'importation à partir de fichiers externes pour le contenu de plus grandes tailles. Lors de l'importation de données à partir de fichiers, les données peuvent être exécutées via le moteur de modèles ou importées non complétées 'comme «si elle contient déjà des expressions de modèles qui doivent être transmises à l'application consommée. En mettant l'accent sur la gestion pratique des scénarios standard, vous pouvez également définir le contenu du fichier comme une structure YAML ordinaire dans les values.yaml et faire sérialiser la coque automatiquement à JSON ou YAML par l'extension de fichier ou explicitement à toute représentation de votre choix. Hull s'occupe du codage de base64 de secrets, de sorte que l'écriture de configmaps et de secrets fonctionne exactement de la même manière et l'ajout de configmaps ou de secrets à votre déploiement ne nécessite que quelques lignes de code.
Pour plus de détails, reportez-vous à la documentation sur les configmaps et les secrets.
Capacités de défaillance étendues pour instanier des instances d'objets. Que vous souhaitiez que toutes vos instances d'objet ou groupes d'instances partagent certains aspects tels que des étiquettes ou des annotations, des variables d'environnement de conteneur ou des volumes montés, Hull prend en charge pour définir efficacement les valeurs par défaut pour les champs d'instance d'objet en évitant les répétitions de configuration inutiles.
Pour plus de détails, reportez-vous aux conseils de conception des graphiques.
Pour les scénarios plus complexes où les valeurs réelles dans le YAML cible sont soumises à des configurations dans les values.yaml , il y a un support pour remplir dynamiquement les valeurs en injectant les expressions de modèles GO définies à la place de la valeur dans les values.yaml . Par exemple, si vos arguments de conteneur en béton dépendent de divers autres paramètres dans values.yaml values.yaml .
Pour plus de détails, reportez-vous à la documentation sur les transformations.
Activer le hachage automatique des configmaps et des secrets référencés pour faciliter les redémarrages du pod sur les modifications de configuration en cas de besoin.
Pour plus de détails, reportez-vous à la documentation sur les pods.
Pour en savoir plus sur l'architecture générale et les fonctionnalités de la bibliothèque de Hull, voir la vue d'ensemble de l'architecture
Quelques choses importantes à mentionner d'abord avant de regarder la bibliothèque plus en détail:
/templates n'est pas affecté par l'intégration du tableau de la bibliothèque de coque. Parfois, vous pouvez avoir des exigences très spécifiques sur votre configuration ou votre spécification d'objet que la bibliothèque Hull ne répond pas, vous pouvez donc utiliser le flux de travail de casque ordinaire pour eux et la bibliothèque de coque pour vos besoins plus standard - facilement en parallèle dans le même graphique de barre.
hull.yaml , doit être copié `` As-Is '' sans aucune modification d'un dossier racine de graphiques de coque intégré au dossier des graphiques /templates parents pour pouvoir rendre n'importe quel yaml via la coque. Il contient le code qui initie le pipeline de rendu de la coque, voir l'ajout de la carte de bibliothèque de Hull à un graphique de barre pour plus de détails!
3.0.x ne sont pas compatibles avec la coque, toutes les autres versions non bêta et non alpha existantes sont compatibles.
1.29 et 1.30 et 1.31 ont une libération de coque assortie et maintenue.
Si vous aimez une approche pratique, vous êtes invité à jeter un œil à la nouvelle série Tutorials Hull à Dev.to! Le tutoriel Eigth Part commencera depuis le tout début de la configuration de la barre et de la création d'un graphique basé sur la coque pour finaliser un graphique de barre basé sur la coque réelle étape par étape. Pour mettre en évidence les différences avec le flux de travail régulier du graphique de la barre, les tutoriels prennent le graphique populaire de casque kubernetes-dashboard comme source et le transportent vers un graphique de casque basé sur la coque équivalent. En fin de compte, il montre que la réduction des lignes de configuration pour créer et maintenir peut être réduite de plus de 50% lors de l'utilisation d'une approche basée sur la coque au lieu du style de casque régulier des graphiques d'écriture!
Les tâches de création et de configuration d'un graphique de barre à base de coque peuvent être considérées comme deux côtés d'une même pièce. Les deux côtés interagissent avec la même interface (la bibliothèque de coque) pour spécifier les objets qui doivent être créés. La tâche du point de vue des créateurs / maintenneurs est avant tout pour fournir la structure au sol des objets qui composent l'application particulière qui doit être enveloppée dans un graphique de barre. Le consommateur du graphique est chargé d'ajouter de manière appropriée son contexte spécifique à son système à la structure du sol dans laquelle il a la liberté de changer et même d'ajouter ou de supprimer des objets au besoin pour atteindre ses objectifs. À l'heure de déploiement, la structure de base des créateurs est fusionnée avec le fichier YAML spécifique au système des consommateurs pour créer la configuration complète. L'interaction via la même interface de bibliothèque favorise la compréhension commune de la façon de travailler avec la bibliothèque des deux côtés et peut éliminer la plupart des processus de configuration lourds de copie et de coller fastidieux.
Ainsi, tout ce qui est nécessaire pour créer un graphique de barre basé sur la coque est une structure de répertoire de graphique de barre d'échafaudage standard. Ajoutez le graphique de la bibliothèque Hull en tant que sous-carter, copiez le hull.yaml du tableau de la bibliothèque de Hull dans le dossier de vos graphiques /templates barre des parents. Configurez ensuite simplement les objets par défaut à déployer via les values.yaml et vous avez terminé. Il n'y a pas de limite quant au nombre d'objets du type que vous créez pour votre package de déploiement.
Mais en plus de permettre de définir des applications plus complexes avec Hull, vous pouvez également l'utiliser pour envelopper des objets Kubernetes simples que vous déploieriez autrement via Kubectl (étant hors de ligne du point de vue de la gestion avec les versions de barre) ou de vous rédiger d'une quantité importante de Helm Modèles de passe-partout pour y parvenir.
La structure de base des values.yaml comprise par Hull est donnée ici dans la section suivante. Cela forme essentiellement l'interface unique pour produire et consommer des graphiques à base de coque. Tout objet est créé uniquement au cas où il est défini et activé dans les values.yaml , cela signifie que vous voudrez peut-être pré-configurer des objets pour les consommateurs qui auraient juste besoin de leur activer s'ils veulent les utiliser.
Au niveau supérieur de la structure YAML, la coque distingue config et objects . Bien que la sous-configuration config soit destinée à gérer des paramètres spécifiques au graphique tels que les métadonnées et les paramètres du produit, les objets Kubernetes en béton à rendre sont spécifiés sous la clé objects . Une version supplémentaire de troisième niveau nommé nommé est également autorisée, lorsque cela est défini sur la version des graphiques de coque, par exemple pendant le pipeline de libération des graphiques de barreaux parents, il remplira automatiquement l'étiquette vidispine.hull/version sur tous les objets indiquant la version de coque qui a été utilisé pour rendre les objets.
config Dans la section config , vous pouvez configurer les paramètres généraux pour votre graphique de barre. Il est divisé en deux sous-sections, Config. config.general ET config.specific .
config.general Contrairement à la section config.specific , qui doit être remplie de données arbitraires spécifiques uniquement à un seul graphique de barre, la section config.general doit être utilisée pour définir tout ce qui n'est pas particulier à une application unique. D'une part, il contient des options de configuration qui sont pertinentes pour tous les graphiques basés sur la coque, mais laissent également de la place sous la config.general.data Entrée pour définir vos propres champs de données qui sont idéalement modélisés de la même manière dans d'autres graphiques de barre. Par exemple, si plusieurs applications dans une suite de produits dépendent des mêmes points de terminaison, vous pouvez modéliser ces points de terminaison uniformément sous la propriété general.data dans tous les graphiques pertinents et ainsi avoir votre interface de graphiques de barre de la même manière avec EG un pipeline de déploiement continu.
config.general n'a que les sous-champs suivants:
nameOverride
fullnameOverride
namespaceOverride
noObjectNamePrefixes
createImagePullSecretsFromRegistries
globalImageRegistryServer
globalImageRegistryToFirstRegistrySecretServer
debug
rbac
data
serialization
postRender
errorChecks
metadata
| Paramètre | Description | Défaut | Exemple |
|---|---|---|---|
nameOverride | Le remplacement du nom est appliqué aux valeurs de la marque de métadonnées app.kubernetes.io/name . Si définissez-le, cela remplace efficacement le nom du graphique ici. | ||
fullnameOverride | S'il est défini sur une valeur, le nom de nom de nom complet est appliqué en tant que préfixe à tous les noms d'objets et remplace le modèle de préfixe standard <release>-<chart> dans les noms d'objets. | myapp | |
namespaceOverride | S'il est défini sur une valeur, l'espace de noms de tous les objets créés est défini sur cette valeur. Si cela n'est pas défini, l'espace de noms de toutes les instances d'objet parvient par défaut à l'espace de noms de version fourni à la commande HELM respective. | my-namespace | |
noObjectNamePrefixes | S'il est défini, les touches d'instance d'objet servent directement de noms pour les objets Kubernetes créés et ne sont jamais préfixés. Ceci est techniquement équivalent à la définition staticName TRUE sur chaque objet. Notez qu'en définissant ceci sur true la valeur de config.general.fullnameOverride devient hors de propos. | false | true |
createImagePullSecretsFromRegistries | Si cela est vrai, Image Pull Secrets est créé à partir de tous les registres définis dans ce graphique de barre et sont ajoutés à toutes les pods. | true | false |
globalImageRegistryServer | S'il n'est pas vide, le champ registry de tous les champs image de conteneur est défini sur la valeur donnée ici. Le réglage de config.general.globalImageRegistryToFirstRegistrySecretServer est ignoré si ce champ n'est pas vide. Tous les paramètres registry explicites définis pour une image sont écrasés avec cette valeur.L'utilisation prévue de ceci est d'avoir toutes les images tirées d'un registre central Docker en cas de scénarios de déploiement à air. Contrairement à la définition de globalImageRegistryToFirstRegistrySecretServer sur true , dans ce cas, le secret du registre est généralement défini en dehors de ce graphique de barre et le serveur du secret du Registre est référencé par son nom directement. Si vous utilisez cette fonctionnalité et définissez le secret du registre Docker en dehors de ce graphique de barre, vous pourriez en outre ajouter imagePullSecrets à vos pods au cas où le registre Docker référencé n'est pas peu sûr. | "" | mycompany.docker-registry.io |
globalImageRegistryToFirstRegistrySecretServer | Si True et globalImageRegistryServer est vide, le champ registry de tous les champs image de conteneur est défini sur le champ server du premier objet registry trouvé. Notez qu'il s'agit du registre avec le nom de clé alphanumérique le plus bas si vous fournissez plusieurs obejcts registry . Devrait normalement être utilisé avec la définition de createImagePullSecretsFromRegistries à true pour bénéficier de l'image Autopopulée imagePullSecrets et en conséquence registry . Les paramètres registry explicites pour une image sont écrasés avec cette valeur.L'utilisation prévue de ce paramètre est de faire extraire toutes les images d'un registre Docker central en cas de scénarios de déploiement. | false | true |
errorChecks | Options qui déterminent dans quels cas Hull générera une erreur sur helm install ou helm template . Pour plus de détails, voir également la documentation détaillée sur la configuration des vérifications d'erreurN'a que les sous-champs suivants: objectYamlValidhullGetTransformationReferenceValidcontainerImageValidvirtualFolderDataPathExistsvirtualFolderDataInlineValid | ||
errorChecks.objectYamlValid | Valider qu'aucun yaml cassé n'est rendu | true | |
errorChecks.hullGetTransformationReferenceValid | Valider que toutes les références _HT* pointent vers une clé existante dans les values.yaml | true | |
errorChecks.containerImageValid | image initContainers containers pod repository | true | |
errorChecks.virtualFolderDataPathExists | Valider que tous les fichiers référés dans un champ path data de configmap et le secret existent physiquement | true | |
errorChecks.virtualFolderDataInlineValid | Valider qu'aucune valeur null ou valeurs manquantes (qui sont converties en chaînes vides) ne sont définies pour les champs inline data de configmap et de Secret | false | |
debug | Options qui peuvent aider à le débogage des problèmes de graphique. Principalement obsolète et remplacé par des messages d'erreur par défaut par défaut configurés sous errorChecks .N'a que les sous-champs suivants: renderBrokenHullGetTransformationReferencesrenderNilWhenInlineIsNilrenderPathMissingWhenPathIsNonExistent | ||
debug.renderBrokenHullGetTransformationReferences | Switch global qui, si activé, imprimera une chaîne:HULL failed with error BROKEN-HULL-GET-TRANSFORMATION-REFERENCE: Element <y> in path <xyz> was not foundy compris le _HT*/hull.util.transformation.get référence ( xyz ) et la clé manquante ( y ) si la transformation fait référence à une clé de dictionnaire non existante. Ceci est utile pour déboguer le rendu des graphiques et réduit la recherche de références cassées car normalement l'installation abandonne avec une erreur sur les références brisées (ce qui peut rendre difficile le point de pointer la ou les références problématiques).NOTE: À présent, toute référence BROKED GET sera signalée par une erreur de barre parlante par défaut, donc ce commutateur est principalement obsolète pour le débogage des références cassées. Il est recommandé pour désactiver cette option et échouer dur sur les références BROKE Get à la place et analyser les problèmes directement à partir du message d'erreur. | false | true |
debug.renderNilWhenInlineIsNil | Switch global qui, si activé, imprimera une chaîne:<nil>En tant que champs data ont une valeur lorsqu'une spécification inline fait référence à un pointeur nil dans une configmap ou un secret. S'il est défini sur false, la valeur nil sera imprimée en tant que chaîne vide dans le champ data configmap ou secret.NOTE: À présent, tous les champs en ligne non valides seront signalés par une erreur de barre parlante par défaut (ce qui signifie que hull.config.general.errorChecks.virtualFolderDataInlineValid est true ). L'activation de ce commutateur est principalement obsolète pour le débogage et il est recommandé pour désactiver cette option et échouer dur sur les champs en ligne invalides. | false | true |
debug.renderPathMissingWhenPathIsNonExistent | Switch global qui, si activé, imprimera une chaîne:<path missing: the_missing_path>Dans une valeur configmap ou des champs data secrets, y compris la valeur the_missing_path qui ne résout pas un fichier. Si FALSE, la valeur des champs data se résoudra en une chaîne vide.NOTE: À présent, tout fichier inexistant référencé dans un champ de chemin sera signalé par une erreur de barre parlante par défaut (ce qui signifie que hull.config.general.errorChecks.virtualFolderDataPathExists est true ). L'activation de ce commutateur est principalement obsolète pour le débogage et il est recommandé pour désactiver cette option et échouer dur sur les références de chemin de fichier inexistantes. | false | true |
render | Options pour influencer la façon dont Hull rend les objets en tant que YAML. N'a que les sous-champs suivants: emptyAnnotationsemptyLabelsemptyHullObjects | ||
render.emptyAnnotations | Si true , Hull rend annotations: {} si aucune annotation n'existe pour un objet, si false la clé annotations est omise. | false | true |
render.emptyLabels | Si true , Hull rend labels: {} Si aucune étiquette n'existe pour un objet, si false la clé labels est omise. | false | true |
render.emptyTemplateAnnotations | Si true , Hull rend annotations: {} dans le template d'un pod si aucune annotation n'existe pour un objet, si false la clé annotations est omise. | false | true |
render.emptyTemplateLabels | Si true , Hull rend labels: {} Dans le template de pods if no labels exist for an object, if FAUX the touche d'étiquettes est omise. | false | true |
render.emptyHullObjects | Si true , Hull rend les tableaux en tant que tableaux vides si aucun éléments n'existe pour certains champs traités par Hull. Si FALSE, la paire de valeurs clés est ouverte.Cela affecte les champs qui sont mappés d'un dictionnaire dans la configuration de la coque vers un tableau Kubernetes dans le YAML rendu. Ce qui suit est une liste des champs affectés dans la configuration de l'objet de Hull:
| false | true |
postRender | Après que Hull ait rendu un objet entièrement, il est possible de manipuler la chaîne YAML résultante. Les possibilités de le faire sont fournies comme des actions postRender ici.AVERTISSEMENT: utilisez avec prudence car cela peut corrompre la structure YAML! | ||
postRender.globalStringReplacements | Un dictionnaire des possibilités de remplacement qui peuvent être appliqués au YAML de l'objet rendu. Le cas d'utilisation principal pour cela est en combinaison avec un défaut étendu dans _HULL_OBJECT_TYPE_DEFAULT_ et sources des instances d'objet où il permet d'injecter des chaînes spécifiques d'instance dans le YAML par défaut. Les mappages préconfigurés fournis peuvent être enabled: true à la demande. Chaque cartographie consiste à suivre les champs:
| ||
postRender.globalStringReplacements.instanceKey | Si enabled , la valeur string sera remplacée par l' instance_key de l'objet réel_key comme dans hull.objects.<object_type>.<instance_key> . La valeur du replacement est OBJECT_INSTANCE_KEY pour ce mappage. | instanceKey:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_KEY | |
postRender.globalStringReplacements.instanceKeyResolved | Si enabled , la valeur string sera remplacée par l' instance_key de l'objet réel comme dans hull.objects.<object_type>.<instance_key> ou par hull.objects.<object_type>.<instance_key>.metadataNameOverride si cela est défini. La valeur du replacement est OBJECT_INSTANCE_KEY_RESOLVED pour ce mappage. | instanceKeyResolved:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_KEY_RESOLVED | |
postRender.globalStringReplacements.instanceName | S'il enabled , la valeur string sera remplacée par le metadata.name rendues de l'objet réel. La valeur du replacement est OBJECT_INSTANCE_NAME pour ce mappage. | instanceName:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_NAME | |
serialization | Options générales de sérialisation. | ||
serialization.configmap.enabled | Si enabled , les extensions de fichiers mappées sous fileExtensions sont sérialisées avec la méthode de sérialisation donnée par défaut. Si la clé data se termine par l'une des extensions mappées, la méthode de sérialisation dans la valeur est utilisée pour écrire le contenu en chaîne. Un champ serialization spécifique sur une saisie data ConfigMaps écrase tous les paramètres par défaut. | true | |
serialization.configmap.fileExtensions | Un dictionnaire des mappages des extensions de fichiers aux méthodes de sérialisation. | fileExtensions:json: toPrettyJsonyaml: toYamlyml: toYaml | |
serialization.secret.enabled | Si enabled , les extensions de fichiers mappées sous fileExtensions sont sérialisées avec la méthode de sérialisation donnée par défaut. Si la clé data se termine par l'une des extensions mappées, la méthode de sérialisation dans la valeur est utilisée pour écrire le contenu en chaîne. Un champ serialization spécifique sur une saisie data secrets écrase tous les paramètres par défaut. | true | |
serialization.secret.fileExtensions | Un dictionnaire des mappages des extensions de fichiers aux méthodes de sérialisation. | fileExtensions:json: toPrettyJsonyaml: toYamlyml: toYaml | |
config.general.rbac | Switch global qui permet des objets RBAC pour l'installation. Si true Tous les objets RBAC activés sont déployés dans le cluster, si false aucun objet RBAC n'est créé du tout.Les objets RBAC qui sont déployables sont: rolesrolebindingsclusterrolesclusterrolebindings | true | false |
config.general.data | Champ de forme libre tandis que les sous-champs de ce champ devraient avoir une signification clairement définie dans le contexte de votre suite de produits. Par exemple, supposons que tous vos produits ou microservices (chacun venant en tant que graphique de barre séparé) dépend des mêmes points de terminaison donnés (authentification, configuration, ...). Vous pourriez avoir un travail Kubernetes partagé exécuté par chaque graphique de barre qui cible ces points de terminaison. Vous pouvez maintenant spécifier une values.yaml de coque externe values.yaml | {} | |
config.general.metadata | Les champs de métadonnées définis ici seront automatiquement ajoutés à toutes les métadonnées d'objets. N'a que les sous-champs suivants: labelsannotations | ||
config.general.metadata.labels | Étiquettes qui sont ajoutées à tous les objets. Les étiquettes common se réfèrent aux étiquettes communes de Kubernetes et Helm et des étiquettes custom peuvent être spécifiées librement.N'a que les sous-champs suivants: commoncustom | ||
config.general.metadata.labels.common | Spécification des étiquettes communes telles que définies dans https://helm.sh/docs/chart_best_practices/labels/ et https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/. Sauf si spécifiquement écrasé avec des valeurs vides ( '' ) Toutes les étiquettes de métadonnées sont automatiquement ajoutées à tous les objets en fonction de leur définition par défaut. Il doit être considéré pour définir une valeur pour config.general.metadata.labels.common.'app.kubernetes.io/part-of' Si le graphique de la barre fait partie d'une suite de produits. | ||
config.general.metadata.labels.common.'app.kubernetes.io/managed-by' | Géré par les métadonnées. | {{ .Release.Service }} | |
config.general.metadata.labels.common.'app.kubernetes.io/version' | Métadonnées de version. | {{ .Chart.AppVersion }} | |
config.general.metadata.labels.common.'app.kubernetes.io/part-of' | Métadonnées partielles. | "unspecified" | |
config.general.metadata.labels.common.'app.kubernetes.io/name' | Nom des métadonnées. | {{ printf "%s-%s" .ChartName <hullObjectKey> }} | |
config.general.metadata.labels.common.'app.kubernetes.io/instance' | Métadonnées d'instance. | {{ .Release.Name }} | |
config.general.metadata.labels.common.'app.kubernetes.io/component' | Métadonnées des composants. | <hullObjectKey> | |
config.general.metadata.labels.common.'helm.sh/chart' | HELM Metadata. | `{{(printf"% s-% s ".chart.name .chart.version) | remplacer "+" "_"}} ` |
config.general.metadata.labels.custom | Toutes les étiquettes personnalisées spécifiées sont automatiquement ajoutées à tous les objets de ce graphique de barre. | {} | |
config.general.metadata.annotations | Annotations qui sont ajoutées à tous les objets. Les étiquettes custom peuvent être spécifiées librement.N'a que les sous-champs suivants: custom . | ||
config.general.metadata.annotations.custom | Toutes les annotations personnalisées spécifiées sont automatiquement ajoutées à tous les objets de ce graphique de barre. | {} | |
config.specific | Champ de formulaire gratuit qui contient des options de configuration spécifiques au produit spécifique contenu dans le graphique de la barre. En règle générale, les valeurs spécifiées ici doivent être utilisées pour remplir le contenu des fichiers de configuration auxquels une application particulière lisait leur configuration à partir de startup. Par conséquent, les champs config.specific sont généralement consommés dans les configmaps ou les secrets. | {} | maxDatepickerRange: 50defaultPoolColor: "#FB6350"updateInterval: 60000 |
objects Les types d'objets de niveau supérieur sous hull.objects représentent les types d'objets Kubernetes pris en charge à partir des instances. Chaque type d'objet est un dictionnaire où les valeurs des entrées sont les propriétés des objets et chaque objet a sa propre clé qui est unique au type d'objet auquel il appartient. D'autres types d'objets K8S peuvent être ajoutés au besoin à la bibliothèque afin qu'il puisse facilement être étendu.
Un aspect important est que pour tous les types d'objets de niveau supérieur, les instances d'un type particulier sont toujours identifiées par une clé unique à la combinaison d'instance et de type d'objet. La même clé peut cependant être utilisée pour les instances de différents types d'objets.
En ayant des clés qui identifient les instances que vous pouvez:
faire la fusion multicouches des propriétés d'objets en empilant des fichiers values.yaml les uns sur les autres. Vous pouvez commencer par définir la structure d'objet par défaut de l'application ou du micro-service défini dans le graphique de casque donné. Ensuite, vous pouvez ajouter une couche values.yaml . Ensuite, vous pouvez ajouter une couche de values.yaml pour les informations d'identification. Et ainsi de suite. By uniquely identifying the instances of a particular K8s object type it becomes easy to adjust the objects properties through a multitude of layers.
use the key of an instance for naming the instance. All instance names are constructed by the following ground rule: {{ printf "%s-%s-%s" .Release.Name .Chart.Name key }} . This generates unique, dynamic names per object type and release + instance key combination.
For example, assuming the parent Helm chart is named my_webservice and the release named staging and given this specification in values.yaml :
hull :
objects :
deployment :
nginx :
pod :
containers :
nginx :
repository : nginx
tag : 1.14.2 a Kubernetes deployment object with the following metadata.name is created:
my_webservice-staging-nginx
Note that you can opt to define a static name for instances you create by adding a property
staticName: trueto your objects definition. If you do so the objects name will exactly match the key name you chose.
each particular instance can have an enabled sub-field set to true or false . This way you can predefine instances of object types in your helm charts values.yaml but not deploy them in a default scenario. Or enable them by default and refrain from deploying them in a particular environment by disabling them in an superimposed system specific values.yaml . Note that unless you explicitly specify enabled: false each instance you define will be created by default, a missing enabled key is equivalent to enabled: true .
cross-referencing objects within a helm chart by the instance key is a useful feature of the HULL library. This is possible in these contexts:
Note that you can in these cases opt to refer to a static name instead too. Adding a property
staticName: trueto the dictionary with your reference will force the referenced objects name to exactly match the name you entered.
The values of object instance keys reflects the Kubernetes objects to create for the chart. To specify these objects efficiently, the available properties for configuration can be split into three groups:
Basic HULL object configuration with hull.ObjectBase.v1 whose properties are available for all object types and instances. These are enabled , staticName , annotations and labels .
Given the example of a deployment named nginx you can add the following properties of hull.ObjectBase.v1 to the object instance:
hull :
objects :
deployment :
nginx : # unique key/identifier of the deployment to create
staticName : true # property of hull.ObjectBase.v1
# forces the metadata.name to be just the <KEY> 'nginx'
# and not a dynamic name '<CHART>-<RELEASE>-<KEY>' which
# would be the better default behavior of creating
# unique object names for all objects.
enabled : true # property of hull.ObjectBase.v1
# this deployment will be rendered to a YAML object if enabled
labels :
demo_label : " demo " # property of hull.ObjectBase.v1
# add all labels here that shall be added
# to the object instance metadata section
annotations :
demo_annotation : " demo " # property of hull.ObjectBase.v1
# add all annotations here that shall be added
# to the object instance metadata section
pod :
... # Here would come the hull.PodTemplate.v1 definition
# see below for details
Specialized HULL object properties for some object types. Below is a reference of which object type supports which special properties in addition to the basic object configuration.
Again given the example of a deployment named nginx you would want to add properties of the HULL hull.PodTemplate.v1 to the instance. With them you set the pod property to define the pod template (initContainers, containers, volumes, ...) and can add templateLabels and templateAnnotations just to the pods created metadata and not the deployment objects metadata section:
hull :
objects :
deployment :
nginx :
staticName : true
enabled : true
labels :
demo_label : " demo "
annotations :
demo_annotation : " demo "
templateLabels : # property of hull.PodTemplate.v1 to define
# labels only added to the pod
demo_pod_label : " demo pod "
templateAnnotations : # property of hull.PodTemplate.v1 to define
# annotations only added to the pod
demo_pod_annotation : " demo pod "
pod : # property of hull.PodTemplate.v1 to define the pod template
containers :
nginx : # all containers of a pod template are also referenced by a
# unique key to make manipulating them easy.
image :
repository : nginx # specify repository and tag
# separately with HULL for easier composability
tag : 1.14.2
... # further properties (volumeMounts, affinities, ...)
Kubernetes object properties. For each object type it is basically possible to specify all existing Kubernetes properties. In case a HULL property overwrites a identically named Kubernetes property the HULL property has precedence. Even if a HULL property overrides a Kubernetes property it is intended to provide the same complete configuration options, even if sometimes handled differently by HULL.
Some of the typical top-level Kubernetes object properties and fields don't require setting them with HULL based objects because they can be deducted automatically:
apiVersion and kind are determined by the HULL object type and Kubernetes API version and don't require to be explicitly set (except for objects of type customresource ).metadata dictionary on objects is handled by HULL via the annotations and labels fields and the naming rules explained above. So the metadata field does not require configuration and is hence not configurable for any object.Some lower level structures are also converted from the Kubernetes API array form to a dictionary form or are modified to improve working with them. This also enables more sophisticated merging of layers since arrays don't merge well, they only can be overwritten completely. Overwriting arrays however can make it hard to forget about elements that are contained in the default form of the array (you would need to know that they existed in the first place). In short, for a layered configuration approach without an endless amount of elements the dictionary is preferable for representing data since it offers a much better merging support.
So again using the example of a deployment named nginx you can add the remaining available Kubernetes properties to the object instance which are not handled by HULL as shown below. For a deployment specifically you can add all the remaining properties defined in the deploymentspec API schema from deploymentspec-v1-apps which are minReadySeconds , paused , progressDeadlineSeconds , replicas , revisionHistoryLimit and strategy . If properties are marked as mandatory in the Kubernetes JSON schema you must provide them otherwise the rendering process will fail:
hull :
objects :
deployment :
nginx :
staticName : true
enabled : true
labels :
demo_label : " demo "
annotations :
demo_annotation : " demo "
pod :
... # Here would come the hull.PodTemplate.v1 definition
# see above for details
replicas : 3 # property from the Kubernetes API deploymentspec
strategy : # property from the Kubernetes API deploymentspec
type : Recreate
... # further Kubernetes API deploymentspec options
Here is an overview of which top level properties are available for which object type in HULL. The HULL properties are grouped by the respective HULL JSON schema group they belong to. A detailed description of these groups and their properties is found in the documentation of this helm chart and the respective linked documents.
Workloads APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
deployment | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.PodTemplate.v1 templateAnnotationstemplateLabelspod | deploymentspec-v1-appsminReadySecondspausedprogressDeadlineSecondsreplicasrevisionHistoryLimitstrategy |
job | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.PodTemplate.v1 templateAnnotationstemplateLabelspod | jobspec-v1-batchactiveDeadlineSecondsbackoffLimitcompletionModecompletionsmanualSelectorparallelismselectorsuspendttlSecondsAfterFinished |
daemonset | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.PodTemplate.v1 templateAnnotationstemplateLabelspod | daemonsetspec-v1-appsminReadySecondsrevisionHistoryLimitupdateStrategy |
statefulset | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.PodTemplate.v1 templateAnnotationstemplateLabelspod | statefulsetspec-v1-appspodManagementPolicyreplicasrevisionHistoryLimitserviceNameupdateStrategyserviceNamevolumeClaimTemplates |
cronjob | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Job.v1 job | cronjobspec-v1-batchconcurrencyPolicyfailedJobsHistoryLimitschedulestartingDeadlineSecondssuccessfulJobsHistoryLimitsuspend |
Service APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
endpoints | hull.ObjectBase.v1enabledannotationslabelsstaticName | endpoints-v1-coresubsets |
endpointslice | hull.ObjectBase.v1enabledannotationslabelsstaticName | endpointslice-v1-discovery-k8s-ioaddressTypeendpointsports |
service | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Service.v1 ports | servicespec-v1-coreallocateLoadBalancerNodePortsclusterIPclusterIPsexternalIPsexternalNameexternalTrafficPolicyhealthCheckNodePortinternalTrafficPolicyipFamiliesipFamilyPolicyloadBalancerClassloadBalancerIPloadBalancerSourceRangespublishNotReadyAddressesselectorsessionAffinitysessionAffinityConfigtopologyKeystype |
ingress | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Ingress.v1 tlsrules | ingressspec-v1-networking-k8s-iodefaultBackendingressClassName |
ingressclass | hull.ObjectBase.v1enabledannotationslabelsstaticName | ingressclassspec-v1-networking-k8s-iocontrollerparameters |
Config and Storage APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
configmap | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.VirtualFolder.v1 data | configmap-v1-corebinaryDataimmutable |
secret | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.VirtualFolder.v1 data | secret-v1-coreimmutablestringDatatype |
registry | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Registry.v1 serverusernamepassword | secret-v1-core |
persistentvolumeclaim | hull.ObjectBase.v1enabledannotationslabelsstaticName | persistentvolumeclaimspec-v1-coreaccessModesdataSourceresourcesselectorstorageClassNamevolumeModevolumeName |
storageclass | hull.ObjectBase.v1enabledannotationslabelsstaticName | storageclass-v1-storage-k8s-ioallowVolumeExpansionallowedTopologiesmountOptionsparametersprovisionerreclaimPolicyvolumeBindingMode |
Metadata APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
customresource | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.CustomResource.v1 apiVersionkindspec | |
limitrange | hull.ObjectBase.v1enabledannotationslabelsstaticName | limitrange-v1-corelimits |
horizontalpodautoscaler | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.HorizontalPodAutoscaler.v1 scaleTargetRef | horizontalpodautoscalerspec-v2-autoscalingbehaviormaxReplicasmetricsminReplicas |
mutatingwebhookconfiguration | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.MutatingWebhook.v1 webhooks | |
poddisruptionbudget | hull.ObjectBase.v1enabledannotationslabelsstaticName | poddisruptionbudgetspec-v1-policymaxUnavailableminAvailableselector |
validatingwebhookconfiguration | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.ValidatingWebhook.v1 webhooks | |
priorityclass | hull.ObjectBase.v1enabledannotationslabelsstaticName | priorityclass-v1-scheduling-k8s-iodescriptionglobalDefaultpreemptionPolicyvalue |
Cluster APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
clusterrole | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Rule.v1 rules | clusterrole-v1-rbac-authorization-k8s-ioaggregationRule |
clusterrolebinding | hull.ObjectBase.v1enabledannotationslabelsstaticName | clusterrolebinding-v1-rbac-authorization-k8s-ioroleRefsubjects |
namespace | hull.ObjectBase.v1enabledannotationslabelsstaticName | namespace-v1-corespecstatus |
persistentvolume | hull.ObjectBase.v1enabledannotationslabelsstaticName | persistentvolumespec-v1-coreaccessModesawsElasticBlockStoreazureDiskazureFilecapacitycephfscinderclaimRefcsifcflexVolumeflockergcePersistentDiskglusterfshostPathiscsilocalmountOptionsnfsnodeAffinitypersistentVolumeReclaimPolicyphotonPersistentDiskportworxVolumequobyterbdscaleIOstorageClassNamestorageosvolumeModevsphereVolume |
role | hull.ObjectBase.v1enabledannotationslabelsstaticNamehull.Rule.v1 rules | role-v1-rbac-authorization-k8s-io |
rolebinding | hull.ObjectBase.v1enabledannotationslabelsstaticName | rolebinding-v1-rbac-authorization-k8s-ioroleRefsubjects |
serviceaccount | hull.ObjectBase.v1enabledannotationslabelsstaticName | serviceaccount-v1-coreautomountServiceAccountTokenimagePullSecretssecrets |
resourcequota | hull.ObjectBase.v1enabledannotationslabelsstaticName | resourcequotaspec-v1-corehardscopeSelectorscopes |
networkpolicy | hull.ObjectBase.v1enabledannotationslabelsstaticName | networkpolicyspec-v1-networking-k8s-ioegressingresspodSelectorpolicyTypes |
Other APIs
| COQUE Object Type | COQUE Propriétés | Kubernetes/External Propriétés |
|---|---|---|
servicemonitor | hull.ObjectBase.v1enabledannotationslabelsstaticName | ServiceMonitor CRDspec |
To test or install a chart based on HULL the standard Helm v3 tooling is usable. See also the Helm documentation at the Helm website.
To inspect the outcome of a specific values.yaml configuration you can simply render the templates which would be deployed to Kubernetes and inspect them with the below command adapted to your needs:
<PATH_TO_HELM_V3_BINARY> template --debug --namespace <CHART_RELEASE_NAMESPACE> --kubeconfig <PATH_TO_K8S_CLUSTER_KUBECONFIG> -f <PATH_TO_SYSTEM_SPECIFIC_VALUES_YAML> --output-dir <PATH_TO_OUTPUT_DIRECTORY> <PATH_TO_CHART_DIRECTORY>
Installing or upgrading a chart using HULL follows the standard procedures for every Helm chart:
<PATH_TO_HELM_V3_BINARY> upgrade --install --debug --create-namespace --atomic --namespace <CHART_RELEASE_NAMESPACE> --kubeconfig <PATH_TO_K8S_CLUSTER_KUBECONFIG> -f <PATH_TO_SYSTEM_SPECIFIC_VALUES_YAML> <RELEASE_NAME> <PATH_TO_CHART_DIRECTORY>
Using the nginx deployment example from the Kubernetes documentation https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#creating-a-deployment as something we want to create with our HULL based Helm chart:
apiVersion : apps/v1
kind : Deployment
metadata :
name : nginx
labels :
app : nginx
spec :
replicas : 3
selector :
matchLabels :
app : nginx
template :
metadata :
labels :
app : nginx
spec :
containers :
- name : nginx
image : nginx:1.14.2
ports :
- containerPort : 80 To render this analogously using the HULL library your chart needs to be setup for using HULL. In the following section we assume the parent Helm chart is named hull-test and we use the helm template command to test render the values.yaml 's.
A minimal example of creating the expected result from above would be to create a values.yaml like below in your parent chart (commented with some explanations). Note that some default features of HULL such as RBAC and dynamic naming are explicitly disabled here to obtain the output matching the above example closely:
hull :
config :
general :
rbac : false # Don't render RBAC objects. By default HULL would provide
# a 'default' Role and 'default' RoleBinding associated with
# a 'default' ServiceAccount to use for all pods.
# You can modify this as needed. Here we turn it off to not
# render the default RBAC objects.
objects :
serviceaccount :
default :
enabled : false # The release specific 'default' ServiceAccount created
# for a release by default is disabled here. In this case
# it will not be rendered out and automatically used as
# 'serviceAccountName' in the pod templates.
deployment :
nginx : # all object instances have a key used for naming the objects and
# allowing to overwrite properties in multiple values.yaml layers
staticName : true # forces the metadata.name to be just the <KEY> 'nginx'
# and not a dynamic name '<CHART>-<RELEASE>-<KEY>' which
# would be the better default behavior of creating
# unique object names for all objects.
replicas : 3
pod :
containers :
nginx : # all containers of a pod template are also referenced by a
# unique key to make manipulating them easy.
image :
repository : nginx
tag : 1.14.2
ports :
http : # unique key per container here too. All key-value structures
# which are finally arrays in the K8S objects are converted to
# arrays on rendering the chart.
containerPort : 80 This produces the following rendered deployment when running the helm template command (commented with some brief explanations):
apiVersion : apps/v1 # derived from object type 'deployment'
kind : Deployment # derived from object type 'deployment'
metadata :
annotations : {}
labels : # standard Kubernetes metadata is created always automatically.
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
helm.sh/chart : hull-test-1.31.0
name : nginx # default name would be 'release-name-hull-test-nginx'
# but with staticName: true in the HULL spec it is just the key name
spec :
replicas : 3
selector : # selector is auto-created to match the unique metadata combination
# found also in the in the object's metadata labels.
matchLabels :
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/name : hull-test
template :
metadata :
annotations : {}
labels : # auto-created metadata is added to pod template
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
helm.sh/chart : hull-test-1.31.0
spec :
containers :
- env : []
envFrom : []
image : nginx:1.14.2
name : nginx
ports :
- containerPort : 80
name : http # name 'http' derived from the key of the port
# object defined in the values.yaml
volumeMounts : []
imagePullSecrets : {}
initContainers : []
volumes : [] Now to render the nginx deployment example showcasing extra features of the HULL library you can could create the below values.yaml file in your parent chart. Note that this is a very advanced example of what is possible using this library chart.
This example highlights:
hull :
config :
general : # This time we are not setting rbac: false
# so RBAC default objects are created.
# If the default objects don't match the use-case
# you can tweak all aspects individually if needed
metadata :
labels :
custom : # Additional labels added to all K8S objects
general_custom_label_1 : General Custom Label 1
general_custom_label_2 : General Custom Label 2
general_custom_label_3 : General Custom Label 3
annotations :
custom : # Additional annotations added to all K8S objects
general_custom_annotation_1 : General Custom Annotation 1
general_custom_annotation_2 : General Custom Annotation 2
general_custom_annotation_3 : General Custom Annotation 3
specific : # Put configuration options specific to this chart here
nginx_tag : 1.14.2 # You can also use entries here to globally
# define values that are referenced in multiple
# places in your chart. See how this field
# is accessed below in the deployment.
objects :
deployment :
_HULL_OBJECT_TYPE_DEFAULT_ : # A special object key available for
# all object types allowing defining
# defaults for properties of all object
# type instances created.
annotations :
default_annotation_1 : Default Annotation 1
default_annotation_2 : Default Annotation 2
general_custom_annotation_2 : Default Annotation 2 # overwriting this
# general annotation for
# all deployments
labels :
default_label_1 : Default Label 1
default_label_2 : Default Label 2
general_custom_label_2 : Default Label 2 # overwriting this
# general label for
# all deployments
nginx : # specify the nginx deployment under key 'nginx'
# This time we're not setting the metadata.name to be static so
# name will be created dynamically and will be unique
annotations :
general_custom_annotation_3 : Specific Object Annotation 3 # overwrite a
# general annotation
default_annotation_2 : Specific Object Annotation 2 # overwrite a default annotation
specific_annotation_1 : Specific Object Annotation 1 # add a specific annotation
# to the all this object's metadata
labels :
general_custom_label_3 : Specific Object Label 3 # overwrite a
# general label
default_label_2 : Specific Object Label 2 # overwrite a default label
specific_label_1 : Specific Object Label 1 # add a specific label
# to the all this object's metadata
templateAnnotations :
specific_annotation_2 : Specific Template Annotation 2 # this annotation will only appear
# in the pod template metadata
templateLabels :
specific_label_2 : Specific Template Label 2 # this label will only appear
# in the pod template metadata
replicas : 3
pod :
containers :
nginx : # all containers of a pod template are also referenced by a
# unique key to make manipulating them easy.
image :
repository : nginx
tag : _HT!{{ (index . "$").Values.hull.config.specific.nginx_tag }}
# Applies a tpl transformation allowing to inject dynamic data based
# on values in this values.yaml into the resulting field (here the tag
# field of this container).
# _HT! is the short form of the transformation that applies tpl to
# a given value. This example just references the value of the field
# which is specified further above in the values.yaml and will
# produce 'image: nginx:1.14.2' when rendered in the resulting
# deployment YAML but complex conditional Go templating logic is
# applicable too.
# There are some limitations to using this approach which are
# detailed in the transformation.md in the doc section.
ports :
http : # unique key per container here too. All key-value structures
# which are array in the K8S objects are converted to arrays
# on rendering the chart.
containerPort : 80
configmap : # this is to highlight the secret/configmap inclusion feature
nginx_configmap : # configmap objects have keys too
data : # specify for which contents a data entry shall be created
# within only a few lines of configuration. Contents can come from ...
an_inline_configmap.txt : # ... an inline specified content or ...
inline : |-
Top secret contents
spread over
multiple lines...
contents_from_an_external_file.txt : # ... something from an external file.
path : files/my_secret.txt
This produces the following rendered objects when running the helm template command (commented with some brief explanations):
---
# Source: hull-test/templates/hull.yaml
apiVersion : v1
kind : ServiceAccount
metadata :
annotations :
general_custom_annotation_1 : General Custom Annotation 1 # All objects share the general_custom_annotations
general_custom_annotation_2 : General Custom Annotation 2 # if they are not overwritten for the object type's
general_custom_annotation_3 : General Custom Annotation 3 # default or specific instance
labels :
app.kubernetes.io/component : default
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
general_custom_label_1 : General Custom Label 1 # All objects share the general_custom_labels
general_custom_label_2 : General Custom Label 2 # if they are not overwritten for the object type's
general_custom_label_3 : General Custom Label 3 # default or specific instance
helm.sh/chart : hull-test-1.31.0
name : release-name-hull-test-default # This is the default ServiceAccount created for this chart.
# As all object instances by default it will be assigned a
# dynamically created unique name in context of this object type.
# In the simple example we disabled this rendering by
# setting enabled: false for this object's key.
---
# Source: hull-test/templates/hull.yaml
apiVersion : rbac.authorization.k8s.io/v1
kind : Role
metadata :
annotations :
general_custom_annotation_1 : General Custom Annotation 1
general_custom_annotation_2 : General Custom Annotation 2
general_custom_annotation_3 : General Custom Annotation 3
labels :
app.kubernetes.io/component : default
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
general_custom_label_1 : General Custom Label 1
general_custom_label_2 : General Custom Label 2
general_custom_label_3 : General Custom Label 3
helm.sh/chart : hull-test-1.31.0
name : release-name-hull-test-default # A default Role for RBAC.
rules : []
---
# Source: hull-test/templates/hull.yaml
apiVersion : rbac.authorization.k8s.io/v1
kind : RoleBinding
metadata :
annotations :
general_custom_annotation_1 : General Custom Annotation 1
general_custom_annotation_2 : General Custom Annotation 2
general_custom_annotation_3 : General Custom Annotation 3
labels :
app.kubernetes.io/component : default
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
general_custom_label_1 : General Custom Label 1
general_custom_label_2 : General Custom Label 2
general_custom_label_3 : General Custom Label 3
helm.sh/chart : hull-test-1.31.0
name : release-name-hull-test-default
roleRef :
apiGroup : rbac.authorization.k8s.io/v1
kind : Role
name : release-name-hull-test-default
subjects :
- apiGroup : rbac.authorization.k8s.io/v1
kind : ServiceAccount
name : release-name-hull-test-default # A default RoleBinding for RBAC. It connects the
# default ServiceAccount with the default Role.
# By default RBAC is enabled in charts.
---
# Source: hull-test/templates/hull.yaml
apiVersion : apps/v1
kind : Deployment
metadata :
annotations :
default_annotation_1 : Default Annotation 1 # non-overwritten default_annotation
default_annotation_2 : Specific Object Annotation 2 # overwritten default_annotation by instance
general_custom_annotation_1 : General Custom Annotation 1 # non-overwritten general_custom_annotation
general_custom_annotation_2 : Default Annotation 2 # overwritten general_custom_annotation
# by default_annotation
general_custom_annotation_3 : Specific Object Annotation 3 # overwritten general_custom_annotation
# by specific_annotation
specific_annotation_1 : Specific Object Annotation 1 # added annotation for instance metadata only
labels :
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
default_label_1 : Default Label 1 # non-overwritten default_label
default_label_2 : Specific Object Label 2 # overwritten default_label by instance
general_custom_label_1 : General Custom Label 1 # non-overwritten general_custom_label
general_custom_label_2 : Default Label 2 # overwritten general_custom_label by default_label
general_custom_label_3 : Specific Object Label 3 # overwritten general_custom_label
# by specific_label
helm.sh/chart : hull-test-1.31.0
specific_label_1 : Specific Object Label 1 # added label for instance metadata only
name : release-name-hull-test-nginx
spec :
replicas : 3
selector :
matchLabels :
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/name : hull-test
template :
metadata :
annotations :
default_annotation_1 : Default Annotation 1
default_annotation_2 : Specific Object Annotation 2
general_custom_annotation_1 : General Custom Annotation 1
general_custom_annotation_2 : Default Annotation 2
general_custom_annotation_3 : Specific Object Annotation 3
specific_annotation_1 : Specific Object Annotation 1
specific_annotation_2 : Specific Template Annotation 2 # this annotation was added only
# for the pod template's metadata
labels :
app.kubernetes.io/component : nginx
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
default_label_1 : Default Label 1
default_label_2 : Specific Object Label 2
general_custom_label_1 : General Custom Label 1
general_custom_label_2 : Default Label 2
general_custom_label_3 : Specific Object Label 3
helm.sh/chart : hull-test-1.31.0
specific_label_1 : Specific Object Label 1
specific_label_2 : Specific Template Label 2 # this label was added only
# for the pod template's metadata
spec :
containers :
- env : []
envFrom : []
image : nginx:1.14.2
name : nginx
ports :
- containerPort : 80
name : http
volumeMounts : []
imagePullSecrets : {}
initContainers : []
serviceAccountName : release-name-hull-test-default # the dynamically created name
volumes : []
---
# Source: hull-test/templates/hull.yaml
apiVersion : v1
data :
an_inline_configmap.txt : " Top secret contents n spread over n multiple lines... "
contents_from_an_external_file.txt : " Whatever was in this file ... "
kind : ConfigMap
metadata :
annotations :
general_custom_annotation_1 : General Custom Annotation 1 # All objects share the general_custom_annotations
general_custom_annotation_2 : General Custom Annotation 2 # if they are not overwritten for the object type's
general_custom_annotation_3 : General Custom Annotation 3 # default or specific instance
labels :
app.kubernetes.io/component : nginx_configmap
app.kubernetes.io/instance : release-name
app.kubernetes.io/managed-by : Helm
app.kubernetes.io/name : hull-test
app.kubernetes.io/part-of : undefined
app.kubernetes.io/version : 1.31.0
general_custom_label_1 : General Custom Label 1 # All objects share the general_custom_labels
general_custom_label_2 : General Custom Label 2 # if they are not overwritten for the object type's
general_custom_label_3 : General Custom Label 3 # default or specific instance
helm.sh/chart : hull-test-1.31.0
name : release-name-hull-test-nginx_configmapRead the additional documentation in the documentation folder on how to utilize the features of the HULL library to the full effect.
