9장. API 인프라 문제 해결

이 가이드는 API 인프라 문제의 원인을 확인하고 수정하는 데 도움이 됩니다.

API 인프라는 길고 복잡한 주제입니다. 그러나 최소한 다음 세 가지 이동 부분은 인프라에서 보유하게 됩니다.

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

이러한 세 가지 요소 중 하나에서 오류가 발생하면 API 소비자가 API에 액세스할 수 없습니다. 그러나 오류가 발생한 구성 요소를 찾는 것은 어렵습니다. 이 가이드에서는 문제를 식별하기 위한 몇 가지 팁을 제공합니다.

다음 섹션을 사용하여 발생할 수 있는 일반적인 문제를 식별하고 해결합니다.

9.1. 일반적인 통합 문제

3scale과의 통합과 관련하여 몇 가지 매우 일반적인 문제를 가리킬 수 있는 몇 가지 증거가 있습니다. 이는 API 프로젝트를 시작했는지, 인프라를 설정했는지 또는 이미 운영 중인 운영 환경에 따라 달라질 수 있습니다.

9.1.1. 통합 문제

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

9.1.1.1. APIcast 호스팅

Service Integration(서비스 통합) 화면에서 먼저 API를 APIcast와 통합하려는 경우 페이지에 표시되거나 테스트 호출에서 반환하여 통합에 성공했는지 확인하는 몇 가지 오류가 발생할 수 있습니다.

  • 테스트 요청 실패: 실행 만료

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

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

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

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

    • 405: 엔드포인트에서 GET 요청을 수락하는지 확인합니다. APIcast는 통합을 테스트하기 위해 GET 요청만 지원합니다.
    • 403: 인증 매개변수 누락: API에 이미 일부 인증이 있는 경우 APIcast에서 테스트 요청을 할 수 없습니다.
    • 403: 인증 실패: 3scale을 사용하여 만든 첫 번째 서비스가 아닌 경우 테스트 요청을 수행하기 위해 자격 증명을 사용하여 서비스 아래에 애플리케이션을 생성했는지 확인합니다. 통합 중인 첫 번째 서비스인 경우 가입 시 생성한 테스트 계정이나 애플리케이션을 삭제하지 않았는지 확인합니다.

9.1.1.2. APIcast 자체 관리

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

  • 업스트림 시간 초과(110: 연결 시간이 초과되었습니다) 업스트림에 연결하는 동안

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

  • 서비스 목록을 가져오지 못했습니다: 잘못된 상태: 403 (제외됨)

      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 값에서 사용한 액세스 토큰이 올바른지 그리고 Account Management API 범위가 있는지 확인합니다. curl 명령으로 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을 구성한 후 다음을 수행합니다.

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

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

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

9.1.2. 프로덕션 문제

설정을 완전히 테스트하고 잠시 API와 함께 실행한 후 API 게이트웨이에 문제가 발생하는 것은 드뭅니다. 그러나 실시간 프로덕션 환경에서 발생할 수 있는 몇 가지 문제는 다음과 같습니다.

9.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 게이트웨이 구성 파일은 매번 IP 확인을 강제 적용하는 변수로 3scale을 정의합니다. 빠른 수정을 위해 NGINX 인스턴스를 다시 로드합니다. 장기적인 수정을 위해 업스트림 블록에서 3scale 백엔드를 정의하지 않고 각 서버 블록 내에서 변수로 정의합니다. 예:

    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 확인자를 설정합니다. 확인자 8.8.8.8 8.8.4.4;.
      2. 서버 섹션의 상단에서 API 기본 URL을 변수로 설정합니다. $api_base "http://api.example.com:80"를 설정합니다.
      3. 위치 / 섹션에서 proxy _pass 행을 찾아 proxy _ pass $api_base; 로 바꿉니다.

9.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 여행의 모든 단계에서 발생할 수 있는 가장 일반적인 잘 알려진 문제에 대한 개요를 제공합니다.

이러한 모든 사항이 확인되어 문제에 대한 원인과 해결 방법을 찾을 수 없는 경우 API 요청 문제 식별에 대한 자세한 섹션을 진행해야 합니다. API에서 시작하고 실패 지점을 식별하기 위해 클라이언트로 돌아가십시오.