이 페이지는 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}/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}/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
- 쿼리 실행을 클릭합니다.
- 필터링된 로그 항목이 쿼리 결과 창에 표시됩니다.
APIMExtensionPolicyGoogle Cloud 네트워크 서비스 생성, 업데이트 또는 삭제와 관련된 문제나 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}.iam.gserviceaccount.com
서비스 계정에
roles/iam.workloadIdentityUser역할이 있어야 합니다.예를 들어 다음 출력은
roles/iam.workloadIdentityUser역할을 보여줍니다.bindings: - members: - serviceAccount:${PROJECT}.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 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 런타임 트래픽 문제를 해결할 수도 있습니다.