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.

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

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 les versions 1.27.3-gke.1700 ou ultérieures de GKE pour les images de nœuds Container-Optimized OS, et les versions 1.33 ou ultérieures pour les images de nœuds Ubuntu.

Pour obtenir des instructions, consultez Accéder à des 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 complets.
  • 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 globaux 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 les paramètres avancés des registres containerd, tels que les capacités, les en-têtes personnalisés et les certificats. Cela correspond à hosts.toml de containerd.

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

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 IPv4.
  • hosts : liste des configurations spécifiques à l'hôte pour server.
  • host : nom d'hôte d'un miroir de registre (par exemple, mirror.example.com). Il doit s'agir de noms de domaine complets ou d'adresses IPv4.
  • capabilities : liste des 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 capacité à récupérer des fichiers manifestes et des blobs par condensé.
    • HOST_CAPABILITY_RESOLVE : représente la capacité à récupérer des fichiers manifestes par nom.
    • HOST_CAPABILITY_PUSH : représente la capacité à envoyer des blobs et des fichiers manifestes.
    Si aucune 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. Cela peut être utilisé 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 de "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 des en-têtes HTTP personnalisés à envoyer à l'hôte du 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 de l'hôte du registre. Pour créer un secret pour les certificats et configurer les autorisations requises, suivez 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 de l'autorité de certification. Il accepte les secrets globaux et régionaux. Voici les formats pour les types de secrets respectifs :
      • Format du secret global : projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Format du secret régional : projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client : liste de paires clé/certificat client pour l'authentification auprès de l'hôte du 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 accepte les secrets globaux 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 globaux 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 les versions GKE 1.34.1-gke.2541000 ou ultérieures.

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 commande gcloud container clusters create avec les mêmes options.

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

Vérifier les niveaux d'accès

Les clusters existants doivent disposer du niveau d'accès cloud-platform pour utiliser cette fonctionnalité. Cette section explique comment vérifier vos niveaux d'accès et mettre à jour un cluster existant avec un fichier de configuration de registre privé 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 ci-dessous.

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

Si votre cluster ne dispose pas du niveau d'accès https://www.googleapis.com/auth/cloud-platform, 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 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 ci-dessous.

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

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.