Définir un nombre minimal d'instances (services)

Cette page explique comment activer des instances inactives pour votre service à l'aide des paramètres du nombre minimal d'instances.

Pour les services Cloud Run, Cloud Run effectue un scaling par défaut du nombre d'instances en fonction du nombre de requêtes entrantes. Toutefois, si votre service nécessite une latence réduite, en particulier lors d'un scaling des instances actives à partir de zéro, vous pouvez modifier ce comportement par défaut en spécifiant un nombre minimal d'instances de conteneur à garder en attente et prêtes à diffuser des requêtes. Pour en savoir plus sur cette optimisation, reportez-vous à la section Conseils de développement généraux.

Cloud Run supprime les instances qui ne diffusent pas de requêtes (inactives). Lorsque le nombre minimal d'instances est défini, Cloud Run conserve au moins le nombre minimal d'instances en cours d'exécution, même si elles ne diffusent pas de requêtes. Les instances actives qui dépassent le nombre min-instances peuvent devenir inactives si elles ne reçoivent pas de requêtes.

Par exemple, si min-instances est défini sur 10 et que le nombre d'instances actives est 0, le nombre d'instances inactives est de 10. Lorsque le nombre d'instances actives grimpe à 6, le nombre d'instances inactives diminue à 4.

Appliquer un nombre minimal d'instances au niveau du service ou au niveau de la révision

Vous pouvez configurer le nombre minimal d'instances au niveau du service ou de la révision. Google vous recommande d'appliquer un nombre minimal d'instances au niveau du service et d'éviter de combiner les instances minimales au niveau du service et au niveau de la révision.

Si vous appliquez un nombre minimal d'instances au niveau de la révision, les paramètres prennent effet lors du déploiement de la révision. Si vous appliquez cette fonctionnalité au niveau du service, le paramètre prend effet sans qu'il soit nécessaire de déployer une nouvelle révision.

Révisions avec tag et instances minimales au niveau du service

Les révisions avec tag sont démarrées, mais ne sont comptabilisées dans le nombre minimal d'instances au niveau du service que si elles font partie d'une répartition du trafic.

Facturation

Les instances qui continuent d'être exécutées à l'aide de la fonctionnalité d'instances minimales entraînent la facturation de frais. Étant donné que ces frais sont hautement prévisibles, Google recommande de souscrire une remise sur engagement d'utilisation.

Nombre minimal d'instances et allocation systématique de processeur

Vous pouvez configurer une allocation systématique de processeur si vous avez besoin d'un processeur en dehors des requêtes.

Redémarrages du nombre minimal d'instances

Le nombre minimal d'instances peut être redémarré à tout moment.

Révisions et nombre minimal d'instances

Lorsque le nombre minimal d'instances est défini au niveau du service, il est réparti entre toutes les révisions qui diffusent du trafic proportionnellement à la répartition du trafic.

Lorsque le nombre minimal d'instances est défini au niveau de la révision, ces instances sont démarrées dès que la révision est référencée dans une répartition du trafic (même à 0 %) ou présente un tag de trafic attribué.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer et déployer des services Cloud Run, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Développeur Cloud Run (roles/run.developer) sur le service Cloud Run
Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service

Pour obtenir la liste des rôles et des autorisations IAM associés à Cloud Run, consultez les sections Rôles IAM Cloud Run et Autorisations IAM Cloud Run. Si votre service Cloud Run communique avec les API Google Cloud, telles que les bibliothèques clientes Cloud, consultez le guide de configuration de l'identité du service. Pour en savoir plus sur l'attribution de rôles, consultez les sections Autorisations de déploiement et Gérer les accès.

Définir et mettre à jour le nombre minimal d'instances au niveau du service

Par défaut, le nombre minimal d'instances au niveau du service est désactivé pour les instances de conteneur, avec une valeur de 0. Vous pouvez modifier cette valeur par défaut à l'aide de la console Google Cloud, de Google Cloud CLI ou d'un fichier YAML :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Si vous configurez un nouveau service, cliquez sur Déployer un conteneur et sélectionnez Service pour afficher le formulaire Créer un service. Si vous configurez un service existant, cliquez sur celui-ci pour afficher son panneau de détails, puis sur l'icône Stylo à côté de Nombre minimal d'instances en haut à droite.
Recherchez le formulaire Autoscaling des services.
- Dans le champ Nombre minimal d'instances, spécifiez le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes.
Cliquez sur Créer pour un nouveau service ou sur Déployer pour un service existant.

gcloud

Mettez à jour service-min-instances pour un service donné à l'aide de la commande suivante :

gcloud run services update SERVICE --service-min-instances MIN-VALUE

Remplacez :

SERVICE par le nom de votre service.
MIN-VALUE par le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes. Spécifiez default pour effacer tout paramétrage du nombre minimal d'instances.

Vous pouvez également définir service-min-instances lors du déploiement à l'aide de la commande suivante :

gcloud run deploy --image IMAGE_URL --service-min-instances MIN-VALUE

Remplacer

