Configurar o Kubernetes com Kustomize

O Kustomize é uma ferramenta de transformação de configuração do Kubernetes que permite personalizar arquivos YAML sem modelos, deixando os arquivos originais intactos. O Kustomize também gera recursos como ConfigMaps e Secrets de outras representações. O Kustomize foi criado para a API Kubernetes, por isso consegue entender e modificar objetos no estilo Kubernetes.

Se você quiser usar os gráficos do Helm com o Config Sync, há dois métodos compatíveis: renderizar o Helm pelo Kustomize ou usar a API Helm. Nesta página, detalhamos os requisitos para renderizar gráficos do Helm por meio do Kustomize. Para mais informações sobre como usar a API Helm, consulte Como sincronizar gráficos do Helm a partir do Artifact Registry.

As seguintes diferenças se aplicam ao usar o Kustomize para renderizar gráficos do Helm:

  • Registros particulares e baseados em OCI não são compatíveis. Com a API Helm, os registros privados e baseados em OCI são compatíveis.
  • Os valores do Helm podem ser gerenciados na fonte da verdade. Com a API Helm, os valores são gerenciados como parte da API RootSync ou RepoSync.
  • É possível renderizar vários gráficos do Helm em um objeto RootSync ou RepoSync. Com a API Helm, é possível renderizar apenas um gráfico do Helm em um objeto RootSync ou RepoSync.

Requisitos do Config Sync para Kustomize

Para renderizar automaticamente as configurações do Kustomize e os gráficos do Helm, verifique se o ambiente do Config Sync atende aos seguintes requisitos:

  • Usa uma fonte de verdade não estruturada. A renderização automática não é compatível com origens hierárquicas.
  • Para acionar o processo de renderização, sua fonte da verdade precisa ter um arquivo de configuração do Kustomization (kustomization.yaml, kustomization.yml ou Kustomization) na raiz do seu diretório. Se o diretório raiz não tiver um arquivo de configuração do Kustomization, o Config Sync sincronizará as configurações como estão sem qualquer renderização.
  • Inclua suas configurações no arquivo kustomization.yaml. Se você não incluir esses arquivos de configuração, eles não serão sincronizados com o cluster.

Renderizar gráficos do Helm no Kustomize

Esta seção explica como renderizar gráficos do Helm por meio do Kustomize. As versões do Helm e do Kustomize incluídas listam as versões do Kustomize e do Helm incluídas na versão correspondente do Config Sync.

Campos do gráfico Helm

É possível adicionar os seguintes campos do gráfico do Helm aos arquivos kustomization.yaml para aceitar a renderização de gráficos do Helm por meio do Kustomize:

Campo Descrição
helmGlobals Parâmetros aplicados a todos os gráficos Helm
helmGlobals.chartHome Aceita uma string. Um caminho relativo à raiz do Kustomization, para um diretório que contém um subdiretório para cada gráfico a ser incluído no Kustomization. O valor padrão desse campo é charts.
helmGlobals.configHome Aceita uma string. Define um valor que o Kustomize precisa passar para o Helm com a variável de ambiente HELM_CONFIG_HOME. O Kustomize não tenta ler nem gravar esse diretório. Se omitido, TMP_DIR/helm é usado, em que TMP_DIR é um diretório temporário criado pelo Kustomize para Helm.
helmCharts Uma matriz de parâmetros de gráfico do Helm
helmCharts.name Aceita uma string. É o nome do gráfico. Este campo é obrigatório.
helmCharts.version Aceita uma string. A versão do gráfico
helmCharts.repo Aceita uma string. O URL usado para localizar o gráfico
helmCharts.releaseName Aceita uma string. Substitui RELEASE_NAME na saída do modelo de gráfico.
helmCharts.namespace Aceita uma string. Define o namespace de destino para uma versão (.Release.Namespace no modelo)
helmCharts.valuesInline Valores a serem usados em vez de valores padrão que acompanham o gráfico
helmCharts.valuesFile Aceita uma string. ValuesFile é um caminho do local ou um URL remoto para um arquivo a ser usado em vez dos valores padrão que acompanham o gráfico. Os valores padrão estão em CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Aceita merge, override, (default) ou replace. ValuesMerge especifica como tratar ValuesInline em relação a Values.
helmCharts.includeCRDs Aceita true ou false. Especifica se Helm também deve gerar CustomResourceDefinitions. O valor padrão é false.

Exemplo de arquitetura para configurações do Kustomize

O exemplo abaixo demonstra como configurar sua fonte de verdade para usar as configurações do Kustomize com renderização automática. Esse diretório inclui três sobreposições (team-a, team-b e team-c) que fazem referência à mesma base.

O diagrama a seguir mostra a estrutura de diretórios:

├── base
│   ├── kustomization.yaml
│   ├── namespace.yaml
│   ├── networkpolicy.yaml
│   ├── rolebinding.yaml
│   └── role.yaml
├── kustomization.yaml
├── README.md
├── team-a
│   └── kustomization.yaml
├── team-b
│   └── kustomization.yaml
└── team-c
    └── kustomization.yaml

O arquivo kustomization.yaml abaixo está na raiz da fonte da verdade e contém referências às três sobreposições:

# ./kustomization.yaml
resources:
- team-a
- team-b
- team-c

O kustomize.yaml a seguir está no diretório team-a e é a sobreposição de team-a:

# ./team-a/kustomization.yaml
namespace: team-a

resources:
- ../base

patches:
- target:
   kind: RoleBinding
   name: team-admin-rolebinding
  patch: |-
    - op: replace
      path: /subjects/0/name
      value: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

O seguinte kustomization.yaml está no diretório base e é a base do Kustomize:

# ./base/kustomization.yaml
resources:
- namespace.yaml
- rolebinding.yaml
- role.yaml
- networkpolicy.yaml

Confira um repositório de exemplo no diretório Como configurar políticas específicas de namespace no GitHub (link em inglês).

Renderizar um gráfico Helm remoto

O Config Sync é compatível com a renderização de gráficos Helm remotos em clusters que têm acesso público à Internet.

O kustomization.yaml a seguir renderiza um cert-manager remoto definindo os seguintes campos helmCharts:

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  repo: https://charts.jetstack.io
  version: v1.5.3
  releaseName: my-cert-manager
  namespace: cert-manager
...

Renderizar um gráfico Helm local

O Config Sync é compatível com a renderização de gráficos Helm locais. Para usar uma versão personalizada de um gráfico do Helm, extraia a versão lançada do gráfico do Helm (por exemplo, ArtifactHub), faça alterações localmente e envie por push as mudanças em sua fonte de informações.

O kustomization.yaml a seguir renderiza um gráfico cert-manager local. O diretório padrão para gráficos do Helm é charts e, como esse gráfico é verificado no diretório charts, não é necessário especificar .helmCharts.repo ou .helmCharts.version. de dados.

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
...

Renderizar vários gráficos Helm

O Config Sync é compatível com a renderização de vários gráficos Helm em um arquivo kustomization.yaml, independentemente de o gráfico ser remoto ou local.

O seguinte kustomization.yaml renderiza um gráfico Helm local (cert-manager):

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
- name: prometheus
  repo: https://prometheus-community.github.io/helm-charts
  version: 14.3.0
  releaseName: my-prometheus
  namespace: monitoring
...

A seguir