Configure Kubernetes con Kustomize

Kustomize es una herramienta de transformación de configuración de Kubernetes que te permite personalizar archivos YAML sin plantillas y dejar los archivos originales sin modificar. Kustomize también puede generar recursos como ConfigMaps y Secrets a partir de otras representaciones. Kustomize está compilado para la API de Kubernetes, por lo que puede comprender y modificar objetos con estilo de Kubernetes.

Si quieres usar gráficos de Helm con el Sincronizador de configuración, hay dos métodos compatibles: renderizar Helm a través de Kustomize o usar la API de Helm. En esta página, se detallan los requisitos para renderizar gráficos de Helm a través de Kustomize. Para obtener más información sobre el uso de la API de Helm, consulta Sincroniza gráficos de Helm desde Artifact Registry.

Se aplican las siguientes diferencias cuando se usa Kustomize para renderizar gráficos de Helm:

  • No se admiten los registros de Helm privados ni basados en OCI. Con la API de Helm, se admiten registros privados y basados en OCI.
  • Los valores de Helm se pueden administrar en la fuente de información. Con la API de Helm, los valores se administran como parte de la API de RootSync o RepoSync.
  • Se admite la renderización de varios gráficos de Helm en un objeto RootSync o RepoSync. Con la API de Helm, puedes renderizar solo un gráfico de Helm en un objeto RootSync o RepoSync.

Requisitos del Sincronizador de configuración para Kustomize

Para renderizar de forma automática las opciones de configuración de Kustomize y los gráficos de Helm, asegúrate de que el entorno del Sincronizador de configuración cumpla con los siguientes requisitos:

  • Usa una fuente de información no estructurada. El procesamiento automático no es compatible con las fuentes jerárquicas.
  • Para activar el proceso de renderización, tu fuente de información debe tener un archivo de configuración de Kustomization (kustomization.yaml, kustomization.yml o Kustomization) en la raíz de tu directorio. Si el directorio raíz no tiene un archivo de configuración de Kustomization, el Sincronizador de configuración sincroniza los archivos de configuración como están sin ninguna renderización.
  • Incluye tus archivos de configuración en el archivo kustomization.yaml. Si no incluyes estos archivos de configuración, no se sincronizan con el clúster.
  • Antes del Sincronizador de configuración 1.19.0, todas las configuraciones se debían incluir en el directorio raíz de Kustomization. A partir de la versión 1.19.0, el Sincronizador de configuración admite archivos fuera del directorio raíz.

Renderiza configuraciones de Kustomize

En el siguiente ejemplo, se muestra cómo puedes configurar tu fuente de información para usar las opciones de configuración de Kustomize con la renderización automática.

Arquitectura de ejemplo para las opciones de configuración de Kustomize

Este directorio incluye cuatro superposiciones (team-a, team-b, team-c y external-team) que hacen referencia a la misma base y un archivo que usa el generador de ConfigMap.

En el siguiente diagrama, se muestra la estructura del directorio:

├── 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

El siguiente archivo kustomization.yaml se encuentra en la raíz de la fuente de información y contiene referencias a las cuatro superposiciones con un generador de ConfigMap desde un archivo 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.

El siguiente kustomize.yaml está en el directorio team-a y es la superposición 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: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

El siguiente kustomization.yaml está en el directorio base y es la base de Kustomize:

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

Puedes explorar un repositorio de ejemplo en el directorio configura políticas específicas de espacio de nombres en GitHub.

Renderiza gráficos de Helm a través de Kustomize

En esta sección, se explica cómo renderizar gráficos de Helm a través de Kustomize. En Versiones de Helm y Kustomize empaquetadas, se enumeran las versiones de Kustomize y Helm empaquetadas con la versión correspondiente del Sincronizador de configuración.

Campos del gráfico de Helm

Puedes agregar los siguientes campos de gráfico de Helm a tus archivos kustomization.yaml para admitir la renderización de gráficos de Helm a través de Kustomize:

Campo Descripción
helmGlobals Parámetros aplicados a todos los gráficos de Helm
helmGlobals.chartHome Acepta una string. Una ruta de acceso, en relación con la raíz de Kustomization, a un directorio que contiene un subdirectorio para cada gráfico que se incluirá en Kustomization. El valor predeterminado de este campo es charts.
helmGlobals.configHome Acepta una string. Define un valor que Kustomize debe pasar a Helm con la variable de entorno HELM_CONFIG_HOME. Kustomize no intenta leer ni escribir este directorio. Si se omite, se usa TMP_DIR/helm, en el que TMP_DIR es un directorio temporal que Kustomize creó para Helm.
helmCharts Un arreglo de parámetros de gráficos de Helm
helmCharts.name Acepta una string. Es el nombre del gráfico. Este campo es obligatorio.
helmCharts.version Acepta una string. La versión del gráfico
helmCharts.repo Acepta una string. La URL que se usa para ubicar el gráfico
helmCharts.releaseName Acepta una string. Reemplaza RELEASE_NAME en el resultado de la plantilla del gráfico.
helmCharts.namespace Acepta una string. Establece el espacio de nombres de destino de una versión (.Release.Namespace en la plantilla)
helmCharts.valuesInline Valores para usar en lugar de valores predeterminados que acompañan al gráfico
helmCharts.valuesFile Acepta una string. ValuesFile es una ruta de acceso local o una URL remota a un archivo de valores para usar en lugar de los valores predeterminados que acompañaban al gráfico. Los valores predeterminados están en CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Se acepta merge, override, (default) o replace. ValueFusion especifica cómo tratar los valores en línea con respecto a los valores.
helmCharts.includeCRDs Se acepta true o false. Especifica si Helm también debe generar CustomResourceDefinitions. El valor predeterminado es false.

Renderiza un gráfico de Helm remoto

El Sincronizador de configuración admite la renderización de gráficos de Helm remotos en clústeres que tienen acceso público a Internet.

El siguiente kustomization.yaml renderiza un cert-manager remoto mediante la configuración de los siguientes campos helmCharts:

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

Renderiza un gráfico de Helm local

El Sincronizador de configuración admite la renderización de gráficos de Helm locales. Para usar una versión personalizada de un gráfico de Helm, puedes extraer la versión de actualización desde el gráfico de Helm (por ejemplo, ArtifactHub), realizar cambios de forma local y, luego, enviar los cambios a tu fuente de confianza.

En el siguiente diagrama, se muestra la estructura del directorio:

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

En el siguiente kustomization.yaml, se renderiza un gráfico cert-manager local. El directorio predeterminado para los gráficos de Helm es charts y, como este gráfico se registra en el directorio charts, no necesitas especificar .helmCharts.repo ni .helmCharts.version.

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

Renderiza varios gráficos de Helm

El Sincronizador de configuración admite la renderización de varios gráficos de Helm en un archivo kustomization.yaml, sin importar si el gráfico es remoto o local.

En el siguiente kustomization.yaml, se renderiza un gráfico de 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
...

¿Qué sigue?