7장. 문제 해결


이 가이드에서는 API 인프라의 문제를 식별하고 해결하는 데 도움이 되는 것을 목표로 합니다.

API 인프라는 길고 복잡한 주제입니다. 그러나 최소한 인프라에는 세 가지 이동 부분이 있습니다.

  1. API 게이트웨이
  2. 3scale
  3. API
3scale 게이트웨이 흐름도

이러한 세 가지 요소에 오류가 발생하면 클라이언트가 API에 액세스할 수 없습니다. 그러나 오류를 발생시킨 구성 요소를 찾기가 어렵습니다. 이 가이드에서는 문제를 식별하기 위해 인프라 문제를 해결할 수 있는 몇 가지 팁을 제공합니다.

7.1. 일반적인 문제

3scale과의 통합과 관련된 몇 가지 일반적인 문제를 가리킬 수 있는 몇 가지 증거가 있습니다. 이는 API 프로젝트 시작, 인프라 설정 또는 이미 프로덕션 단계에 있는지에 따라 달라집니다.

7.1.1. 통합 문제

다음 섹션에서는 3scale과의 통합 초기 단계에서 APIcast 오류 로그에 표시될 수 있는 몇 가지 일반적인 문제를 간략하게 설명합니다. 시작 시 APIcast Hosted를 사용하기 전에 자체 관리 APIcast를 실행합니다.

7.1.1.1. APIcast 호스팅

Service Integration 화면에서 API를 APIcast Hosted와 처음 통합할 때 페이지에 표시되는 다음 오류 중 일부가 표시되거나 테스트 호출에 반환되어 성공적인 통합을 확인할 수 있습니다.

  • 테스트 요청에 실패했습니다: 실행이 만료됨

    공용 인터넷에서 API에 연결할 수 있는지 확인합니다. APIcast Hosted는 프라이빗 API와 함께 사용할 수 없습니다. API를 APIcast Hosted와 통합할 수 있도록 공개하지 않으려면 APIcast Hosted와 API 간에 개인 시크릿을 설정하여 API 게이트웨이에서 가져오지 않는 호출을 거부할 수 있습니다.

  • 허용된 형식은 'protocol://address(:port)'입니다.

    API 개인 기본 URL 끝에 있는 모든 경로를 제거합니다. "mapping rules" 패턴 또는 API 테스트 GET 요청의 시작 부분에 추가할 수 있습니다.

  • HTTP 코드 XXX로 테스트 요청에 실패했습니다.

    • 405: 끝점이 GET 요청을 수락하는지 확인합니다. APIcast는 통합을 테스트하기 위한 GET 요청만 지원합니다.
    • 403: 인증 매개변수가 누락됨: API에 이미 일부 인증이 있는 경우 APIcast는 테스트 요청을 수행할 수 없습니다.
    • 403: 인증에 실패했습니다. 3scale로 생성한 첫 번째 서비스가 아닌 경우 인증 정보를 사용하여 애플리케이션을 생성했는지 확인하여 테스트 요청을 수행합니다. 통합할 첫 번째 서비스인 경우 등록 시 생성한 테스트 계정 또는 애플리케이션을 삭제하지 않았는지 확인하십시오.

7.1.1.2. APIcast 자체 관리

