Personnaliser la configuration containerd dans les nœuds GKE

Cette page explique comment personnaliser la configuration de l'environnement d'exécution des conteneurs containerd sur vos nœuds Google Kubernetes Engine (GKE). Avant de lire ce document, assurez-vous de maîtriser ce qu'est un environnement d'exécution de conteneur et pourquoi vous souhaitez le personnaliser.

À propos de la configuration containerd dans GKE

Vous pouvez configurer manuellement un ensemble d'options dans l'environnement d'exécution containerd sur des nœuds GKE exécutant un système d'exploitation tel que Container-Optimized OS. La personnalisation de l'environnement d'exécution vous permet de configurer des exigences spéciales telles que l'accès aux registres d'images privés. Pour définir ces options, vous devez créer un fichier YAML appelé fichier de configuration de l'environnement d'exécution et le transmettez à GKE lorsque vous créez ou mettez à jour un cluster ou un pool de nœuds.

Cette méthode de personnalisation de containerd vous permet d'éviter de déployer des DaemonSet privilégiés, qui constituent un risque pour la sécurité. Lorsque vous fournissez un fichier de configuration d'exécution à GKE, GKE recrée vos nœuds et met à jour le fichier config.toml de containerd sur chaque nœud avec votre configuration. La configuration persiste lors de l'arrêt, des mises à niveau et des recréation des nœuds.

Vous pouvez configurer les paramètres containerd au niveau du cluster ou du pool de nœuds. Une configuration au niveau du pool de nœuds remplace une configuration au niveau du cluster pour ces options. Lorsque vous mettez à jour une option de configuration containerd au niveau du cluster (telle que registryHosts ou writableCgroups), GKE met à jour et recrée les nœuds uniquement dans les pools de nœuds qui ne disposent pas de leurs propres paramètres au niveau du pool de nœuds pour ces options. Les pools de nœuds avec leurs propres configurations au niveau du pool de nœuds pour l'option ne seront pas mis à jour ni recréés et continueront à utiliser leurs propres paramètres.

Le fichier de configuration de l'environnement d'exécution vous permet uniquement de configurer des options dans containerd. GKE accepte également la configuration d'options kubelet spécifiques et d'options de noyau Linux de bas niveau à l'aide d'un fichier distinct appelé fichier de configuration du système de nœud. Pour en savoir plus, consultez la page Personnaliser la configuration du système de nœud.

Limites

Vous ne pouvez pas utiliser un fichier de configuration d'exécution pour modifier les paramètres containerd dans les images de nœuds Windows.

Options de configuration containerd disponibles

Les sections suivantes décrivent les options que vous pouvez configurer à l'aide d'un fichier de configuration d'environnement d'exécution.

privateRegistryAccessConfig

Accédez à des registres d'images privés à l'aide d'identifiants privés que vous stockez dans Secret Manager.

Cette option est disponible avec GKE versions 1.27.3-gke.1700 ou ultérieure pour les images de nœuds Container-Optimized OS, et 1.33 ou ultérieure pour les images de nœuds Ubuntu.

Pour obtenir des instructions, consultez la section Accéder aux registres privés avec des certificats CA privés.

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

Cette configuration comporte les champs suivants:

  • enabled : valeur booléenne permettant d'activer la configuration du registre privé. Si vous définissez enabled: false, supprimez tous les autres champs de l'élément privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig : contient jusqu'à cinq définitions de certificat et de noms de domaine complet.
  • gcpSecretManagerCertificateConfig : contient un certificat stocké dans Secret Manager et un tableau de noms de domaine complets.
  • secretURI : emplacement du certificat dans Secret Manager. privateRegistryAccessConfig n'accepte que les secrets mondiaux dans secretURI.
  • fqdns : liste de noms de domaine complets des registres privés. Vous pouvez également utiliser des adresses IPv4, mais nous vous recommandons d'utiliser le nom de domaine complet.

registryHosts

Configurez des paramètres avancés pour les registres containerd, tels que les fonctionnalités, les en-têtes personnalisés et les certificats. Cela correspond à hosts.toml de containerd.

Cette option est disponible pour GKE versions 1.34.1-gke.2980000 ou ultérieure.

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"

