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 del entorno de ejecución y pásalo a GKE cuando crees o actualices un clúster o un grupo de nodos.

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 los nodos.

Puedes establecer la configuración de containerd a nivel del clúster o del grupo de nodos. La configuración a nivel del grupo de nodos anula la configuración a nivel del clúster para esas opciones. Cuando actualizas una opción de configuración de containerd a nivel del clúster (como registryHosts o writableCgroups), GKE actualiza y vuelve a crear los nodos solo en los grupos de nodos que no tienen su propia configuración a nivel del grupo de nodos para esas opciones. Los grupos de nodos con sus propias configuraciones a nivel del grupo de nodos para la opción no se actualizarán ni se volverán a crear, y seguirán usando su propia configuración.

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 opciones del kernel de Linux de bajo nivel 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 del entorno de ejecución.

privateRegistryAccessConfig

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

Esta opción está disponible en las versiones 1.27.3-gke.1700 o posteriores de GKE para las imágenes de nodo de Container-Optimized OS, y en la versión 1.33 o posterior 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 IP sin esquema, puerto ni ruta de acceso.
  • 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, https://mirror.example.com:8000/1234, 1.2.3.4:80). Deben ser nombres de dominio completamente calificados o direcciones IP. Se admiten Scheme, puertos y rutas de acceso. Scheme solo puede ser http o https.
  • capabilities: Es una lista de capacidades que especifican qué operaciones puede realizar un host. Los valores admitidos son cualquiera de 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 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 configura, 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 para enviar al host del registro.
    • key: Es la clave del encabezado.
    • value: Es una lista de valores de encabezado.
  • ca: Es una lista de configuraciones de certificados para la autoridad certificadora (AC) 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 AC. Admite secretos globales y regionales. Los formatos son los siguientes, para los tipos de secretos respectivos:
      • 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 Secret en Secret Manager que contiene el certificado de 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 Configura cgroups de escritura 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 de Standard nuevos ejecutando el comando gcloud container clusters create con las mismas opciones. A menos que especifiques una configuración de containerd diferente, los grupos de nodos nuevos que se creen en el clúster heredarán la configuración predeterminada de containerd a nivel del clúster.

Aplica la configuración de containerd a los 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: Es la ubicación de Compute Engine del grupo de nodos nuevo.
  • 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.

La actualización de la configuración de containerd a nivel del clúster solo se aplica a los grupos de nodos que no tienen su propia configuración definida a nivel del grupo de nodos (como registryHosts o writableCgroups). GKE vuelve a crear los nodos en estos grupos de nodos para aplicar la nueva configuración. Los grupos de nodos con configuración a nivel del grupo de nodos siguen usando su propia configuración, y sus nodos no se vuelven a crear. La actualización de un clúster o grupo de nodos con una configuración de containerd vuelve a crear los nodos para aplicar la configuración. Esto puede causar interrupciones temporales en cargas de trabajo en ejecución. GKE solo vuelve a crear los nodos si las actualizaciones automáticas están habilitadas. Esta recreación respeta cualquier período de mantenimiento que establezcas. En los clústeres estándar que no tienen habilitadas las actualizaciones automáticas, debes volver a crear los nodos de forma manual para aplicar la configuración.

Verifica los permisos de acceso

Si tu archivo de configuración usa secretos de Secret Manager, tu clúster o grupo de nodos debe tener el permiso de acceso cloud-platform. En esta sección, se muestra cómo verificar tus permisos de acceso y actualizar un clúster existente con un archivo de configuración de tiempo de ejecución 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 comando siguiente:

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

Si usas secretos de Secret Manager y 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 usas Secrets de Secret Manager y 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 comando siguiente:

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

Actualiza un grupo de nodos para que use un archivo de configuración

Para actualizar la configuración de containerd de un grupo de nodos, ejecuta el siguiente comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Reemplaza lo siguiente:

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

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 borrar 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 el 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.