Apigee 및 Apigee Hybrid 문서입니다.
이 주제에 해당하는 Apigee Edge 문서가 없습니다.
증상
경우에 따라 외부 클라이언트가 원하는 방식으로 Apigee에 액세스하거나 연결할 수 없습니다. 여기에는 네트워크 연결 실패(TLS 핸드셰이크 실패) 또는 Apigee의 4xx/5xx
응답이 포함됩니다.
오류 메시지
클라이언트에서 Apigee로 API 요청을 전송할 때 Apigee UI에서 API 프록시가 정상으로 보이는 경우에도 TLS 핸드셰이크 오류 또는 4xx/5xx
응답이 표시됩니다.
가능한 원인
원인 | 설명 | 오류 코드 |
---|---|---|
HTTPS 부하 분산기의 TLS 오류 | HTTPS 부하 분산기의 TLS 구성을 관리합니다. HTTPS 부하 분산기 로그에서 모든 TLS 오류를 조사합니다. | 부하 분산기 IP 주소의 TLS 핸드셰이크 오류 |
요청을 차단하는 Google Cloud Armor | Google Cloud Armor를 사용 중인 경우 요청을 차단하는 규칙이 있을 수 있습니다. |
API 응답 코드는 Google Cloud Armor 구성에 따라 다를 수 있습니다. 거부 규칙은 HTTP 403 (승인되지 않음), 404 (액세스 거부), 502 (잘못된 게이트웨이) 응답 또는 다른 응답 코드를 반환할 수 있습니다.
|
Apigee 프록시 VM은 트래픽을 Apigee 인스턴스로 전달할 수 없음 | Apigee API 트래픽 라우터 프록시 구성과 그 상태를 조사해야 합니다. | 502 Server Error |
잘못된 네트워크 구성 | 올바른 네트워크가 Apigee VPC와 피어링되었는지 확인합니다. | 502 Server error |
리전 확장의 일부로 생성된 새 Apigee 인스턴스의 연결되지 않은 환경 | 두 번째 리전과 같은 새 인스턴스를 만든 후 환경을 연결해야 합니다. 그렇지 않으면 API 요청에 응답할 수 없습니다. | 503 error response |
원인: HTTPS 부하 분산기의 TLS 오류
진단
- 부하 분산기와 연결된 TLS 인증서를 찾습니다.
- Google Cloud 콘솔 사용:
-
Google Cloud 콘솔에서 부하 분산 페이지로 이동합니다.
-
부하 분산기 이름을 클릭합니다. 부하 분산기 세부정보 페이지가 열립니다.
- 프런트엔드 영역의 IP:포트 열에서 IP 주소와 포트를 확인하여 올바른 부하 분산기를 찾고 있는지 확인합니다.
- 인증서 열에서 인증서 이름을 클릭하여 TLS 인증서를 확인합니다.
-
-
gcloud 명령어를 사용합니다.
-
다음
gcloud 명령어를 사용하여 부하 분산기를 나열합니다. 이 명령어는 각 부하 분산기와 연결된
SSL_CERTIFICATES
도 표시합니다.gcloud compute target-https-proxies list --project=PROJECT_NAME
PROJECT_NAME
를 프로젝트 이름으로 바꿉니다.다음과 비슷한 결과가 반환됩니다.
NAME: example-proxy-https-proxy SSL_CERTIFICATES: example-ssl-cert URL_MAP: example-proxy-url-map REGION: CERTIFICATE_MAP:
-
다음 gcloud 명령어를 사용하여 TLS 인증서를 확인합니다.(여기서는 머신에
jq
또는 유사한 도구가 설치되어 있다고 가정합니다.)gcloud compute ssl-certificates describe CERTICATE_NAME \ --project PROJECT_NAME --format json | jq -r '.certificate' | openssl x509 -text -noout
CERTIFICATE_NAME을 인증서 이름으로 바꿉니다. 예를 들면
example-ssl-cert
입니다.다음과 비슷한 결과가 반환됩니다.
certCertificate: Data: Version: 3 (0x2) Serial Number: 51:3b:a4:60:fe:49:34:a2:09:af:14:85:96:a2:4f:d9 Signature Algorithm: sha256WithRSAEncryption Issuer: C = US, O = Google Trust Services LLC, CN = GTS CA 1D4 Validity Not Before: Jul 11 11:51:52 2023 GMT Not After : Oct 9 12:44:45 2023 GMT Subject: CN = 34.149.207.105.nip.io Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public-Key: (2048 bit) . . Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication X509v3 Basic Constraints: critical CA:FALSE X509v3 Subject Key Identifier: A5:DB:7C:6A:8B:0B:7A:22:45:52:1E:85:29:32:77:18:A3:9D:87:76 X509v3 Authority Key Identifier: keyid:25:E2:18:0E:B2:57:91:94:2A:E5:D4:5D:86:90:83:DE:53:B3:B8:92 Authority Information Access: OCSP - URI:http://ocsp.pki.goog/s/gts1d4/qMhEcTt7LjA CA Issuers - URI:http://pki.goog/repo/certs/gts1d4.der X509v3 Subject Alternative Name: DNS:34.149.207.105.nip.io X509v3 Certificate Policies: Policy: 2.23.140.1.2.1 Policy: 1.3.6.1.4.1.11129.2.5.3 X509v3 CRL Distribution Points: Full Name: URI:http://crls.pki.goog/gts1d4/LjtNmxrQfWE.crl
인증서의 일반 이름(CN)이 Apigee > 관리 > 환경 > 그룹에 구성된 호스트 이름과 일치하는지 확인합니다. 인증서가 유효하고 만료되지 않았는지 확인합니다.
openssl
을 사용하여 이러한 검사를 수행할 수 있습니다.
-
다음
gcloud 명령어를 사용하여 부하 분산기를 나열합니다. 이 명령어는 각 부하 분산기와 연결된
- Google Cloud 콘솔 사용:
-
부하 분산기에서 반환한 TLS 인증서를 확인하려면 클라이언트 머신에서 다음
openssl
명령어를 실행합니다. 이 인증서가 위의 1단계에서 반환된 인증서와 일치하는지 확인합니다.openssl s_client -connect LB_HOSTNAME_OR_IP:443 -servername LB_HOSTNAME -showcerts
다음을 바꿉니다.
-
LB_HOSTNAME_OR_IP: 부하 분산기 호스트 이름 또는 IP 주소. 예를 들면
my-load-balancer
입니다. -
LB_HOSTNAME: 부하 분산기 호스트 이름. 예를 들면
my-hostname
입니다.
인증서가 일치하는지 확인하려면 클라이언트에서 다음 명령어를 실행합니다.
echo | openssl s_client -connect HOST_NAME:443 -servername HOST_NAME | openssl x509 -noout -text | openssl md5
HOST_NAME을 Apigee에 구성된 호스트 이름으로 바꿉니다(관리자 > 환경 > 그룹).
그런 다음 다음 gcloud 명령어를 실행하여
md5
가 일치하는지 확인합니다.gcloud compute ssl-certificates describe CERTIFICATE_NAME --project PROJECT_NAME --format json | jq -r '.certificate' | openssl x509 -noout -text | openssl md5
CERTIFICATE_NAME을 인증서의 이름으로 바꿉니다. 예를 들면
my-certificate
입니다. -
LB_HOSTNAME_OR_IP: 부하 분산기 호스트 이름 또는 IP 주소. 예를 들면
-
1단계 및 2단계 인증서가 일치하는 경우(예:
md5
값이 일치하는 경우) 클라이언트 측에서packet capture
수집을 진행하여 TLS 핸드셰이크 실패를 조사합니다. Wireshark, tcpdump 또는 기타 신뢰할 수 있는 도구와 같은 도구를 사용하여 클라이언트 측에서 패킷 캡처를 수행할 수 있습니다. - 기존 백엔드 서비스에 로깅 사용 설정의 안내에 따라 부하 분산기에서 로그를 사용 설정합니다.
- 오류가 있는지 부하 분산기 로그를 검토합니다.
해결 방법
- 부하 분산기의 자체 관리형 인증서가 만료되었거나 잘못된 CN/SAN 값이 있는 경우 부하 분산기의 인증서를 교체해야 할 수 있습니다.
-
1단계의 부하 분산기에서 반환된 인증서 및 2단계의 인증서가 일치하지 않는 경우 부하 분산기가 오래되거나 잘못된 인증서를 제공함을 의미할 수 있으므로 Google Cloud Customer Care에 티켓을 제출해야 합니다.
-
tcpdump
에서 TLS 핸드셰이크 실패를 나타내는 경우 연결 실패가 부하 분산기 또는 클라이언트 측에서 발생했는지 조사합니다.- 실패 또는 연결 재설정이 클라이언트 측에서 발생한 경우 클라이언트 애플리케이션을 확인하여 오작동하는 이유를 파악합니다. 예를 들어 클라이언트 측에서 네트워크 구성을 확인하거나 클라이언트 애플리케이션이 Apigee와 연결되어 있는지 확인할 수 있습니다.
- 부하 분산기 자체에서 실패/재설정이 표시되면 일반 연결 문제 해결을 참조하고 필요한 경우 Google Cloud Customer Care에 티켓을 제출하세요.
- 부하 분산기 로그에 오류가 표시되면 설명되지 않은 5XX 오류를 참조하고 필요한 경우 Google Cloud Customer Care에 티켓을 제출하세요.
여전히 지원이 필요한 경우 진단 정보 수집 필요를 참조하세요.
원인: Cloud Armor에서 요청을 차단함
진단
Cloud Armor 구성을 기반으로 403
, 404
또는 502
오류 응답이 표시되면 부하 분산기 및 MIG 구성을 검토하여 올바르게 구성되어 있고 정상으로 나타나는지 확인합니다.
- Google Cloud 환경에서 Google Cloud Armor를 사용하는 경우 Google Cloud Armor 구성을 검토하여 요청을 차단할 수 있는 규칙이 있는지 확인합니다. 보안 정책은 Google Cloud Armor 보안 정책 구성에서 확인할 수 있습니다.
- 트래픽을 거부하는 규칙이 확실하지 않은 경우 기존 백엔드 서비스에 로깅 사용 설정에 설명된 대로 부하 분산기에서 로깅을 사용 설정해 볼 수 있습니다.
-
로깅이 사용 설정되면 로그 쿼리를 수행하여 Google Cloud Armor 정책에 의해 차단된 요청을 찾습니다.
-
Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
-
다음을 쿼리 창에 붙여넣습니다.
jsonPayload.enforcedSecurityPolicy.outcome="DENY"
- 쿼리 실행을 클릭합니다.
-
적용된 정책의 이름이 쿼리 결과 창의
jsonPayload.enforcedSecurityPolicy.name
에 표시됩니다.
-
해결 방법
이 문제를 해결하려면 사용자의 요구사항에 맞춰 Google Cloud Armor 규칙/구성을 수정합니다. 이와 관련된 지원이 필요하면 Google Cloud Customer Care에 문의하세요.
원인: Apigee 프록시 VM은 트래픽을 Apigee 인스턴스로 전달할 수 없음
진단
-
API 클라이언트에서 다음 오류 메시지와 함께
HTTP 502
오류를 수신하면 Apigee API 트래픽 라우터 프록시 VM이 비정상 상태일 수 있습니다.다음과 같은
502
오류가 클라이언트에 수신될 수 있습니다.<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>502 Server Error</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Server Error</h1> <h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2> <h2></h2> </body></html>
부하 분산기 로그에서 다음과 같은 오류 메시지를 검토합니다.
statusDetails: "failed_to_pick_backend" severity: "WARNING"
트래픽을 Apigee 인스턴스로 전달하는 관리형 인스턴스 그룹(MIG)에서 실행되는 VM 집합(
apigee-proxy
프리픽스 포함)이 있습니다. 위와 같은 메시지가 표시되면 다음 단계를 통해 인스턴스 그룹에 속하는apigee-proxy
VM의 상태를 확인합니다.-
Google Cloud 콘솔에서 부하 분산 페이지로 이동합니다.
-
부하 분산기 이름을 클릭합니다. 부하 분산기 세부정보 페이지가 열립니다.
-
백엔드 섹션에서 모든 부하 분산기 백엔드의 정상 열에 녹색 체크표시가 있는지 확인합니다.
-
-
MIG 템플릿의 엔드포인트 IP 주소가 Apigee 인스턴스 IP 주소와 일치하는지 확인합니다.
apigee-proxy
VM은 인스턴스 템플릿을 사용하여 생성됩니다. 템플릿은 Apigee 인스턴스 IP 주소에 연결하기 위한ENDPOINT
IP 주소를 정의합니다.-
Apigee 인스턴스 IP 주소를 가져옵니다.
curl -s -H "Authorization: Bearer (gcloud auth print-access-token)" \ "https://apigee.googleapis.com/v1/organizations/ORG_NAME/instances/INSTANCE_NAME"
다음을 바꿉니다.
-
ORG_NAME: 조직의 이름. 예를 들면
my-org
입니다. -
INSTANCE_NAME: 인스턴스의 이름. 예를 들면
apigee-proxy-example
입니다.
-
ORG_NAME: 조직의 이름. 예를 들면
-
또는 Apigee UI를 사용하여 Apigee 인스턴스 IP 주소를 가져옵니다.
- Apigee UI에서 관리자 > 인스턴스를 클릭합니다.
-
IP 주소 열에 IP 주소가 나열됩니다.
-
템플릿에서
ENDPOINT
IP 주소를 가져옵니다.-
Google Cloud 콘솔에서 부하 분산 페이지로 이동합니다.
- 부하 분산기 이름을 클릭합니다. 부하 분산기 세부정보 페이지가 열립니다.
- 백엔드 영역에서 백엔드 서비스 이름을 클릭합니다.
-
인스턴스 그룹 구성원 영역에서 템플릿 이름을 클릭합니다.
-
템플릿 페이지에서 ENDPOINT IP 주소가 표시될 커스텀 메타데이터로 스크롤합니다.
-
ENDPOINT IP 주소가 2단계에서 반환된 Apigee IP 주소와 일치하는지 확인합니다. 일치하지 않으면 해결 방법으로 이동합니다.
-
Apigee 인스턴스 IP 주소를 가져옵니다.
해결 방법
-
인스턴스 그룹의
apigee-proxy
VM에 비정상 상태가 표시된 경우 부하 분산 IP 주소 범위130.211.0.0/22
및35.191.0.0/16
에서 MIG에 액세스할 수 있는 방화벽 규칙이 있는지 확인합니다. -
Google Cloud 콘솔에서 방화벽 페이지로 이동합니다.
-
443 TCP
포트를 통해gke-apigee-proxy
와 같은target-tag
와130.211.0.0/22
및35.191.0.0/16
과 같은 소스 IP 범위를 가진 인그레스 방화벽 규칙이 있는지 확인하세요.MIG에
gke-apigee-proxy
와 다른 태그가 있는 경우 태그가 방화벽 규칙의target-tag
에 추가되었는지 확인합니다.방화벽 규칙이 없으면 추가합니다.
- ENDPOINT IP 주소가 Apigee 인스턴스 IP 주소와 일치하지 않는 경우 인스턴스가 삭제되고 다시 생성되었을 수 있으며, 이로 인해 IP 주소가 더 이상 템플릿의 IP 주소와 일치하지 않게 됩니다. 새 IP 주소를 사용하도록 템플릿을 업데이트하려면 인스턴스 IP 변경의 안내를 따릅니다.
원인: 잘못된 네트워크 구성
진단
-
다음 API 호출을 실행하여
authorizedNetwork
값을 찾습니다.curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/ORG_NAME"
다음과 비슷한 결과가 반환됩니다.
{ "name": "apigee-example-org", "createdAt": "1621287579456", "lastModifiedAt": "1674063833580", "environments": [ "test" ], "properties": { "property": [ { "name": "features.mart.connect.enabled", "value": "true" }, { "name": "features.hybrid.enabled", "value": "true" } ] }, "analyticsRegion": "us-west1", "authorizedNetwork": "default", "runtimeType": "CLOUD", "subscriptionType": "PAID", "caCertificate": "certificate-number", "runtimeDatabaseEncryptionKeyName": "projects/apigee-example-org/locations/us-west1/keyRings/my-database-key-ring/cryptoKeys/my-database-key", "projectId": "apigee-example-org", "state": "ACTIVE", "billingType": "SUBSCRIPTION", "addonsConfig": { "advancedApiOpsConfig": {}, "integrationConfig": {}, "monetizationConfig": {} }, "apigeeProjectId": "l09587a43efde330cp-tp" }
이 예시에서는
authorizedNetwork
값이 기본값입니다. -
authorizedNetwork
값이servicenetworking
과 피어링된 네트워크와 동일한지 확인합니다.-
호스트 프로젝트의 Google Cloud 콘솔에서 VPC 네트워크 피어링 페이지로 이동합니다.
-
내 VPC 네트워크의
servicenetworking-googleapis-com
에 나열된 값은 API 호출에서 반환된 값과 동일해야 합니다. 예를 들면default
입니다.
-
-
공유 VPC를 사용하는 경우
authorizedNetwork
값에servicenetworking
과 피어링된 호스트 프로젝트의 실제 VPC 값이 있는지 확인합니다.-
Google Cloud 콘솔에서 공유 VPC 페이지로 이동합니다.
- 호스트 프로젝트를 선택합니다.
-
내 VPC 네트워크의
servicenetworking-googleapis-com
에 나열된 값은 API 호출에서 반환된authorizedNetwork
값과 동일해야 합니다. 예를 들면default
입니다.
-
-
부하 분산기에 연결된 인스턴스 그룹이
authorizedNetwork
값과 동일한 네트워크인지 확인합니다.-
Google Cloud 콘솔에서 부하 분산 페이지로 이동합니다.
-
부하 분산기 이름을 클릭합니다. 부하 분산기 세부정보 페이지가 열립니다. 백엔드 영역에 인스턴스 그룹 목록이 표시됩니다.
- 인스턴스 그룹 이름을 클릭합니다. 인스턴스 그룹 개요 페이지가 표시됩니다.
- 세부정보 탭을 클릭합니다.
-
네트워킹 섹션으로 스크롤합니다.
-
여기에서 기본 네트워크가
authorizedNetwork
값과 동일한지 확인합니다. 예를 들면default
입니다. - 개요 탭을 클릭합니다.
- 인스턴스 그룹 구성원 섹션에서 인스턴스 이름을 클릭합니다. 세부정보 페이지가 표시됩니다.
-
네트워크 인터페이스 섹션으로 스크롤합니다.
-
네트워크 값이
authorizedNetwork
값과 동일한지 확인합니다. 예를 들면default
입니다. - 개요 탭으로 이동하여 인스턴스 그룹 구성원 섹션의 모든 인스턴스에 대해 h 단계부터 j 단계까지 반복합니다.
-
해결 방법
-
2단계 또는 3단계에서
authorizedNetwork
값이servicenetworking
과 피어링된 네트워크와 동일하지 않은 경우 4단계: 서비스 네트워킹 구성의 단계에 따라servicenetworking
과 올바른 VPC 네트워크를 피어링했는지 확인하세요. -
4f 및 4j 단계에서 네트워크 값이
authorizedNetwork
값과 동일하지 않은 경우authorizedNetwork
가servicenetworking.
과 피어링된 네트워크인지 확인합니다. 올바르게 피어링되었지만 네트워크가 여전히authorizedNetwork,
와 동일하지 않은 경우 이는 인스턴스 그룹이 잘못 생성되었음을 의미하므로 Google Cloud Customer Care에 문의해야 합니다.
원인: 리전 확장의 일부로 생성된 새 Apigee 인스턴스의 연결되지 않은 환경
진단
-
클라이언트 측에
503
오류가 표시됩니다. 예를 들면 다음과 같습니다.HTTP/2 503 date: Thu, 08 Jun 2023 07:22:15 GMT content-length: 0 via: 1.1 google alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
-
리전 확장 직후 두 번째 리전에
503
오류가 표시되는 경우:-
다음 API 호출을 실행하여 환경이 새 인스턴스에 연결되었는지 확인합니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/instances/NEW_INSTANCE/attachments"
예를 들면 다음과 같습니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/apigee-example-org/instances/apigee-proxy-example/attachments"
다음과 비슷한 결과가 반환됩니다.
{ "attachments": [ { "name": "9ed157df-5ef2-4cdc-b1d5-2643b480eb33", "environment": "dev", "createdAt": "1628153855420" }, { "name": "a9e04dff-4ca4-4749-902f-5058e28c26a5", "environment": "prod", "createdAt": "1664517347106" } ] }
이 예시에서
apigee-proxy-example
이라는 인스턴스는dev
및prod
라는 두 환경에 연결됩니다. -
두 번째 리전의 관리형 인스턴스 그룹(MIG)이 만들어지고 정상으로 표시되는지 확인합니다.
-
Google Cloud 콘솔에서 부하 분산 페이지로 이동합니다.
- 부하 분산기 이름을 클릭합니다. 부하 분산기 세부정보 페이지가 열립니다.
-
백엔드에 리전 1용 MIG와 리전 2용 MIG가 표시됩니다. 둘 다 정상인지 확인합니다.
- Apigee 프록시 VM은 트래픽을 Apigee 인스턴스로 전달할 수 없음의 단계에 따라 두 번째 MIG의 유효성을 검사합니다.
-
-
다음 API 호출을 실행하여 환경이 새 인스턴스에 연결되었는지 확인합니다.
해결 방법
-
새 인스턴스가 환경에 연결되지 않은 경우 새 인스턴스에 환경 연결의 안내에 따라 인스턴스를 환경에 연결합니다.
또 다른 옵션은 부하 분산기가 환경이 이미 연결된 올바른 백엔드로 요청을 라우팅하는지 확인하는 것입니다. 비프로덕션 환경을 예로 들어 보겠습니다. 한 리전에만 이를 연결하려고 했는데 부하 분산기가 요청을 잘못된 리전으로 라우팅하는 경우가 있을 수 있습니다. 올바른 리전으로 라우팅되도록 하려면 부하 분산기 구성을 업데이트해야 합니다.
- MIG가 비정상인 경우 Apigee 프록시 VM은 트래픽을 Apigee 인스턴스로 전달할 수 없음에서 진단 및 해결 방법을 참조하세요.
진단 정보 수집 필요
위 안내를 따른 후에도 문제가 지속되면 다음 진단 정보를 수집한 후 Google Cloud Customer Care에 문의하세요.
- Apigee 조직
- 문제가 발생한 환경 및 API 프록시
- 다운로드한 디버그 세션(문제가 간헐적인 경우)
- 실패한 요청의 상세 curl 출력
- Apigee로 API 호출을 보내도록 구성된 부하 분산기