Come posso risolvere gli errori 500 che ricevo quando utilizzo le integrazioni di collegamenti VPC con le REST API di Gateway API?

Breve descrizione

Gateway API con integrazioni di collegamenti VPC potrebbe non riuscire a inoltrare il traffico alle risorse del backend.

Potrebbe inoltre restituire un codice di stato "HTTP 500" per uno dei seguenti motivi:

• Il collegamento VPC si trova nello stato Non riuscito. Oppure il servizio endpoint non esiste o è nello stato Rifiutato.
• Il gruppo di destinazione visualizza la destinazione registrata come non integra o non in uso.
• I gruppi di sicurezza non consentono il traffico su porte specifiche.
• La lista di controllo degli accessi alla rete (ACL) blocca il traffico.
• La destinazione non è in ascolto sulle porte di destinazione.
• Il certificato del nome dominio non corrisponde al Network Load Balancer o all'Application Load Balancer con TLS attivato.

Se hai attivato Amazon CloudWatch Logs per l'API, nei log di esecuzione compare un messaggio con la causa dell'errore.

Risoluzione

Convalida la connettività del backend

Prima di risolvere i problemi relativi a Gateway API, intraprendi una delle seguenti azioni:

• Utilizza strumenti, come curl o Postman per inviare una richiesta al nome DNS del Network Load Balancer dall'interno del VPC. Se la richiesta ha esito negativo, è presente un problema con la configurazione del Network Load Balancer, l'integrità della destinazione di backend o la rete.
• Utilizza il sistema di analisi della reperibilità VPC per convalidare il flusso di traffico dalle sottoreti di collegamento VPC di Gateway API alle risorse del backend.

Verifica la causa dell'errore

Attiva la registrazione delle API in CloudWatch. Inoltre, configura la registrazione delle esecuzioni.

Nota: quando configuri le impostazioni di registrazione, imposta il livello di registrazione su Log di errori e informazioni e seleziona Tracciamento dei dati. Queste impostazioni forniscono i log completi delle richieste e delle risposte.

Per identificare la causa degli errori, visualizza i log di esecuzione delle REST API in CloudWatch. Quindi risolvi il problema in base al messaggio di errore ricevuto.

Risolvi il problema "There was an internal error while executing your request"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to configuration error: There was an internal error while executing your request"

Per risolvere questo problema, controlla le seguenti configurazioni:

• Il bilanciatore del carico del collegamento VPC esiste e non è stato eliminato.
• Il collegamento VPC si trova nello stato Disponibile. Se il collegamento VPC si trova nello stato Non riuscito, devi creare un nuovo collegamento VPC e associarlo all'API.
  Nota: distribuisci l'API dopo aver modificato la richiesta di integrazione.
• La connessione all'endpoint del collegamento VPC associata al Network Load Balancer di destinazione è nello stato Disponibile.
• Hai indicato l'ID dell'account Gateway API specifico per la Regione AWS in Consenti entità principali.
• Una connessione all'endpoint dall'account Gateway API in Connessioni endpoint per il servizio endpoint è nello stato Disponibile.
• Se Gateway API fa riferimento all'ID del VPC con una variabile di fase, verifica che l'ID del collegamento VPC sia corretto.
• Il bilanciatore del carico del collegamento VPC è in ascolto sulla porta HTTP/HTTPS per cui hai configurato la richiesta. Assicurati di aver configurato i listener per la porta corretta e che le ACL non blocchino la richiesta.
• Il gruppo di destinazione accetta la richiesta. Le ACL devono consentire il traffico in entrata e in uscita e i gruppi di sicurezza devono consentire il traffico in entrata per le porte configurate.
• Se la richiesta restituisce un errore con codice di stato "HTTP 500", la connessione potrebbe ricevere il numero totale di pacchetti di ripristino (RST) TCP. Il server di backend deve essere in esecuzione. Inoltre, un servizio deve essere in esecuzione sulla destinazione di backend della porta di destinazione. Verifica che la destinazione di backend sia in ascolto sulla porta di destinazione.
• Hai disattivato le regole in entrata per il traffico di AWS PrivateLink. L'opzione Applicazione di regole in entrata sul traffico PrivateLink applica tutte le regole del gruppo di sicurezza in entrata e in uscita al traffico proveniente dal collegamento VPC. Se non configuri il gruppo di sicurezza in modo da consentire il traffico proveniente dal collegamento VPC, tale gruppo potrebbe bloccare il traffico di Gateway API.

