Configure o Kubernetes com o Kustomize

O Kustomize é uma ferramenta de transformação de configuração do Kubernetes que lhe permite personalizar ficheiros YAML sem modelos, deixando os ficheiros originais intactos. O Kustomize também pode gerar recursos, como ConfigMaps e Secrets, a partir de outras representações. O Kustomize foi criado para a API Kubernetes, pelo que pode compreender e modificar objetos no estilo do Kubernetes.

Se quiser usar gráficos Helm com o Config Sync, existem dois métodos suportados: renderizar o Helm através do Kustomize ou usar a API Helm. Esta página detalha os requisitos para a renderização de gráficos Helm através do Kustomize. Para mais informações sobre a utilização da API Helm, consulte Sincronizar gráficos Helm do Artifact Registry.

As seguintes diferenças aplicam-se quando usa o Kustomize para renderizar gráficos Helm:

  • Os registos Helm privados e baseados em OCI não são suportados. Com a API Helm, são suportados registos privados e baseados em OCI.
  • Os valores do Helm podem ser geridos na fonte de verdade. Com a API Helm, os valores são geridos como parte da API RootSync ou RepoSync.
  • A renderização de vários gráficos Helm num objeto RootSync ou RepoSync é suportada. Com a API Helm, só pode renderizar um gráfico Helm num objeto RootSync ou RepoSync.

Requisitos do Config Sync para o Kustomize

Para renderizar automaticamente as configurações do Kustomize e os gráficos do Helm, certifique-se de que o seu ambiente do Config Sync cumpre os seguintes requisitos:

  • Usa uma fonte de informações verdadeiras não estruturada. A renderização automática não é suportada para origens hierárquicas.
  • Para acionar o processo de renderização, a sua fonte de dados fidedignos tem de ter um ficheiro de configuração de personalização (kustomization.yaml, kustomization.yml ou Kustomization) na raiz do diretório. Se o diretório raiz não tiver um ficheiro de configuração de personalização, o Config Sync sincroniza as configurações tal como estão, sem qualquer renderização.
  • Inclua as suas configurações no ficheiro kustomization.yaml. Se não incluir estes ficheiros de configuração, as configurações não são sincronizadas com o cluster.

Renderize configurações do Kustomize

O exemplo seguinte demonstra como pode configurar a sua fonte de dados fidedignos para usar configurações do Kustomize com renderização automática.

Exemplo de arquitetura para configurações do Kustomize

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

O diagrama seguinte mostra a estrutura do diretório:

├── 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 seguinte ficheiro kustomization.yaml encontra-se na raiz da fonte prioritária e contém referências às quatro sobreposições com um gerador ConfigMap a partir de um ficheiro local:

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

configMapGenerator:
- name: my-configmap
  namespace: my-namespace
  files:
    - ../external-data.txt

O seguinte kustomize.yaml está no diretório team-a e é a sobreposição para 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: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

O seguinte kustomization.yaml encontra-se no diretório base e é a base do Kustomize:

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

Pode explorar um repositório de exemplo no diretório configuring namespace-specific policies no GitHub.

Renderize gráficos Helm através do Kustomize

Esta secção explica como renderizar gráficos Helm através do Kustomize. A lista de versões do Helm e do Kustomize incluídas apresenta as versões do Kustomize e do Helm incluídas na versão correspondente do Config Sync.

Campos do gráfico Helm

Pode adicionar os seguintes campos de gráfico Helm aos seus ficheiros kustomization.yaml para suportar a renderização de gráficos Helm através do Kustomize:

Campo Descrição
helmGlobals Parâmetros aplicados a todos os gráficos Helm
helmGlobals.chartHome Aceita uma string. Um caminho, relativo à raiz de personalização, para um diretório que contenha um subdiretório para cada gráfico a incluir na personalização. O valor predefinido deste campo é charts.
helmGlobals.configHome Aceita uma string. Define um valor que o Kustomize deve transmitir ao Helm com a variável de ambiente HELM_CONFIG_HOME. O Kustomize não tenta ler nem escrever neste diretório. Se for omitido, é usado TMP_DIR/helm, onde TMP_DIR é um diretório temporário criado pelo Kustomize para o Helm.
helmCharts Uma matriz de parâmetros do gráfico 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 espaço de nomes de destino para uma versão (.Release.Namespace no modelo)
helmCharts.valuesInline Valores a usar em vez dos valores predefinidos que acompanham o gráfico
helmCharts.valuesFile Aceita uma string. ValuesFile é um caminho local ou um URL remoto para um ficheiro de valores a usar em vez dos valores predefinidos que acompanhavam o gráfico. Os valores predefinidos estão em CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Aceita merge, override, (default) ou replace. ValuesMerge especifica como tratar ValuesInline relativamente a Values.
helmCharts.includeCRDs Aceita true ou false. Especifica se o Helm também deve gerar CustomResourceDefinitions. O valor predefinido é false.

Renderize um gráfico Helm remoto

O Config Sync suporta a renderização de gráficos Helm remotos em clusters com acesso público à Internet.

O seguinte kustomization.yaml 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
...

Renderize um gráfico Helm local

O Config Sync suporta a renderização de gráficos Helm locais. Para usar uma versão personalizada de um gráfico Helm, pode extrair a versão lançada do gráfico Helm (por exemplo, ArtifactHub), fazer alterações localmente e, em seguida, enviar as alterações para a sua fonte de verdade.

O diagrama seguinte mostra a estrutura do diretório:

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

O seguinte kustomization.yaml renderiza um gráfico cert-manager local. O diretório predefinido para gráficos Helm é charts e, uma vez que este gráfico está registado no diretório charts, não precisa de especificar .helmCharts.repo nem .helmCharts.version.

# ./overlays/stage/kustomization.yaml
...
# This field is optional if your Helm charts are located in the default 'charts' directory.
helmGlobals:
  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
...

Renderize vários gráficos Helm

O Config Sync suporta a renderização de vários gráficos Helm num ficheiro kustomization.yaml, independentemente de o gráfico ser remoto ou local.

O seguinte comando 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
...

O que se segue?