hull
hull-demo-1.31.2
Este repositório contém o gráfico da biblioteca do Hull Helm. Ele foi projetado para facilitar a construção, a manutenção e a configuração dos objetos Kubernetes nos gráficos de comando e pode ser adicionado a qualquer gráfico de comando como um complemento para aprimorar a funcionalidade sem nenhum risco de quebrar as configurações de gráfico de leme existentes.
O gráfico em si e toda a documentação relacionada a ele podem ser encontrados na pasta hull , que é a pasta raiz do gráfico de compensação da Biblioteca do Hull.
Os esquemas Kubernetes API JSON são armazenados na pasta kubernetes-json-schema .
Abaixo está os gráficos do Hull README.md :
As abstrações precisam ser mantidas - Kelsey Hightower
Um dos principais aspectos do design do comando é que ele força o usuário a criar abstrações individuais da configuração de aplicativos Kubernetes. Para cada gráfico de compensação individual que é realizado na forma de modelos de YAML em uma pasta de gráficos /templates de leme. Esses arquivos de modelo, contendo blocos de código YAML de caldeira Kubernetes, por um lado, e mapeamentos de configuração personalizados que utilizam expressões de modelos GO, por outro lado, fornecem a cola entre a configuração da aplicação através do arquivo de configuração values.yaml centrais. . Indiscutivelmente, essa abordagem de abstração por aplicativo é adequada para criar pacotes de configuração adequados para as aplicações mais especializadas, mas têm um custo de ter uma grande sobrecarga para casos de uso de embalagens de aplicativos mais simples, recorrentes e prontos para uso. Criar, manter e (geralmente) entender as abstrações introduzidas por gráficos de comando - especialmente quando enfrentam um alto número de gráficos de comando individuais de várias fontes - pode se tornar tedioso e desafiador.
O recurso principal da Biblioteca Hull é a capacidade de remover os arquivos de modelo YAML personalizados inteiramente dos fluxos de trabalho do gráfico de helm e, assim, permitindo remover um nível de abstração. Usando o gráfico da Biblioteca Hull, os objetos Kubernetes, incluindo todas as suas propriedades, podem ser completamente especificados e transparentemente especificados nos values.yaml . O próprio gráfico da biblioteca do Hull fornece a camada uniforme para otimizar a especificação, configuração e renderização dos gráficos de comando para conseguir isso. Você também pode pensar nisso como uma camada fina no topo da API Kubernetes para evitar o intermediário entre o gráfico de leme e a configuração de objetos da API de Kubernetes, mas fornece flexibilidade quando é necessário personalizar opções de configuração individuais, em vez de exigir que você adicione cada chave de configuração manualmente para os modelos. A validação do esquema JSON com base no recurso de validação do Helm JSON (via values.schema.json ) ajuda a escrever objetos de conformidade da API da Kubernetes desde o início ao usar um IDE que suporta a validação do Live JSON Schema. Benefícios adicionais (metadados de objeto herdáveis uniformes, inclusão simplificada de configurações/segredos, valores de referência cruzada dentro dos values.yaml , ...) estão disponíveis com o casco sobre o qual você pode ler abaixo na visão geral dos recursos . Mas talvez o mais importante é que a biblioteca do Hull possa ser adicionada como uma dependência a qualquer gráfico de comando existente e ser usada lado a lado sem quebrar as funcionalidades existentes do gráfico de comando, consulte Adicionando o gráfico da biblioteca do Hull a um gráfico de compensação para obter mais informações. E, finalmente, por ser um gráfico de bibliotecas, tudo funciona 100% dentro da funcionalidade que o leme simples oferece - nenhuma ferramenta adicional é introduzida ou envolvida.
Seus comentários sobre este projeto são avaliados, portanto, comente ou inicie uma discussão na seção Issues ou crie desejos de recursos e relatórios de bugs. Obrigado!
A idéia do gráfico da biblioteca do Hull é parcialmente inspirada no conceito de gráfico de comando comum e para testar
.
hull-demo Antes de mergulhar nos detalhes de Hull, aqui está o primeiro vislumbre de como ele funciona. Você pode simplesmente fazer o download da versão mais recente do gráfico hull-demo Helm na seção de lançamentos desta página, ela tem tudo o que está sendo inicializado para testar o Hull ou configurar um novo gráfico de comando baseado no casco com um esforço mínimo.
O gráfico hull-demo envolve um aplicativo fictício myapp com um par de frontend e backend e par de serviços. Existe um arquivo de configuração para a configuração do servidor montada nas vagens backend . As vagens frontend precisam saber sobre o endereço de serviço backend por meio de variáveis de ambiente. Além disso, a configuração deve, por padrão, ser facilmente comutável de uma configuração debug (usando um Nodeport para acessar o front-end) a uma configuração semelhante à produção (usando um serviço de clusterip e uma entrada).
Uma estrutura padrão nua para capturar esses aspectos pode ser assim (com comentários de linha adicionais para explicação):
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 Este é o exemplo que constitui como values.yaml de hull-demo hull-demo
helm template hull-demo-<version>.tgz
Ele cria um conjunto de objetos com base nos values.yaml acima.
myapp-frontend que possui um conjunto tag de imagem configurado centralmente (por padrão v23.1 ) e variáveis de ambiente apontando para o endereço em cluster do myapp-backendmyapp-backend , que tem um conjunto tag de imagem configurado centralmente (por padrão v23.1 ) e uma configuração montada no myappconfig ConfigMapmyappconfig com um arquivo JSON que é construído dinamicamente incorporando expressões de modelos e referenciando valores definidos em outros lugares em values.yamlmyapp-backendmyapp-frontend , cuja configuração de tipo e porta depende do interruptor debug central-digite NodePort em um modo de configuração debug ou tipo ClusterIP em combinação com uma entrada myapp em configurações não debutasmyapp , que é apenas renderizado/criado caso o debug: false seja definido Todos os aspectos desta configuração podem ser alterados ou substituídos no tempo de implantação usando values.yaml adicionais.
debug e para configurações debug: true ou debug: falsemyapp ConfigMaps ( rate_limit e max_connections ) ou substitua -o completamente Todos os objetos e lógica foram criados com menos de cem linhas de código de configuração geral nos values.yaml do hull-demo . Você pode testar todos os aspectos mencionados acima ou helm template experimentar adicionando values.yaml adicionais. Para inicializar seu name gráfico de compensação, basta esvaziar os values.yaml Chart.yaml
Esta é uma primeira demonstração de como o Hull pode ser usado, mas há muito mais funcionalidade e casos de uso suportados. Verifique os principais recursos e a documentação detalhada para obter mais informações.
Conforme destacado acima, quando incluído em um gráfico de comando, o gráfico da biblioteca do Hull pode assumir o trabalho de renderizar dinamicamente os objetos Kubernetes de suas especificações fornecidas apenas pelo arquivo values.yaml . Com a construção de objetos YAML adiada para as funções de modelos GO da Biblioteca Hull, em vez de modelos de YAML personalizados na pasta /templates você pode aplicar centralmente as melhores práticas:
Concentre -se no que é necessário para especificar objetos Kubernetes sem precisar adicionar modelos de YAML de caldeira individuais ao seu gráfico. Isso remove uma fonte comum de erros e manutenção do fluxo de trabalho regular do comando. Para que o hull renderizasse a saída em conformidade com a especificação da API Kubernetes, um grande número de testes de unidade valida a saída do casco em relação ao esquema Kubernetes API JSON.
Para mais detalhes, consulte a documentação sobre a validação do esquema JSON.
Para todos os tipos de objetos de Kubernetes suportados pelo Hull, o acesso configuracional completo às propriedades dos tipos de objetos Kubernetes está disponível diretamente . Isso alivia os mantenedores de gráficos de adicionar as opções de configuração ausentes, uma a uma e os usuários do gráfico de compensação do gráfico do helm para adicionar apenas as propriedades necessárias para a configuração. Somente a atualização do gráfico do Hull para uma versão mais recente com a versão da API Kubernetes correspondente é necessária para permitir a configuração das propriedades adicionadas aos objetos Kubernetes, enquanto isso nas versões mais recentes da API. Os gráficos do Hull são versionados para refletir as versões mínimas da API Kubernetes suportadas por eles.
Para mais detalhes, consulte a documentação sobre a visão geral da arquitetura.
A interface única da biblioteca Hull é usada para criar e configurar objetos em gráficos para implantação. Isso promove a compreensão mútua dos criadores/mantenedores e consumidores de como o gráfico realmente funciona e o que ele contém. Cavar a pasta /templates para entender as implicações dos gráficos do comando não é mais necessária. Para evitar qualquer configuração incorreta, a interface para a biblioteca - os values.yaml . Ao usar um IDE que suporta a Validação do Esquema JSON ao vivo (por exemplo, VSCODE), você pode obter orientação do IDE ao criar os objetos do casco. Antes de renderizar, a conformidade do esquema JSON é validada pela Biblioteca Hull.
Para mais detalhes, consulte a documentação sobre a validação do esquema JSON.
Metadados uniformes e ricos são fixados automaticamente a todos os objetos criados pela Biblioteca do Hull.
Para obter mais detalhes sobre a sobrescrição de metadados, consulte o exemplo avançado abaixo.
Manuseio flexível do ConfigMap e entrada secreta escolhendo entre a especificação embutida do conteúdo em values.yaml ou importar de arquivos externos para conteúdo de tamanhos maiores. Ao importar dados dos arquivos, os dados podem ser executados através do mecanismo de modelos ou importados não tocados 'como estão' se já contiver expressões de modelos que serão transmitidas para o aplicativo consumidor. Com foco no manuseio conveniente de cenários padrão, você também pode definir o conteúdo de arquivo como uma estrutura de YAML regular nos values.yaml . Hull cuida da codificação Base64 de segredos, portanto, a gravação de configurações e segredos funciona exatamente da mesma maneira e a adição de configurações ou segredos à sua implantação requer apenas algumas linhas de código.
Para obter mais detalhes, consulte a documentação sobre o ConfigMaps and Secrets.
Extensos recursos de inadimplência para instanciar instâncias de objetos. Se você deseja ter todas as instâncias de objetos ou grupos de instâncias compartilham certos aspectos, como rótulos ou anotações, variáveis de ambiente de contêineres ou volumes montados, o Hull fornece suporte para definir com eficiência valores padrão para campos de instância de objeto, evitando repetições de configuração desnecessárias.
Para mais detalhes, consulte os conselhos de design de gráficos.
Para cenários mais complexos em que os valores reais no YAML alvo estão sujeitos a configurações nos values.yaml values.yaml Por exemplo, se os argumentos do seu contêiner de concreto dependem de várias outras configurações nos values.yaml , você poderá injetar as condições no cálculo dos argumentos ou simplesmente referenciar outros campos nos values.yaml .
Para mais detalhes, consulte a documentação sobre transformações.
Habilite o hash automático de configurações e segredos de configuração referenciados para facilitar o POD reiniciar as alterações de configuração quando necessário.
Para mais detalhes, consulte a documentação sobre pods.
Para saber mais sobre a arquitetura geral e os recursos da Biblioteca Hull, consulte a visão geral da arquitetura
Algumas coisas importantes a mencionar primeiro antes de olhar para a biblioteca com mais detalhes:
/templates não é completamente afetado pela integração do gráfico da biblioteca do Hull. Às vezes, você pode ter requisitos muito específicos em sua configuração ou especificação de objeto, que a Biblioteca do Hull não atende para que você possa usar o fluxo de trabalho de compensação regular para eles e a biblioteca do Hull para suas necessidades mais padrão - facilmente em paralelo no mesmo gráfico de comando.
hull.yaml , deve ser copiado 'como é' sem nenhuma modificação de uma pasta root de gráficos de casco incorporada na pasta dos gráficos /templates dos pais para poder renderizar qualquer YAML via casco. Ele contém o código que inicia o pipeline de renderização do Hull, consulte Adicionando o gráfico da biblioteca Hull a um gráfico de compensação para obter mais detalhes!
3.0.x não é compatível com o Hull, todas as outras versões não-beta e não alfa existentes atualmente são compatíveis.
1.29 e 1.30 e 1.31 têm uma liberação de casco correspondente e mantida.
Se você gosta de uma abordagem prática, é convidado a dar uma olhada na nova série de tutoriais do Hull em Dev.to! O tutorial da Eigth Part começará desde o início da criação de leme e criando um gráfico baseado em casco para finalizar um gráfico de leme baseado em casco na vida real passo a passo. Para destacar as diferenças para o fluxo de trabalho regular do gráfico de comando, os tutoriais pegam o gráfico popular kubernetes-dashboard como fonte e o transportam para um gráfico de leme baseado em casco funcionalmente equivalente. No final, mostra que a redução das linhas de configuração para criar e manter pode ser reduzida em mais de 50% ao usar uma abordagem baseada em casco, em vez do estilo regular do comando de escrita!
As tarefas de criação e configuração de um gráfico de leme baseadas em casco podem ser consideradas como dois lados da mesma moeda. Ambos os lados interagem com a mesma interface (a biblioteca do Hull) para especificar os objetos que devem ser criados. A tarefa da perspectiva de criadores/mantenedores é o principal de fornecer a estrutura do solo para os objetos que compõem o aplicativo específico que deve ser envolvido em um gráfico de comando. O consumidor do gráfico é encarregado de adicionar adequadamente o contexto específico do seu sistema à estrutura do solo, na qual ele tem a liberdade de mudar e até adicionar ou excluir objetos conforme necessário para atingir seus objetivos. No momento da implantação, a estrutura da base dos criadores é mesclada com o arquivo YAML específico do sistema de consumidores para criar a configuração completa. A interação através da mesma interface da biblioteca promove a compreensão comum de como trabalhar com a biblioteca de ambos os lados e pode eliminar a maioria dos tediosos processos de criação e exame de cópia e pasta.
Portanto, tudo o que é necessário para criar um gráfico de compensação baseado no Hull é uma estrutura de diretório de gráficos de companheiro de andaimes padrão. Adicione o gráfico da biblioteca Hull como um sub-chart, copie o hull.yaml do gráfico da biblioteca do Hull para a pasta /templates comando dos pais. Em seguida, basta configurar os objetos padrão a serem implantados por meio dos values.yaml e você terminou. Não há limite para quantos objetos de que tipo você cria para o seu pacote de implantação.
Mas, além de permitir definir aplicativos mais complexos com o Hull, você também pode usá-lo para embrulhar objetos simples de Kubernetes que você implantaria via Kubectl (estar fora da linha da perspectiva de gerenciamento com liberações de leme) ou ter que escrever uma quantidade significativa de quantidade de Modelos de caldeira de leme para conseguir isso.
A estrutura base dos values.yaml entendida por Hull é dada aqui na próxima seção. Isso forma essencialmente a interface única para produzir e consumir gráficos baseados em casco. Qualquer objeto é criado apenas caso seja definido e ativado nos values.yaml
No nível superior da estrutura YAML, o casco distingue entre config e objects . Enquanto a subconfiguração config visa lidar com configurações específicas do gráfico, como metadados e configurações de produto, os objetos concretos de Kubernetes a serem renderizados são especificados na chave objects . Uma terceira version de nível superior adicional também é permitida, quando ela está sendo definida para a versão dos gráficos do Hull, por exemplo, durante o pipeline de liberação de gráficos de companheiro de companheiro, ele preencherá automaticamente o rótulo vidispine.hull/version em todos os objetos indicando a versão do Hull que foi usado para renderizar os objetos.
config Na seção config , você pode definir configurações gerais para o seu gráfico de comando. É dividido em duas subseções, config.general e config.specific .
config.general Em contraste com a seção config.specific , que deve ser preenchida com dados arbitrários que são específicos apenas para um único gráfico de compensação, a seção config.general deve ser usada para definir tudo o que não é específico para um aplicativo exclusivo. Por um lado, ele contém opções de configuração relevantes para todos os gráficos baseados em casco, mas também deixa espaço sob a entrada config.general.data para definir seus próprios campos de dados, que idealmente são modelados da mesma maneira em outros gráficos de comando. Por exemplo, se vários aplicativos em um pacote de produtos dependem dos mesmos pontos de extremidade, você poderá modelar esses pontos de extremidade uniformemente na propriedade general.data em todos os gráficos relevantes e, assim, fazer com que seus gráficos de compensação interface da mesma maneira com um tubo de implantação contínuo.
config.general tem apenas os seguintes subfulitos:
nameOverride
fullnameOverride
namespaceOverride
noObjectNamePrefixes
createImagePullSecretsFromRegistries
globalImageRegistryServer
globalImageRegistryToFirstRegistrySecretServer
debug
rbac
data
serialization
postRender
errorChecks
metadata
| Parâmetro | Descrição | Padrão | Exemplo |
|---|---|---|---|
nameOverride | A substituição do nome é aplicada aos valores do Metadata Label app.kubernetes.io/name . Se definido, isso substitui efetivamente o nome do gráfico aqui. | ||
fullnameOverride | Se definido como um valor, a substituição do Name Fullname é aplicada como um prefixo a todos os nomes de objetos e substitui o padrão <release>-<chart> padrão em nomes de objetos. | myapp | |
namespaceOverride | Se definido como um valor, o espaço para nome de todos os objetos criados é definido como este valor. Se isso não estiver definido, o espaço para nome de todas as instâncias de objeto padrão no espaço de nome de liberação fornecido ao respectivo comando Helm. | my-namespace | |
noObjectNamePrefixes | Se definido, as teclas da instância do objeto servem diretamente como os nomes dos objetos Kubernetes criados e nunca são prefixados. Isso é tecnicamente equivalente a definir staticName TRUE em cada objeto. Observe que, ao definir isso como true o valor de config.general.fullnameOverride se torna irrelevante. | false | true |
createImagePullSecretsFromRegistries | Se verdadeiro, os segredos de tração da imagem são criados a partir de todos os registros definidos neste gráfico de comando e são adicionados a todos os pods. | true | false |
globalImageRegistryServer | Se não estiver vazio, o campo registry de todos os campos image de contêiner está definido como o valor fornecido aqui. A configuração de config.general.globalImageRegistryToFirstRegistrySecretServer é ignorada se esse campo não estiver vazio. Todas as configurações registry explícitas definidas para uma image são substituídas com esse valor.O uso pretendido disso é convenientemente ter todas as imagens extraídas de um registro central do Docker em caso de cenários de implantação como gap-ar. Ao contrário de definir globalImageRegistryToFirstRegistrySecretServer como true , neste caso o segredo do registro é normalmente definido fora deste gráfico de comando e o servidor do Secret do Registro é referenciado diretamente por seu nome. Se você usar esse recurso e definir o segredo do registro do Docker fora deste gráfico de comando, também poderá adicionar imagePullSecrets às suas vagens, caso o registro do Docker referenciado não seja inseguro. | "" | mycompany.docker-registry.io |
globalImageRegistryToFirstRegistrySecretServer | Se True e globalImageRegistryServer estiverem vazios, o campo registry de todos os campos image de contêiner será definido no campo server do primeiro objeto registry encontrado. Observe que este é o registro com o menor nome de chave alfanumérico se você fornecer vários obejcts registry . Normalmente, deve ser usado em conjunto com a configuração createImagePullSecretsFromRegistries , desde os registros do true para se beneficiar de imagePullSecrets automaticamente e definir registry . As configurações explícitas registry para uma image são substituídas com esse valor.O uso pretendido dessa configuração é convenientemente ter todas as imagens retiradas de um registro do Docker Central em caso de cenários de implantação como gap-ar. | false | true |
errorChecks | Opções que determinam em quais casos o Hull gerará um erro no helm template helm install ou capacete do Helm. Para mais detalhes, consulte também a documentação detalhada sobre a configuração de verificações de errosTem apenas os seguintes subfulitos: objectYamlValidhullGetTransformationReferenceValidcontainerImageValidvirtualFolderDataPathExistsvirtualFolderDataInlineValid | ||
errorChecks.objectYamlValid | Validar que nenhum YAML quebrado é renderizado | true | |
errorChecks.hullGetTransformationReferenceValid | Validar que todas as referências de todas _HT* apontam para uma chave existente nos values.yaml | true | |
errorChecks.containerImageValid | Validar que todos containers de pod e seções image initContainers existem e têm pelo menos um conjunto repository | true | |
errorChecks.virtualFolderDataPathExists | Validar que todos os arquivos que estão sendo referidos em um campo de dados e o campo path data do Secret existem fisicamente | true | |
errorChecks.virtualFolderDataInlineValid | Validar que não há valores null ou valores ausentes (que são convertidos em strings vazios) estão definidos para o ConfigMap e os campos inline data do Secret | false | |
debug | Opções que podem ajudar nos problemas de gráficos de depuração. Principalmente obsoleto e substituído pelas mensagens de erro padrão faladas configuradas em errorChecks .Tem apenas os seguintes subfulitos: renderBrokenHullGetTransformationReferencesrenderNilWhenInlineIsNilrenderPathMissingWhenPathIsNonExistent | ||
debug.renderBrokenHullGetTransformationReferences | Switch global que, se ativado, imprimirá uma string:HULL failed with error BROKEN-HULL-GET-TRANSFORMATION-REFERENCE: Element <y> in path <xyz> was not foundincluindo a referência _HT*/hull.util.transformation.get ( xyz ) e a chave ausente ( y ) se a transformação faz referência a uma chave de dicionário não existente. Isso é útil para a renderização do gráfico de depuração e reduz a busca de referências quebradas, porque normalmente a instalação aborta com um erro em referências quebradas (o que pode dificultar o identificação das referências problemáticas).OBSERVAÇÃO: A essa altura, qualquer referência de Get Broken será sinalizada por um erro de comando falante por padrão, para que esse comutador seja obsoleto principalmente por depurar referências quebradas. É recomendado para desativar essa opção e falhar com o Broken, obtenha referências e analise os problemas diretamente da mensagem de erro. | false | true |
debug.renderNilWhenInlineIsNil | Switch global que, se ativado, imprimirá uma string:<nil>Como um valor de campos de data , quando uma especificação inline faz referência a um ponteiro nil em um configuração ou segredo. Se definido como false, o valor nil será impresso como uma string vazia no campo ConfigMap ou Secret data .OBSERVAÇÃO: A essa altura, todos os campos em linha inválidos serão sinalizados por um erro de comando falante por padrão (significando hull.config.general.errorChecks.virtualFolderDataInlineValid é true ). A habilitação desse comutador é obsoleto principalmente para depuração e é recomendado para desativar essa opção e falhar duro em campos embutidos inválidos. | false | true |
debug.renderPathMissingWhenPathIsNonExistent | Switch global que, se ativado, imprimirá uma string:<path missing: the_missing_path>em um valor de campos de data de configuração ou dados secretos, incluindo o valor the_missing_path , que não resolve um arquivo. Se false, o valor dos campos data será resolvido em uma string vazia.OBSERVAÇÃO: A essa altura, qualquer arquivo inexistente referenciado em um campo de caminho será sinalizado por um erro de comando falante por padrão (significando hull.config.general.errorChecks.virtualFolderDataPathExists é true ). A habilitação desse comutador é obsoleto principalmente para depuração e é recomendado para desativar essa opção e falhar duro em referências de caminho de arquivo inexistentes. | false | true |
render | Opções para influenciar como o Hull renderiza objetos como YAML. Tem apenas os seguintes subfulitos: emptyAnnotationsemptyLabelsemptyHullObjects | ||
render.emptyAnnotations | Se true , o Hull renderiza annotations: {} Se não houver anotações para um objeto, se a chave annotations for false . | false | true |
render.emptyLabels | Se true , o Hull renderiza labels: {} Se não houver etiquetas para um objeto, se a chave false the labels for omitida. | false | true |
render.emptyTemplateAnnotations | Se true , o Hull renderiza annotations: {} no template de um pod se não houver anotações para um objeto, se a chave annotations for false . | false | true |
render.emptyTemplateLabels | Se true , o Hull renderiza labels: {} no template de pods if no labels exist for an object, if false the tecla Labels` for omitida. | false | true |
render.emptyHullObjects | Se true , o Hull renderiza as matrizes como matrizes vazias se não houver elementos para alguns campos processados pelo Hull. Se false, o par de valores-chave está omitido.Isso afeta os campos que são mapeados de um dicionário na configuração do casco para uma matriz de Kubernetes no YAML renderizado. A seguir, é apresentada uma lista de campos afetados na configuração de objetos de Hull:
| false | true |
postRender | Depois que o Hull renderizou totalmente um objeto, é possível manipular a sequência YAML resultante. As possibilidades de fazer isso são fornecidas como ações postRender aqui.Aviso: use com cautela, pois isso pode corromper a estrutura YAML! | ||
postRender.globalStringReplacements | Um dicionário de possibilidades de reposição que podem ser aplicadas ao YAML do objeto renderizado. O principal caso de uso para isso está em combinação com a extensa inadimplência em _HULL_OBJECT_TYPE_DEFAULT_ e sources instâncias de objeto em que permite injetar seqüências específicas de instância no YAML padrão. Os mapeamentos pré -configurados fornecidos podem ser enabled: true sob demanda. Cada mapeamento consiste em seguintes campos:
| ||
postRender.globalStringReplacements.instanceKey | Se enabled , o valor string será substituído pela instance_key do objeto real, como em hull.objects.<object_type>.<instance_key> O valor da replacement é OBJECT_INSTANCE_KEY para este mapeamento. | instanceKey:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_KEY | |
postRender.globalStringReplacements.instanceKeyResolved | Se enabled , o valor string será substituído pela instance_key do objeto real hull.objects.<object_type>.<instance_key>.metadataNameOverride como em hull.objects.<object_type>.<instance_key> O valor da replacement é OBJECT_INSTANCE_KEY_RESOLVED para este mapeamento. | instanceKeyResolved:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_KEY_RESOLVED | |
postRender.globalStringReplacements.instanceName | Se enabled , o valor string será substituído pelos metadata.name renderizados do objeto real. O valor da replacement é OBJECT_INSTANCE_NAME para este mapeamento. | instanceName:enabled: falsestring: _HULL_OBJECT_TYPE_DEFAULT_replacement: OBJECT_INSTANCE_NAME | |
serialization | Opções de serialização geral. | ||
serialization.configmap.enabled | Se enabled , as extensões de arquivo mapeadas em fileExtensions são serializadas com o método de serialização fornecido por padrão. Se a chave data terminar com uma das extensões mapeadas, o método de serialização no valor for usado para gravar o conteúdo na string. Um campo serialization específico em uma entrada data ConfigMaps substitui todas as configurações padrão. | true | |
serialization.configmap.fileExtensions | Um dicionário de mapeamentos de extensões de arquivo a métodos de serialização. | fileExtensions:json: toPrettyJsonyaml: toYamlyml: toYaml | |
serialization.secret.enabled | Se enabled , as extensões de arquivo mapeadas em fileExtensions são serializadas com o método de serialização fornecido por padrão. Se a chave data terminar com uma das extensões mapeadas, o método de serialização no valor for usado para gravar o conteúdo na string. Um campo serialization específico em uma entrada data de segredos substitui todas as configurações padrão. | true | |
serialization.secret.fileExtensions | Um dicionário de mapeamentos de extensões de arquivo a métodos de serialização. | fileExtensions:json: toPrettyJsonyaml: toYamlyml: toYaml | |
config.general.rbac | Switch global que permite objetos RBAC para instalação. Se todos os objetos RBAC habilitados true forem implantados no cluster, se os objetos false nenhum RBAC forem criados.Os objetos RBAC implantáveis são: rolesrolebindingsclusterrolesclusterrolebindings | true | false |
config.general.data | Campo de formulário livre, enquanto os subcampos desse campo devem ter um significado claramente definido no contexto do seu conjunto de produtos. Por exemplo, suponha que todos os seus produtos ou microsserviços (cada um como um gráfico de comando separado) depende dos mesmos pontos de extremidade (autenticação, configuração, ...). Você pode ter um trabalho de Kubernetes compartilhado executado por cada gráfico de comando que visa esses pontos de extremidade. Agora você pode especificar um values.yaml externos do casco. YAML contendo a especificação do trabalho e a definição de endpoint aqui de uma maneira que você vê ajuste e construa um values.yaml de sobreposição. | {} | |
config.general.metadata | Os campos de metadados definidos aqui serão adicionados automaticamente a todos os metadados dos objetos. Tem apenas os seguintes subfulitos: labelsannotations | ||
config.general.metadata.labels | Rótulos adicionados a todos os objetos. Os rótulos common se referem aos Kubernetes e rótulos comuns do comando e rótulos custom podem ser especificados gratuitamente.Tem apenas os seguintes subfulitos: commoncustom | ||
config.general.metadata.labels.common | Especificação de etiquetas comuns, conforme definido em https://helm.sh/docs/chart_best_practices/labels/ e https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/. A menos que especificamente substituído por valores vazios ( '' ), todos os rótulos de metadados são adicionados automaticamente a todos os objetos de acordo com sua definição padrão. Deve-se considerar definir um valor para config.general.metadata.labels.common.'app.kubernetes.io/part-of' Se o gráfico do helm for parte de um conjunto de produtos. | ||
config.general.metadata.labels.common.'app.kubernetes.io/managed-by' | Gerenciado por metadados. | {{ .Release.Service }} | |
config.general.metadata.labels.common.'app.kubernetes.io/version' | Metadados da versão. | {{ .Chart.AppVersion }} | |
config.general.metadata.labels.common.'app.kubernetes.io/part-of' | Parte dos metadados. | "unspecified" | |
config.general.metadata.labels.common.'app.kubernetes.io/name' | Nome Metadata. | {{ printf "%s-%s" .ChartName <hullObjectKey> }} | |
config.general.metadata.labels.common.'app.kubernetes.io/instance' | Metadados da instância. | {{ .Release.Name }} | |
config.general.metadata.labels.common.'app.kubernetes.io/component' | Metadados do componente. | <hullObjectKey> | |
config.general.metadata.labels.common.'helm.sh/chart' | Metadados do comando. | `{{(printf"%s-%s ".Chart.Name .Chart.version) | Substitua "+" "_"}} ` |
config.general.metadata.labels.custom | Todos os rótulos personalizados especificados são adicionados automaticamente a todos os objetos deste gráfico de compensação. | {} | |
config.general.metadata.annotations | Anotações adicionadas a todos os objetos. Os rótulos custom podem ser especificados gratuitamente.Tem apenas os seguintes subfulitos: custom . | ||
config.general.metadata.annotations.custom | Todas as anotações personalizadas especificadas são adicionadas automaticamente a todos os objetos deste gráfico de compensação. | {} | |
config.specific | Campo de formulário livre que contém opções de configuração específicas para o produto específico contido no gráfico de comando. Normalmente, os valores especificados aqui devem ser usados para preencher o conteúdo dos arquivos de configuração que um determinado aplicativos leu sua configuração na inicialização. Portanto, os campos config.specific estão sendo consumidos em configmaps ou segredos. | {} | maxDatepickerRange: 50defaultPoolColor: "#FB6350"updateInterval: 60000 |
objects Os tipos de objetos de nível superior abaixo do hull.objects representam os tipos de objetos Kubernetes suportados dos quais você pode querer criar instâncias. Cada tipo de objeto é um dicionário em que os valores de entradas são as propriedades dos objetos e cada objeto tem sua própria chave, exclusiva do tipo de objeto a que pertence. Mais tipos de objetos K8S podem ser adicionados conforme necessário à biblioteca, para que possa ser facilmente estendida.
Um aspecto importante é que, para todos os tipos de objetos de nível superior, as instâncias de um tipo específico são sempre identificadas por uma chave exclusiva da combinação de instância e tipo de objeto. No entanto, a mesma chave pode ser usada para instâncias de diferentes tipos de objetos.
Ao ter chaves que identificam instâncias, você pode:
Faça a fusão de várias camadas das propriedades do objeto, values.yaml os arquivos. Você pode começar com a definição da estrutura de objeto padrão do aplicativo ou micro serviço definido no gráfico de compensação fornecida. Em seguida, você pode adicionar um values.yaml . Então você pode adicionar um values.yaml Camada para credenciais. E assim por diante. 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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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
| CASCO Object Type | CASCO Propriedades | Kubernetes/External Propriedades |
|---|---|---|
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.