Risolvi il problema "Host name 'domain.com.com' does not match the certificate subject provided by the peer"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)"

Assicurati che il nome dominio dell'endpoint corrisponda al certificato restituito dalla destinazione del bilanciatore del carico con TLS attivato. I certificati configurati nell'istanza di destinazione devono essere considerati attendibili dall'elenco di autorità di certificazione supportate.

Risoluzione del problema "PKIX path building failed:...unable to find valid certification path to requested target"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

Questo errore si verifica quando il servizio REST API indica un certificato che l'integrazione restituisce come non valido. Anche se l'opzione insecureSkipVerification è impostata su true nella proprietà TlsConfig dell'integrazione, Gateway API esegue la convalida di base del certificato.

Gateway API esamina le seguenti informazioni:

• La data di scadenza del certificato
• Il nome host
• La presenza di un'autorità di certificazione (CA) root
  Nota: l'integrazione deve includere e restituire l'intera catena di certificati affinché Gateway API verifichi la catena di attendibilità e stabilisca una connessione sicura. La catena completa include tutti i certificati intermedi, dal certificato del server fino al certificato della CA root. Inoltre, la CA root deve includere KeyUsage con keyCertSign e basicConstraints con CA:TRUE. Per ulteriori informazioni, consulta Oggetto x-amazon-apigateway-integration.tlsConfig.

Risolvi il problema "Cannot verify ECDH ServerKeyExchange signature"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature"

Questo errore si verifica perché la chiave e il certificato non corrispondono, quindi l'handshake TLS ha esito negativo. Per risolvere il problema, verifica il contenuto dei file utilizzati per le CA, le chiavi e i certificati configurati.

Risolvi il problema "Execution failed due to an internal error"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to an internal error"

Questo errore si verifica quando Gateway API non si connette al bilanciatore del carico tramite il collegamento VPC a causa del ripristino della destinazione nel bilanciatore del carico. Per risolvere il problema, imposta un timeout più lungo per la destinazione rispetto al timeout predefinito (350 secondi) nel bilanciatore del carico.

Risolvi il problema "Execution failed due to a VPC link error"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to a VPC link error"

Gateway API ha molte dipendenze. Potresti ricevere errori quando una delle dipendenze presenta problemi di connessione transitori. In caso di errori poco frequenti, è consigliabile implementare la ripetizione con backoff esponenziale. Se invece la frequenza degli errori è elevata, contatta il Supporto AWS. Assicurati di fornire i log di esecuzione di Gateway API che mostrano gli errori.

Risolvi il problema "Execution failed due to configuration error: Not a valid protocol version"

Ricevi il seguente messaggio di errore:

"Error: Execution failed due to configuration error: Not a valid protocol version"

Questo errore si verifica quando l'integrazione fornisce una risposta HTTP non valida che non rispetta le specifiche HTTP. Il backend integrato potrebbe restituire dati non validi a Gateway API.

Per risolvere il problema, intraprendi le seguenti azioni:

• Riproduci la richiesta effettuata da Gateway API. Per verificare l'endpoint del servizio utilizzato da Gateway API, crea un endpoint VPC collegato all'ID dell'endpoint del servizio. Puoi inoltre eseguire acquisizioni di pacchetti per esaminare la risposta restituita dal backend integrato.
• Per evitare la doppia crittografia, cambia il protocollo del bilanciatore del carico in TLS o TCP, a seconda della risposta delle destinazioni.
• Assicurati che l'opzione insecureSkipVerification sia impostata su true nella proprietà TlsConfig dell'integrazione.

Monitora e rileva errori e problemi

Utilizza i seguenti strumenti per determinare se il problema è transitorio o se sono presenti problemi di configurazione persistenti:

• Monitora le metriche 5XXError e IntegrationLatency di Gateway API in CloudWatch per individuare modelli.
• Attiva il tracciamento di AWS X-Ray per monitorare i percorsi delle richieste da Gateway API al collegamento VPC, dal collegamento VPC al Network Load Balancer e dal Network Load Balancer al backend.

Informazioni correlate

Understanding VPC Links in Amazon API Gateway private Integrations (Collegamenti VPC nelle integrazioni private di Gateway Amazon API)

Monitora l'esecuzione delle REST API con le metriche di Amazon CloudWatch

Configurazione di un Network Load Balancer per le integrazioni private di Gateway API (legacy)