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.
• Antes da versão 1.19.0 do Config Sync, todas as configurações precisavam estar incluídas no diretório raiz do Kustomization. A partir da versão 1.19.0, o Config Sync tem suporte para arquivos fora do diretório raiz.

Observação: o Config Sync não é compatível com bases remotas de fontes de verdade particulares. É possível extrair bases remotas de fontes públicas de verdade durante a renderização se você definir spec.override.enableShellInRendering como true, mas isso não é recomendado devido a riscos de segurança.

Renderizar 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.

Exemplo de arquitetura para configurações do Kustomize

Esse diretório inclui quatro sobreposições (team-a, team-b, team-c e external-team) que fazem referência à mesma base e um arquivo usado pelo gerador de ConfigMap.

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

├── example
│   ├── 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
├── external-team
│   └── kustomization.yaml
└── external-data.txt

O arquivo kustomization.yaml abaixo está na raiz da fonte da verdade e contém referências às quatro sobreposições com um gerador de ConfigMap de um arquivo local:

# ./example/kustomization.yaml
resources:
- team-a
- team-b
- team-c
- ../external-team # Starting from 1.19.0, Config Sync allows external resources located outside of the Kustomization root directory.

configMapGenerator:
- name: my-configmap
  namespace: my-namespace
  files:
    - ../external-data.txt # Starting from 1.19.0, Config Sync allows external files located outside of the Kustomization root directory.

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

# ./example/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: [e-mail]
- 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:

# ./example/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 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.

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 diagrama a seguir mostra a estrutura de diretórios:

├── base
│   ├── charts
│   │   └── cert-manager
│   └── kustomization.yaml
├── overlays
│   └── stage
│       └── kustomization.yaml
└── base_value_overrides.yaml

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.

# ./overlays/stage/kustomization.yaml
...
# This field is optional if your Helm charts are located in the default 'charts' directory.
helmGlobals:
  # Starting from 1.19.0, Config Sync allows loading from an external directory outside of the Kustomization root.
  chartHome: ../../base/charts
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
  # Specify a local path or a remote URL to a values file instead of using the default values in CHART_HOME/NAME/values.yaml.
  valuesFile: ../../base_value_overrides.yaml
...

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

• Usar o Config Sync com o Kustomize e o Helm
• Usar o Config Sync em vários ambientes com renderização automatizada