APIcast 자체 관리와의 통합을 성공적으로 테스트한 후 API 게이트웨이를 직접 호스팅할 수 있습니다. 다음은 자체 관리 게이트웨이를 처음 설치하고 이를 통해 API를 호출할 때 발생할 수 있는 몇 가지 오류입니다.

  • 업스트림에 연결하는 동안 업스트림 시간 초과(연결 시간 초과)

    자체 관리 게이트웨이가 3scale에 도달하지 못하도록 API 게이트웨이와 공용 인터넷 사이에 방화벽 또는 프록시가 없는지 확인합니다.

  • 서비스 목록을 가져올 수 없음: 잘못된 상태: 403 (Forbidden)

      2018/06/04 08:04:49 [emerg] 14#14: [lua] configuration_loader.lua:134: init(): failed to load configuration,   exiting (code 1)
      2018/06/04 08:04:49 [warn] 22#22: *2 [lua] remote_v2.lua:163: call(): failed to get list of services:   invalid status: 403 (Forbidden) url: https://example-admin.3scale.net/admin/api/services.json , context:   ngx.timer
      ERROR: /opt/app-root/src/src/apicast/configuration_loader.lua:57: missing configuration

    THREESCALE_PORTAL_ENDOINT 값에서 사용한 액세스 토큰이 올바르고 계정 관리 API 범위가 있는지 확인합니다. curl -v "https://example-admin.3scale.net/admin/api/services.json?access_token=<YOUR_ACCESS_TOKEN>"을 사용하여 확인합니다.

    JSON 본문이 포함된 200 응답을 반환해야 합니다. 오류 상태 코드를 반환하는 경우 응답 본문에서 세부 정보를 확인합니다.

  • 호스트 apicast.example.com에 대한 서비스를 찾을 수 없음

      2018/06/04 11:06:15 [warn] 23#23: *495 [lua] find_service.lua:24: find_service(): service not found for host apicast.example.com, client: 172.17.0.1, server: _, request: "GET / HTTP/1.1", host: "apicast.example.com"

    이 오류는 Public Base URL이 제대로 구성되지 않았음을 나타냅니다. 구성된 Public Base URL이 자체 관리 APIcast 요청에 사용하는 것과 동일한지 확인해야 합니다. 올바른 공용 기본 URL을 구성한 후 다음을 수행합니다.

    • "production"으로 APIcast가 구성되었는지 확인합니다( THREESCALE_DEPLOYMENT_ENV 변수로 재정의하지 않는 경우 독립 실행형 APIcast의 기본 구성). 구성을 프로덕션으로 승격해야 합니다.
    • APICAST_CONFIGURATION_CACHEAPICAST_CONFIGURATION_LOADER 환경 변수를 사용하여 구성 자동 로드를 구성하지 않은 경우 APIcast를 다시 시작합니다.

다음은 잘못된 APIcast 자체 관리 통합을 가리킬 수 있는 몇 가지 다른 증상입니다.

  • API 호출이 일치하지 않는 매핑 규칙: API 에서 메서드와 실제 URL 끝점 간의 매핑을 정의한 방식에 따라 메서드가 일치하지 않거나 요청당 한 번 이상 증가되는 경우가 있음을 알 수 있습니다. 이 문제를 해결하려면 3scale 디버그 헤더 를 사용하여 API를 테스트하십시오. 그러면 API 호출과 일치하는 모든 메서드 목록이 반환됩니다.
  • 인증 매개변수를 찾을 수 없음: 서비스 통합 화면에 지정된 대로 매개변수를 올바른 위치로 전송했는지 확인합니다. 자격 증명을 헤더로 보내지 않으면 인증 정보를 다른 모든 HTTP 메서드의 GET 요청 및 본문 매개변수에 대한 쿼리 매개변수로 보내야 합니다. 3scale 디버그 헤더를 사용하여 API 게이트웨이에서 요청에서 읽을 수 있는 인증 정보를 다시 확인합니다.

7.1.2. 프로덕션 문제

설정을 완전히 테스트한 후 잠시 동안 API 게이트웨이에서 발생하는 문제가 발생하지 않는 경우가 많습니다. 그러나 라이브 프로덕션 환경에서 발생할 수 있는 몇 가지 문제는 다음과 같습니다.

7.1.2.1. 가용성 문제

가용성 문제는 일반적으로 nginx error.log의 업스트림 시간 초과 오류로 표시됩니다. 예를 들면 다음과 같습니다.

upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"

