Personalizar la configuración de containerd en nodos de GKE

En esta página se explica cómo personalizar la configuración del tiempo de ejecución de contenedores containerd en los nodos de Google Kubernetes Engine (GKE). Antes de leer este documento, asegúrate de que sabes qué es un runtime de contenedor y por qué querrías personalizarlo.

Información sobre la configuración de containerd en GKE

Puedes configurar manualmente un conjunto de opciones en el tiempo de ejecución de containerd en nodos de GKE que ejecuten un sistema operativo como Container-Optimized OS. La personalización del tiempo de ejecución te permite configurar requisitos especiales, como el acceso a registros de imágenes privadas. Para definir estas opciones, debes crear un archivo YAML llamado archivo de configuración de tiempo de ejecución y pasárselo a GKE cuando crees o actualices un clúster.

Este método de personalización de containerd te permite evitar la implementación de DaemonSets con privilegios, que suponen un riesgo para la seguridad. Cuando proporcionas a GKE un archivo de configuración de tiempo de ejecución, GKE vuelve a crear los nodos y actualiza el archivo config.toml de containerd en cada nodo con tu configuración. La configuración se mantiene aunque se termine, actualice o vuelva a crear el nodo.

El archivo de configuración de tiempo de ejecución solo te permite configurar opciones en containerd. GKE también permite configurar opciones específicas de kubelet y opciones de kernel de Linux de bajo nivel mediante un archivo independiente llamado archivo de configuración del sistema de nodos. Para obtener más información, consulta el artículo sobre cómo personalizar la configuración del sistema de nodos.

Limitaciones

No puedes usar un archivo de configuración de tiempo de ejecución para cambiar los ajustes de containerd en imágenes de nodos de Windows.

Opciones de configuración de containerd disponibles

En las siguientes secciones se describen las opciones que puede configurar mediante un archivo de configuración de tiempo de ejecución.

privateRegistryAccessConfig

Accede a registros de imágenes privados con credenciales privadas que almacenes en Secret Manager.

Esta opción está disponible en las versiones de GKE 1.27.3-gke.1700 o posteriores para las imágenes de nodo de Container-Optimized OS, y en la versión 1.33 o posteriores para las imágenes de nodo de Ubuntu.

Para obtener instrucciones, consulta Acceder a registros privados con certificados de CA privada.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

Esta configuración tiene los siguientes campos:

  • enabled: valor booleano para habilitar la configuración del registro privado. Si has definido enabled: false, elimina los demás campos del elemento privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: contiene hasta cinco definiciones de certificados y FQDN.
  • gcpSecretManagerCertificateConfig: contiene un certificado almacenado en Secret Manager y un array de FQDNs.
  • secretURI: la ubicación del certificado en Secret Manager. privateRegistryAccessConfig solo admite secretos globales en secretURI.
  • fqdns: una lista de nombres de dominio completos de registros privados. También puedes usar direcciones IPv4, pero te recomendamos que utilices el FQDN.

registryHosts

Configura los ajustes avanzados de los registros de containerd, como las funciones, los encabezados personalizados y los certificados. Esto corresponde al archivo hosts.toml de containerd.

Esta opción está disponible en las versiones 1.34.1-gke.2980000 o posteriores de GKE.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

Esta configuración tiene los siguientes campos:

  • server: nombre de host del servidor de registro (por ejemplo, example.com). Se usa para asignar un nombre al archivo de configuración del nodo. Debe ser un nombre de dominio completo o una dirección IPv4.
  • hosts: lista de configuraciones específicas del host para server.
  • host: el nombre de host de un mirror del registro (por ejemplo, mirror.example.com). Deben ser nombres de dominio completos o direcciones IPv4.
  • capabilities: lista de funciones que especifican las operaciones que puede realizar un host. Los valores posibles son:
    • HOST_CAPABILITY_PULL: representa la capacidad de obtener manifiestos y blobs por digest.
    • HOST_CAPABILITY_RESOLVE: representa la capacidad de obtener manifiestos por nombre.
    • HOST_CAPABILITY_PUSH: representa la capacidad de enviar blobs y manifiestos.
    Si no se especifica, todas las funciones están habilitadas.
  • overridePath: un valor booleano. Si true, indica que el endpoint raíz de la API del host se define en la ruta de la URL en lugar de en la especificación de la API. Se puede usar con registros de OCI que no cumplan los requisitos y a los que les falte el prefijo /v2. El valor predeterminado es false.
  • dialTimeout: una cadena de duración (por ejemplo, "30s") que especifica la duración máxima permitida para que se complete un intento de conexión. El valor máximo permitido es "180s". Si no se define, containerd establece el valor predeterminado "30s". El valor debe ser un número decimal de segundos con el sufijo s.
  • header: lista de encabezados HTTP personalizados que se enviarán al host del registro.
    • key: la clave de la cabecera.
    • value: lista de valores de encabezado.
  • ca: lista de configuraciones de certificados de la autoridad de certificación (CA) del host del registro. Para crear un secreto para los certificados y configurar los permisos necesarios, consulta las instrucciones de Almacenar las claves públicas de la AC en Secret Manager.
    • gcpSecretManagerSecretUri: el URI de un secreto de Secret Manager que contiene el certificado de la AC. Admite secretos globales y regionales. Los formatos son los siguientes para los respectivos tipos de secreto:
      • Formato de secreto global: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Formato del secreto regional: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: lista de pares de claves y certificados de cliente para autenticar el host del registro. Para crear un secreto para los certificados y configurar los permisos necesarios, consulta las instrucciones de Almacenar las claves públicas de la AC en Secret Manager.
    • cert: la configuración del certificado de cliente.
      • gcpSecretManagerSecretUri: el URI de un secreto de Secret Manager que contiene el certificado de cliente. Admite tanto secretos globales como regionales.
    • key: configuración de la clave privada del cliente.
      • gcpSecretManagerSecretUri: el URI de un secreto de Secret Manager que contiene la clave de cliente. Admite tanto secretos globales como regionales.

