이 페이지는 Apigee에 적용되지만 Apigee Hybrid에는 적용되지 않습니다.
Apigee Edge 문서 보기
이 페이지에서는 Kubernetes용 Apigee APIM Operator 문제를 해결하는 방법을 설명합니다. 발생할 수 있는 문제를 해결하는 데 사용할 수 있는 도구가 많이 있습니다. 이 페이지에서는 커스텀 리소스 상태를 확인하고 로그 탐색기를 사용하고 Apigee 런타임 트래픽과 관련된 문제를 해결하는 방법을 설명합니다.
커스텀 리소스 상태 확인
Kubernetes용 Apigee APIM Operator에 사용되는 모든 커스텀 리소스에는 두 필드가 있는 상태 객체가 포함됩니다.
- STATE: 리소스의 상태를 설명합니다. 값은
running,created입니다. - ERRORMESSAGE: 리소스 작업이 실패하면 오류 메시지 필드에 설명 메시지가 표시됩니다.
커스텀 리소스 yaml 파일이 클러스터에 적용되면 Kubernetes에서 기본 인프라를 이에 맞게 변경합니다. 커스텀 리소스의 상태 객체를 확인하면 리소스의 상태를 파악할 수 있으며, 기본 인프라 작업이 실패할 경우 발생하는 오류를 확인할 수 있습니다.
다음 명령어를 사용하여 커스텀 리소스 상태를 확인할 수 있습니다.
kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME
각 항목의 의미는 다음과 같습니다.
NAMESPACE: 커스텀 리소스가 배포되는 네임스페이스입니다.CUSTOM_RESOURCE_KIND: 커스텀 리소스 종류입니다.CUSTOM_RESOURCE_NAME: 커스텀 리소스의 이름입니다.
예를 들어 다음 명령어는 apim 네임스페이스에서 apim-extension-policy라는 APIMExtensionPolicy 커스텀 리소스의 상태를 확인합니다.
kubectl -n apim get APIMExtensionPolicy apim-extension-policy-1
출력은 다음과 비슷합니다.
NAME STATE ERRORMESSAGE apim-extension-policy Create_Update_Failed Permission denied
로그 보기
이 섹션에서는 로그를 사용하여 Google Kubernetes Engine(GKE) 게이트웨이 리소스 및 APIM Operator 리소스의 문제를 해결하는 방법을 설명합니다.
GKE 게이트웨이 로그
APIMExtensionPolicy를 적용하면 클러스터에서 만든 GKE 게이트웨이가 트래픽 확장 프로그램으로 구성됩니다.
이 확장 프로그램은 Kubernetes 외부 처리(ext-proc)를 사용하여 Apigee 런타임 및 프로세스 정책을 호출합니다.
ext-proc 트래픽과 관련된 로그는 문제를 해결할 때 유용할 수 있습니다.
ext-proc 콜아웃 로그 보기
ext-proc 콜아웃 트래픽의 로그를 보려면 다음 단계를 따르세요.
- Apigee 런타임용으로 생성된 백엔드 서비스의 ID를 가져옵니다.
kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"
여기서
GATEWAY_NAME은 GKE 게이트웨이 이름입니다.백엔드 서비스의 ID에
apigee-service-extension-backend-service가 포함됩니다. - 백엔드 서비스에 로깅 사용 설정 단계를 수행하여 로깅을 사용 설정합니다.
- Google Cloud 콘솔에서 로그를 보려면 로그 탐색기 페이지로 이동합니다.
-
백엔드 서비스의 로그 메시지를 검토하여
service_extension_info부하 분산기 로그 항목의 JSON 페이로드 구조를 비롯한 사용 가능한 호출 로그 항목 정보를 확인하세요. 로그 탐색기의 검색 필드를 사용하여 관련 정보를 필터링할 수 있습니다.다음은 실패한
ext-proc콜아웃에 대해 표시될 수 있는 로그 항목의 예시입니다.{ "insertId": "s14dmrf10g6hi", "jsonPayload": { "serviceExtensionInfo": [ { "extension": "ext11", "perProcessingRequestInfo": [ { "eventType": "REQUEST_HEADERS", "latency": "0.001130s" } ], "backendTargetType": "BACKEND_SERVICE", "grpcStatus": "ABORTED", "backendTargetName": "gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh", "chain": "chain1", "resource": "projects/$PROJECT_ID/locations/us-west1/lbTrafficExtensions/apim-extension" } ], "backendTargetProjectNumber": "projects/763484362408", "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry" }, "httpRequest": { ... }, "resource": { "type": "internal_http_lb_rule", "labels": { ... } }, "timestamp": "2024-04-01T20:15:15.182137Z", "severity": "INFO", "logName": "projects/$PROJECT_ID/logs/loadbalancing.googleapis.com%2Frequests", "receiveTimestamp": "2024-04-01T20:15:18.209706689Z" }grpcStatus필드에ABORTED가 표시됩니다.
APIM Operator 로그
APIM Operator는 APIM 커스텀 리소스 이벤트(예: 생성, 읽기, 업데이트, 삭제)를 처리하고 적절한 Apigee 구성에서 이러한 이벤트를 변환하는 Kubernetes 연산자입니다.
APIM Operator의 로그를 보려면 다음 단계를 따르세요.
- Google Cloud 콘솔에서 로그를 보려면 로그 탐색기 페이지로 이동합니다.
- 쿼리 창에 다음과 유사한 쿼리를 입력합니다.
resource.type="k8s_container" resource.labels.namespace_name="apim" labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
- 쿼리 실행을 클릭합니다.
- 필터링된 로그 항목이 쿼리 결과 창에 표시됩니다.
- Google Cloud 네트워크 서비스에서
APIMExtensionPolicy생성, 업데이트 또는 삭제와 관련된 문제나 Apigee 관리 영역의 API 제품과 관련된 문제를 기록합니다.오류의 예시는 다음과 유사하게 나타납니다.
ApimExtensionPolicy creation status400 response body:{ "error": { "code": 400, "message": "The request was invalid: backend service https://www.googleapis.com/compute/v1/projects/... must use HTTP/2 as the protocol", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "fieldViolations": [ { "field": "lb_traffic_extension.extension_chains[0].extensions[0].service" } ] }, { "@type": "type.googleapis.com/google.rpc.RequestInfo", "requestId": "d4e6f00ab5d367ec" } ] } }
APIM Operator에서 403 액세스 오류 문제 해결
액세스 문제를 나타내는 상태 코드 403 오류가 발견되면 다음을 확인하세요.
- GKE 클러스터에는 워크로드 아이덴티티 제휴가 사용 설정되어 있습니다. Autopilot 모드로 만든 클러스터에는 워크로드 아이덴티티 제휴가 기본적으로 사용 설정되어 있습니다. 표준 모드를 사용하여 클러스터를 만든 경우 표준 클러스터를 사용할 때 GKE용 워크로드 아이덴티티 제휴 사용 설정의 설명대로 워크로드 아이덴티티 제휴를 사용 설정합니다.
- Kubernetes 서비스 계정(
apim-ksa)이 Helm 설치에 의해 올바르게 주석 처리됩니다. 다음 명령어를 실행하여 이를 확인할 수 있습니다.kubectl describe serviceaccount apim-ksa -n NAMESPACE
여기서 NAMESPACE는 APIM Operator가 배포된 네임스페이스입니다.
출력의 주석 필드에
apigee-apim-gsa@$PROJECT.iam.gserviceaccount.com가 표시되는지 확인합니다.예를 들면 다음과 같습니다.
kubectl describe serviceaccount apim-ksa -n apim
출력은 다음과 유사합니다. 이름: apim-ksa 네임스페이스: apim 라벨: ... 주석: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... 이미지 가져오기 보안 비밀:
마운트 가능한 보안 비밀: 토큰: 이벤트: apigee-apim-gsa서비스 계정에 올바른 IAM 역할과 권한이 있습니다. 다음 명령어를 사용하여 이를 확인할 수 있습니다.gcloud iam service-accounts get-iam-policy \ apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com
서비스 계정에
roles/iam.workloadIdentityUser역할이 있어야 합니다.예를 들어 다음 출력은
roles/iam.workloadIdentityUser역할을 보여줍니다.bindings: - members: - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa] role: roles/iam.workloadIdentityUser etag: BwYUpeaM7XQ= version: 1
- 필요한 역할에 연산자의 액세스를 차단하는 특별한 IAM 조건이 없습니다.
Apigee 런타임 트래픽 문제 해결
이 섹션에서는 Apigee 런타임 트래픽과 관련된 문제를 해결하는 방법을 설명합니다. 다음 섹션에서는 유효한 요청 및 잘못된 요청과 관련된 문제를 해결하는 방법을 설명합니다.
유효한 요청 실패
Apigee 런타임에 유효한 요청을 전송할 수 없는 경우 다음과 같은 문제가 있을 수 있습니다.
- GKE 게이트웨이가 Apigee 런타임에 도달할 수 없습니다.
- API 키 또는 JWT 사용자 인증 정보가 잘못되었습니다.
- Apigee API 제품이 올바른 대상 및 환경에 맞게 구성되지 않았습니다.
- Apigee 런타임에서 Apigee API 제품을 인식하지 못합니다.
문제 해결 단계
유효한 요청과 관련된 문제를 해결하려면 다음 단계를 따르세요.
- GKE 게이트웨이에 부하 분산기 로그를 사용 설정하고 로그를 검토하여 확장 프로그램 콜아웃에서 실패의 원인을 파악합니다. 자세한 내용은 GKE 게이트웨이 로그를 참조하세요.
- ext-proc 서비스에서 참조된 백엔드 서비스가 정상인지 확인합니다.
- Apigee에서 API 제품 구성을 검토합니다.
- API 제품이 올바른 환경(예:
test또는prod)에 사용 설정되어 있는지 확인합니다. - 리소스 경로가 요청과 일치하는지 확인합니다.
/또는/**와 같은 경로는 모든 경로와 일치합니다. 일치에*또는**와일드 카드를 사용할 수도 있습니다. - API 제품에 개발자 앱이 구성되어 있는지 확인합니다. API 키를 검증하려면 API 제품이 개발자 앱에 바인딩되어야 합니다.
- API 제품이 올바른 환경(예:
- 게이트웨이에 대한 요청을 검토합니다.
- 고객 키가
x-api-key헤더에 전달되는지 확인합니다. - 고객 키가 유효한지 확인합니다. 개발자 앱의 사용자 인증 정보가 API 제품에 승인되어야 합니다.
- 고객 키가
잘못된 요청이 성공함
Apigee 런타임에 대한 잘못된 요청이 성공하면 다음과 같은 문제가 있을 수 있습니다.
FailOpen은 APIMExtensionPolicy에서true로 설정됩니다.- GKE 게이트웨이 부하 분산기에 설정된 트래픽 확장 프로그램이 없습니다.
문제 해결 단계
잘못된 요청과 관련된 문제를 해결하려면 다음 단계를 따르세요.
- 서비스 확장 프로그램이 존재하고 GKE 게이트웨이의 올바른 백엔드 서비스 및 전달 규칙을 참조하는지 확인합니다.
다음 명령어를 사용하여 서비스 확장 프로그램을 확인합니다.
gcloud beta service-extensions lb-traffic-extensions describe NAME_OF_APIM_EXTENSION_POLICY --location=LOCATION --project=PROJECT
각 항목의 의미는 다음과 같습니다.
NAME_OF_APIM_EXTENSION_POLICY:APIMExtensionPolicy커스텀 리소스 이름입니다.PROJECT: 프로젝트 ID입니다.LOCATION: 게이트웨이가 배포된 GKE 클러스터의 위치입니다.
출력은 다음과 비슷하게 표시됩니다.
... extensionChains: - extensions: - authority: ext11.com failOpen: false # make sure this is false name: ext11 service: https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/backendServices/gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh # Confirm this is correct supportedEvents: - REQUEST_HEADERS - RESPONSE_HEADERS - REQUEST_BODY - RESPONSE_BODY - REQUEST_TRAILERS - RESPONSE_TRAILERS timeout: 0.100s matchCondition: celExpression: 'true' # Confirm this is set name: chain1 forwardingRules: - https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/forwardingRules/gkegw1-2y13-default-internal-http-h6c1hhp1ce6q # Confirm this is the correct forwarding rule for your application load balancer loadBalancingScheme: INTERNAL_MANAGED name: projects/my-project/locations/us-west1/lbTrafficExtensions/apim-extension-policy-1분석 누락됨
Google Cloud 콘솔에서 APIM Operator에 대한 Apigee API 애널리틱스를 볼 수 없으면 Apigee 처리가 몇 분 지연될 수 있습니다.
추가 리소스
다음 리소스를 사용하여 APIM Operator 및 Apigee 런타임 트래픽 문제를 해결할 수도 있습니다.