IMAGE_URL par une référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL se présente sous la forme suivante : LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MIN-VALUE par le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes. Spécifiez default pour effacer tout paramétrage du nombre minimal d'instances.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Mettez à jour l'attribut run.googleapis.com/minScale :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/minScale: 'MIN_INSTANCE'
```
Remplacez :
- SERVICE par le nom de votre service Cloud Run
- MIN-INSTANCE par le nombre d'instances à garder en attente et prêtes à recevoir des requêtes.
Créez ou mettez à jour le service à l'aide de la commande suivante :
```
gcloud run services replace service.yaml
```

Bibliothèques clientes

Pour mettre à jour le nombre minimal d'instances de votre service à partir du code, procédez comme suit :

API REST

Pour mettre à jour le nombre minimal d'instances au niveau du service pour un service donné, envoyez une requête HTTP PATCH au point de terminaison service de l'API Cloud Run Admin.

Exemple, à l'aide de curl :

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X PATCH \
-d '{ "scaling": { "minInstanceCount": MIN-VALUE }}' \
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE?update_mask=scaling.minInstanceCount

Remplacez :

ACCESS_TOKEN par un jeton d'accès valide pour un compte disposant des autorisations IAM pour mettre à jour un service. Par exemple, si vous êtes connecté à gcloud, vous pouvez récupérer un jeton d'accès à l'aide de gcloud auth print-access-token. À partir d'une instance de conteneur Cloud Run, vous pouvez récupérer un jeton d'accès via le serveur de métadonnées d'instance de conteneur.
MIN-VALUE par le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes.
SERVICE par le nom du service ;
REGION par la région Google Cloud du service.
PROJECT-ID par l'ID du projet Google Cloud.

Afficher le nombre minimal d'instances au niveau du service

Pour afficher les paramètres actuels du nombre minimal d'instances pour votre service Cloud Run, procédez comme suit :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Cliquez sur le service qui vous intéresse pour ouvrir le panneau Informations sur le service.
Le paramètre actuel est affiché en haut à droite du panneau d'informations sur le service, à côté du Nombre minimal d'instances.

gcloud

Exécutez la commande suivante :
```
gcloud run services describe SERVICE
```
Recherchez la valeur Nombre minimal d'instances au niveau du service dans la configuration renvoyée.

Définir et mettre à jour le nombre minimal d'instances au niveau de la révision

Tout changement de configuration entraîne la création d'une révision. Les révisions ultérieures obtiennent aussi automatiquement le même paramètre de configuration, à moins que vous ne le mettiez explicitement à jour.

Par défaut, le paramètre min-instances est désactivé pour les instances de conteneur, et sa valeur est 0. Vous pouvez modifier cette valeur par défaut à l'aide de la console Google Cloud, de Google Cloud CLI ou d'un fichier YAML lorsque vous créez un service ou déployez une nouvelle révision :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Cliquez sur Déployer un conteneur et sélectionnez Service pour configurer un nouveau service. Si vous configurez un service existant, cliquez sur celui-ci puis sur Modifier et déployer la nouvelle révision.
Si vous configurez un nouveau service, remplissez la page initiale des paramètres du service, puis cliquez sur Conteneur(s), volumes, mise en réseau et sécurité pour développer la page de configuration du service.
Cliquez sur l'onglet Conteneur.
- Dans le champ Nombre minimal d'instances, spécifiez le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes.
Cliquez sur Créer ou Déployer.

gcloud

Vous pouvez mettre à jour le paramètre min-instance d'un service donné à l'aide de la commande suivante :

gcloud run services update SERVICE --min-instances MIN-VALUE

Remplacez :

SERVICE par le nom de votre service.
MIN-VALUE par le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes. Spécifiez default pour effacer tout paramétrage du nombre minimal d'instances.

Vous pouvez également définir min-instance lors du déploiement à l'aide de la commande suivante :

gcloud run deploy --image IMAGE_URL --min-instances MIN-VALUE

Remplacez :

IMAGE_URL par une référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL se présente sous la forme suivante : LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MIN-VALUE par le nombre d'instances de conteneur à garder en attente et prêtes à recevoir des requêtes. Spécifiez default pour effacer tout paramétrage du nombre minimal d'instances.

YAML

Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :
```
gcloud run services describe SERVICE --format export > service.yaml
```
Mettez à jour l'attribut autoscaling.knative.dev/minScale: :
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: 'MIN-INSTANCE'
      name: REVISION
```
Remplacez :
- SERVICE par le nom de votre service Cloud Run
- MIN-INSTANCE par le nombre d'instances à garder en attente et prêtes à recevoir des requêtes.
- REVISION par un nouveau nom de révision ou supprimez-le (le cas échéant). Si vous indiquez un nouveau nom de révision, il doit répondre aux critères suivants :
  - Commencer par SERVICE-
  - Ne contenir que des lettres minuscules, des chiffres et -
  - Ne pas se terminer par -
  - Ne pas dépasser 63 caractères