writableCgroups

Monta el sistema de archivos /sys/fs/cgroup en modo de lectura y escritura para que las cargas de trabajo puedan gestionar los recursos de sus procesos secundarios.

Esta opción está disponible en las versiones 1.34.1-gke.2541000 o posteriores de GKE.

Para obtener más información, consulta Configurar cgroups grabables para contenedores.

writableCgroups:
  enabled: true

Aplicar la configuración de containerd a clústeres nuevos

En esta sección se explica cómo aplicar un archivo de configuración de containerd al crear un clúster de GKE.

Ejecuta el siguiente comando para crear clústeres de Autopilot:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Haz los cambios siguientes:

  • CLUSTER_NAME: el nombre del nuevo clúster.
  • LOCATION: la ubicación de Compute Engine de tu nuevo clúster.
  • PATH_TO_CONFIG_FILE: la ruta al archivo de configuración que has creado, como ~/containerd-configuration.yaml.

Puedes habilitar la configuración de containerd en los nuevos clústeres estándar ejecutando el comando gcloud container clusters create con las mismas opciones.

Aplicar la configuración de containerd a grupos de nodos nuevos

Puedes aplicar la configuración de containerd a un nuevo grupo de nodos de GKE con el siguiente comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Haz los cambios siguientes:

  • NODE_POOL_NAME: el nombre del nuevo grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster.
  • LOCATION: la ubicación de Compute Engine de tu nuevo grupo de nodos.
  • PATH_TO_CONFIG_FILE: la ruta al archivo de configuración que has creado, como ~/containerd-configuration.yaml.

Aplicar la configuración de containerd a clústeres

En esta sección se muestra cómo aplicar una configuración de containerd a clústeres y nodos.

Comprobar los permisos de acceso

Los clústeres ya creados deben tener el ámbito de acceso cloud-platform para usar esta función. En esta sección se explica cómo comprobar los ámbitos de acceso y actualizar un clúster con un archivo de configuración de registro privado nuevo o modificado.

Para obtener información sobre los permisos de acceso predeterminados en los clústeres nuevos, consulta Permisos de acceso en GKE.

Comprobar los permisos de acceso de Autopilot

Ejecuta el siguiente comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Si tu clúster no tiene el ámbito de acceso https://www.googleapis.com/auth/cloud-platform, crea uno nuevo con este ámbito.

Consultar los permisos de acceso estándar

Para comprobar los ámbitos de acceso de tu clúster estándar, consulta un grupo de nodos:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

Sustituye NODE_POOL_NAME por el nombre del grupo de nodos.

Si tu clúster no tiene el ámbito de acceso https://www.googleapis.com/auth/cloud-platform, crea un grupo de nodos con el ámbito de acceso cloud-platform y elimina el grupo de nodos que ya tengas.

Actualizar el clúster para que use el archivo de configuración

Ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Volver a crear nodos en clústeres estándar

Si tu clúster estándar no usa actualizaciones automáticas, debes volver a crear manualmente tus grupos de nodos para aplicar la nueva configuración. Para activar una recreación manual de nodos, actualiza tu clúster a la misma versión de GKE que ya utiliza.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Sustituye VERSION por la misma versión del parche de GKE que ya usa el clúster.

Inhabilitar las opciones de configuración de containerd

Inhabilitar privateRegistryAccessConfig

  1. Actualiza el archivo de configuración para especificar enabled: false en privateRegistryAccessConfig y elimina cualquier otro campo del elemento, como en el siguiente ejemplo:

    privateRegistryAccessConfig:
  enabled: false
  2. Aplica el archivo de configuración actualizado a tu clúster. Para obtener instrucciones, consulta Aplicar la configuración de containerd a clústeres ya creados.

Inhabilitar registryHosts

  1. Actualiza el archivo de configuración para especificar una matriz vacía en el elemento registryHosts, como en el siguiente ejemplo:

    registryHosts: []
  2. Aplica el archivo de configuración actualizado a tu clúster. Para obtener instrucciones, consulta Aplicar la configuración de containerd a clústeres ya creados.