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 privados. 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.

Este método de personalización de containerd te permite evitar la implementación de DaemonSets privilegiados, que son un riesgo de seguridad. Cuando le 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.

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 de kernel de Linux de bajo nivel mediante un archivo independiente llamado archivo de configuración del sistema de nodos. Para obtener más detalles, consulta Personaliza 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 con las versiones 1.27.3-gke.1700 o posteriores de GKE para imágenes de nodos de Container-Optimized OS y 1.33 o posteriores para imágenes de nodos 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 estableces enabled: false, borra cualquier otro campo en el privateRegistryAccessConfig elemento.
  • certificateAuthorityDomainConfig: Contiene hasta cinco certificados y definiciones de FQDN.
  • gcpSecretManagerCertificateConfig: Contiene un certificado almacenado en el Secret Manager y un array de FQDN.
  • secretURI: Es la ubicación del certificado en Secret Manager. privateRegistryAccessConfig admite secretos globales solo en secretURI.
  • fqdns: Es 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 parámetros avanzados para registros de containerd, como capacidades, encabezados personalizados y certificados. hosts.toml

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 de 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 el Scheme, el puerto y la ruta 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 objetos binarios por resumen.
    • HOST_CAPABILITY_RESOLVE: Representa la capacidad de recuperar manifiestos por nombre.
    • HOST_CAPABILITY_PUSH: Representa la capacidad de enviar objetos binarios 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 no compatibles a los que les falta el prefijo /v2. El valor predeterminado 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 para enviar al host de 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 certificada (CA) del host de 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 CA. Admite secretos globales y regionales. Los formatos son los siguientes para los tipos de secretos respectivos:
      • Formato de secreto global: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Formato de 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 de 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 Configura 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 gcloud container clusters create comando 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 para el 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.

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 los permisos de acceso y actualizar un clúster existente con un archivo de configuración del entorno 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 siguiente comando:

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 https://www.googleapis.com/auth/cloud-platform permiso de acceso, 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 secretos de Secret Manager y tu clúster no tiene el https://www.googleapis.com/auth/cloud-platform permiso de acceso, crea un grupo de nodos nuevo con el cloud-platform permiso de acceso 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

Inhabilita privateRegistryAccessConfig

  1. Actualiza tu 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.

Inhabilita registryHosts

  1. Actualiza tu archivo de configuración para especificar un array vacío en el registryHosts elemento, 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.