Configurer des liens express

Les liens express sur la mise en réseau ambiante vous permettent de connecter un service Cloud Run source à un service Cloud Run de destination dans le même projet et la même région sans écrire de code d'authentification dans votre application ni configurer de maillage de services.

Lorsqu'un service Cloud Run appelle un autre service Cloud Run protégé par Identity and Access Management (IAM), la requête doit inclure un jeton d'ID OpenID Connect (OIDC) afin que la destination puisse vérifier l'identité et les autorisations de l'appelant. Sans lien express, vous devez soit écrire du code d'authentification de service à service dans votre application pour récupérer et associer des jetons à partir du serveur de métadonnées, soit configurer des ressources Cloud Service Mesh telles qu'un réseau cloud privé virtuel (VPC), des services de backend et des règles de routage. Un lien express délègue ce travail d'authentification et de routage au conteneur side-car ambiant entièrement géré, ce qui permet de conserver la portabilité du code de votre application et de le concentrer sur la logique métier.

Cas d'utilisation

Vous pouvez utiliser des liens express dans les scénarios suivants :

  • Décharger l'authentification de service à service du code d'application : connectez un service Cloud Run appelant à un service Cloud Run de destination protégé par IAM via HTTP standard. Le side-car ambiant récupère et injecte automatiquement le jeton d'ID OIDC du service source, puis chiffre la requête via HTTPS.
  • Abstraire les URL de destination avec des noms d'hôte personnalisés : configurez un nom d'hôte personnalisé sur le lien express à l'aide de l'option --matches-hostname afin que votre application source envoie des requêtes à une adresse logique, telle que http://my-backend, au lieu de coder en dur l'URL déterministe de la destination. Si le service de destination change, vous pouvez recréer le lien express pour qu'il pointe vers la nouvelle destination sans modifier ni redéployer le code de votre application source.
  • Simplifiez les appels de service point à point sans maillage de services : bénéficiez d'une injection automatique d'identifiants entre les services Cloud Run sans provisionner de réseau VPC, de groupes de points de terminaison du réseau, de services de backend ou d'enregistrements Cloud DNS requis par Cloud Service Mesh.

Le tableau suivant compare les étapes de configuration de la communication authentifiée de service à service avec et sans lien express :

Étape Sans lien express Avec un lien express
1. Déployer le service de destination Déployez le service Cloud Run de destination avec l'authentification IAM requise (--no-allow-unauthenticated). Identique.
2. Accorder l'autorisation d'appelant Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) sur le service de destination au compte de service du service source. Identique.
3. Configurer la requête sortante Écrivez du code dans votre application source pour récupérer un jeton d'ID OIDC pour l'URL de destination et l'associer à l'en-tête Authorization: Bearer via HTTPS. Envoyez une requête http:// simple à l'URL de destination ou au nom d'hôte personnalisé sans code d'authentification dans votre application source.
4. Déployer le service source Déployez le service Cloud Run source. Déployez le service Cloud Run source avec la mise en réseau ambiante activée, puis créez un lien express entre les services source et de destination déployés.

Architecture

Lorsque vous activez la mise en réseau ambiante sur un service Cloud Run source et que vous créez un lien express, Cloud Run configure le conteneur side-car Envoy entièrement géré qui s'exécute avec le conteneur de votre application dans chaque instance de conteneur.

Lorsque votre application envoie une requête HTTP simple à l'URL déterministe du service de destination ou à un nom d'hôte personnalisé que vous configurez sur le lien express, le conteneur side-car ambiant effectue automatiquement les opérations suivantes :

  1. Intercepte les requêtes HTTP sortantes destinées au service cible.
  2. Récupère un jeton d'ID OIDC pour le compte de service du service source et l'injecte dans l'en-tête Authorization.
  3. Chiffre et transfère la requête via HTTPS (TLS unidirectionnel) au service Cloud Run de destination, qui vérifie les autorisations IAM de l'appelant.
Un conteneur d'application dans un service Cloud Run source envoie une requête HTTP simple au conteneur side-car ambiant, qui intercepte la requête, injecte un jeton d'ID OIDC et transmet le jeton d'ID et la charge utile via HTTPS via un lien express vers un service Cloud Run de destination.
Figure 1. Le conteneur side-car ambiant intercepte les requêtes sortantes de votre service source, injecte un jeton d'ID OIDC et transfère la requête via HTTPS (TLS unidirectionnel) au service de destination.

Connectivité réseau et plan de données