간헐적인 3scale 가용성 문제가 발생하는 경우 다음과 같은 이유가 있을 수 있습니다.

  • 더 이상 사용되지 않는 이전 3scale IP로 확인 중입니다.

    API 게이트웨이 구성 파일의 최신 버전은 3scale을 변수로 정의하여 매번 IP 확인을 강제 적용합니다. 빠른 수정을 위해 NGINX 인스턴스를 다시 로드합니다. 장기 수정의 경우 업스트림 블록에서 3scale 백엔드를 정의하는 대신 각 server 블록 내에서 변수로 정의합니다.

    server {
      # Enabling the Lua code cache is strongly encouraged for production use. Here it is enabled
      .
      .
      .
      set $threescale_backend "https://su1.3scale.net:443";

    이를 언급할 때:

    location = /threescale_authrep {
      internal;
      set $provider_key "YOUR_PROVIDER_KEY";
    
      proxy_pass $threescale_backend/transactions/authrep.xml?provider_key=$provider_key&service_id=$service_id&$usage&$credentials&log%5Bcode%5D=$arg_code&log%5Brequest%5D=$arg_req&log%5Bresponse%5D=$arg_resp;
    }
  • 허용 목록에서 일부 3scale IP가 누락되어 있습니다. 다음은 3scale이 확인하는 현재 IP 목록입니다.

    • 75.101.142.93
    • 174.129.235.69
    • 184.73.197.122
    • 50.16.225.117
    • 54.83.62.94
    • 54.83.62.186
    • 54.83.63.187
    • 54.235.143.255

      위의 문제는 3scale 가용성에 대한 문제를 나타냅니다. 그러나 API가 AWS ELB 뒤에 있는 경우 API 게이트웨이에서 API 가용성과 유사한 문제가 발생할 수 있습니다. 이는 NGINX가 기본적으로 시작 시 DNS 확인을 수행한 다음 IP 주소를 캐시하기 때문입니다. 그러나 ELB는 고정 IP 주소를 확인하지 않으며 자주 변경될 수 있습니다. ELB가 다른 IP로 변경될 때마다 NGINX에 연결할 수 없습니다.

      이에 대한 솔루션은 런타임 DNS 확인을 강제 적용하기 위한 위의 수정 사항과 유사합니다.

      1. http 섹션의 상단에 이 행을 추가하여 Google DNS와 같은 특정 DNS 확인자를 설정합니다. resolver 8.8.8.8.8.4.4;.
      2. API 기본 URL을 server 섹션 상단에 있는 변수로 설정합니다. set $api_base "http://api.example.com:80";
      3. location / section에서 proxy_pass 행을 찾아서 proxy_pass $api_base 로 바꿉니다.

7.1.3. 배포 후 문제

새 엔드포인트 추가와 같은 API를 변경하는 경우 API 게이트웨이의 새 구성 파일 세트를 다운로드하기 전에 새 메서드 및 URL 매핑을 추가해야 합니다.

3scale에서 다운로드한 구성을 수정할 때 가장 일반적인 문제는 Lua의 코드 오류이며 다음과 같은 500 - 내부 서버 오류가 발생합니다.

curl -v -X GET "http://localhost/"
* About to connect() to localhost port 80 (#0)
*   Trying 127.0.0.1... connected
> GET / HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: localhost
> Accept: */*
>
< HTTP/1.1 500 Internal Server Error
< Server: openresty/1.5.12.1
< Date: Thu, 04 Feb 2016 10:22:25 GMT
< Content-Type: text/html
< Content-Length: 199
< Connection: close
<

<head><title>500 Internal Server Error</title></head>

<center><h1>500 Internal Server Error</h1></center>
<hr><center>openresty/1.5.12.1</center>


* Closing connection #0

nginx error.log에서 다음과 같은 원인을 알 수 있습니다.

2016/02/04 11:22:25 [error] 8980#0: *1 lua entry thread aborted: runtime error: /home/pili/NGINX/troubleshooting/nginx.lua:66: bad argument #3 to '_newindex' (number expected, got nil)
stack traceback:
coroutine 0:
  [C]: in function '_newindex'
  /home/pili/NGINX/troubleshooting/nginx.lua:66: in function 'error_authorization_failed'
  /home/pili/NGINX/troubleshooting/nginx.lua:330: in function 'authrep'
  /home/pili/NGINX/troubleshooting/nginx.lua:283: in function 'authorize'
  /home/pili/NGINX/troubleshooting/nginx.lua:392: in function  while sending to client, client: 127.0.0.1, server: api-2445581381726.staging.apicast.io, request: "GET / HTTP/1.1", host: "localhost"

access.log에서 다음과 같이 표시됩니다.

127.0.0.1 - - [04/Feb/2016:11:22:25 +0100] "GET / HTTP/1.1" 500 199 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"

위의 섹션에서는 3scale 이동의 모든 단계에서 발생할 수 있는 가장 일반적인 잘 알려진 문제에 대한 개요를 제공합니다.

이러한 모든 항목이 확인되었으며 여전히 문제에 대한 원인 및 솔루션을 찾을 수 없는 경우 아래의 보다 자세한 [operational troubleshooting](#troubleshooting-checklists) 섹션으로 진행해야 합니다. API에서 시작하고 실패 지점을 식별할 수 있도록 클라이언트로 다시 작업합니다.

Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

© 2024 Red Hat, Inc.