Créez ou mettez à jour le service à l'aide de la commande suivante :
```
gcloud run services replace service.yaml
```

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base.

La ressource google_cloud_run_v2_service suivante spécifie un nombre minimal d'instances de 1 sous template.scaling. Remplacez 1 par votre propre nombre minimal d'instances.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-min-instances"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    scaling {
      # Min instances
      min_instance_count = 1
    }
  }
}

Afficher les paramètres du nombre minimal d'instances au niveau de la révision

Pour afficher les paramètres actuels du nombre minimal d'instances au niveau de la révision pour votre service Cloud Run, procédez comme suit :

Console

Dans la console Google Cloud, accédez à Cloud Run :

Accédez à Cloud Run
Cliquez sur le service qui vous intéresse pour ouvrir la page Informations sur le service.
Cliquez sur l'onglet Révisions.
Dans le panneau de détails sur la droite, le paramètre du nombre minimal d'instances au niveau de la révision s'affiche sous l'onglet Conteneur.

gcloud

Exécutez la commande suivante :
```
gcloud run services describe SERVICE
```
Recherchez le paramètre du nombre minimal d'instances au niveau de la révision dans la configuration renvoyée.

Utiliser des instances minimales ou maximales au niveau du service et de la révision

Le tableau suivant indique le comportement si vous combinez le nombre minimal d'instances au niveau du service et le nombre minimal ou maximal d'instances au niveau de la révision :

Paramètre de configuration	Comportement
Les instances minimales au niveau du service et les instances minimales au niveau de la révision sont définies.	La valeur effective de la révision est la plus élevée entre le nombre minimal d'instances au niveau de la révision et le nombre minimal d'instances au niveau du service.
Les instances minimales au niveau du service et les instances maximales au niveau de la révision sont définies.	La valeur effective de la révision est la plus faible entre le nombre maximal d'instances au niveau de la révision et le nombre minimal d'instances au niveau du service. Cela reste vrai même si le nombre maximal d'instances au niveau de la révision empêche le service d'atteindre le nombre d'instances configuré pour le nombre minimal d'instances au niveau du service.

Utiliser un nombre minimal d'instances avec la répartition du trafic

Si vous utilisez la répartition du trafic, le nombre minimal d'instances au niveau du service est réparti entre les révisions en fonction de la proportion de la répartition du trafic. Par exemple, si le nombre minimal d'instances au niveau du service est égal à 10, une répartition du trafic à 50/50 alloue cinq instances minimales au niveau du service à chaque révision.

Le tableau suivant présente des exemples de scénarios de configuration :

Exemple de cas d'utilisation	Exemple de configuration	Comportement observé
Aucun paramètre au niveau de la révision	Nombre minimal d'instances au niveau du service : 10 Nombre minimal d'instances de la révision A : 0 Nombre minimal d'instances de la révision B : 0 Répartition du trafic : 60/40	La révision A reçoit six instances provenant du nombre minimal d'instances au niveau du service, proportionnellement à la répartition du trafic. La révision B reçoit quatre instances provenant du nombre minimal d'instances au niveau du service, proportionnellement à la répartition du trafic.
Recevoir plus que le nombre minimal d'instances au niveau du service en raison du nombre minimal d'instances au niveau de la révision	Nombre minimal d'instances au niveau du service : 10 Nombre minimal d'instances de la révision A : 6 Nombre minimal d'instances de la révision B : 0 Répartition du trafic : 50/50	La révision A reçoit six instances provenant du nombre minimal d'instances au niveau de la révision. La révision B reçoit cinq instances provenant du nombre minimal d'instances au niveau du service, proportionnellement à la répartition du trafic. Cela dépasse le nombre minimal d'instances au niveau du service, ce qui est voulu.
Recevoir moins que le nombre minimal d'instances au niveau du service en raison du nombre maximal d'instances au niveau de la révision	Nombre minimal d'instances au niveau du service : 10 Nombre minimal d'instances de la révision A : 0 Nombre maximal d'instances de la révision A : 3 Nombre minimal d'instances de la révision B : 0 Répartition du trafic : 50/50	La révision A reçoit trois instances du nombre minimal d'instances au niveau du service qui sont générées par la répartition du trafic, mais est limitée au nombre maximal d'instances au niveau de la révision. La révision B reçoit cinq instances du nombre minimal d'instances au niveau du service, proportionnellement à la répartition du trafic. Cela entraîne huit instances au niveau du service, car deux sont perdues en raison du nombre maximal d'instances au niveau de la révision de la révision A.
Le nombre minimal d'instances au niveau du service est supérieur au nombre de révisions dans la répartition du trafic, et la quantité d'instances est proportionnelle à la répartition du trafic.	Nombre minimal d'instances au niveau du service : 3 Nombre minimal d'instances de la révision A : 0 Nombre minimal d'instances de la révision B : 0 La révision B est la première dans la section Trafic de configuration de service Répartition du trafic : 50/50	La révision A reçoit au moins une instance, et la révision B au moins deux instances. Le nombre d'instances pour le service est de trois.