Un lien express configure l'interception des requêtes sortantes et l'injection d'identifiants dans le side-car ambiant, mais il ne remplace pas le chemin réseau sous-jacent entre vos services. Vous devez toujours vous assurer que votre service source peut atteindre le chemin d'entrée du service de destination :

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Activez les API Cloud Run, Network Services et Traffic Director, si elles ne sont pas déjà activées.

    Rôles requis pour activer les API

    Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  7. Assurez-vous de disposer d'un service Cloud Run source et d'un service Cloud Run de destination existants dans le même projet et la même région.
  8. Assurez-vous que la mise en réseau ambiante est activée avec le champ d'application global sur votre service Cloud Run source. Par exemple, exécutez gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION, en n'oubliant pas d'augmenter d'abord les limites de processeur et de mémoire de votre service.

  9. Consultez la page Tarifs de Cloud Run pour en savoir plus sur l'utilisation du side-car de mise en réseau ambiante. La facturation des fonctionnalités ambiantes n'est pas appliquée pendant la phase preview.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer des liens express, demandez à votre administrateur de vous accorder les rôles IAM suivants :

  • Configurer le lien express : Développeur Cloud Run (roles/run.developer) et Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le projet
  • Gérer les ressources de lien express : Administrateur de services réseau (roles/networkservices.admin) sur le projet

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

L'identité de service du service Cloud Run source doit également disposer des rôles suivants sur le projet :

  • Client Traffic Director (roles/trafficdirector.client)
  • Agent Cloud Trace (roles/cloudtrace.agent)

Pour attribuer ces rôles à l'identité de service, utilisez gcloud :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • RUN_CLIENT_SA : nom du compte de service associé à votre service Cloud Run source.

Si l'identité de service Cloud Run ne dispose pas de ces rôles, le service Cloud Run est tout de même déployé, mais les fonctionnalités qui dépendent de la mise en réseau ambiante ne fonctionnent pas. Ce comportement diffère de celui de Cloud Service Mesh, où le service Cloud Run ne parvient pas à se déployer s'il ne dispose pas des rôles requis.

Limites

Les limites suivantes s'appliquent aux liens express :

  • Seuls les services Cloud Run sont acceptés en tant que ressources sources et de destination. Les jobs, les pools de nœuds de calcul et les instances Cloud Run ne sont pas compatibles.
  • Les configurations interprojets et interrégionales ne sont pas acceptées. Les services Cloud Run source et de destination doivent se trouver dans le même projet et la même région.
  • Les liens express nécessitent une mise en réseau ambiante avec le champ d'application global sur le service source. Si le service source utilise le champ d'application regional, la création du lien express réussit, mais le trafic n'est pas acheminé.
  • Vous devez créer les services Cloud Run source et de destination avant de créer le lien express. La création désordonnée n'est pas acceptée. Si vous supprimez un service de destination, le lien express peut continuer à afficher et à diffuser la configuration obsolète jusqu'à ce que vous supprimiez ou recréiez le lien express.
  • Vous ne pouvez pas modifier le service source, le service de destination ni le nom d'hôte personnalisé d'un lien express existant. La commande gcloud beta network-services express-links update ne met à jour que la description du lien express. Pour modifier la configuration de routage, supprimez et recréez le lien express.
  • L'URL run.app par défaut doit être activée pour les services Cloud Run de destination, même si vous utilisez des URL personnalisées, des domaines personnalisés ou si vous configurez un nom d'hôte personnalisé avec l'option --matches-hostname.
  • Les requêtes envoyées à l'URL non déterministe de la destination ne sont pas interceptées et échouent avec une erreur 403 Forbidden. Si le service de destination n'a pas d'URL déterministe, car le nom du service et le numéro de projet combinés dépassent 63 caractères, vous devez spécifier --matches-hostname, sinon la création du lien express échoue avec une erreur Cloud Run Service name is too long.
  • Lorsque vous affichez l'état complet d'un lien express, seules les informations sur le service de destination sont renvoyées. Les détails sur les révisions Cloud Run sources et l'authentification négociée peuvent être manquants ou afficher des données obsolètes. Cela n'affecte pas la façon dont le lien express achemine ou authentifie le trafic.
  • Les services Cloud Run sources configurés avec l'identité d'agent et des jetons liés à mTLS ne sont pas compatibles.
  • Les services Cloud Run sources configurés pour acheminer le trafic sortant via Agent Gateway sur Cloud Run et Secure Web Proxy ne sont pas compatibles. Les liens express nécessitent le champ d'application de mise en réseau ambiante globale, tandis qu'Agent Gateway nécessite le champ d'application régional.
  • Si une requête sortante du service source inclut déjà un en-tête Authorization, le lien express transfère la requête avec cet en-tête inchangé et n'injecte pas de jeton. L'injection automatique de jetons dans l'en-tête X-Serverless-Authorization n'est pas possible.
  • Le trafic généré à partir des conteneurs de bac à sable Cloud Run n'est pas pris en charge.
  • Vous ne pouvez pas utiliser de liens express pour transférer le trafic vers des services Cloud Run de destination sécurisés par Identity-Aware Proxy.
  • Chaque lien express est compatible avec un service Cloud Run de destination, et vous pouvez créer jusqu'à 5 000 liens express par projet.

