Personaliza la configuración de containerd en nodos de GKE

En esta página, se muestra cómo personalizar la configuración del entorno de ejecución del contenedor de containerd en tus nodos de Google Kubernetes Engine (GKE). Antes de leer este documento, asegúrate de conocer qué es un entorno de ejecución de contenedores y por qué te gustaría personalizarlo.

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

Puedes configurar de forma manual un conjunto de opciones en el entorno de ejecución de containerd en nodos de GKE que ejecutan un sistema operativo como Container-Optimized OS. La personalización del entorno de ejecución te permite configurar requisitos especiales, como el acceso a registros de imágenes privadas. Para establecer estas opciones, crea un archivo YAML llamado archivo de configuración de tiempo de ejecución y pásalo a GKE cuando crees o actualices un clúster.

Este método para personalizar containerd te permite evitar la implementación de DaemonSets con privilegios, que son un riesgo de seguridad. Cuando proporcionas a GKE un archivo de configuración del entorno de ejecución, GKE vuelve a crear tus nodos y actualiza el archivo config.toml de containerd en cada nodo con tu configuración. La configuración persiste durante la finalización, las actualizaciones y las recreaciones de nodos.

El archivo de configuración del entorno de ejecución solo te permite configurar opciones en containerd. GKE también admite la configuración de opciones específicas de kubelet y del kernel de Linux de nivel bajo con un archivo independiente llamado archivo de configuración del sistema de nodos. Para obtener más detalles, consulta Cómo personalizar la configuración del sistema de nodos.

Limitaciones

No puedes usar un archivo de configuración del entorno de ejecución para cambiar la configuración 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 puedes configurar con un archivo de configuración de tiempo de ejecución.

privateRegistryAccessConfig

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

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

Para obtener instrucciones, consulta Accede a registros privados con certificados de la AC privados.

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

Esta configuración tiene los siguientes campos:

  • enabled: Es un valor booleano para habilitar la configuración del registro privado. Si configuras enabled: false, borra cualquier otro campo en el elemento privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: Contiene hasta cinco certificados y definiciones de FQDN.
  • gcpSecretManagerCertificateConfig: Contiene un certificado almacenado en Secret Manager y un array de FQDN.
  • secretURI: Es la ubicación del certificado en Secret Manager. privateRegistryAccessConfig solo admite secretos globales en secretURI.
  • fqdns: una lista de nombres de dominio completamente calificados de registros privados. También puedes usar direcciones IPv4, pero te recomendamos que uses el FQDN.

registryHosts

Configura los parámetros avanzados de los registros de containerd, como las capacidades, los encabezados personalizados y los certificados. Esto corresponde a hosts.toml de containerd.

Esta opción está disponible para 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: Es el nombre de host del servidor de registro (por ejemplo, example.com). Se usa para nombrar el archivo de configuración en el nodo. Debe ser un nombre de dominio completamente calificado o una dirección IPv4.
  • hosts: Es una lista de configuraciones específicas del host para el server.
  • host: Es el nombre de host de un duplicado del registro (por ejemplo, mirror.example.com). Debe ser un nombre de dominio completamente calificado o una dirección IPv4.
  • capabilities: Es una lista de capacidades que especifican qué operaciones puede realizar un host. Los valores admitidos son los siguientes:
    • HOST_CAPABILITY_PULL: Representa la capacidad de recuperar manifiestos y BLOB por resumen.
    • HOST_CAPABILITY_RESOLVE: Representa la capacidad de recuperar manifiestos por nombre.
    • HOST_CAPABILITY_PUSH: Representa la capacidad de enviar blobs y manifiestos.
    Si no se especifica, se habilitan todas las capacidades.
  • overridePath: Es un valor booleano. Si es true, indica que el extremo raíz de la API del host se define en la ruta de URL en lugar de en la especificación de la API. Se puede usar con registros de OCI que no cumplen con los requisitos y a los que les falta el prefijo /v2. La configuración predeterminada es false.
  • dialTimeout: Es 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 establece, containerd establece un valor predeterminado de "30s". El valor debe ser un número decimal de segundos con un sufijo s.
  • header: Es una lista de encabezados HTTP personalizados que se enviarán al host del registro.
    • key: Es la clave del encabezado.
    • value: Es una lista de valores de encabezado.
  • ca: Es una lista de parámetros de configuración de certificados para la autoridad certificadora (CA) del host del registro. Para crear un secreto para los certificados y configurar los permisos necesarios, consulta las instrucciones en Almacena tus claves públicas de CA en Secret Manager.
    • gcpSecretManagerSecretUri: Es el URI de un secreto en Secret Manager que contiene el certificado de la CA. Admite secretos globales y regionales. Los formatos son los siguientes para los respectivos tipos de secretos:
      • Formato del 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: Es una lista de pares de claves y certificados de cliente para la autenticación en el host del registro. Para crear un secreto para los certificados y configurar los permisos necesarios, consulta las instrucciones en Almacena tus claves públicas de CA en Secret Manager.
    • cert: Es la configuración del certificado del cliente.
      • gcpSecretManagerSecretUri: Es el URI de un secreto en Secret Manager que contiene el certificado del cliente. Admite secretos globales y regionales.
    • key: Es la configuración de la clave privada del cliente.
      • gcpSecretManagerSecretUri: Es el URI de un secreto en Secret Manager que contiene la clave del cliente. Admite secretos globales y regionales.

writableCgroups

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

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

Para obtener más información, consulta Cómo configurar cgroups grabables para contenedores.

writableCgroups:
  enabled: true

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

En esta sección, se muestra cómo aplicar un archivo de configuración de containerd cuando creas clúster de GKE nuevo.

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"

Reemplaza lo siguiente:

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

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

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

Puedes aplicar la configuración de containerd a un grupo de nodos nuevo 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"

Reemplaza lo siguiente:

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

Aplica la configuración de containerd a los clústeres existentes

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

Verifica los permisos de acceso

Los clústeres existentes deben tener el permiso de acceso cloud-platform para usar esta función. En esta sección, se muestra cómo verificar los permisos de acceso y actualizar un clúster existente con un archivo de configuración de registro privado nuevo o modificado.

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

Verifica 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 permiso de acceso https://www.googleapis.com/auth/cloud-platform, crea un clúster nuevo con este permiso de acceso.

Verifica los permisos de acceso de Standard

Para verificar los permisos de acceso al clúster estándar, verifica un grupo de nodos:

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

Reemplaza NODE_POOL_NAME por el nombre del grupo de nodos.

Si tu clúster no tiene el permiso de acceso https://www.googleapis.com/auth/cloud-platform, crea un grupo de nodos nuevo con el permiso de acceso cloud-platform y borra el grupo de nodos existente.

Actualiza el clúster para usar 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"

Vuelve a crear los nodos en los clústeres de Standard

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

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

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

Inhabilita las opciones de configuración de containerd

Inhabilitar privateRegistryAccessConfig

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

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

Inhabilitar registryHosts

  1. Actualiza tu archivo de configuración para especificar un array vacío en el elemento registryHosts, como en el siguiente ejemplo:

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