Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Résolution des problèmes liés aux connexions privées
Cette page décrit les problèmes courants que vous pouvez rencontrer lors de la création ou de l'utilisation d'un AWS DevOps agent Connexion à des outils hébergés en privé for, et explique comment les résoudre. Chaque section décrit un symptôme, ses causes les plus probables et les étapes à suivre pour y remédier.
Pour un aperçu du fonctionnement des connexions privées, consultezConnexion à des outils hébergés en privé.
Une adresse d'hôte DNS ne se résout pas ou le trafic atteint le mauvais endroit
Symptôme
Vous avez créé une connexion privée en utilisant un nom DNS pour l'adresse hôte, mais la connexion ne peut pas atteindre votre service. Cela est le plus courant lorsque votre service cible est une GitLab instance auto-hébergée, un équilibreur de charge d'application (ALB) interne ou un serveur MCP dont le nom d'hôte n'existe que dans votre VPC.
Un échec de résolution DNS ne produit pas de message mentionnant le DNS. Au lieu de cela, il apparaît comme une erreur générique d'accessibilité ou de fournisseur lorsque vous enregistrez ou utilisez le fournisseur de capacités. Par exemple, vous pouvez voir Could not complete request to provider.Unable to connect to the MCP server at <endpoint>. The connection was interrupted., ou même une erreur d'authentification telle que Authentication with provider failed. Parce que le message ne pointe pas vers le DNS, effectuez la vérification suivante pour en confirmer la cause.
Cause
Par défaut, une connexion privée résout l'adresse hôte à l'aide du DNS public (dnsResolution: PUBLIC). Si votre nom d'hôte ne possède qu'un enregistrement dans une zone hébergée privée, une règle de résolution Amazon Route 53 ou un serveur DNS local, la résolution publique échoue et la connexion n'atteint jamais votre service.
Comment confirmer que le DNS en est la cause
Vérifiez si votre adresse d'hôte est résolue uniquement à l'intérieur de votre VPC. À partir d'une instance ou d'une AWS CloudShell session Amazon EC2 dans le même VPC, exécutez.
nslookup <your-host-address>Si le problème y est résolu mais pas à partir du DNS public et que votre connexion privée l'utilisednsResolution: PUBLIC, la résolution DNS en est la cause.Testez avec l'adresse IP au lieu du nom. Créez temporairement une connexion privée qui utilise l'adresse IP privée de la cible (ou une adresse IP d'équilibreur de charge) comme adresse hôte au lieu du nom DNS. Si la connexion atteint ensuite votre service, l'échec précédent était lié à la résolution DNS, et non au chemin réseau ou au service lui-même.
Résolution
Si votre nom d'hôte est résolu uniquement à l'intérieur de votre VPC, définissez le mode de résolution DNS sur In VPC (
IN_VPC) lorsque vous créez la connexion. Dans ce mode, l'adresse d'hôte est résolue depuis le contexte de votre VPC, de sorte que les noms d'hôte réservés au secteur privé sont résolus correctement. Consultez la section Créer une connexion privée.Le mode de résolution DNS est choisi lors de la création et s'applique à l'adresse hôte que vous fournissez. Vous ne pouvez pas modifier la façon dont la passerelle de ressources gérées par les services résout le DNS après sa création. Choisissez donc le mode approprié dès le départ. Si vous avez sélectionné le mauvais mode, supprimez la connexion et recréez-la avec le mode approprié.
Si vous spécifiez une adresse IP (plutôt qu'un nom DNS) pour l'adresse hôte, le mode de résolution DNS n'a aucun effet et le trafic est directement dirigé vers cette adresse IP.
Si vous ne pouvez pas l'utiliser
IN_VPCpour votre configuration, vous pouvez pointer l'adresse hôte vers l'adresse IP privée de la cible ou vers le nom DNS d'un équilibreur de charge qui peut être résolu publiquement mais qui est transféré vers une adresse IP privée.
La connexion est bloquée dans Create failed
Symptôme
Une fois que vous avez créé une connexion privée, la console affiche l'état Échec de la connexion (et describe-private-connection renvoie le statutCREATE_FAILED).
Cause
L'échec de création résulte le plus souvent d'un problème de configuration dans la demande ou dans votre VPC, plutôt que d'une erreur de service. Lorsqu'une connexion a un statut d'échec, l' AWS DevOps agent en décrit la raison dans le failureMessage champ. Lisez donc ce champ avant de parcourir la liste de contrôle.
Résolution
Vérifiez les points suivants, dans l'ordre :
Lisez
failureMessageles détails de la connexion. Ce champ décrit pourquoi une connexion a un statut d'échec et est présent lorsque l'état estCREATE_FAILEDouDELETE_FAILED:
aws devops-agent describe-private-connection \ --name my-mcp-tool-connection
failureMessageapparaît également dans la sortie delist-private-connections. Si le champ indique la cause, agissez en conséquence. Si le champ est absent, aucune raison n'a été renvoyée. Continuez donc avec les autres vérifications.
Les plages de ports utilisent un format valide. Spécifiez chaque plage de ports comme un port unique (par exemple
443) ou comme une plage authentique avec des ports de début et de fin différents (par exemple,8080-8090). Une « plage » dont le début et la fin sont identiques (par exemple443-443) est rejetée. Vous pouvez spécifier jusqu'à 11 plages de ports.Vos sous-réseaux disposent d'adresses IP disponibles. La passerelle de ressources fournit des interfaces réseau élastiques (ENI) dans les sous-réseaux que vous spécifiez. Si ces sous-réseaux sont épuisés, la création échoue. Choisissez des sous-réseaux dotés d'un espace d'adressage libre.
Vos sous-réseaux se trouvent dans des zones de disponibilité prises en charge. Amazon VPC Lattice ne prend pas en charge toutes les zones de disponibilité. Exécutez les opérations suivantes et comparez-les aux zones non prises en charge répertoriées dans Créer une connexion privée :
aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'
Vous n'avez pas atteint les quotas de service Amazon VPC Lattice. Vérifiez votre compte par rapport aux quotas Amazon VPC Lattice, en particulier aux limites des passerelles de ressources.
Aucune politique IAM ou SCP ne bloque le rôle lié au service. La passerelle de ressources gérée par les services est créée via un rôle lié à un service. Si votre organisation dispose de politiques de contrôle des services (SCP) qui limitent les actions d'API Amazon VPC Lattice ou Amazon EC2, assurez-vous qu'elles autorisent le rôle lié au service à créer ces ressources.
Si la connexion continue d'échouer après avoir vérifié tous ces éléments, contactez le AWS support.
La connexion est active, mais l'enregistrement des capacités échoue en raison d'une erreur d'accessibilité
Symptôme
La connexion privée passe à l'état Actif, mais lorsque vous enregistrez un fournisseur de fonctionnalités (par exemple, un serveur MCP) qui l'utilise, l'enregistrement échoue. Pour un serveur MCP, le message d'erreur décrit l'échec de la vérification d'accessibilité. L'un des éléments suivants peut s'afficher :
The MCP server at '<endpoint>' timed out while initializing the session.(une variante similaire fait référence à la liste des ressources)Unable to connect to the MCP server at <endpoint>. The connection was interrupted. Verify the server is running and accessible, then try again.Unable to access tools from the MCP server at '<endpoint>' ...Could not complete request to provider.(peut également apparaître sous forme deAPI error: 504)
Cause
Une connexion privée atteignant Active confirme que le chemin réseau vers votre VPC est établi. Cela ne confirme pas que votre service cible répond à l'adresse et au port attendus. Lorsque vous enregistrez un fournisseur de fonctionnalités, AWS DevOps l'agent vérifie que le point de terminaison est accessible et répond, et c'est là qu'une cible mal configurée apparaît. Le message vous indique quelle couche a échoué :
Un message d'expiration signifie que la connexion n'a jamais atteint un service d'écoute. La plupart du temps, les plages de ports de la connexion n'incluent pas le port du terminal, l'adresse hôte ou la résolution DNS est incorrecte, ou un groupe de sécurité bloque le trafic.
Un message indiquant que la connexion a été interrompue signifie que la connexion a été réinitialisée ou interrompue, généralement en raison d'un échec d'établissement de liaison TLS ou de la fermeture de la connexion par le service.
Un message d'impossibilité d'accéder aux outils signifie que le terminal a répondu mais a rejeté la demande. Il s'agit généralement d'une erreur d'autorisation ou d'une erreur du côté du fournisseur plutôt que d'un problème réseau.
Un message « Impossible de terminer la demande au fournisseur » indique que la demande adressée à votre terminal par le biais de la connexion privée échoue généralement. Passez en revue les étapes de résolution qui suivent.
Une demande réussie provenant d'une instance ou d'une AWS CloudShell session Amazon EC2 de votre VPC confirme que le service est accessible depuis cet environnement de test. Cela ne confirme pas que la passerelle de ressources utilise la même URL de point de terminaison, le même port, la même cible DNS ou la même configuration TLS.
Comment confirmer
Répétez le test avec l'URL de point de terminaison exacte que vous avez enregistrée, y compris son chemin et tout port autre que celui par défaut.
Vérifiez que le port de l'URL du point de terminaison est inclus dans les plages de ports de la connexion privée.
Vérifiez que l'adresse hôte de la connexion privée correspond à l'équilibreur de charge ou au service qui met fin au protocole TLS sur ce port, plutôt qu'à l'adresse IP d'une tâche ou d'une instance sur un port d'application différent.
Vérifiez que la cible sert le protocole HTTPS avec TLS 1.2 ou version ultérieure et présente la chaîne de certificats attendue.
Vérifiez que le groupe de sécurité de la passerelle de ressources autorise le trafic sortant sur le port cible et que le groupe de sécurité cible autorise le trafic entrant correspondant.
Résolution
Vérifiez que les plages de ports de la connexion incluent le port du terminal. Une connexion privée ne transfère le trafic que sur les plages de ports que vous avez configurées lors de sa création. Si vous n'avez pas spécifié de plages de ports, la connexion n'autorise que les ports
443. La connexion interrompt le trafic vers n'importe quel autre port sans erreur descriptive. Le trafic interrompu apparaît sous la forme d'un délai d'attente, d'uneUnable to access toolserreur ou d'uneCould not complete request to provider.erreur. Cela affecte généralement les points de terminaison des ports non standard (par exemple,https://tools.example.com:8089/mcp). La réussitecurld'une instance EC2 dans le même VPC n'exclut pas cette possibilité : ce test contourne complètement la connexion privée. Vous ne pouvez pas modifier les plages de ports après leur création. Supprimez la connexion privée, recréez-la avec des plages de ports qui incluent tous les ports de l'URL de votre point de terminaison, puis enregistrez à nouveau le fournisseur de fonctionnalités.Vérifiez que la passerelle de ressources peut atteindre votre cible. C'est la première chose à exclure lorsque la cible s'exécute sur un autre AWS compte ou sur site. En mode géré par les services, la passerelle de ressources est créée dans le VPC et les sous-réseaux que vous avez spécifiés, dans le même compte que la connexion privée, de sorte que le VPC a besoin d'un itinéraire vers votre cible. Une connexion atteignant Active signifie uniquement que les interfaces réseau de la passerelle ont été créées et sont saines ; cela ne signifie pas qu'elles peuvent accéder à votre service. Vérifiez le mode de connexion et le VPC de la passerelle, puis confirmez l'itinéraire :
aws devops-agent list-private-connections aws vpc-lattice list-resource-gateways
Si le VPC de la passerelle n'a aucune route vers la cible, ajoutez-en une via le peering VPC, AWS Transit Gateway ou une connexion de réseau privé virtuel (VPN), ou déplacez la passerelle vers le compte de la cible en mode autogéré. Consultez la section Créer une connexion privée.
Dirigez le DNS vers l'équilibreur de charge, et non vers une adresse IP de tâche ou d'instance. Une cause fréquente est un enregistrement DNS ou une adresse d'hôte qui se résout en une tâche de conteneur ou en une adresse IP d'instance sur un port d'application (par exemple
8100) au lieu de l'équilibreur de charge qui met fin au protocole TLS sur le port que vous avez configuré (par exemple).443Vérifiez que l'adresse de l'hôte correspond au point de terminaison qui sert réellement le protocole HTTPS sur le port cible.Vérifiez que le service diffuse le protocole HTTPS sur le port configuré. La cible doit servir HTTPS avec une version TLS minimale de 1.2 sur un port inclus dans les plages de ports de la connexion.
Vérifiez les règles du groupe de sécurité dans les deux sens. Vérifiez que le groupe de sécurité attaché à la passerelle de ressources ENiS autorise le trafic sortant sur le port cible et que le groupe de sécurité de votre service autorise le trafic entrant sur ce port. Le trafic provient des adresses IP des plans de données Amazon VPC Lattice comprises dans la plage CIDR de votre VPC. Vous pouvez utiliser le référencement par groupe de sécurité (autoriser le groupe de sécurité ENI en tant que source) ou autoriser le trafic entrant depuis le CIDR du VPC. Consultez la section Configuration des règles de pare-feu pour les connexions privées.
Vérifiez la chaîne de certificats complète pour une autorité de certification privée. Si une autorité de certification privée a émis le certificat TLS de votre service, fournissez la chaîne de PEM-encoded certificats complète lorsque vous créez la connexion. Placez d'abord le certificat foliaire, puis les produits intermédiaires, puis la racine. Si la chaîne est incomplète, la prise de contact TLS échoue même si le chemin réseau est actif. Pour les messages d'erreur que cela génère, voir Le certificat TLS du fournisseur n'est pas fiable.
Vérifiez que la cible est en cours d'exécution. Assurez-vous que votre service est opérationnel et accepte les connexions sur le port prévu avant de terminer l'enregistrement.
Le certificat TLS du fournisseur n'est pas fiable
Symptôme
L'enregistrement ou l'utilisation d'un fournisseur de fonctionnalités échoue en raison d'une erreur de certificat. Le libellé dépend du type de capacité, mais ils décrivent tous la même catégorie de problèmes :
Could not establish a trusted TLS connection to the provider host: its certificate could not be validated against a publicly trusted certificate authority.The server is using a self-signed TLS certificate. Use a certificate from a publicly trusted certificate authority.The server's TLS certificate could not be verified. Ensure the full certificate chain is served and issued by a publicly trusted certificate authority.The server's TLS certificate has expired. Renew the certificate.The server's TLS certificate does not match the endpoint hostname. Ensure the certificate covers the endpoint's domain.
Cause
AWS DevOps L'agent n'a pas pu valider la chaîne de certificats présentée par votre service. Les causes les plus courantes sont un certificat émis par une autorité de certification (CA) privée ou interne, une chaîne dont les certificats intermédiaires sont absents, un certificat expiré dans la chaîne ou un certificat qui ne couvre pas le nom d'hôte dans l'URL de votre point de terminaison.
Note
Ces messages demandent un certificat auprès d'une autorité de certification de confiance publique, mais une autorité de certification privée est prise en charge. Fournissez la chaîne sur la connexion privée, comme décrit dans les étapes de résolution.
Comment confirmer
À partir d'une instance ou d'une AWS CloudShell session Amazon EC2 qui peut atteindre votre cible, inspectez la chaîne que votre service présente sur le port que vous avez configuré et vérifiez quelle autorité de certification a signé en haut de celui-ci :
openssl s_client -connect <your-host-address>:<port> -showcerts
Si une autorité de certification interne a signé le certificat, fournissez la chaîne sur la connexion. Si une autorité de certification publique l'a signée, la chaîne envoyée par votre service est probablement incomplète.
Résolution
Pour un certificat provenant d'une autorité de certification privée, fournissez la chaîne complète sur la connexion privée. Définissez la clé publique du certificat dans la console, ou dans le
certificatechamp decreate-private-connection, sur la PEM-encoded chaîne complète : le certificat feuille d'abord, puis tous les certificats CA intermédiaires, puis la racine. Consultez la section Créer une connexion privée.Pour obtenir un certificat d'une autorité de certification publique, envoyez la chaîne complète. Configurez votre service pour envoyer le certificat Leaf ainsi que tous les certificats intermédiaires, et non le certificat Leaf uniquement.
Remplacez tout certificat expiré de la chaîne.
Vérifiez que le certificat couvre le nom d'hôte dans l'URL de votre point de terminaison.
L'échange de jetons OAuth n'est pas atteint
Symptôme
Vous avez enregistré un serveur OAuth-based MCP (Client Credentials ou 3LO) ou un agent distant qui utilise les informations d'identification client OAuth via une connexion privée, mais l'échange de jetons échoue même si le serveur MCP ou le point de terminaison de l'agent distant est accessible.
Cause
Pour les OAuth-based fournisseurs de fonctionnalités, AWS DevOps l'agent appelle deux points de terminaison : l'URL cible (le serveur MCP ou le point de terminaison de l'agent distant) et l'URL d'échange (le point de terminaison d'échange de jetons OAuth). Lorsque vous sélectionnez une seule connexion privée, elle s'applique aux deux terminaux. Si les deux points de terminaison ne sont accessibles que par des chemins réseau différents, une seule connexion privée ne peut pas être acheminée vers les deux.
Résolution
Si les deux points de terminaison sont accessibles par le même chemin, assurez-vous que l'adresse hôte de la connexion privée peut être acheminée à la fois vers le point de terminaison du serveur MCP ou de l'agent distant et vers le point de terminaison d'échange de jetons.
Si les points de terminaison nécessitent des chemins réseau différents, utilisez les champs par point de terminaison au lieu d'un seul.
privateConnectionNameDéfinisseztargetUrlPrivateConnectionNamepour le point de terminaison du serveur MCP ou de l'agent distant etexchangeUrlPrivateConnectionNamepour le point de terminaison d'échange de jetons. Si vous n'en définissez qu'un, l'autre point de terminaison est atteint via l'Internet public et il ne revient pas à l'autre connexion privée. Vous ne pouvez pas combiner les noms par point de terminaisonprivateConnectionNamedans la même demande. Consultez la section Routage du terminal et échange de jetons OAuth via différentes connexions privées.
Une connexion privée ne peut pas être supprimée pendant son utilisation
Symptôme
La suppression d'une connexion privée échoue avec Private connection '<name>' is in use by one or more services. Deregister the services first.
Cause
Une connexion privée ne peut pas être supprimée tant qu'un fournisseur de fonctionnalités enregistré y fait toujours référence. AWS DevOps L'agent refuse la suppression avant de supprimer des ressources, de sorte que votre connexion reste dans son état actuel.
Résolution
Identifiez les fournisseurs de fonctionnalités qui utilisent la connexion, puis désenregistrez-les ou mettez-les à jour pour qu'ils ne l'utilisent plus.
Supprimez la connexion privée.
Supprimer un fournisseur de fonctionnalités d'un espace d'agent n'est pas la même chose que le désenregistrer. Un enregistrement existe au niveau du compte. Supprimez-le de tous les espaces d'agent, puis supprimez l'enregistrement avant de supprimer la connexion.
La passerelle de ressources ou les ENI sont conservés après la suppression d'une connexion
Symptôme
Vous vous attendiez à ce que la passerelle de ressources gérées et ses ENI soient supprimés, mais ils apparaissent toujours dans votre VPC. Cela peut entraîner des frais ENI et bloquer les opérations qui dépendent d'un VPC propre, telles que. terraform destroy
Cause
La passerelle de ressources gérées et les ENI ne sont supprimés que lorsque vous supprimez la connexion privée via l' AWS DevOps Agent. Les raisons les plus courantes pour lesquelles ils persistent sont qu'ils n'ont jamais DeletePrivateConnection été réellement appelés ou que la AWSAIDevOpsManaged balise a été supprimée des ressources gérées, de sorte que la suppression ne peut pas avoir lieu.
Important
AWS DevOps L'agent étiquette les ressources qu'il gère (la passerelle de ressources et ses ENI). AWSAIDevOpsManaged Le rôle lié à un service ne peut agir que sur les ressources qui portent cette balise, donc ne supprimez ni ne modifiez la AWSAIDevOpsManaged balise. Si la balise est manquante, DeletePrivateConnection impossible de nettoyer les ressources et la suppression échoue.
Résolution
Supprimez la connexion via AWS DevOps l'agent. Utilisez la console (fournisseurs de fonctionnalités > Connexions privées > Actions > Supprimer) ou l'interface de ligne de commande :
aws devops-agent delete-private-connection \ --name my-mcp-tool-connection
L'état passe DELETE_IN_PROGRESS alors que AWS DevOps l'agent supprime la passerelle de ressources gérées et les ENI de votre VPC.
Si la suppression échoue, vérifiez que la
AWSAIDevOpsManagedbalise est toujours présente. Si la balise a été supprimée de la passerelle de ressources ou de ses ENI, appliquez-la de nouveau à ces ressources, puis exécutez à nouveau la suppression.N'essayez pas de supprimer directement la passerelle de ressources gérées. La passerelle de ressources est en lecture seule sur votre compte et est entièrement gérée par l' AWS DevOps Agent. Vous ne pouvez pas la supprimer vous-même via Amazon VPC Lattice. C'est la suppression de la connexion privée qui déclenche sa suppression.
Si vous avez supprimé la connexion privée, que la balise est présente et que la passerelle de ressources ou les ENI sont toujours présentes une fois la suppression terminée, contactez le AWS support pour réconcilier les ressources.
Demander de l'aide
Si vous consultez la section correspondant à votre problème et que le problème persiste, contactez le AWS support. Incluez le nom de votre connexion privée, son état actuel, la AWS région, l'adresse et le port de l'hôte cible afin que le support puisse étudier le chemin réseau.
Rubriques associées