Cette configuration comporte les champs suivants:

  • server : nom d'hôte du serveur de registre (par exemple, example.com). Il est utilisé pour nommer le fichier de configuration sur le nœud. Il doit s'agir d'un nom de domaine complet ou d'une adresse IP sans schéma, port ni chemin d'accès.
  • hosts : liste de configurations spécifiques à l'hôte pour le server.
  • host : nom d'hôte d'un miroir de registre (par exemple, https://mirror.example.com:8000/1234, 1.2.3.4:80). Il doit s'agir de noms de domaine complets ou d'adresses IP. Scheme, le port et le chemin d'accès sont acceptés. Scheme ne peut être que http ou https.
  • capabilities : liste de fonctionnalités spécifiant les opérations qu'un hôte est capable d'effectuer. Les valeurs acceptées sont les suivantes :
    • HOST_CAPABILITY_PULL : représente la possibilité d'extraire des fichiers manifestes et des blobs par condensé.
    • HOST_CAPABILITY_RESOLVE : représente la possibilité d'extraire des fichiers manifestes par nom.
    • HOST_CAPABILITY_PUSH : représente la possibilité d'envoyer des blobs et des fichiers manifestes.
    Si aucune valeur n'est spécifiée, toutes les fonctionnalités sont activées.
  • overridePath : valeur booléenne. Si la valeur est true, cela indique que le point de terminaison racine de l'API de l'hôte est défini dans le chemin d'accès de l'URL plutôt que par la spécification de l'API. Cette option peut être utilisée avec des registres OCI non conformes qui ne comportent pas le préfixe /v2. La valeur par défaut est false.
  • dialTimeout : chaîne de durée (par exemple, "30s") spécifiant la durée maximale autorisée pour qu'une tentative de connexion se termine. La valeur maximale autorisée est "180s". Si ce champ n'est pas défini, containerd définit la valeur par défaut sur "30s". La valeur doit être un nombre décimal de secondes avec un suffixe s.
  • header : liste d'en-têtes HTTP personnalisés à envoyer à l'hôte de registre.
    • key : clé d'en-tête.
    • value : liste de valeurs d'en-tête.
  • ca : liste des configurations de certificat pour l'autorité de certification (CA) de l'hôte de registre. Pour créer un secret pour les certificats et configurer les autorisations requises, consultez les instructions de la section Stocker vos clés publiques CA dans Secret Manager.
    • gcpSecretManagerSecretUri : URI d'un secret dans Secret Manager contenant le certificat CA. Il est compatible avec les secrets mondiaux et régionaux. Les formats sont les suivants, pour les types de secrets respectifs :
      • Format de secret mondial : projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Format de secret régional : projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client : liste de paires de clés et de certificats clients pour l'authentification auprès de l'hôte de registre. Pour créer un secret pour les certificats et configurer les autorisations requises, consultez les instructions de la section Stocker vos clés publiques CA dans Secret Manager.
    • cert : configuration du certificat client.
      • gcpSecretManagerSecretUri : URI d'un secret dans Secret Manager contenant le certificat client. Il est compatible avec les secrets mondiaux et régionaux.
    • key : configuration de la clé privée du client.
      • gcpSecretManagerSecretUri : URI d'un secret dans Secret Manager contenant la clé client. Il est compatible avec les secrets mondiaux et régionaux.

writableCgroups

Installez le système de fichiers /sys/fs/cgroup en mode lecture-écriture afin que les charges de travail puissent gérer les ressources de leurs processus enfants.

Cette option est disponible pour GKE versions 1.34.1-gke.2541000 ou ultérieure.

Pour en savoir plus, consultez Configurer des cgroups accessibles en écriture pour les conteneurs.

writableCgroups:
  enabled: true

Appliquer la configuration containerd aux nouveaux clusters

Cette section explique comment appliquer un fichier de configuration containerd lorsque vous créez un cluster GKE.

Exécutez la commande suivante pour créer des clusters Autopilot :

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

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom de votre nouveau cluster
  • LOCATION : emplacement Compute Engine du nouveau cluster.
  • PATH_TO_CONFIG_FILE : chemin d'accès au fichier de configuration que vous avez créé, par exemple ~/containerd-configuration.yaml.

Vous pouvez activer la configuration containerd sur les nouveaux clusters Standard en exécutant la gcloud container clusters create commande avec les mêmes options. Sauf si vous spécifiez une autre configuration containerd, les nouveaux pools de nœuds créés dans le cluster héritent de la configuration containerd par défaut au niveau du cluster.

Appliquer la configuration containerd aux nouveaux pools de nœuds

Vous pouvez appliquer la configuration containerd à un nouveau pool de nœuds GKE à l'aide de la commande suivante :

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

Remplacez les éléments suivants :

  • NODE_POOL_NAME : nom de votre nouveau pool de nœuds.
  • CLUSTER_NAME : nom du cluster existant.
  • LOCATION : emplacement Compute Engine de votre nouveau pool de nœuds.
  • PATH_TO_CONFIG_FILE : chemin d'accès au fichier de configuration que vous avez créé, par exemple ~/containerd-configuration.yaml.

Appliquer la configuration containerd aux clusters existants

Cette section vous explique comment appliquer une configuration containerd à des clusters et à des nœuds existants.

La mise à jour de la configuration containerd au niveau du cluster ne s'applique qu'aux pools de nœuds qui ne disposent pas de leurs propres paramètres définis au niveau du pool de nœuds (tels que registryHosts ou writableCgroups). GKE recrée les nœuds de ces pools de nœuds pour appliquer la nouvelle configuration. Les pools de nœuds avec des paramètres au niveau du pool de nœuds continuent d'utiliser leur propre configuration et leurs nœuds ne sont pas recréés. La mise à jour d'un cluster ou d'un pool de nœuds avec une configuration containerd recrée les nœuds pour appliquer la configuration. Cela peut entraîner des interruptions temporaires de l'exécution des charges de travail. GKE ne recrée les nœuds que si les mises à niveau automatiques sont activées. Cette recréation respecte les intervalles de maintenance que vous avez définis. Dans les clusters standards pour lesquels les mises à niveau automatiques ne sont pas activées, vous devez recréer manuellement vos nœuds pour appliquer la configuration.

Vérifier les niveaux d'accès

Si votre fichier de configuration utilise des secrets provenant de Secret Manager, votre cluster ou pool de nœuds doit disposer du niveau d'accès cloud-platform. Cette section explique comment vérifier vos niveaux d'accès et mettre à jour un cluster existant avec un fichier de configuration d'exécution nouveau ou modifié.

Pour en savoir plus sur les niveaux d'accès par défaut dans les nouveaux clusters, consultez la section Niveaux d'accès dans GKE.

Vérifier les niveaux d'accès à Autopilot

Exécutez la commande suivante :

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

Si vous utilisez des secrets provenant de Secret Manager et que votre cluster ne dispose pas du https://www.googleapis.com/auth/cloud-platform niveau d'accès, créez un cluster avec ce niveau d'accès.

Vérifier les niveaux d'accès standards

Pour vérifier les niveaux d'accès à votre cluster standard, vérifiez un pool de nœuds:

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

Remplacez NODE_POOL_NAME par le nom du pool de nœuds.

Si vous utilisez des secrets provenant de Secret Manager et que votre cluster ne dispose pas du niveau d'accès https://www.googleapis.com/auth/cloud-platform, créez un pool de nœuds doté du niveau d'accès cloud-platform et supprimez le pool de nœuds existant.

Mettre à jour le cluster pour utiliser votre fichier de configuration

Exécutez la commande suivante :

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

Mettre à jour un pool de nœuds pour utiliser un fichier de configuration

Pour mettre à jour la configuration containerd d'un pool de nœuds, exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • NODE_POOL_NAME : nom du pool de nœuds que vous souhaitez mettre à jour.
  • CLUSTER_NAME : nom du cluster existant.
  • LOCATION : emplacement Compute Engine du cluster.
  • PATH_TO_CONFIG_FILE : chemin d'accès au fichier de configuration que vous avez créé, par exemple ~/containerd-configuration.yaml.

Recréer des nœuds dans des clusters standards

Si votre cluster standard n'utilise pas les mises à niveau automatiques, vous devez recréer manuellement vos pools de nœuds pour appliquer la nouvelle configuration. Pour déclencher une recréation manuelle des nœuds, mettez à niveau votre cluster vers la version GKE qu'il utilise déjà.

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

Remplacez VERSION par la même version de correctifs de GKE que celle utilisée par le cluster.

Désactiver les options de configuration containerd

Désactiver privateRegistryAccessConfig

  1. Mettez à jour le fichier de configuration pour spécifier enabled: false dans privateRegistryAccessConfig et supprimez tous les autres champs de l'élément, comme dans l'exemple suivant :

    privateRegistryAccessConfig:
  enabled: false
  2. Appliquez le fichier de configuration mis à jour au cluster : Pour obtenir des instructions, consultez la page Appliquer la configuration containerd aux clusters existants.

Désactiver registryHosts

  1. Mettez à jour le fichier de configuration pour spécifier un tableau vide dans l'élément registryHosts, comme dans l'exemple suivant :

    registryHosts: []
  2. Appliquez le fichier de configuration mis à jour au cluster : Pour obtenir des instructions, consultez la page Appliquer la configuration containerd aux clusters existants.