As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Solução de problemas de conexões privadas
Esta página descreve problemas comuns que você pode encontrar ao criar ou usar um Conectando-se a ferramentas hospedadas de forma privada for AWS DevOps Agent e como resolvê-los. Cada seção descreve um sintoma, as causas mais prováveis e as etapas para corrigi-lo.
Para obter uma visão geral de como as conexões privadas funcionam, consulteConectando-se a ferramentas hospedadas de forma privada.
Um endereço de host DNS não é resolvido ou o tráfego chega ao lugar errado
Sintomas
Você criou uma conexão privada usando um nome DNS para o endereço do host, mas a conexão não pode acessar seu serviço. Isso é mais comum quando seu serviço de destino é uma GitLab instância auto-hospedada, um Application Load Balancer (ALB) interno ou um servidor MCP cujo nome de host só existe dentro da sua VPC.
Uma falha na resolução do DNS não produz uma mensagem que mencione o DNS. Em vez disso, ele aparece como um erro genérico de acessibilidade ou de provedor quando você registra ou usa o provedor de recursos. Por exemplo, você pode ver Could not complete request to provider.Unable to connect to the MCP server at <endpoint>. The connection was interrupted., ou até mesmo um erro de autenticação, como Authentication with provider failed. Como a mensagem não aponta para o DNS, use a verificação a seguir para confirmar a causa.
Causa
Por padrão, uma conexão privada resolve o endereço do host usando o DNS público ()dnsResolution: PUBLIC. Se seu nome de host tiver apenas um registro em uma zona hospedada privada, uma regra do Amazon Route 53 Resolver ou um servidor DNS local, a resolução pública falhará e a conexão nunca alcançará seu serviço.
Como confirmar que o DNS é a causa
Verifique se o endereço do seu host é resolvido somente dentro da sua VPC. Em uma instância ou AWS CloudShell sessão do Amazon EC2 na mesma VPC, execute.
nslookup <your-host-address>Se for resolvido lá, mas não a partir do DNS público, e sua conexão privada for usadadnsResolution: PUBLIC, a resolução do DNS é a causa.Teste com o endereço IP em vez do nome. Crie temporariamente uma conexão privada que use o endereço IP privado do alvo (ou um IP do balanceador de carga) para o endereço do host em vez do nome DNS. Se a conexão chegar ao seu serviço, a falha anterior foi a resolução do DNS, não o caminho da rede ou o próprio serviço.
Resolução
Se seu nome de host for resolvido somente dentro da sua VPC, defina o modo de resolução de DNS como In VPC (
IN_VPC) ao criar a conexão. Nesse modo, o endereço do host é resolvido de dentro do seu contexto de VPC, portanto, nomes de host somente privados são resolvidos corretamente. Consulte Criar uma conexão privada.O modo de resolução de DNS é escolhido no momento da criação e se aplica ao endereço de host que você fornece. Você não pode alterar a forma como o gateway de recursos gerenciados pelo serviço resolve o DNS após a criação, então escolha o modo correto de antemão. Se você selecionou o modo errado, exclua a conexão e recrie-a com o modo correto.
Se você especificar um endereço IP (em vez de um nome DNS) para o endereço do host, o modo de resolução de DNS não terá efeito e o tráfego será direcionado diretamente para esse IP.
Se você não puder usar
IN_VPCpara sua configuração, poderá apontar o endereço do host para o endereço IP privado do destino ou para o nome DNS de um balanceador de carga que pode ser resolvido publicamente, mas encaminhado para um IP privado.
A conexão está travada em Criar falhou
Sintomas
Depois de criar uma conexão privada, o console mostra o status como Falha na conexão (e describe-private-connection retorna um status deCREATE_FAILED).
Causa
A falha na criação geralmente resulta de um problema de configuração na solicitação ou na sua VPC, em vez de um erro de serviço. Quando uma conexão tem um status de falha, o AWS DevOps Agente descreve o motivo no failureMessage campo, então leia esse campo antes de trabalhar na lista de verificação.
Resolução
Verifique o seguinte, na ordem:
Leia
failureMessageos detalhes da conexão. Esse campo descreve por que uma conexão tem um status de falha e está presente quando o status éCREATE_FAILEDouDELETE_FAILED:
aws devops-agent describe-private-connection \ --name my-mcp-tool-connection
failureMessagetambém aparece na saída delist-private-connections. Se o campo indicar a causa, aja de acordo com ela. Se o campo estiver ausente, nenhum motivo foi retornado, então continue com as verificações restantes.
Os intervalos de portas usam um formato válido. Especifique cada intervalo de portas como uma única porta (por exemplo,
443) ou um intervalo genuíno com portas inicial e final diferentes (por exemplo,8080-8090). Um “intervalo” cujo início e fim são iguais (por exemplo,443-443) é rejeitado. Você pode especificar até 11 intervalos de portas.Suas sub-redes têm endereços IP disponíveis. O gateway de recursos provisiona interfaces de rede elásticas (ENIs) nas sub-redes que você especificar. Se essas sub-redes estiverem esgotadas, a criação falhará. Escolha sub-redes com espaço de endereço livre.
Suas sub-redes estão em zonas de disponibilidade suportadas. O Amazon VPC Lattice não oferece suporte a todas as zonas de disponibilidade. Execute o seguinte e compare com as zonas não suportadas listadas em Criar uma conexão privada:
aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'
Você não atingiu as cotas de serviço Amazon VPC Lattice. Compare sua conta com as cotas do Amazon VPC Lattice, especialmente os limites do gateway de recursos.
Nenhuma política de IAM ou SCP está bloqueando a função vinculada ao serviço. O gateway de recursos gerenciados pelo serviço é criado por meio de uma função vinculada ao serviço. Se sua organização tiver políticas de controle de serviços (SCPs) que restringem as ações da Amazon VPC Lattice ou da API do Amazon EC2, certifique-se de que elas permitam que a função vinculada ao serviço crie esses recursos.
Se a conexão continuar falhando depois de verificar todos esses itens, entre em contato com o AWS Suporte.
A conexão está ativa, mas o registro da capacidade falha com um erro de acessibilidade
Sintomas
A conexão privada atinge o estado Ativo, mas quando você registra um provedor de recursos (por exemplo, um servidor MCP) que a usa, o registro falha. Para um servidor MCP, a mensagem de erro descreve como a verificação de acessibilidade falhou. Você pode ver uma das seguintes opções:
The MCP server at '<endpoint>' timed out while initializing the session.(uma variante semelhante se refere à listagem de recursos)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.(também pode aparecer como umAPI error: 504)
Causa
Uma conexão privada alcançando o Active confirma que o caminho da rede para sua VPC foi estabelecido. Isso não confirma que seu serviço de destino esteja respondendo no endereço e na porta esperados. Quando você registra um provedor de recursos, o AWS DevOps Agente valida se o endpoint está acessível e respondendo, e é aí que surge um alvo mal configurado. A mensagem informa qual camada falhou:
Uma mensagem expirada significa que a conexão nunca chegou a um serviço de escuta. Na maioria das vezes, os intervalos de portas da conexão não incluem a porta do endpoint, o endereço do host ou a resolução do DNS estão errados ou um grupo de segurança está bloqueando o tráfego.
Uma mensagem de conexão foi interrompida significa que a conexão foi reiniciada ou interrompida, normalmente por uma falha no handshake TLS ou pelo serviço fechando a conexão.
Uma mensagem de incapacidade de acessar as ferramentas significa que o endpoint respondeu, mas rejeitou a solicitação. Isso geralmente é um erro de autorização ou do provedor, e não um problema de rede.
A mensagem Não foi possível concluir a solicitação ao provedor é uma falha geral em concluir a solicitação ao seu endpoint por meio da conexão privada. Analise as etapas de resolução a seguir.
Uma solicitação bem-sucedida de uma instância ou AWS CloudShell sessão do Amazon EC2 em sua VPC confirma que o serviço pode ser acessado a partir desse ambiente de teste. Ele não confirma que o gateway de recursos usa a mesma URL, porta, destino DNS ou configuração TLS do endpoint.
Como confirmar
Repita o teste com a URL exata do endpoint que você registrou, incluindo seu caminho e qualquer porta não padrão.
Confirme se a porta do URL do endpoint está incluída nos intervalos de portas da conexão privada.
Confirme se o endereço do host da conexão privada é resolvido para o balanceador de carga ou serviço que encerra o TLS nessa porta, em vez de para um IP de tarefa ou instância em uma porta de aplicativo diferente.
Confirme se o destino serve HTTPS com TLS 1.2 ou posterior e apresenta a cadeia de certificados esperada.
Confirme se o grupo de segurança do gateway de recursos permite tráfego de saída na porta de destino e se o grupo de segurança de destino permite o tráfego de entrada correspondente.
Resolução
Confirme se os intervalos de portas da conexão incluem a porta do endpoint. Uma conexão privada só encaminha o tráfego nos intervalos de portas que você configura ao criá-la. Se você não especificou intervalos de portas, a conexão permite somente portas
443. A conexão descarta o tráfego para qualquer outra porta sem um erro descritivo. O tráfego perdido aparece como um tempo limite, umUnable to access toolserro ou umCould not complete request to provider.erro. Isso geralmente afeta endpoints em portas não padrão (por exemplo,https://tools.example.com:8089/mcp). O sucessocurlde uma instância do EC2 na mesma VPC não descarta isso — esse teste ignora totalmente a conexão privada. Você não pode alterar os intervalos de portas após a criação. Exclua a conexão privada, recrie-a com intervalos de portas que incluam todas as portas na URL do seu endpoint e registre o provedor de recursos novamente.Confirme se o gateway de recursos pode alcançar seu alvo. Essa é a primeira coisa a ser descartada quando o alvo é executado em uma AWS conta diferente ou no local. No modo gerenciado por serviços, o gateway de recursos é criado na VPC e nas sub-redes que você especificou, na mesma conta da conexão privada, para que a VPC precise de uma rota para seu destino. Uma conexão chegando à Ativa significa apenas que as interfaces de rede do gateway foram criadas e estão íntegras; isso não significa que elas possam acessar seu serviço. Verifique o modo da conexão e a VPC do gateway e confirme a rota:
aws devops-agent list-private-connections aws vpc-lattice list-resource-gateways
Se a VPC do gateway não tiver nenhuma rota para o destino, adicione uma por meio de emparelhamento de VPC, AWS Transit Gateway ou uma conexão de rede virtual privada (VPN) ou mova o gateway para a conta do destino usando o modo autogerenciado. Consulte Criar uma conexão privada.
Aponte o DNS para o balanceador de carga, não para um IP de tarefa ou instância. Uma causa frequente é um registro DNS ou endereço de host que é resolvido para uma tarefa de contêiner ou IP de instância em uma porta de aplicativo (por exemplo,
8100) em vez do balanceador de carga que encerra o TLS na porta que você configurou (por exemplo,).443Confirme se o endereço do host é resolvido para o endpoint que realmente serve HTTPS na porta de destino.Confirme se o serviço serve HTTPS na porta configurada. O destino deve servir HTTPS com uma versão TLS mínima de 1.2 em uma porta incluída nos intervalos de portas da conexão.
Verifique as regras do grupo de segurança em ambas as direções. Verifique se o grupo de segurança conectado ao gateway de recursos ENiS permite tráfego de saída na porta de destino e se o grupo de segurança do seu serviço permite tráfego de entrada nessa porta. O tráfego chega dos IPs do plano de dados Amazon VPC Lattice dentro da sua faixa CIDR da VPC. Você pode usar a referência ao grupo de segurança (permitir o grupo de segurança ENI como origem) ou permitir a entrada do CIDR da VPC. Consulte Configuração de regras de firewall para conexões privadas.
Verifique toda a cadeia de certificados de uma CA privada. Se uma autoridade de certificação privada emitiu o certificado TLS do seu serviço, forneça toda a cadeia de PEM-encoded certificados ao criar a conexão. Coloque primeiro o certificado foliar, depois os intermediários e depois a raiz. Se a cadeia estiver incompleta, o handshake TLS falhará mesmo que o caminho da rede esteja ativo. Para ver as mensagens de erro que isso produz, consulte O certificado TLS do provedor não é confiável.
Confirme se o alvo está em execução. Certifique-se de que seu serviço esteja ativo e aceitando conexões na porta esperada antes de concluir o registro.
O certificado TLS do provedor não é confiável
Sintomas
O registro ou o uso de um provedor de recursos falha com um erro de certificado. O texto depende do tipo de capacidade, mas todas elas descrevem a mesma classe de problema:
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.
Causa
AWS DevOps O agente não conseguiu validar a cadeia de certificados que seu serviço apresentou. As causas comuns são um certificado emitido por uma autoridade de certificação (CA) privada ou interna, uma cadeia sem seus certificados intermediários, um certificado expirado na cadeia ou um certificado que não cobre o nome do host na URL do seu endpoint.
nota
Essas mensagens solicitam um certificado de uma CA publicamente confiável, mas há suporte para uma CA privada. Forneça a cadeia na conexão privada, conforme descrito nas etapas de resolução.
Como confirmar
Em uma instância ou AWS CloudShell sessão do Amazon EC2 que possa atingir seu alvo, inspecione a cadeia que seu serviço apresenta na porta que você configurou e verifique qual CA assinou a parte superior:
openssl s_client -connect <your-host-address>:<port> -showcerts
Se uma CA interna assinou o certificado, forneça a cadeia na conexão. Se uma CA pública a assinou, a cadeia que seu serviço envia provavelmente está incompleta.
Resolução
Para obter um certificado de uma CA privada, forneça toda a cadeia na conexão privada. Defina a chave pública do certificado no console, ou o
certificatecampo emcreate-private-connection, para a PEM-encoded cadeia completa: primeiro o certificado folha, depois todos os certificados CA intermediários e depois a raiz. Consulte Criar uma conexão privada.Para obter um certificado de uma CA pública, envie a cadeia completa. Configure seu serviço para enviar o certificado leaf mais todos os certificados intermediários, não apenas o leaf.
Substitua qualquer certificado expirado na cadeia.
Confirme se o certificado abrange o nome do host na URL do seu endpoint.
A troca de tokens OAuth não pode ser alcançada
Sintomas
Você registrou um servidor OAuth-based MCP (Client Credentials ou 3LO) ou um agente remoto que usa credenciais de cliente OAuth por meio de uma conexão privada, mas a troca de tokens falha mesmo que o terminal do servidor MCP ou do agente remoto esteja acessível.
Causa
Para provedores OAuth-based de recursos, o AWS DevOps Agente chama dois endpoints: o URL de destino (o servidor MCP ou o endpoint do agente remoto) e o URL de troca (o endpoint de troca de tokens OAuth). Quando você seleciona uma única conexão privada, ela se aplica aos dois terminais. Se os dois endpoints só puderem ser acessados por meio de caminhos de rede diferentes, uma única conexão privada não poderá rotear para ambos.
Resolução
Se os dois endpoints puderem ser acessados pelo mesmo caminho, certifique-se de que o endereço do host da conexão privada possa ser roteado tanto para o servidor MCP quanto para o endpoint do agente remoto e para o endpoint de troca de tokens.
Se os endpoints exigirem caminhos de rede diferentes, use os campos por endpoint em vez de um único.
privateConnectionNameDefinidotargetUrlPrivateConnectionNamepara o servidor MCP ou endpoint do agente remoto eexchangeUrlPrivateConnectionNamepara o endpoint de troca de tokens. Se você definir apenas um, o outro endpoint será acessado pela Internet pública e não retornará à outra conexão privada. Você não pode combinar os nomes por endpointprivateConnectionNamena mesma solicitação. Consulte Roteamento do endpoint e troca de tokens OAuth por meio de diferentes conexões privadas.
Uma conexão privada não pode ser excluída enquanto estiver em uso
Sintomas
A exclusão de uma conexão privada falha com Private connection '<name>' is in use by one or more services. Deregister the services first.
Causa
Uma conexão privada não pode ser excluída enquanto um provedor de recursos registrado ainda fizer referência a ela. AWS DevOps O agente recusa a exclusão antes de remover qualquer recurso, para que sua conexão permaneça no estado atual.
Resolução
Identifique os provedores de recursos que usam a conexão e cancele o registro deles ou atualize-os para que não a usem mais.
Exclua a conexão privada.
Remover um provedor de recursos de um Agent Space não é o mesmo que cancelar seu registro. Existe um registro no nível da conta, então remova-o de todos os Espaços do Agente e exclua o registro antes de excluir a conexão.
O gateway de recursos ou ENIs permanecem após você excluir uma conexão
Sintomas
Você esperava que o gateway de recursos gerenciados e seus ENIs fossem removidos, mas eles ainda aparecem na sua VPC. Isso pode gerar cobranças de ENI e bloquear operações que dependem de uma VPC limpa, como. terraform destroy
Causa
O gateway de recursos gerenciados e os ENIs são removidos somente quando você exclui a conexão privada por meio do AWS DevOps Agente. Os motivos mais comuns pelos quais elas permanecem são que nunca DeletePrivateConnection foi realmente chamada ou porque a AWSAIDevOpsManaged tag foi removida dos recursos gerenciados, portanto, a exclusão não pode continuar.
Importante
AWS DevOps O agente marca os recursos que ele gerencia (o gateway de recursos e seus ENIs). AWSAIDevOpsManaged A função vinculada ao serviço pode atuar somente em recursos que carregam essa tag, portanto, não remova nem modifique a AWSAIDevOpsManaged tag. Se a tag estiver ausente, não será DeletePrivateConnection possível limpar os recursos e a exclusão falhará.
Resolução
Exclua a conexão por meio do AWS DevOps Agente. Use o console (Provedores de capacidade > Conexões privadas > Ações > Remover) ou a CLI:
aws devops-agent delete-private-connection \ --name my-mcp-tool-connection
O status muda para DELETE_IN_PROGRESS while AWS DevOps Agent remove o gateway de recursos gerenciados e os ENIs da sua VPC.
Se a exclusão falhar, confirme se a
AWSAIDevOpsManagedtag ainda está presente. Se a tag foi removida do gateway de recursos ou de seus ENIs, aplique-a novamente a esses recursos e execute a exclusão novamente.Não tente excluir diretamente o gateway de recursos gerenciados. O gateway de recursos é somente para leitura em sua conta e é totalmente gerenciado pelo AWS DevOps Agente, e você não pode excluí-lo sozinho por meio do Amazon VPC Lattice. A exclusão da conexão privada é o que aciona sua remoção.
Se você excluiu a conexão privada, a tag está presente e o gateway de recursos ou ENIs ainda permanecem após a conclusão da exclusão, entre em contato com o AWS Suporte para reconciliar os recursos.
Solicitando ajuda
Se você ler a seção relevante para seu problema e o problema persistir, entre em contato com o AWS Suporte. Inclua o nome da sua conexão privada, seu status atual, a AWS região e o endereço e a porta do host de destino para que o suporte possa investigar o caminho da rede.
Tópicos relacionados