Pour connecter vos services Cloud Run, créez un lien express en spécifiant le service source et le service de destination, puis accordez le rôle "Demandeur Cloud Run" sur le service de destination.

Se connecter à un autre service Cloud Run

Pour connecter un service Cloud Run source à un service Cloud Run de destination, créez un lien express à l'aide de gcloud ou de YAML.

gcloud

Utilisez la commande gcloud beta network-services express-links create pour créer un lien express :

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

Remplacez les éléments suivants :

  • EXPRESS_LINK_NAME : nom de votre lien express.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • REGION : région dans laquelle vos services Cloud Run sont déployés.
  • SOURCE_SERVICE : nom du service Cloud Run source.
  • DESTINATION_SERVICE : nom du service Cloud Run de destination.

Une fois la commande terminée, la propagation de la configuration de routage vers les instances de service source en cours d'exécution peut prendre jusqu'à deux minutes.

Par défaut, le lien express n'intercepte que les requêtes envoyées à l'URL déterministe du service de destination, et non à son URL non déterministe. Pour utiliser un nom d'hôte personnalisé, transmettez le nom d'hôte sans schéma dans l'option --matches-hostname="HOSTNAME", par exemple --matches-hostname="DESTINATION_SERVICE", et envoyez des requêtes de votre application source à http://HOSTNAME. La spécification de --matches-hostname remplace l'URL déterministe au lieu de l'ajouter.

YAML

  1. Créez un fichier de configuration, par exemple express-link.yaml :

    name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
source:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
destination:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région où vos services sont déployés.
    • EXPRESS_LINK_NAME : nom de votre lien express.
    • SOURCE_SERVICE : nom du service Cloud Run source.
    • DESTINATION_SERVICE : nom du service Cloud Run de destination.

  2. Importez le fichier YAML à l'aide de la commande gcloud beta network-services express-links import :

    gcloud beta network-services express-links import EXPRESS_LINK_NAME \
    --location=global \
    --source=YAML_FILENAME.yaml

    Remplacez les éléments suivants :

    • EXPRESS_LINK_NAME : nom de votre lien express.
    • YAML_FILENAME : nom de votre fichier YAML.

Accorder des autorisations d'appelant sur le service de destination

Pour permettre au service source d'appeler un service de destination protégé par IAM, attribuez le rôle Demandeur Cloud Run (roles/run.invoker) au compte de service du service source sur le service Cloud Run de destination. Cette étape est nécessaire pour que l'authentification fonctionne dans le plan de données.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

Remplacez les éléments suivants :

  • DESTINATION_SERVICE : nom du service Cloud Run de destination.
  • SOURCE_SA : nom du compte de service associé à votre service Cloud Run source.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • REGION : région dans laquelle votre service de destination est déployé.

Vérifier l'état du lien express

Pour afficher la configuration de base de votre lien express, utilisez la commande gcloud beta network-services express-links describe :

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

Pour afficher l'état complet du lien express, y compris connectionStatus (type de route actif, noms d'hôte correspondants et URI de révision source) et cloudRunSourceInfo (méthodes d'authentification configurées et réseau VPC), incluez ?view=EXPRESS_LINK_VIEW_FULL# dans le nom de la ressource :

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

Remplacez EXPRESS_LINK_NAME par le nom de votre lien express. Conservez les guillemets simples et le caractère # de fin lorsque vous interrogez la vue complète.

Pour supprimer un lien express et arrêter l'injection automatique d'identifiants et l'interception du trafic depuis le service source, utilisez la commande gcloud beta network-services express-links delete :

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

Remplacez EXPRESS_LINK_NAME par le nom de votre lien express.

Pour faire pointer un lien express existant vers un autre service de destination ou modifier le paramètre --matches-hostname, supprimez le lien express à l'aide de la commande précédente, puis créez un lien express avec la configuration mise à jour.

Étapes suivantes