12장. API 인프라 문제 해결
이 가이드에서는 API 인프라의 문제의 원인을 식별하고 해결하는 데 도움이 됩니다.
API 인프라는 길고 복잡한 주제입니다. 그러나 최소한 인프라 내에서 이동하는 세 가지 부분이 있습니다.
- API 게이트웨이
- 3scale
- API
이 세 요소 중 하나에서 오류가 발생하면 API 소비자가 API에 액세스할 수 없습니다. 그러나 오류를 일으킨 구성 요소를 찾기가 어렵습니다. 이 가이드에서는 문제를 식별하는 데 필요한 몇 가지 팁을 제공합니다.
다음 섹션을 사용하여 발생할 수 있는 일반적인 문제를 식별하고 해결합니다.
12.1. 공통 통합 문제 링크 복사링크가 클립보드에 복사되었습니다!
3scale과의 통합과 매우 일반적인 문제를 가리킬 수 있는 몇 가지 증거가 있습니다. 이는 API 프로젝트 시작, 인프라 설정 또는 이미 프로덕션 상태에 있는지 여부에 따라 달라집니다.
12.1.1. 통합 문제 링크 복사링크가 클립보드에 복사되었습니다!
다음 섹션에서는 3scale과의 통합 초기 단계에서 APIcast 오류 로그에 표시될 수 있는 몇 가지 일반적인 문제를 설명하려고 합니다. APIcast 호스팅을 사용하기 전에 APIcast 호스팅을 사용하기 전에 셀프 관리 APIcast를 실행하여 APIcast 호스팅을 사용하기 시작합니다.
12.1.1.1. APIcast 호스트 링크 복사링크가 클립보드에 복사되었습니다!
Service Integration 화면에서 APIcast 호스팅과 APIcast 호스팅을 처음 통합하는 경우 페이지에 표시되거나 테스트 호출에서 반환된 몇 가지 오류가 성공적으로 통합되는지 확인할 수 있습니다.
테스트 요청 실패: 실행이 만료됨
공용 인터넷에서 API에 연결할 수 있는지 확인합니다. APIcast Hosted는 개인 API와 함께 사용할 수 없습니다. APIcast Hosted와 통합하기 위해 APIcast Hosted와 공개적으로 API를 공개하지 않으려면 APIcast Hosted와 API 게이트웨이에서 발생하지 않는 모든 호출을 거부하도록 APIcast Hosted와 개인 시크릿을 설정할 수 있습니다.
허용되는 형식은
protocol://address(:port)
입니다.API 개인 기본 URL 끝에 있는 경로를 제거합니다. 이러한 규칙은 "mapping rules" 패턴 또는 API 테스트 GET 요청 시작 부분에 추가할 수 있습니다.
테스트 요청이 HTTP 코드 XXX로 실패했습니다.
-
405
: 끝점이 GET 요청을 수락하는지 확인합니다. APIcast는 통합을 테스트하기 위해 GET 요청만 지원합니다. -
403: 인증 매개 변수가 누락
됨 : API에 이미 인증이 있는 경우 APIcast는 테스트 요청을 할 수 없습니다. -
403: authentication failed: 이 서비스가 3scale로 생성한 첫 번째 서비스가 아닌 경우 테스트 요청을 할 수 있는 인증
정보가 있는 서비스에서 애플리케이션을 생성했는지 확인합니다. 통합 중인 첫 번째 서비스인 경우 등록 시 생성한 테스트 계정 또는 애플리케이션을 삭제하지 않았는지 확인하십시오.
-
12.1.1.2. APIcast 자체 관리 링크 복사링크가 클립보드에 복사되었습니다!
APIcast 자체 관리와의 통합을 성공적으로 테스트한 후 API 게이트웨이를 직접 호스팅할 수 있습니다. 다음은 자체 관리 게이트웨이를 설치하고 이를 통해 API를 호출할 때 발생할 수 있는 몇 가지 오류입니다.
업스트림에 연결하는 동안 (110: 연결 시간 초과)
자체 관리 게이트웨이가 3scale에 도달하지 못하도록 API 게이트웨이와 공용 인터넷 사이에 방화벽 또는 프록시가 없는지 확인합니다.
서비스 목록 가져오기 실패: invalid status: 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
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
Copy to Clipboard Copied! Toggle word wrap Toggle overflow THREESCALE_PORTAL_ENDOINT
값에서 사용한 액세스 토큰이 올바르고 계정 관리 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"
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"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 이 오류는 Public Base URL이 올바르게 구성되지 않았음을 나타냅니다. 구성된 Public Base URL이 자체 관리 APIcast에 대한 요청에 사용하는 것과 동일한지 확인해야 합니다. 올바른 공개 기본 URL을 구성한 후 다음을 수행하십시오.
-
APIcast가 "production"(
THREESCALE_DEPLOYMENT_ENV
변수로 재정의되지 않은 경우 독립 실행형 APIcast의 기본 구성)에 대해 구성되어 있는지 확인합니다. 구성을 프로덕션으로 승격하는지 확인합니다. -
APIcast를 재시작합니다.
APICAST_CONFIGURATION_CACHE
및APICAST_CONFIGURATION_LOADER
환경 변수를 사용하여 구성 자동 로드를 구성하지 않은 경우 APIcast를 다시 시작합니다.
-
APIcast가 "production"(
다음은 잘못된 APIcast 자체 관리 통합을 가리키는 몇 가지 다른 증상입니다.
- API 호출의 매핑 규칙과 일치하지 않음 : API의 실제 URL 끝점과 메서드 간의 매핑을 정의한 방식에 따라 요청마다 일치되거나 증가하지 않는 방법을 찾을 수 있습니다. 이 문제를 해결하려면 3scale debug 헤더 를 사용하여 API를 테스트 호출하십시오. 이렇게 하면 API 호출과 일치하는 모든 메서드 목록이 반환됩니다.
- 인증 매개 변수를 찾을 수 없음: 서비스 통합 화면에 지정된 대로 매개 변수를 올바른 위치로 보내고 있는지 확인합니다. 자격 증명을 헤더로 보내지 않으면 자격 증명을 GET 요청 및 기타 모든 HTTP 메서드에 대한 쿼리 매개변수로 보내야 합니다. 3scale 디버그 헤더를 사용하여 API 게이트웨이의 요청에서 읽은 자격 증명을 두 번 확인합니다.
12.1.2. 프로덕션 문제 링크 복사링크가 클립보드에 복사되었습니다!
설정을 완전히 테스트한 후 API 게이트웨이에서 문제가 발생하지 않으며 잠시 API로 사용 중입니다. 그러나 라이브 프로덕션 환경에서 발생할 수 있는 몇 가지 문제는 다음과 같습니다.
12.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"
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 백엔드를 정의하는 대신 각 서버 블록 내에서 변수로 정의하십시오. 예:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 이를 참조할 때:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 화이트리스트에서 일부 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 확인을 강제 적용하는 데 위의 수정 사항과 유사합니다.
-
http
섹션 상단에 이 행을 추가하여 Google DNS와 같은 특정 DNS 확인자를 설정합니다.리졸버 8.8.8.4.4;
. -
API 기본 URL을
server
섹션 상단에 있는 변수로 설정합니다.set $api_base "http://api.example.com:80";
-
위치 /
섹션에서proxy_pass
행을 찾아proxy_pass $api_base
로 바꿉니다.
-
12.1.3. 배포 후 문제 링크 복사링크가 클립보드에 복사되었습니다!
새 끝점 추가와 같이 API를 변경하는 경우 API 게이트웨이에 대한 새로운 구성 파일 세트를 다운로드하기 전에 새 메서드 및 URL 매핑을 추가해야 합니다.
3scale에서 다운로드한 구성을 수정한 가장 일반적인 문제는 Lua에서 코드 오류가 발생하여 다음과 같은 500 내부 서버 오류가 발생합니다
.
nginx error.log가 다음과 같은 원인을 알 수 있습니다.
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"
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에서 시작하여 오류 발생 지점을 확인하기 위해 다시 클라이언트로 작업하십시오.