API 게이트웨이
설치를 관리하기 위한 고급 목표에 중간.
초록
Red Hat 문서에 관한 피드백 제공 링크 복사링크가 클립보드에 복사되었습니다!
문서 개선을 위한 의견에 감사드립니다.
개선 사항을 제안하려면 Jira 문제를 열고 제안된 변경 사항을 설명합니다. 귀하의 요청을 신속하게 처리할 수 있도록 가능한 한 자세한 정보를 제공하십시오.
사전 요구 사항
- Red Hat 고객 포털 계정이 있어야 합니다. 이 계정을 사용하면 Red Hat Jira Software 인스턴스에 로그인할 수 있습니다. 계정이 없는 경우 계정을 생성하라는 메시지가 표시됩니다.
절차
- 다음 링크를 클릭합니다. 문제 생성.
- 요약 텍스트 상자에 문제에 대한 간략한 설명을 입력합니다.
설명 텍스트 상자에 다음 정보를 입력합니다.
- 문제를 발견한 페이지의 URL입니다.
-
문제에 대한 자세한 설명입니다.
다른 필드에 있는 정보는 기본값에 따라 그대로 둘 수 있습니다.
- 생성 을 클릭하여 Jira 문제를 문서 팀에 제출합니다.
피드백을 제공하기 위해 시간을 내어 주셔서 감사합니다.
API Gateway는 3scale 설치에 중간에서 고급 구성 기능을 적용하는 데 도움이 됩니다. 설치에 대한 기본 내용은 3scale 설치를 참조하십시오.
I 부. API 게이트웨이 링크 복사링크가 클립보드에 복사되었습니다!
1장. Docker 컨테이너 환경 운영 링크 복사링크가 클립보드에 복사되었습니다!
1.1. Docker 컨테이너 환경에서 APIcast 문제 해결 링크 복사링크가 클립보드에 복사되었습니다!
이 섹션에서는 Docker 컨테이너 환경에서 APIcast로 작업할 때 찾을 수 있는 가장 일반적인 문제에 대해 설명합니다.
1.1.1. Docker 데몬 오류에 연결할 수 없음 링크 복사링크가 클립보드에 복사되었습니다!
docker: Cannot connect to the Docker daemon. docker 데몬이 이 호스트에서 실행 중입니까? 오류 메시지는 Docker 서비스가 시작되지 않았기 때문일 수 있습니다. sudo systemctl status docker.service 명령을 실행하여 Docker 데몬의 상태를 확인할 수 있습니다.
Docker 컨테이너 환경에서는 기본적으로 RHEL에서 root 권한이 필요하므로 이 명령을 root 사용자로 실행해야 합니다. 자세한 내용은 여기에서참조하십시오.
1.1.2. 기본 Docker 명령줄 인터페이스 명령 링크 복사링크가 클립보드에 복사되었습니다!
분리 모드(-d 옵션)에서 컨테이너를 시작하고 실행 중인 APIcast 인스턴스의 로그를 확인하려면 log 명령인 sudo docker logs <container >를 사용할 수 있습니다. 여기서 <container >는 컨테이너 이름(위 예제의"apicast" 또는 컨테이너 ID)입니다. sudo docker ps 명령을 사용하여 실행 중인 컨테이너 및 해당 ID 및 이름 목록을 가져올 수 있습니다.
컨테이너를 중지하려면 sudo docker stop <container> 명령을 실행합니다. sudo docker rm <container> 명령을 실행하여 컨테이너를 제거할 수도 있습니다.
사용 가능한 명령에 대한 자세한 내용은 Docker 명령 참조를 참조하십시오.
2장. 고급 APIcast 구성 링크 복사링크가 클립보드에 복사되었습니다!
이 섹션에서는 스테이징 환경에서 3scale API 게이트웨이의 고급 설정 옵션에 대해 설명합니다.
2.1. 시크릿 토큰 정의 링크 복사링크가 클립보드에 복사되었습니다!
보안상의 이유로 3scale 게이트웨이에서 API 백엔드로의 모든 요청에는 X-3scale-proxy-secret-token 이라는 헤더가 포함되어 있습니다. Integration 페이지의 인증 설정에서 이 헤더의 값을 설정할 수 있습니다.
시크릿 토큰을 설정하면 프록시와 API 간의 공유 시크릿 역할을 하여 게이트웨이에서 제공되지 않는 모든 API 요청을 차단할 수 있습니다. 샌드박스 게이트웨이로 트래픽 관리 정책을 설정하는 동안 공용 끝점을 보호하는 추가 보안 계층을 추가합니다.
API 백엔드에는 게이트웨이가 작동할 공개 확인 가능한 도메인이 있어야 API 백엔드를 알고 있는 모든 사용자가 인증 정보 검사를 바이패스할 수 있습니다. 스테이징 환경의 API 게이트웨이는 프로덕션용이 아니라 펜싱을 사용할 수 있는 것이 더 좋기 때문에 문제가 되지 않아야 합니다.
2.2. 인증 정보 링크 복사링크가 클립보드에 복사되었습니다!
user_key,app_key, client_secret 필드에 대한 최대 길이 및 예약된 문자의 필드 제한 사항이 있습니다.
5자에서 256자 사이의 영숫자 [0-9, a-z, A-Z], 하이픈 마이너스 (-) 만 가능합니다. 허용된 공간도 없습니다.
또한 app_id 및 client_id 는 최대 140자 길이를 갖습니다.
3scale 내의 API 자격 증명은 사용 중인 인증 모드에 따라 user_key 또는 app_id/app_key 입니다. OpenID Connect는 스테이징 환경의 API 게이트웨이에 유효하지만 통합 페이지에서는 테스트할 수 없습니다.
그러나 API에서 다른 인증 정보 이름을 사용할 수 있습니다. 이 경우 API 키 모드를 사용하는 경우 user_key 의 사용자 지정 이름을 설정해야 합니다.
또는 app_id 및 app_key 의 경우 :
예를 들어, API에 더 적합한 경우 app_id 를 키로 변경할 수 있습니다. 게이트웨이는 3scale 백엔드에 대한 권한 부여 호출을 수행하기 전에 name 키 를 사용하여 app_id 로 변환합니다. 새 인증 정보 이름은 영숫자여야 합니다.
API가 HTTP 기본 인증 형식 또는 쿼리 매개변수(GET) 또는 본문 매개변수(POST/PUT/DELETE)로 인증 정보를 전달하는지 여부를 결정할 수 있습니다.
APIcast는 인증 정보를 추출할 때 헤더 이름을 정규화합니다. 즉, 대소문자를 구분하지 않으며 밑줄과 하이픈은 동일하게 처리됩니다. 예를 들어 App Key 매개 변수를 App_Key 로 설정하면 app-key 와 같은 다른 값도 유효한 앱 키 헤더로 승인됩니다.
2.3. 오류 메시지 구성 링크 복사링크가 클립보드에 복사되었습니다!
이 섹션에서는 APIcast 오류 메시지를 구성하는 방법에 대해 설명합니다.
프록시로 3scale APIcast는 다음과 같은 방식으로 요청을 관리합니다.
- 오류가 없는 경우 APIcast는 클라이언트에서 API 백엔드 서버로 요청을 전달하고 수정 없이 API 응답을 클라이언트에 반환합니다. 응답을 수정하려면 헤더 수정 정책을 사용할 수 있습니다.
-
404 Not Found또는400ECDHE Request와 같은 오류 메시지로 API가 응답하는 경우 APIcast에서 메시지를 클라이언트에 반환합니다. 그러나 APIcast에서인증 누락과 같은 다른 오류를 감지하면 APIcast에서 오류 메시지를 보내고 요청을 종료합니다.
따라서 APIcast에서 반환되는 다음 오류 메시지를 구성할 수 있습니다.
인증이 실패했습니다
이 오류는 잘못된 인증 정보로 인해 또는 애플리케이션이 일시적으로 일시 중단되어도 API 요청에 유효한 인증 정보가 포함되어 있지 않음을 의미합니다. 또한 이 오류는 메트릭이 비활성화될 때 생성되며, 이는 값이
0입니다.인증이 누락됨
이 오류는 API 요청에 인증 정보가 포함되지 않을 때마다 생성됩니다. 사용자가 API 요청에 자격 증명을 추가하지 않으면 발생합니다.
일치하지 않음
이 오류는 요청이 매핑 규칙과 일치하지 않아 메트릭이 업데이트되지 않음을 의미합니다. 이는 반드시 오류가 발생하지는 않지만 사용자가 임의의 경로를 시도하거나 매핑 규칙이 적법한 사례를 다루지 않음을 의미합니다.
사용량 제한 초과
이 오류는 클라이언트가 요청된 엔드포인트의 속도 제한에 도달했음을 의미합니다. 요청이 여러 매핑 규칙과 일치하는 경우 클라이언트가 두 개 이상의 속도 제한에 도달할 수 있습니다.
오류를 구성하려면 다음 단계를 따르십시오.
- [gradle_product_name] > Integration > Settings에서 이동합니다.
- 게이트웨이 응답 에서 구성할 오류 유형을 선택합니다.
이러한 필드의 값을 지정합니다.
- 응답 코드: 세 자리 HTTP 응답 코드입니다.
-
content-type:
Content-Type헤더의 값입니다. - response body: 응답 메시지 본문의 값입니다.
- 변경 사항을 저장하려면 제품 업데이트를 클릭합니다.
2.4. 구성 내역 링크 복사링크가 클립보드에 복사되었습니다!
APIcast로 v.[n]를 클릭하면 마다 [n] 은 버전 번호를 나타내며 현재 구성이 JSON 파일에 저장됩니다. 스테이징 게이트웨이는 새 요청마다 최신 구성을 가져옵니다. 각 환경, 스테이징 또는 프로덕션에 대해 이전 구성 파일의 기록을 확인할 수 있습니다.
- [gradle_product_name] > Integration > Configuration에서 이동합니다.
- 관심 있는 환경 옆에 있는 Configuration history 링크를 클릭합니다.
이전 버전으로 자동 롤백할 수 없습니다. 대신 관련 JSON 파일이 있는 모든 구성 버전의 기록에 액세스할 수 있습니다. 이러한 파일을 사용하여 언제든지 배포한 구성을 확인합니다. 원하는 경우 모든 배포를 수동으로 다시 생성할 수 있습니다.
2.5. 디버깅 링크 복사링크가 클립보드에 복사되었습니다!
게이트웨이 구성을 설정하는 것은 쉽지만 여전히 오류가 발생할 수 있습니다. 이러한 경우 게이트웨이는 유용한 디버그 정보를 반환하여 오류를 추적할 수 있습니다.
APIcast에서 디버깅 정보를 가져오려면 도달 중인 API 서비스에 해당하는 서비스 토큰과 함께 API 요청에 다음 헤더를 추가해야 합니다. X-3scale-debug: {SERVICE_TOKEN}.
헤더가 확인되고 서비스 토큰이 유효하면 게이트웨이는 응답 헤더에 다음 정보를 추가합니다.
X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
x-3scale-matched-rules 는 쉼표로 구분된 목록으로 요청에 대한 매핑 규칙이 일치함을 나타냅니다.
X-3scale-credentials 헤더는 3scale 백엔드에 전달된 인증 정보를 반환합니다.
x-3scale-usage 는 3scale 백엔드에 보고된 사용량을 나타냅니다. usage%5Bversion_1%5D=1&usage%5Bword%5D=1 은 URL로 인코딩된 usage[version_1]=1&usage[word]=1 이며, API 요청이 메서드(metrics) version_1 을 증가시키고 1번까지 단어를 도달했음을 보여줍니다.
2.6. 경로 라우팅 링크 복사링크가 클립보드에 복사되었습니다!
APIcast는 3scale 계정에 구성된 모든 API 서비스(또는 APICAST_SERVICES_LIST 환경 변수가 구성된 경우 서비스의 서브 세트)를 처리합니다. 일반적으로 APIcast는 Public Base URL 과 일치시켜 요청의 호스트 이름을 기반으로 API 요청을 적절한 API 서비스로 라우팅합니다. 일치가 확인된 첫 번째 서비스는 권한 부여에 사용됩니다.
경로 라우팅 기능을 사용하면 여러 서비스에서 동일한 공개 기본 URL 을 사용할 수 있으며 요청 경로를 사용하여 요청을 라우팅할 수 있습니다. 기능을 활성화하려면 APICAST_PATH_ROUTING 환경 변수를 true 또는 1 로 설정합니다. 활성화하면 APIcast는 호스트 이름과 경로를 기반으로 들어오는 요청을 서비스에 매핑합니다.
이 기능은 동일한 Public Base URL 을 사용하여 하나의 게이트웨이를 통해 다른 도메인에 호스팅되는 여러 백엔드 서비스를 노출하려는 경우 사용할 수 있습니다. 이를 위해 각 API 백엔드(예: Private Base URL )에 대해 여러 API 서비스를 구성하고 경로 라우팅 기능을 활성화할 수 있습니다.
예를 들어 다음과 같은 방식으로 3개의 서비스가 구성됩니다.
-
Service는 공개 기본 URL:
api.example.com매핑 규칙:/a -
Service B Public Base URL:
api.example.com매핑 규칙:/b -
Service C Public Base URL:
api.example.com매핑 규칙:/c
경로 라우팅이 비활성화 된 경우(APICAST_PATH_ROUTING=false)에 대한 모든 호출은 서비스 A.example.com과 일치하려고 합니다. 따라서 및 api.example.com api.example.com/b 호출은 "No Mapping Rule matched" 오류와 함께 실패합니다.
경로 라우팅이 활성화되면 (APICAST_PATH_ROUTING=true) 호출이 호스트 및 경로와 일치합니다. 예를 들면 다음과 같습니다.
-
api.example.com/a는 서비스 A로 라우팅됩니다. -
api.example.com/c는 서비스 C로 라우팅됩니다. -
API.example2.com/b는 "No Mapping Rule matched" 오류와 함께 실패합니다. 즉, Public Base URL 이 일치하지 않기 때문에 서비스 B와 일치하지 않습니다.
경로 라우팅을 사용하는 경우 동일한 공개 기본 URL 을 사용하는 다른 서비스의 매핑 규칙 간에 충돌이 없는지 확인해야 합니다. 즉, 메서드 + 경로 패턴의 각 조합은 하나의 서비스에서만 사용됩니다.
3장. APIcast 정책 링크 복사링크가 클립보드에 복사되었습니다!
APIcast 정책은 APIcast 작동 방식을 수정하는 기능 단위입니다. 정책을 활성화, 비활성화 및 구성하여 APIcast 수정 방법을 제어할 수 있습니다. 정책을 사용하여 기본 APIcast 배포에서 사용할 수 없는 기능을 추가합니다. 자체 정책을 생성하거나 Red Hat 3scale에서 제공하는 표준 정책을 사용할 수 있습니다.
다음 주제에서는 표준 APIcast 정책에 대한 정보를 제공하고, 정책 체인을 생성하며, 사용자 정의 APIcast 정책을 생성합니다.
3.1. 기본 3scale API Management APIcast 동작을 변경하는 표준 정책 링크 복사링크가 클립보드에 복사되었습니다!
3scale은 APIcast 요청 및 응답을 처리하는 방법을 수정하는 기능 단위인 기본 제공 표준 정책을 제공합니다. APIcast 수정 방법을 제어하도록 정책을 활성화, 비활성화 또는 구성할 수 있습니다.
자세한 내용은 3scale 관리 포털에서 정책 활성화를 참조하십시오. 3scale은 다음과 같은 표준 정책을 제공합니다.
- 3scale API Management Auth Caching
- 3scale API Management Batcher
- 3scale API Management Referrer
- 익명 액세스
- Camel 서비스
- 조건부 정책
- 콘텐츠 캐싱
- CORS 요청 처리
- 사용자 정의 메트릭
- echo
- 엣지 제한
- 헤더 수정
- HTTP 상태 코드 덮어쓰기
- HTTP2 Endpoint
- IP 확인
- JWT 클레임 확인
- 유동적인 컨텍스트 디버그
- 로깅
- 유지 관리 모드
- NGINX 필터
- OAuth 2.0 상호 TLS 클라이언트 인증
- OAuth 2.0 토큰 인트로스펙션
- On Fail
- 프록시 서비스
- 속도 제한 헤더
- 응답 요청 콘텐츠 제한
- Retry
- rh-SSO/Keycloak 역할 검사
- 라우팅
- SOAP
- TLS 클라이언트 인증서 검증
- TLS 종료
- 업스트림
- 업스트림 연결
- 업스트림 상호 TLS
- URL 재작성
- 캡처를 사용하여 URL 재작성
- WebSocket
3.1.1. 3scale API Management 관리 포털에서 정책 활성화 링크 복사링크가 클립보드에 복사되었습니다!
관리 포털에서 각 3scale API 제품에 대해 하나 이상의 정책을 활성화할 수 있습니다.
사전 요구 사항
- 3scale API 제품입니다.
절차
- 3scale에 로그인합니다.
- 관리 포털 대시보드에서 정책을 활성화할 API 제품을 선택합니다.
- [your_product_name] 에서 통합 > 정책으로 이동합니다.
-
POLICIES 섹션에서
정책 추가를클릭합니다. - 추가할 정책을 선택하고 필수 필드에 값을 입력합니다.
- Update Policy Chain 을 클릭하여 정책 체인을 저장합니다.
3.1.2. 3scale API Management 인증 캐싱 링크 복사링크가 클립보드에 복사되었습니다!
항상 정책 체인의 APIcast 정책 앞에 auth 캐싱 정책을 배치합니다.
3scale 인증 캐싱 정책은 APIcast에 대한 인증 호출을 캐시합니다. 운영 모드를 선택하여 캐시 작업을 구성할 수 있습니다.
3scale 인증 캐싱은 다음과 같은 모드에서 사용할 수 있습니다.
1. Strict - 인증된 호출만 캐시합니다.
"제한" 모드는 권한이 부여된 호출만 캐시합니다. 정책이 "제한" 모드로 실행되고 호출이 실패하거나 거부되는 경우 정책은 캐시 항목을 무효화합니다. 백엔드에 연결할 수 없는 경우 캐시된 상태에 관계없이 캐시된 모든 호출이 거부됩니다.
2. 복원력 - 백엔드가 중단될 때 마지막 요청에 따라 인증합니다.
"Resilient" 모드는 인증된 호출과 거부된 호출을 모두 캐시합니다. 정책이 "resilient" 모드에서 실행 중인 경우 실패한 호출은 기존 캐시 항목을 무효화하지 않습니다. 백엔드에 연결할 수 없는 경우 캐시에 도달한 호출은 캐시된 상태에 따라 계속 인증되거나 거부됩니다.
3. allow - 백엔드가 다운되면 이전 및 거부되지 않는 한 모든 것을 허용합니다.
"Allow" 모드는 권한이 부여된 호출과 거부된 호출을 모두 캐시합니다. 정책이 "허용" 모드에서 실행 중인 경우 캐시된 호출은 캐시된 상태에 따라 계속 거부되거나 허용됩니다. 그러나 새 호출은 권한 부여로 캐시됩니다.
"허용" 모드에서 작동하면 보안에 영향을 미칩니다. "allow" 모드를 사용할 때 다음과 같은 의미와 동작을 고려하십시오.
4. none - 캐싱을 비활성화합니다.
"없음" 모드에서는 캐싱을 비활성화합니다. 이 모드는 정책을 활성 상태로 유지하되 캐싱을 사용하지 않으려는 경우에 유용합니다.
구성 속성
| 속성 | description | 값 | 필수 여부 |
|---|---|---|---|
| caching_type |
| 데이터 유형: 열거된 문자열 [resilient, strict, allow, none] | 제공됨 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 생성 섹션을 참조하십시오.
3.1.3. 3scale API Management Batcher 링크 복사링크가 클립보드에 복사되었습니다!
3scale Batcher 정책은 APIcast가 수신하는 각 API 요청에 대해 3scale 백엔드(Service Management API)에 대한 하나의 호출을 수행하는 표준 APIcast 권한 부여 메커니즘에 대한 대안을 제공합니다.
이 정책을 사용하려면 정책 체인의 3scale APIcast 정책 앞에 3scale Batcher 를 배치해야 합니다.
3scale Batcher 정책은 권한 부여 상태 및 배치 사용 보고서를 캐시하므로 3scale 백엔드에 대한 요청 수를 크게 줄일 수 있습니다. 3scale Batcher 정책을 사용하면 대기 시간을 줄이고 처리량을 높여 APIcast 성능을 향상시킬 수 있습니다.
3scale Batcher 정책이 활성화되면 APIcast는 다음 권한 부여 흐름을 사용합니다.
각 요청에서 정책은 인증 정보가 캐시되었는지 확인합니다.
- 자격 증명이 캐시되면 정책은 3scale 백엔드를 호출하는 대신 캐시된 권한 부여 상태를 사용합니다.
- 인증 정보가 캐시되지 않으면 정책은 백엔드를 호출하고 구성 가능한 Time to Live(TTL)로 권한 부여 상태를 캐시합니다.
- 3scale 백엔드 요청에 해당하는 사용량을 즉시 보고하는 대신, 정책은 사용 카운터를 누적하여 일괄 처리로 백엔드에 보고합니다. 별도의 스레드는 누적된 사용 카운터를 구성 가능한 빈도와 함께 단일 호출로 3scale 백엔드에 보고합니다.
3scale Batcher 정책은 정확도가 감소하면서 처리량을 개선합니다. 사용량 제한과 현재 사용률은 3scale에 저장되며 APIcast는 3scale 백엔드를 호출할 때만 올바른 권한 부여 상태를 가져올 수 있습니다. 3scale Batcher 정책이 활성화되면 APIcast가 3scale에 호출을 보내지 않는 기간이 있습니다. 이 기간 동안 호출을 수행하는 애플리케이션은 정의된 제한을 통과할 수 있습니다.
속도 제한의 정확성보다 처리량이 더 중요한 경우 높은 로드 API에 대해 이 정책을 사용합니다. 3scale Batcher 정책은 보고 빈도 및 권한 TTL이 속도 제한 기간보다 훨씬 적은 경우 정확도 측면에서 더 나은 결과를 제공합니다. 예를 들어 하루에 제한이 있고 보고 빈도 및 권한 부여 TTL이 몇 분으로 구성된 경우입니다.
3scale Batcher 정책은 다음과 같은 구성 설정을 지원합니다.
auths_ttl: 권한 부여 캐시가 만료될 때 TTL을 초 단위로 설정합니다.-
현재 호출에 대한 인증이 캐시되면 APIcast는 캐시된 값을 사용합니다.
auths_ttl매개변수에 설정된 시간이 지나면 APIcast에서 캐시를 제거하고 3scale 백엔드를 호출하여 권한 부여 상태를 검색합니다. -
auths_ttl매개변수를0이 아닌 값으로 설정합니다.auths_ttl을0으로 설정하면 요청이 캐시될 때 권한 부여 카운터가 업데이트되어 속도 제한이 적용되지 않습니다.
-
현재 호출에 대한 인증이 캐시되면 APIcast는 캐시된 값을 사용합니다.
-
batch_report_seconds: APIcast가 3scale 백엔드로 보내는 일괄 보고서 빈도를 설정합니다. 기본값은10초입니다.
3.1.4. 3scale API Management Referrer 링크 복사링크가 클립보드에 복사되었습니다!
3scale Referrer 정책에서는 Referrer Filtering 기능을 활성화합니다. 서비스 정책 체인에서 정책이 활성화되면 APIcast는 3scale Referrer 정책 값을 서비스 관리 API 에 upwards AuthRep 호출로 보냅니다. 3scale Referrer 정책의 값은 호출의 참조 매개변수로 전송됩니다.
참조 필터링이 작동하는 방법에 대한 자세한 내용은 인증 패턴 아래의 참조 필터링 섹션을 참조하십시오.
3.1.5. 익명 액세스 링크 복사링크가 클립보드에 복사되었습니다!
익명 액세스 정책은 인증 없이 서비스를 노출합니다. 예를 들어 인증 매개 변수를 전송하도록 조정할 수 없는 레거시 애플리케이션에 유용할 수 있습니다. 익명 액세스 정책은 API 키 및 앱 ID / 앱 키 인증 옵션이 있는 서비스를 지원합니다. 인증 정보가 제공되지 않은 API 요청에 대해 정책이 활성화되면 APIcast는 정책에 구성된 기본 인증 정보를 사용하여 호출을 승인합니다. API 호출을 승인하려면 구성된 인증 정보가 있는 애플리케이션이 존재하고 활성 상태여야 합니다.
애플리케이션 계획을 사용하여 기본 인증 정보에 사용되는 애플리케이션의 속도 제한을 구성할 수 있습니다.
정책 체인에서 이러한 두 정책을 함께 사용할 때 APIcast 정책 앞에 익명 액세스 정책을 배치해야 합니다.
다음은 정책에 필요한 구성 속성입니다.
auth_type
아래 대안 중 하나에서 값을 선택하고 속성이 API에 대해 구성된 인증 옵션에 해당하는지 확인합니다.
app_id_and_app_key
App ID / 앱 키 인증 옵션의 경우
user_key
API 키 인증 옵션의 경우
app_id ( app_id_and_app_key 인증 유형 전용)
API 호출과 함께 제공되는 인증 정보가 없는 경우 권한 부여에 사용할 애플리케이션의 앱 ID입니다.
app_key ( app_id_and_app_key 인증 유형 전용)
API 호출과 함께 제공되는 인증 정보가 없는 경우 권한 부여에 사용할 애플리케이션의 앱 키입니다.
user_key ( user_key auth_type만 해당)
API 호출과 함께 제공되는 인증 정보가 없는 경우 권한 부여에 사용할 애플리케이션의 API 키입니다.
그림 3.1. 익명 액세스 정책
3.1.6. Camel 서비스 링크 복사링크가 클립보드에 복사되었습니다!
Camel 서비스 정책을 사용하여 3scale 트래픽이 정의된 Apache Camel 프록시를 통해 전송되는 HTTP 프록시를 정의할 수 있습니다. 이 경우 Camel은 역방향 HTTP 프록시로 작동하며 APIcast에서 트래픽을 Camel로 보낸 다음 Camel에서 트래픽을 API 백엔드로 보냅니다.
다음 예제에서는 트래픽 흐름을 보여줍니다.
3scale 백엔드로 전송된 모든 APIcast 트래픽은 Camel 프록시를 사용하지 않습니다. 이 정책은 Camel 프록시와 APIcast와 API 백엔드 간의 통신에만 적용됩니다.
프록시를 통해 모든 트래픽을 보내려면 HTTP_PROXY 환경 변수를 사용해야 합니다.
- Camel 서비스 정책은 도메인 이름이 여러 IP 주소로 확인되면 로드 밸런싱 업스트림의 APIcast 기능을 비활성화합니다. Camel 서비스는 업스트림 서비스의 DNS 확인을 관리합니다.
-
HTTP_PROXY,HTTPS_PROXY또는ALL_PROXY매개변수가 정의된 경우 이 정책은 해당 값을 덮어씁니다. - 프록시 연결은 인증을 지원하지 않습니다. 인증을 위해 헤더 수정 정책을 사용합니다.
설정
다음 예제에서는 정책 체인 구성을 보여줍니다.
all_proxy 값은 http_proxy 또는 https_proxy 가 정의되지 않은 경우 사용됩니다.
사용 사례 예
Camel 서비스 정책은 Apache Camel을 사용하여 3scale에서 보다 세분화된 정책과 변환을 적용하도록 설계되었습니다. 이 정책은 Apache Camel over HTTP 및 HTTPS와의 통합을 지원합니다. 자세한 내용은 5장. Fuse의 정책 확장을 사용하여 3scale API Management 메시지 콘텐츠 변환 에서 참조하십시오.
일반 HTTP 프록시 정책 사용에 대한 자세한 내용은 3.1.25절. “프록시 서비스” 을 참조하십시오.
프로젝트 예
GitHub의 Camel 프록시 정책에서 사용 가능한 camel-netty-proxy 예제를 참조하십시오. 이 예제 프로젝트는 응답 본문을 API 백엔드에서 대문자로 변환하는 HTTP 프록시를 보여줍니다.
3.1.7. 조건부 정책 링크 복사링크가 클립보드에 복사되었습니다!
조건 정책은 정책 체인을 포함하므로 다른 APIcast 정책과 다릅니다. 각 nginx 단계에서 평가되는 조건을 정의합니다(예: 액세스,다시 작성,로그 등). 조건이 true이면 조건 정책은 체인에 포함된 각 정책에 대해 해당 단계를 실행합니다.
APIcast 조건부 정책은 기술 프리뷰 기능 전용입니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다. Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.
다음 예제에서는 조건 정책이 다음 조건을 정의한다고 가정합니다. 요청 방법은 POST입니다.
이 경우 요청이 POST 인 경우 각 단계의 실행 순서는 다음과 같습니다.
- APIcast
- 캐싱
- headers
- URL 재작성
- 업스트림
요청이 POST 가 아닌 경우 각 단계의 실행 순서는 다음과 같습니다.
- APIcast
- 캐싱
- 업스트림
조건
조건부 정책 체인에서 정책을 실행할지 여부를 결정하는 조건은 JSON 을 사용하여 표현하고 유동성 템플릿을 사용합니다.
이 예에서는 요청 경로가 /example_path 인지 여부를 확인합니다.
왼쪽 및 오른쪽 피연산자는 모두 유해한 문자열 또는 일반 문자열로 평가될 수 있습니다. 일반 문자열이 기본값입니다.
작업을 및 또는 결합할 수 있습니다. 이 구성은 이전 예제와 동일하게 확인되고 또는 와백엔드 헤더의 값이 추가됩니다.
자세한 내용은 정책 구성 스키마를 참조하십시오.
유동성에서 지원되는 변수
- URI
- host
- remote_addr
- headers['Some-Header']
업데이트된 변수 목록은 여기에서 확인할 수 있습니다. ngx_ECDHE.lua
이 예제에서는 요청의 백엔드 헤더가 staging 인 경우 업스트림 정책을 실행합니다.
3.1.8. 콘텐츠 캐싱 링크 복사링크가 클립보드에 복사되었습니다!
Content Caching 정책을 사용하면 사용자 정의된 조건에 따라 캐싱을 활성화 및 비활성화할 수 있습니다. 이러한 조건은 정책에서 업스트림 응답을 사용할 수 없는 클라이언트 요청에만 적용할 수 있습니다.
Content Caching 정책이 정책 체인에 있을 때 APIcast는 요청 업스트림을 보내기 전에 HEAD 요청을 GET 요청으로 변환합니다. 이 변환을 원하지 않는 경우 정책 체인에 Content Caching 정책을 추가하지 마십시오.
cache-control 헤더를 보낸 경우 APIcast에서 설정한 시간 초과보다 우선합니다.
다음 예제 구성은 Method가 GET인 경우 응답을 캐시합니다.
설정 예
지원되는 구성
-
POST,PUT또는DELETE방법 중 하나에 대해 콘텐츠 캐싱 정책을 disabled로 설정합니다. - 하나의 규칙이 일치하고 캐시를 활성화하면 실행이 중지되고 비활성화되지 않습니다. 여기서 우선순위별로 정렬하는 것이 중요합니다.
업스트림 응답 헤더
NGINX proxy_cache_valid 지시문 정보는 APICAST_CACHE_STATUS_CODES 및 APICAST_CACHE_MAX_TIME 를 사용하여 전역적으로 설정할 수 있습니다. 업스트림에 시간 초과와 관련하여 다른 동작이 필요한 경우 Cache-Control 헤더를 사용하십시오.
3.1.9. CORS 요청 처리 링크 복사링크가 클립보드에 복사되었습니다!
CORS(Cross Origin Resource Sharing) 요청 처리 정책을 사용하면 다음을 지정할 수 있으므로 CORS 동작을 제어할 수 있습니다.
- 허용된 헤더
- 허용된 방법
- 허용된 원본 헤더
- 허용되는 인증 정보
- 최대 기간
CORS 요청 처리 정책은 지정되지 않은 모든 CORS 요청을 차단합니다.
이러한 두 정책을 정책 체인에서 함께 사용할 때 APIcast 정책 앞에 CORS 요청 처리 정책을 배치해야합니다.
구성 속성
| 속성 | description | 값 | 필수 여부 |
|---|---|---|---|
| allow_headers |
| 데이터 유형: 문자열 배열, CORS 헤더여야 합니다. | 제공되지 않음 |
| allow_methods |
| 데이터 유형: 열거된 문자열 [GET, HEAD, POST, PUT, PUT, PATCH, OPTIONS, CONNECT]의 배열 | 제공되지 않음 |
| allow_origin |
| 데이터 유형: 문자열 | 제공되지 않음 |
| allow_credentials |
| 데이터 유형: 부울 | 제공되지 않음 |
| max_age |
| 데이터 유형: 정수 | 제공되지 않음 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 3scale API Management 관리 포털의 정책 체인 수정을 참조하십시오.
3.1.10. 사용자 정의 메트릭 링크 복사링크가 클립보드에 복사되었습니다!
Custom Metrics 정책은 업스트림 API에서 보낸 응답 후 지표를 추가하는 가용성을 추가합니다. 이 정책의 주요 사용 사례는 응답 코드 상태, 헤더 또는 다른 NGINX 변수에 따라 지표를 추가하는 것입니다.
사용자 정의 메트릭의 제한 사항
- 요청이 업스트림 API로 전송되기 전에 인증이 이루어지면 새 메트릭을 업스트림 API에 보고하기 위해 백엔드에 대한 두 번째 호출이 수행됩니다.
- 이 정책은 일괄 처리 정책에서는 작동하지 않습니다.
- 정책이 지표 값을 푸시하려면 관리 포털에서 지표를 생성해야 합니다.
요청 흐름 예
다음 차트는 인증이 캐시되지 않은 경우의 요청 흐름 예와 인증이 캐시될 때의 흐름을 보여줍니다.
구성 예
이 정책은 업스트림 API에서 400 상태를 반환하는 경우 헤더에 의해 지표 오류가 증가합니다.
이 정책은 업스트림 API에서 200 상태를 반환하는 경우 status_code 정보로 적중 지표를 늘립니다.
3.1.11. echo 링크 복사링크가 클립보드에 복사되었습니다!
echo 정책은 선택적 HTTP 상태 코드와 함께 들어오는 요청을 클라이언트에 다시 인쇄합니다.
구성 속성
| 속성 | description | 값 | 필수 여부 |
|---|---|---|---|
| status | echo 정책이 클라이언트로 반환되는 HTTP 상태 코드 | 데이터 유형: 정수 | 제공되지 않음 |
| 종료 |
echo 정책이 사용할 종료 모드를 지정합니다. | 데이터 유형: 열거된 문자열 [request, set] | 제공됨 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 설명서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.12. 엣지 제한 링크 복사링크가 클립보드에 복사되었습니다!
Edge 제한 정책은 백엔드 API로 전송된 트래픽에 대해 유연한 속도 제한을 제공하는 것을 목표로 하며 기본 3scale 권한 부여와 함께 사용할 수 있습니다. 정책에서 지원하는 사용 사례의 예는 다음과 같습니다.
-
최종 사용자 속도 제한: 요청의 Authorization 헤더에 전달된 JWT 토큰의
sub(주체) 클레임 값에 따른 속도 제한입니다. 이는{{ jwt.sub }}로 구성됩니다. - 초당 요청(RPS) 속도 제한입니다.
- 서비스당 글로벌 속도 제한: 애플리케이션 대신 서비스당 제한을 적용합니다.
- 동시 연결 제한: 허용되는 동시 연결 수를 설정합니다.
제한 유형
이 정책은 lua-resty-limit-traffic 라이브러리에서 제공하는 다음 유형의 제한 유형을 지원합니다.
leaky_bucket_limiters
평균 요청 수와 최대 버스트 크기를 기반으로 하는 누출 버킷 알고리즘에 기반합니다.
fixed_window_limiters
고정 시간 창에 따라 마지막 n초입니다.
connection_limiters
동시 연결 수에 따라 다릅니다.
서비스 또는 전역으로 제한 범위를 지정할 수 있습니다.
제한 정의
제한에는 IP 주소, 서비스, 끝점, 식별자, 특정 헤더 및 기타 엔티티와 같은 제한을 정의하는 데 사용되는 엔티티를 인코딩하는 키가 있습니다. 이 키는 제한자의 키 매개변수에 지정됩니다.
key 는 다음 속성으로 정의된 오브젝트입니다.
name
키 이름을 정의합니다. 범위에서 고유해야 합니다.
scope
키의 범위를 정의합니다. 지원되는 범위는 다음과 같습니다.
-
서비스 범위별로 하나의 서비스(
서비스)에 영향을 미칩니다. -
모든 서비스(글로벌)에 영향을 미치는
전역범위입니다.
-
서비스 범위별로 하나의 서비스(
name_type _
name값이 평가되는 방법을 정의합니다.-
일반 텍스트(
일반) -
예를 들면 Liquid (the
Liquid)
-
일반 텍스트(
또한 각 제한에는 유형에 따라 다른 일부 매개 변수가 있습니다.
leaky_bucket_limiters
속도,버스트.속도
지연 없이 초당 요청할 수 있는 요청 수를 정의합니다.
burst
허용된 속도를 초과할 수 있는 초당 요청 수를 정의합니다. 인위적인 지연은 유량에 의해 지정된 허용된 속도 이상의 요청에 대해 도입됩니다.
burst에 정의된 것보다 초당 더 많은 요청으로 속도를 초과하면 요청이 거부됩니다.
fixed_window_limiters
count,창.count는창에정의된 초 수당 수행할 수 있는 요청 수를 정의합니다.connection_limiters
Conn,burst,delay.Conn
허용되는 최대 동시 연결 수를 정의합니다. 초당
버스트연결로 해당 수를 초과할 수 있습니다.delay
제한을 초과하는 연결을 지연할 시간(초)을 정의합니다.
예제
service_A에 분당 10개의 요청을 허용합니다.
{ "key": { "name": "service_A" }, "count": 10, "window": 60 }{ "key": { "name": "service_A" }, "count": 10, "window": 60 }Copy to Clipboard Copied! Toggle word wrap Toggle overflow 1 초의 지연으로 10의 버스트와 100 개의 연결을 허용합니다.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
각 서비스에 대해 여러 제한을 정의할 수 있습니다. 여러 제한이 정의된 경우 하나 이상의 제한에 도달하면 요청을 거부하거나 지연할 수 있습니다.
유동성 템플릿
Edge 제한 정책을 사용하면 키에서 Liquid 변수를 지원함으로써 동적 키의 제한을 지정할 수 있습니다. 이를 위해 키의 name_type 매개 변수를 모방으로 설정해야 하며 name 매개변수는 Liquid 변수를 사용할 수 있습니다. 예를 들어 클라이언트 IP 주소에 대한 {{ remote_addr }} 또는 JWT 토큰의 하위 클레임의 경우 {{ jwt. 입니다.
sub }}
예제
{
"key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
"count": 10,
"window": 60
}
{
"key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
"count": 10,
"window": 60
}
Liquid 지원에 대한 자세한 내용은 4.1절. “정책에서 변수 및 필터 사용” 을 참조하십시오.
조건 적용
각 제한에는 제한이 적용되는 시기를 정의하는 조건이 있어야 합니다. 조건은 제한자의 condition 속성에 지정됩니다.
조건은 다음 속성으로 정의됩니다.
combine_op
작업 목록에 적용된 부울 연산자입니다.
또는및의 값이 지원됩니다.작업
평가해야 하는 조건 목록입니다. 각 작업은 다음 속성이 있는 개체로 표시됩니다.
left
작업의 왼쪽 부분입니다.
left_type
왼쪽속성을 평가하는 방법(일반 또는 유동)입니다.right
작업의 올바른 부분입니다.
right_type
올바른속성(일반 또는 유동)을 평가하는 방법op
왼쪽과 오른쪽 부분 사이에 적용되는 Operator입니다. 다음 두 값이 지원됩니다.
==(equals) 및!=(동일하지 않음).
예제
속도 제한 카운터의 스토리지 구성
기본적으로 Edge 제한 정책은 속도 제한 카운터에 OpenResty 공유 사전을 사용합니다. 그러나 공유 사전 대신 외부 Redis 서버를 사용할 수 있습니다. 이 기능은 여러 APIcast 인스턴스가 배포된 경우 유용할 수 있습니다. redis_url 매개변수를 사용하여 Redis 서버를 구성할 수 있습니다.
오류 처리
제한자는 다음 매개변수를 지원하여 오류 처리 방법을 구성합니다.
limits_exceeded_error
구성된 제한이 초과될 때 클라이언트에 반환되는 오류 상태 코드 및 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.
status_code
제한이 초과된 요청의 상태 코드입니다. 기본값:
429.error_handling
다음 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.
종료
처리 요청을 중지하고 오류 메시지를 반환합니다.
log
처리 요청을 완료하고 출력 로그를 반환합니다.
configuration_error
잘못된 구성의 경우 클라이언트에 반환되는 오류 상태 코드와 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.
status_code
구성 문제가 있을 때 상태 코드입니다. 기본값:
500.error_handling
다음 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.
종료
처리 요청을 중지하고 오류 메시지를 반환합니다.
log
처리 요청을 완료하고 출력 로그를 반환합니다.
3.1.13. 헤더 수정 링크 복사링크가 클립보드에 복사되었습니다!
헤더 수정 정책을 사용하면 기존 헤더를 수정하거나 들어오는 요청 또는 응답에 추가하거나 제거할 추가 헤더를 정의할 수 있습니다. 응답 헤더와 요청 헤더를 둘 다 수정할 수 있습니다.
헤더 수정 정책은 다음과 같은 구성 매개변수를 지원합니다.
요청
요청 헤더에 적용할 작업 목록
응답
응답 헤더에 적용할 작업 목록
각 작업은 다음 매개 변수로 구성됩니다.
-
적용할 작업을 지정합니다.
add작업은 기존 헤더에 값을 추가합니다.set작업에서는 헤더와 값을 생성하고 기존 헤더 값이 이미 있는 경우 덮어씁니다.내보내기작업은 헤더와 값을 생성하지만 이미 존재하는 경우 기존 헤더의 값을 덮어쓰지 않습니다. 대신push는 기존 헤더에 값을 추가합니다.삭제작업에서는 헤더를 제거합니다. -
header: 생성 또는 수정할 헤더를 지정하고 헤더 이름으로 사용할 모든 문자열(예:Custom-Header)일 수 있습니다. -
value_type: 헤더 값이 평가되는 방법을 정의하고일반텍스트 또는 리쿼리드 템플릿으로 평가를 위한유동성일 수 있습니다. 자세한 내용은 4.1절. “정책에서 변수 및 필터 사용”의 내용을 참조하십시오. -
value: 헤더에 사용할 값을 지정합니다. 값 유형 "liquid"의 경우 값은{{ variable_from_context }}형식이어야 합니다. 삭제할 때 필요하지 않습니다.
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 설명서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.14. HTTP 상태 코드 덮어쓰기 링크 복사링크가 클립보드에 복사되었습니다!
API 공급자는 HTTP 상태 코드 오버 쓰기 정책을 API 제품에 추가할 수 있습니다. 이 정책을 통해 지정한 응답 코드로 업스트림 응답 코드를 변경할 수 있습니다. 3scale은 HTTP 상태 코드 덮어쓰기 정책을 업스트림 서비스에서 보낸 응답 코드에 적용합니다. 즉, 3scale이 노출하는 API에서 상황에 맞지 않는 코드를 반환하는 경우 HTTP 상태 코드 덮어쓰기 정책을 구성하여 애플리케이션에 의미 있는 응답 코드로 해당 코드를 변경할 수 있습니다.
정책 체인에서 변경할 응답 코드를 생성하는 모든 정책은 HTTP 상태 코드 덮어쓰기 정책보다 먼저여야 합니다. 변경하려는 상태 코드를 생성하는 정책이 없는 경우 HTTP 상태 코드 덮어쓰기 정책의 정책 체인 위치는 중요하지 않습니다.
관리 포털에서 제품의 정책 체인에 HTTP 상태 코드 오버 쓰기 정책을 추가합니다. 정책 체인에서 정책을 클릭하여 변경할 업스트림 응답 코드와 대신 반환하려는 응답 코드를 지정합니다. 덮어쓸 각 추가 업스트림 응답 코드의 더하기 기호를 클릭합니다. 예를 들어 HTTP 상태 코드 덮어쓰기 정책을 사용하여 업스트림 201, "Created", 응답 코드를 200, "OK", 응답 코드로 변경할 수 있습니다.
변경하려는 응답 코드의 또 다른 예는 콘텐츠 제한을 초과할 때의 응답입니다. 업스트림에서는 응답 코드가 414 이고 request-URI가 너무 긴 경우 413 페이로드가 너무 클 수 있습니다.
관리 포털에서 HTTP 상태 코드 덮어쓰기 정책을 추가하는 대신 3scale API를 정책 체인 구성 파일과 함께 사용하는 것입니다.
예제
정책 체인 구성 파일의 다음 JSON 구성은 두 개의 업스트림 응답 코드를 덮어씁니다.
3.1.15. HTTP2 Endpoint 링크 복사링크가 클립보드에 복사되었습니다!
HTTP2 Endpoint 정책을 사용하면 요청과 APIcast를 전송하는 소비자 애플리케이션 간에 HTTP/2 프로토콜 및 GRPC(Remote Procedure call) 연결을 사용할 수 있습니다. HTTP2 끝점 정책이 제품의 정책 체인에 있는 경우 APIcast에 요청하는 소비자 애플리케이션에서 업스트림 서비스로의 전체 통신 흐름은 HTTP/2 프로토콜 및 gRPC를 사용할 수 있습니다.
HTTP2 Endpoint 정책이 정책 체인에 있는 경우:
-
인증 요청은 JSON 웹 토큰 또는
App_ID및App_Key쌍을 사용해야 합니다. API 키 인증은 지원되지 않습니다. - gRPC 끝점은 TLS(Transport Layer Security)를 종료합니다.
- HTTP2 끝점 정책은 3scale APIcast 정책보다 먼저여야 합니다.
- 업스트림 서비스의 백엔드는 HTTP/1.1 일반 텍스트 또는 TLS(Transport Layer Security)를 구현할 수 있습니다.
정책 체인에는 TLS 종료 정책도 포함되어야 합니다.
APIcast 구성 정책 체인의 예:
"policy_chain": [ { "name": "apicast.policy.tls" }, { "name": "apicast.policy.grpc" }, { "name": "apicast.policy.apicast" } ]"policy_chain": [ { "name": "apicast.policy.tls" }, { "name": "apicast.policy.grpc" }, { "name": "apicast.policy.apicast" } ]Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.1.16. IP 확인 링크 복사링크가 클립보드에 복사되었습니다!
IP Check 정책은 IP 목록을 기반으로 요청을 거부하거나 허용하는 데 사용됩니다.
구성 속성
| 속성 | description | 데이터 유형 | 필수 여부 |
|---|---|---|---|
| check_type |
|
string은 | 제공됨 |
| ips |
| 문자열 배열은 유효한 IP 주소여야 합니다. | 제공됨 |
| error_msg |
| string | 제공되지 않음 |
| client_ip_sources |
|
문자열 배열, 유효한 옵션은 | 제공되지 않음 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 설명서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.17. JWT 클레임 확인 링크 복사링크가 클립보드에 복사되었습니다!
JSON 웹 토큰(JWT) 클레임을 기반으로 JWT 클레임을 통해 리소스 대상 및 메서드 차단에 대한 새 규칙을 정의할 수 있습니다.
JWT 클레임 검사 정책 정보
JWT 클레임 값을 기반으로 라우팅하려면 JWT를 검증하고 정책에서 공유하는 컨텍스트에 클레임을 저장하는 체인에 정책이 필요합니다.
JWT Claim Check 정책이 리소스 및 메서드를 차단하는 경우 정책은 JWT 작업도 검증합니다. 또는 메서드 리소스가 일치하지 않는 경우 요청은 백엔드 API로 계속됩니다.
예: GET 요청의 경우 요청이 거부되지 않는 경우 JWT에 admin으로 역할 클레임이 있어야 합니다. 반면, GET이 아닌 요청은 JWT 작업의 유효성을 검사하지 않으므로 JWT 제약 조건 없이 POST 리소스가 허용됩니다.
정책 체인에서 JWT 클레임 검사 정책 구성
정책 체인에서 JWT 클레임 검사 정책을 구성하려면 다음을 수행합니다.
- 3scale 설치에 액세스해야 합니다.
- 모든 배포가 완료될 때까지 기다려야 합니다.
정책 구성
- API에 JWT 클레임 확인 정책을 추가하려면 3scale API Management 관리 포털에서 정책 활성화에 설명된 단계를 수행하고 JWT 클레임 검사를 선택합니다.
- JWT 클레임 확인 링크를 클릭합니다.
- 정책을 활성화하려면 Enabled 확인란을 선택합니다.
-
규칙을 추가하려면 더하기
+아이콘을 클릭합니다. - resource_type 을 지정합니다.
- operator를 선택합니다.
- 규칙으로 제어하는 리소스를 나타냅니다.
-
허용된 방법을 추가하려면 더하기
+아이콘을 클릭합니다. - 트래픽이 차단될 때 사용자에게 표시할 오류 메시지를 입력합니다.
JWT 클레임 확인으로 API 설정을 완료하면 업데이트 정책.
해당 섹션에서 더하기
+아이콘을 클릭하여 더 많은 리소스 유형과 허용된 메서드를 추가할 수 있습니다.- Update Policy Chain 을 클릭하여 변경 사항을 저장합니다.
3.1.18. 유동적인 컨텍스트 디버그 링크 복사링크가 클립보드에 복사되었습니다!
Liquid Context Debug 정책은 개발 환경의 디버깅 목적으로만 사용되며 프로덕션에는 사용할 수 없습니다.
이 정책은 컨텍스트에서 사용 가능한 오브젝트 및 값을 포함하는 JSON 을 사용하여 API 요청에 응답하며 Liquid 템플릿을 평가하는 데 사용할 수 있습니다. 3scale APIcast 또는 업스트림 정책과 결합될 때 Liquid Context Debug를 정책 체인에 배치하여 올바르게 작동합니다. 원형 참조를 방지하기 위해 정책에는 중복된 오브젝트만 포함되어 스텁 값으로 교체합니다.
정책이 활성화된 경우 APIcast에서 반환된 값의 예입니다.
3.1.19. 로깅 링크 복사링크가 클립보드에 복사되었습니다!
로깅 정책에는 다음 두 가지 용도가 있습니다.
- 액세스 로그 출력을 활성화하고 비활성화하려면 다음을 수행합니다.
- 각 서비스에 대한 사용자 정의 액세스 로그 형식을 생성하고 사용자 정의 액세스 로그를 작성할 조건을 설정하려면 다음을 수행합니다.
로깅 정책과 액세스 로그 위치에 대한 전역 설정을 결합할 수 있습니다. APICAST_ACCESS_LOG_FILE 환경 변수를 설정하여 APIcast 액세스 로그의 위치를 구성합니다. 기본적으로 이 변수는 표준 출력 장치인 /dev/stdout 으로 설정됩니다. 글로벌 APIcast 매개변수에 대한 자세한 내용은 APIcast 환경 변수를 참조하십시오.
또한 로깅 정책에는 다음과 같은 기능이 있습니다.
-
이 정책은
enable_access_logs구성 매개변수만 지원합니다. -
액세스 로그를 활성화하려면
enable_access_logs매개변수를 선택하거나 로깅 정책을 비활성화합니다. API에 대한 액세스 로깅을 비활성화하려면 다음을 수행합니다.
- 정책을 활성화합니다.
-
enable_access_logs매개변수를 지웁니다. -
제출버튼을 클릭합니다.
- 기본적으로 이 정책은 정책 체인에서 활성화되어 있지 않습니다.
3.1.19.1. 모든 API에 대한 로깅 정책 구성 링크 복사링크가 클립보드에 복사되었습니다!
APICAST_ENVIRONMENT 를 사용하여 정책이 모든 API 제품에 전역적으로 적용되는 구성을 로드할 수 있습니다. 다음은 이러한 작업을 수행하는 방법의 예입니다. APICAST_ENVIRONMENT는 배포, 템플릿 또는 Operator의 유형에 따라 파일의 경로를 가리키는 데 사용됩니다.
로깅 정책을 전역적으로 구성하려면 배포 유형에 따라 다음을 고려하십시오.
- 템플릿 기반 배포의 경우: ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트해야 합니다.
3scale Operator 기반 배포의 경우:
- 3scale 2.11 이전 버전에서는 ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트해야 합니다.
- 3scale 2.11부터는 APIManager CR(사용자 정의 리소스)에서 참조하는 시크릿을 사용해야 합니다.
APIcast Operator 배포의 경우:
- 3scale 2.11 이전 버전에서는 구성할 수 없습니다.
- 3scale 2.11부터 APIManager CR에서 참조하는 보안을 사용해야 합니다.
- Docker에 배포된 APIcast 자체 관리의 경우 컨테이너에 파일을 마운트해야 합니다.
로깅 옵션을 사용하면 API에서 올바르게 포맷되지 않은 로그 관련 문제를 방지할 수 있습니다.
다음은 모든 서비스에서 로드하는 정책의 예입니다.
custom_env.lua file
3.1.19.1.1. ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트하여 모든 API에 대한 로깅 정책 구성 링크 복사링크가 클립보드에 복사되었습니다!
custom_env.lua파일을 사용하여 ConfigMap을 생성합니다.oc create configmap logging --from-file=/path/to/custom_env.lua
$ oc create configmap logging --from-file=/path/to/custom_env.luaCopy to Clipboard Copied! Toggle word wrap Toggle overflow ConfigMap의 볼륨을 마운트합니다(예:
apicast-staging):oc set volume dc/apicast-staging --add --name=logging --mount-path=/opt/app-root/src/config/custom_env.lua --sub-path=custom_env.lua -t configmap --configmap-name=logging
$ oc set volume dc/apicast-staging --add --name=logging --mount-path=/opt/app-root/src/config/custom_env.lua --sub-path=custom_env.lua -t configmap --configmap-name=loggingCopy to Clipboard Copied! Toggle word wrap Toggle overflow 환경 변수를 설정합니다.
oc set env dc/apicast-staging APICAST_ENVIRONMENT=/opt/app-root/src/config/custom_env.lua
$ oc set env dc/apicast-staging APICAST_ENVIRONMENT=/opt/app-root/src/config/custom_env.luaCopy to Clipboard Copied! Toggle word wrap Toggle overflow
3.1.19.1.2. APIManager CR에서 참조되는 보안을 사용하여 모든 API의 로깅 정책 구성 링크 복사링크가 클립보드에 복사되었습니다!
Operator 기반 배포의 3scale 2.11에서 로깅 정책을 시크릿으로 구성하고 APIManager CR의 시크릿을 참조합니다.
다음 절차는 3scale Operator에만 유효합니다. 그러나 이러한 단계를 사용하여 유사한 방식으로 APIcast Operator를 구성할 수 있습니다.
사전 요구 사항
- Lua로 코딩된 하나 이상의 사용자 지정 환경입니다.
절차
사용자 정의 환경 콘텐츠를 사용하여 보안을 생성합니다.
oc create secret generic custom-env --from-file=./custom_env.lua
$ oc create secret generic custom-env --from-file=./custom_env.luaCopy to Clipboard Copied! Toggle word wrap Toggle overflow APIcast 사용자 정의 환경을 사용하여 APIManager CR을 구성하고 배포합니다.
apimanager.yaml 콘텐츠:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow APIManager CR을 배포합니다.
oc apply -f apimanager.yaml
$ oc apply -f apimanager.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
secret이 없는 경우 Operator는 CR을 실패로 표시합니다. 보안을 변경하려면 APIcast를 반영하기 위해 pod/container를 재배포해야 합니다.
사용자 정의 환경 업데이트
사용자 지정 환경 콘텐츠를 수정해야 하는 경우 다음 두 가지 옵션이 있습니다.
권장: 다른 이름으로 다른 보안을 생성하고 APIManager CR 필드를 업데이트합니다.
customEnvironments[].secretRef.name
customEnvironments[].secretRef.nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Operator는 롤링 업데이트에서 새 사용자 지정 환경 콘텐츠를 로드하도록 트리거합니다.
-
기존 보안 콘텐츠를 업데이트하고 APIcast를 재배포하여
spec.apicast.productionSpec.replicas또는spec.apicast.stagingSpec.replicas를 0으로 설정한 다음 이전 값으로 돌아갑니다.
3.1.19.1.3. Docker에 배포된 APIcast 자체 관리를 위한 모든 API에 대한 로깅 정책 구성 링크 복사링크가 클립보드에 복사되었습니다!
다음 docker 명령을 사용하여 custom_env.lua를 마운트하여 이 특정 환경에서 APIcast를 실행합니다.
docker run --name apicast --rm -p 8080:8080 \
-v $(pwd):/config \
-e APICAST_ENVIRONMENT=/config/custom_env.lua \
-e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
quay.io/3scale/apicast:master
docker run --name apicast --rm -p 8080:8080 \
-v $(pwd):/config \
-e APICAST_ENVIRONMENT=/config/custom_env.lua \
-e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
quay.io/3scale/apicast:master
다음은 고려해야 할 docker 명령의 주요 개념입니다.
-
현재 Lua 파일을 컨테이너에 공유
-v $(pwd):/config. -
APICAST_ENVIRONMENT 변수를
/config디렉터리에 저장된 Lua 파일로 설정합니다.
3.1.19.2. 로깅 정책의 예 링크 복사링크가 클립보드에 복사되었습니다!
다음은 로깅 정책의 예입니다. 다음 경고는 다음과 같습니다.
-
custom_logging또는enable_json_logs속성이 활성화된 경우 기본 액세스 로그가 비활성화됩니다. -
enable_json_logs가 활성화된 경우custom_logging필드가 생략됩니다.
액세스 로그 비활성화
사용자 정의 액세스 로그 활성화
서비스 식별자를 사용하여 사용자 정의 액세스 로그 활성화
JSON 형식으로 액세스 로그 구성
성공적인 요청에 대해서만 사용자 정의 액세스 로그 구성
응답 상태가 200 또는 500과 일치하는 액세스 로그 사용자 정의
3.1.19.3. 사용자 정의 로깅에 대한 추가 정보 링크 복사링크가 클립보드에 복사되었습니다!
사용자 지정 로깅의 경우 내보낸 변수와 함께 Liquid 템플릿을 사용할 수 있습니다. 이러한 변수는 다음과 같습니다.
-
NGINX 기본 지시문 변수: log_format. 예:
{{remote_addr}}. 응답 및 요청 헤더:
-
{{req.headers.FOO}}: 요청에 FOO 헤더를 가져옵니다. -
{{Res.headers.FOO}}: 응답으로 FOO 헤더를 검색합니다.
-
서비스 정보(예:
{{service.id}}) 및 이러한 매개변수에서 제공하는 모든 서비스 속성:- THREESCALE_CONFIG_FILE
- THREESCALE_PORTAL_ENDPOINT
3.1.20. 유지 관리 모드 링크 복사링크가 클립보드에 복사되었습니다!
에 대한 유지 관리 모드 정책을 사용하면 지정된 상태 코드 및 메시지를 사용하여 들어오는 요청을 거부할 수 있습니다. 유지 관리 기간 또는 API를 일시적으로 차단하는 데 유용합니다.
구성 속성
다음은 가능한 속성 및 기본값 목록입니다.
| 속성 | value | default | description |
|---|---|---|---|
| status | 정수, 선택 사항 | 503 | 응답 코드 |
| message | 문자열, 선택 사항 | 503 서비스 Unavailable - 유지 관리 | 응답 메시지 |
유지 관리 모드 정책 예
특정 업스트림에 대한 유지 관리 모드 적용
정책을 구성하는 방법에 대한 자세한 내용은 설명서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.21. NGINX 필터 링크 복사링크가 클립보드에 복사되었습니다!
NGINX는 일부 요청 헤더를 자동으로 확인하고 해당 헤더를 검증할 수 없을 때 요청을 거부합니다. 예를 들어, NGINX는 NGINX에서 검증할 수 없는 If-Match 헤더가 있는 요청을 거부합니다. NGINX에서 특정 헤더의 유효성 검사를 건너뛰려면 NGINX 필터 정책을 추가합니다.
NGINX 필터 정책을 추가하면 NGINX에서 검증을 건너뛰려는 하나 이상의 요청 헤더를 지정합니다. 지정하는 각 헤더에 대해 요청에 헤더를 유지할지 여부를 나타냅니다. 예를 들어 다음 JSON 코드는 NGINX 필터 정책을 추가하여 If-Match 헤더의 유효성 검사를 건너뛰지만 업스트림 서버로 전달되는 요청에 If-Match 헤더를 유지합니다.
다음 예제에서는 If-Match 헤더의 유효성 검사를 생략하지만 이 코드는 업스트림 서버에 요청을 보내기 전에 NGINX에 If-Match 헤더를 삭제하도록 지시합니다.
지정된 헤더를 업스트림 서버로 이동하는 요청에 추가했는지 여부에 관계없이 NGINX 412 응답 코드를 사용자가 지정하는 헤더를 검증할 수 없습니다.
헤더 수정 정책에 대해 동일한 헤더를 지정하고 NGINX 필터 정책에 대해 지정하는 것은 충돌의 잠재적인 소스입니다.
3.1.22. OAuth 2.0 상호 TLS 클라이언트 인증 링크 복사링크가 클립보드에 복사되었습니다!
이 정책은 모든 API 호출에 대해 OAuth 2.0 상호 TLS 클라이언트 인증을 실행합니다.
OAuth 2.0 상호 작용 TLS 클라이언트 인증 정책 JSON 의 예는 다음과 같습니다.
3.1.23. OAuth 2.0 토큰 인트로스펙션 링크 복사링크가 클립보드에 복사되었습니다!
OAuth 2.0 토큰 인트로스펙션 정책을 사용하면 토큰 발행자(Red Hat Single Sign-On)의 토큰 검사 끝점을 사용하여 OIDC(OpenID Connect) 인증 옵션을 사용하는 서비스에 사용되는 JSON 웹 토큰(JWT) 토큰을 검증할 수 있습니다.
APIcast는 auth_type 필드에서 다음 인증 유형을 지원하여 Token Introspection Endpoint 및 이 끝점을 호출할 때 APIcast가 사용되는 인증 정보를 결정합니다.
use_3scale_oidc_issuer_endpoint: APIcast는 서비스 통합 페이지에 구성된 OIDC Issuer 설정의 클라이언트 자격 증명, 클라이언트 ID 및 클라이언트 시크릿 을 사용하며, OIDC Issuer 설정의 Token Introspection Endpoint를 사용합니다. APIcast는token_introspection_endpoint필드에서 Token Introspection 끝점을 검색합니다. 이 필드는 OIDC 발행자가 반환하는.well-known/openid-configuration끝점에 있습니다.use_3scale_oidc_issuer_endpoint로 설정된 인증 유형 :Copy to Clipboard Copied! Toggle word wrap Toggle overflow client_id+client_secret: 이 옵션을 사용하면 다른 Token Introspection Endpoint와 Client ID 및 Client Secret APIcast가 토큰 정보를 요청하는 데 사용할 수 있습니다. 이 옵션을 사용하는 경우 다음 구성 매개변수를 설정합니다.-
client_id: 토큰 인트로스펙션 끝점의 클라이언트 ID를 설정합니다. -
client_secret: 토큰 인트로스펙션 끝점의 클라이언트 시크릿을 설정합니다. introspection_url: 인트로스펙션 엔드 포인트 URL을 설정합니다.인증 유형을
client_id+client_secret으로 설정합니다.Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
auth_type 필드의 설정에 관계없이 APIcast는 기본 인증을 사용하여 Token Introspection 호출(Authorization: Basic <token> 헤더)을 승인합니다. 여기서 < token >은 Base64로 인코딩된 < client_id>:<client_secret > 설정입니다.
Token Introspection Endpoint의 응답에는 active 속성이 포함되어 있습니다. APIcast는 이 속성의 값을 확인합니다. 특성 값에 따라 APIcast는 호출을 승인하거나 거부합니다.
true
전화가 승인됨
false
Authentication Failed오류와 함께 호출이 거부됩니다.
이 정책을 통해 동일한 JWT 토큰에 대한 모든 호출에서 Token Introspection Endpoint를 호출하지 않도록 토큰 캐싱을 활성화할 수 있습니다. Token Introspection 정책에 대한 토큰 캐싱을 활성화하려면 max_cached_tokens 필드를 기능을 비활성화하는 0 으로부터 값으로 설정하고 10000 을 설정합니다. 또한 max_ttl_tokens 필드의 토큰에 대해 Time to Live(TTL) 값을 1 에서 3600 초로 설정할 수 있습니다.
3.1.24. On Fail 링크 복사링크가 클립보드에 복사되었습니다!
API 공급자로 On Fail 정책을 API 제품에 추가할 수 있습니다. On Fail 정책이 정책 체인에 있고 지정된 API 소비자 요청에 대한 정책 실행이 실패하면 APIcast는 다음을 수행합니다.
- 요청 처리를 중지합니다.
- 요청을 보낸 애플리케이션에 지정하는 상태 코드를 반환합니다.
On Fail 정책은 잘못된 구성으로 인해 또는 사용자 정의 정책의 비호환 코드 때문에 APIcast에서 정책을 처리할 수 없는 경우에 유용합니다. 정책 체인에서 On Fail 정책이 없으면 APIcast에서 적용할 수 없는 정책을 건너뛰고 체인의 다른 정책을 처리하며 업스트림 API로 요청을 보냅니다. 정책 체인의 On Fail 정책을 사용하면 APIcast에서 요청을 거부합니다.
정책 체인에서 On Fail 정책은 모든 위치에 있을 수 있습니다.
관리 포털에서 제품의 정책 체인에 On Fail 정책을 추가합니다. 정책 체인에서 정책을 클릭하여 On Fail 정책을 적용할 때 APIcast를 반환할 상태 코드를 지정합니다. 예를 들어 400 을 지정하면 클라이언트의 잘못된 요청을 나타낼 수 있습니다.
3.1.25. 프록시 서비스 링크 복사링크가 클립보드에 복사되었습니다!
프록시 서비스 정책을 사용하여 3scale 트래픽이 정의된 프록시를 사용하여 전송되는 일반 HTTP 프록시 를 정의할 수 있습니다. 이 경우 프록시 서비스는 역방향 HTTP 프록시로 작동합니다. 여기서 APIcast는 트래픽을 HTTP 프록시로 전송한 다음 프록시는 트래픽을 API 백엔드로 보냅니다.
다음 예제에서는 트래픽 흐름을 보여줍니다.
3scale 백엔드로 전송된 모든 APIcast 트래픽은 프록시를 사용하지 않습니다. 이 정책은 프록시와 API 백엔드와 API 백엔드 간의 통신에만 적용됩니다.
프록시를 통해 모든 트래픽을 보내려면 HTTP_PROXY 환경 변수를 사용해야 합니다.
- * 도메인 이름이 여러 IP 주소로 확인되면 Camel 서비스 정책은 로드 밸런싱 업스트림의 APIcast 기능을 비활성화합니다. Camel 서비스는 업스트림 서비스의 DNS 확인을 관리합니다.
-
HTTP_PROXY,HTTPS_PROXY또는ALL_PROXY매개변수가 정의된 경우 이 정책은 해당 값을 덮어씁니다. - 프록시 연결은 인증을 지원하지 않습니다. 인증을 위해 헤더 수정 정책을 사용합니다.
설정
다음 예제에서는 정책 체인 구성을 보여줍니다.
all_proxy 값은 http_proxy 또는 https_proxy 가 정의되지 않은 경우 사용됩니다.
사용 사례 예
Proxy 서비스 정책은 Apache Camel over HTTP를 사용하여 3scale에서 보다 세분화된 정책과 변환을 적용하도록 설계되었습니다. 그러나 프록시 서비스 정책을 일반 HTTP 프록시 서비스로 사용할 수도 있습니다. HTTPS를 통한 Apache Camel과의 통합은 3.1.6절. “Camel 서비스” 에서 참조하십시오.
프로젝트 예
GitHub에서 camel-netty-proxy 예제를 참조하십시오. 이 프로젝트는 응답 본문을 API 백엔드에서 대문자로 변환하는 HTTP 프록시를 보여줍니다.
3.1.26. 속도 제한 헤더 링크 복사링크가 클립보드에 복사되었습니다!
속도 제한 헤더 정책은 애플리케이션이 속도 제한이 있는 애플리케이션 계획에 서브스크립션할 때 응답 메시지에 RateLimit 헤더를 추가합니다. 이러한 헤더는 구성된 요청 할당량 제한과 현재 시간 창에서 나머지 요청 할당량과 초에 대한 유용한 정보를 제공합니다.
제품에 대한 정책 체인에서 Rate Limit Headers 정책을 추가하는 경우 3scale APIcast 정책 앞에 있어야 합니다. 3scale APIcast 정책이 Rate Limit Headers 정책 이전의 경우 Rate Limit Headers 정책이 작동하지 않습니다.
RateLimit 헤더
각 메시지에 다음 RateLimit 헤더가 추가됩니다.
RateLimit-Limit
구성된 시간 창에 총 요청 할당량을 표시합니다(예:
10개의 요청).RateLimit-Remaining
현재 시간 창에 나머지 요청 할당량을 표시합니다(예:
5개의 요청).RateLimit-Reset
현재 시간 창에 남아 있는 시간(예:
30초)을 표시합니다. 이 헤더의 동작은Retry-After헤더의delta-seconds표기법과 호환됩니다.
기본적으로 Rate Limit Headers 정책이 구성되지 않았거나 애플리케이션 계획에 속도 제한이 없는 경우 응답 메시지에 속도 제한 헤더가 없습니다.
속도 제한이 없는 API 메트릭을 요청하고 있지만 상위 메트릭에 제한이 구성되어 있는 경우 상위 제한이 적용되므로 속도 제한 헤더가 여전히 응답에 포함됩니다.
3.1.27. 응답/요청 콘텐츠 제한 링크 복사링크가 클립보드에 복사되었습니다!
API 공급자는 API 제품에 Response/Request Content Limits 정책을 추가할 수 있습니다. 이 정책을 사용하면 요청 크기를 업스트림 API로 제한할 뿐만 아니라 업스트림 API의 응답 크기를 제한할 수 있습니다. 이 정책이 없으면 요청/응답 크기가 무제한입니다.
이 정책은 의 과부하를 방지하는 데 유용합니다.
- 백엔드가 너무 큰 페이로드에서 작동해야 하기 때문입니다.
- 최종 사용자(API 소비자)는 처리할 수 있는 것보다 더 많은 데이터를 수신하기 때문입니다.
요청 또는 응답에서 3scale이 Response/Request Content Limits 정책을 적용하려면 콘텐츠 길이 헤더가 필요합니다.
관리 포털에서 제품에 Response/Request Content Limits 정책을 추가한 후 이를 클릭하여 제한을 바이트 단위로 지정합니다. 요청 제한 또는 응답 제한을 모두 지정할 수 있습니다. 기본값인 0 은 무제한 크기를 나타냅니다.
또는 다음과 같이 정책 체인 구성 파일을 업데이트하여 이 정책을 추가할 수 있습니다.
3.1.28. Retry 링크 복사링크가 클립보드에 복사되었습니다!
재시도 정책에서는 업스트림 API에 대한 재시도 요청 수를 설정합니다. 재시도 정책은 서비스별로 구성되므로 사용자는 원하는 소수 또는 많은 서비스를 재시도할 수 있을 뿐 만 아니라 다양한 서비스에 대해 다른 재시도 값을 구성할 수 있습니다.
3scale 2.14에서는 정책에서 재시도할 사례를 구성할 수 없습니다. 이는 모든 서비스에 재시도 요청을 적용하는 환경 변수 APICAST_UPSTREAM_RETRY_CASES 를 사용하여 제어됩니다. 이에 대한 자세한 내용은 APICAST_UPSTREAM_RETRY_CASES 를 확인하십시오.
재시도 정책 JSON 의 예는 다음과 같습니다.
3.1.29. rh-SSO/Keycloak 역할 검사 링크 복사링크가 클립보드에 복사되었습니다!
RH-SSO/Keycloak Role Check 정책을 APIcast 정책 체인에 추가하면 APIcast 및 라우팅 정책 앞에 배치합니다.
이 정책은 OpenID Connect 인증 옵션과 함께 사용할 때 역할 검사를 추가합니다. 이 정책은 Red Hat Single Sign-On(RH-SSO)에서 발행한 액세스 토큰에서 영역 역할 및 클라이언트 역할을 확인합니다. 3scale의 모든 클라이언트 리소스에 역할 검사를 추가하려는 경우 realm 역할이 지정됩니다.
역할 유형에는 정책 구성에 type 속성이 지정되는지 확인하는 두 가지 유형이 있습니다.
whitelist
이는 기본값입니다. 허용 목록을 사용하면 APIcast에서 지정된 범위가 JWT 토큰에 있는지 확인하고 JWT에 범위가 없는 경우 호출을 거부합니다.
blacklist
blacklist 을 사용하면 JWT 토큰에 블랙리스트 범위가 포함된 경우 APIcast에서 호출을 거부합니다.
동일한 정책에서 블랙리스트 및 허용 목록 모두를 구성할 수는 없지만 RH-SSO/Keycloak 역할 검사 정책의 두 개 이상의 인스턴스를 APIcast 정책 체인에 추가할 수 있습니다.
정책 구성의 scopes 속성을 통해 범위 목록을 구성할 수 있습니다.
각 scope 오브젝트에는 다음과 같은 속성이 있습니다.
resource
역할에 의해 제어되는 리소스 끝점입니다. 이는 매핑 규칙과 동일합니다. 패턴은 문자열의 시작 부분에서 일치하고 정확히 일치하려면 끝에 $ 를 추가해야 합니다.
resource_type
이는 리소스 값이 평가되는 방법을 정의합니다.
- 일반 텍스트(일반): 리소스 값을 일반 텍스트로 표시합니다. 예: /api/v1/ECDHE$
- Liquid 텍스트(상성): 리소스 값에 Liquid를 사용할 수 있습니다. 예: /resource_{{ jwt.aud }} 는 클라이언트 ID가 포함된 리소스에 대한 액세스를 관리합니다.
methods: 이 매개변수를 사용하여 RH-SSO의 사용자 역할에 따라 APIcast에서 허용된 HTTP 메서드를 나열합니다. 예를 들어 다음을 포함하는 메서드를 허용할 수 있습니다.
-
/resource1에 액세스할 수 있는role1영역 역할입니다. 이 영역 역할이 없는 메서드의 경우 블랙리스트 를 지정해야 합니다. -
/resource1에 액세스하는role1이라는client1역할입니다. -
/resource1에 액세스하는role1및role2영역 역할입니다. realm_roles 에서 역할을 지정합니다. 각 역할의 범위를 표시할 수도 있습니다. -
/resource1에 액세스하기 위한 액세스 토큰의 수신자인 애플리케이션 클라이언트의role1이라는 클라이언트 역할입니다. 유동클라이언트유형을 사용하여 클라이언트에 JSON 웹 토큰(JWT) 정보를 지정합니다. -
애플리케이션 클라이언트의 클라이언트 ID, 액세스 토큰 수신자를 포함하여
/resource1에 액세스할 클라이언트 역할.번성된 클라이언트 유형을 사용하여 클라이언트 역할의이름에JWT 정보를 지정합니다. -
애플리케이션 클라이언트 ID를 포함하여 리소스에 액세스하는
role1이라는 클라이언트 역할입니다.유해한클라이언트 유형을 사용하여 리소스에 JWT 정보를 지정합니다.
-
realm_roles
이를 사용하여 realm 역할을 확인합니다. Red Hat Single Sign-On 설명서의 Cryostat 역할을 참조하십시오.
realm 역할은 Red Hat Single Sign-On에서 발행한 JWT에 있습니다.
"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }Copy to Clipboard Copied! Toggle word wrap Toggle overflow 정책에 실제 역할을 지정해야 합니다.
"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]Copy to Clipboard Copied! Toggle word wrap Toggle overflow 다음은 realm_roles 배열에 있는 각 오브젝트의 사용 가능한 속성입니다.
name
역할의 이름을 지정합니다.
name_type
이름을 평가하는 방법을 정의합니다. 값은 일반 또는 유동일 수 있습니다. 이 명령은 resource_type 과 동일한 방식으로 작동합니다.
client_roles
client_roles 를 사용하여 클라이언트 네임스페이스에서 특정 액세스 역할을 확인합니다. Red Hat Single Sign-On 설명서의 클라이언트 역할을 참조하십시오.
클라이언트 역할은 resource_access 클레임 아래의 JWT에 있습니다.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 정책에 클라이언트 역할을 지정합니다.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 다음은 client_roles 배열에 있는 각 오브젝트의 사용 가능한 속성입니다.
name
역할의 이름을 지정합니다.
name_type
name 값을 평가하는 방법을 정의합니다. 값은 일반 또는 유동일 수 있습니다. resource_type 과 동일한 방식으로 작동합니다.
클라이언트
역할의 클라이언트를 지정합니다. 정의되지 않은 경우 이 정책은 aud 클레임을 클라이언트로 사용합니다.
client_type
클라이언트 값을 평가하는 방법을 정의합니다. 값은 일반 또는 유동일 수 있습니다. resource_type 과 동일한 방식으로 작동합니다.
3.1.30. 라우팅 링크 복사링크가 클립보드에 복사되었습니다!
라우팅 정책이 요청을 처리하는 경우에도 요청에 대한 해당 매핑 규칙이 있어야 합니다.
라우팅 정책을 사용하면 요청을 다른 대상 끝점으로 라우팅할 수 있습니다. 대상 끝점을 정의한 다음 정규식을 사용하여 UI에서 들어오는 요청을 라우팅할 수 있습니다.You can define target endpoints and then you will be able to route incoming requests from the UI to those using regular expressions.
라우팅은 다음 규칙을 기반으로 합니다.
정책 체인에 라우팅 정책을 추가할 때 라우팅 정책은 항상 표준 3scale APIcast 정책 바로 앞에 있어야 합니다. 즉, 라우팅 정책과 3scale APIcast 정책 간에 정책이 있을 수 없습니다. 이렇게 하면 APIcast가 업스트림 API로 전송하는 요청의 올바른 APIcast 출력이 보장됩니다. 다음은 올바른 정책 체인의 두 가지 예입니다.
Liquid Context Debug JWT Claim Check Routing 3scale APIcast
Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast
Liquid Context Debug Routing 3scale APIcast JWT Claim Check
Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check
라우팅 규칙
- 여러 규칙이 있는 경우 라우팅 정책이 첫 번째 일치 규칙을 적용합니다. 이러한 규칙을 분류할 수 있습니다.
- 일치하는 규칙이 없는 경우 정책은 업스트림을 변경하지 않고 서비스 구성에 정의된 정의된 개인 기본 URL을 사용합니다.
요청 경로 규칙
경로가 /accounts 인 경우 http://example.com 로 라우팅되는 구성입니다.
헤더 규칙
Test-Header 헤더 값이 123 인 경우 http://example.com 로 라우팅되는 구성입니다.
쿼리 인수 규칙
쿼리 인수 test_query_arg 값이 123 인 경우 로 라우팅하는 구성입니다.
JWT 클레임 규칙
JWT 클레임의 값을 기반으로 라우팅하려면 JWT를 검증하고 정책에서 공유하는 컨텍스트에 저장하는 체인에 정책이 있어야 합니다.
JWT 클레임 test_claim 값이 123 인 경우 http://example.com 로 라우팅되는 구성입니다.
여러 작업 규칙
규칙에는 'and' combine_op 를 사용하거나 'or' combine_op 를 사용하여 모든 작업이 true로 평가되는 경우에만 지정된 업스트림으로의 경로와 경로가 포함될 수 있습니다. combine_op 의 기본값은 'and'입니다.
요청 경로가 /accounts 이고 헤더 Test-Header 값이 123 인 경우 로 라우팅하는 구성입니다.
요청 경로가 /accounts 일 때 또는 헤더 Test-Header 값이 123 인 경우 http://example.com 로 라우팅되는 구성입니다.
규칙 결합
규칙을 결합할 수 있습니다. 여러 규칙이 있는 경우 선택한 업스트림이 true로 평가되는 첫 번째 규칙 중 하나입니다.
이는 몇 가지 규칙이 있는 구성입니다.
catch-all 규칙
작업이 없는 규칙은 항상 일치합니다. 이는 catch-all 규칙을 정의하는 데 유용할 수 있습니다.
이 설정은 경로가 /abc 인 경우 http://some_upstream.com 로 요청을 라우팅하고, 경로가 /def 인 경우 요청을 http://another_upstream.com 로 라우팅하고, 마지막으로 이전 규칙 중 하나를 true로 평가하지 않으면 요청을 http://default_upstream.com 로 라우팅합니다.
지원되는 작업
지원되는 작업은 ==, !=, 일치 항목 입니다. 후자의 문자열은 정규식이 있는 문자열과 일치하며 ngx.re.match를 사용하여 구현됩니다.
이는 != 를 사용하는 구성입니다. 경로가 /accounts 가 아닌 경우 http://example.com 로 라우팅합니다.
유동성 템플릿
구성 값에 대해 일시 정지된 템플릿을 사용할 수 있습니다. 이를 통해 체인의 정책이 컨텍스트에 my_var 키를 저장하는 경우 동적 값으로 규칙을 정의할 수 있습니다.
이 구성은 해당 값을 사용하여 요청을 라우팅하는 구성입니다.
host_header에 사용된 호스트 설정
기본적으로 요청이 라우팅될 때 정책은 일치하는 규칙의 URL의 호스트를 사용하여 Host 헤더를 설정합니다. host_header 특성을 사용하여 다른 호스트를 지정할 수 있습니다.
some_host.com 을 Host 헤더의 호스트로 지정하는 구성입니다.
3.1.31. SOAP 링크 복사링크가 클립보드에 복사되었습니다!
ECDHE 정책은 정책에 지정된 매핑 규칙을 사용하여 HTTP 요청의ECDHE Action 또는 Content-Type 헤더에 제공된ECDHE 작업 URI와 일치합니다.
구성 속성
| 속성 | description | 값 | 필수 여부 |
|---|---|---|---|
| 패턴 |
| 데이터 유형: 문자열 | 제공됨 |
| metric_system_name |
| data type: string은 유효한 메트릭이어야 합니다. | 제공됨 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.32. TLS 클라이언트 인증서 검증 링크 복사링크가 클립보드에 복사되었습니다!
TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast는 TLS 핸드셰이크를 구현하고 허용 목록에 대해 클라이언트 인증서의 유효성을 검사합니다. 허용 목록에는 CA(인증 기관) 또는 일반 클라이언트 인증서만 서명한 인증서가 포함되어 있습니다. 만료된 인증서 또는 유효하지 않은 인증서가 있는 경우 요청이 거부되고 다른 정책은 처리되지 않습니다.
클라이언트는 APIcast에 연결하여 요청을 보내고 클라이언트 인증서를 제공합니다. APIcast는 정책 구성에 따라 들어오는 요청에서 제공된 인증서의 신뢰성을 확인합니다. APIcast는 업스트림에 연결할 때 사용할 고유한 클라이언트 인증서를 사용하도록 구성할 수도 있습니다.
TLS 클라이언트 인증서 검증에서 작동하도록 APIcast 설정
APIcast는 TLS를 종료하도록 구성해야 합니다. 다음 단계에 따라 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast에서 사용자가 제공하는 클라이언트 인증서의 유효성 검사를 구성합니다.
3scale 설치에 액세스할 수 있어야 합니다. 모든 배포가 완료될 때까지 기다려야 합니다.
정책에서 작동하도록 APIcast 설정
APIcast를 설정하고 TLS를 종료하도록 구성하려면 다음 단계를 따르십시오.
OpenShift 템플릿을 사용하여 Deploying APIcast에 표시된 대로 액세스 토큰을 가져오고 APIcast 자체 관리를 배포해야 합니다.
참고전체 게이트웨이에 일부 인증서를 사용하도록 APIcast 인스턴스를 재구성해야 하므로 APIcast 자체 관리형 배포가 필요합니다.
테스트 목적으로만 캐시 및 스테이징 환경 및
--param플래그 없이 지연 로더를 사용하여 쉽게 테스트할 수 있습니다.oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/master/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
$ oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/master/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 테스트를 위해 인증서를 생성합니다. 또는 프로덕션 배포의 경우 인증 기관에서 제공한 인증서를 사용할 수 있습니다.
TLS 인증서로 보안 생성
oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.key
$ oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow APIcast 배포 내부에 시크릿 마운트
oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
$ oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tlsCopy to Clipboard Copied! Toggle word wrap Toggle overflow HTTPS용 포트 8443에서 수신을 시작하도록 APIcast 구성
oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key
$ oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow 서비스에 8443 노출
oc patch service apicast -p '{"spec":{"ports":[{"name":"httpsproxy","port":8443,"protocol":"TCP"}]}}'$ oc patch service apicast -p '{"spec":{"ports":[{"name":"httpsproxy","port":8443,"protocol":"TCP"}]}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow 기본 경로 삭제
oc delete route api-apicast-staging
$ oc delete route api-apicast-stagingCopy to Clipboard Copied! Toggle word wrap Toggle overflow apicast서비스를 경로로 노출oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
$ oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAINCopy to Clipboard Copied! Toggle word wrap Toggle overflow 참고이 단계는 사용할 모든 API에 대해 필요하며 모든 API의 도메인 변경에 필요합니다.
자리 표시자에 [ECDHE_user_key]를 지정하여 이전에 배포된 게이트웨이가 작동하고 구성이 저장되었는지 확인합니다.
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
정책 체인에서 TLS 클라이언트 인증서 검증 구성
정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하려면 3scale 로그인 자격 증명이 필요합니다. 또한 TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast를 구성해야 합니다.
- API에 TLS 클라이언트 인증서 유효성 검사 정책을 추가하려면 3scale API Management 관리 포털에서 정책 활성화에 설명된 단계를 수행하고 TLS 클라이언트 인증서 유효성 검사를 선택합니다.
- TLS 클라이언트 인증서 유효성 검사 링크를 클릭합니다.
- 정책을 활성화하려면 Enabled 확인란을 선택합니다.
-
허용 목록에 인증서를 추가하려면 더하기
+아이콘을 클릭합니다. -
-----BEGINECDHERTIFICATE----및 -------을 포함한 인증서를 지정합니다. - TLS 클라이언트 인증서 유효성 검사를 사용하여 API 설정을 완료하면 정책 업데이트를 클릭합니다.
추가 사항:
-
더하기
+아이콘을 클릭하여 더 많은 인증서를 추가할 수 있습니다. - 위쪽 및 아래쪽 화살표를 클릭하여 인증서를 재구성할 수도 있습니다.
변경 사항을 저장하려면 업데이트 정책 체인 ( Update Policy Chain )을 클릭합니다.
TLS 클라이언트 인증서 유효성 검사 정책의 기능 확인
TLS 클라이언트 인증서 유효성 검사 정책의 기능을 확인하려면 3scale 로그인 자격 증명이 필요합니다. 또한 TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast를 구성해야 합니다.
자리 표시자에서 [ECDHE_user_key] 를 지정하여 적용된 정책을 확인할 수 있습니다.
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt
허용 목록에서 인증서 제거
허용 목록에서 인증서를 제거하려면 3scale 로그인 자격 증명이 필요합니다. TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast를 설정해야 합니다. 정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하여 허용 목록에 인증서를 추가해야 합니다.
- TLS 클라이언트 인증서 유효성 검사 링크를 클릭합니다.
-
허용 목록에서 인증서를 제거하려면
x아이콘을 클릭합니다. - 인증서 제거를 완료되면 정책 업데이트를 클릭합니다.
변경 사항을 저장하려면 업데이트 정책 체인 ( Update Policy Chain )을 클릭합니다.
인증서 사용에 대한 자세한 내용은 Red Hat Certificate System 을 참조하십시오.
3.1.33. TLS 종료 링크 복사링크가 클립보드에 복사되었습니다!
이 섹션에서는 정책에서 개념, 구성, 확인 및 파일 삭제와 같은 TLS(Transport Layer Security) 종료 정책에 대한 정보를 제공합니다.
TLS 종료 정책을 사용하면 모든 API에 단일 인증서를 사용하지 않고 각 API에 대한 TLS 요청을 완료하도록 APIcast를 구성할 수 있습니다. APIcast는 클라이언트에 대한 연결을 설정하기 전에 구성 설정을 가져옵니다. 이러한 방식으로 APIcast는 정책의 인증서를 사용하여 TLS를 종료합니다. 이 정책은 다음 소스와 함께 작동합니다.
- 정책 구성에 저장됩니다.
- 파일 시스템에 저장됩니다.
기본적으로 이 정책은 정책 체인에서 활성화되어 있지 않습니다.
정책 체인에서 TLS 종료 구성
이 섹션에서는 PEM(개인 정보 기능 개선) 형식의 인증서와 함께 정책 체인에서 TLS 종료를 구성하는 사전 요구 사항 및 단계에 대해 설명합니다. 사전 요구 사항은 다음과 같습니다.
- 사용자가 발급한 인증서입니다.
- PEM 형식의 서버 인증서입니다.
- PEM 형식의 인증서 개인 키입니다.
다음 절차를 따르십시오.
- API에 TLS 종료 정책을 추가하려면 표준 정책 활성화 및 TLS 종료를 선택합니다.
- TLS 종료 링크를 클릭합니다.
- 정책을 활성화하려면 Enabled 확인란을 선택합니다.
-
정책에 TLS 인증서를 추가하려면 더하기
+아이콘을 클릭합니다. 인증서 소스를 선택합니다.
포함된 인증서 는 기본적으로 선택됩니다. 다음 인증서를 업로드합니다.
- PEM 형식 인증서 개인 키: 찾아보기 를 클릭하여 선택하고 업로드합니다.
- PEM 형식 인증서: 찾아보기 를 클릭하여 선택하고 업로드합니다.
파일 시스템의 인증서 - 다음 인증서 경로를 선택하고 지정합니다.
- 인증서 경로
- 인증서 개인 키 경로
- TLS 종료로 API 설정을 완료하면 업데이트 정책 을 클릭합니다.
추가 사항:
-
더하기
+아이콘을 클릭하여 더 많은 인증서를 추가할 수 있습니다. - 위쪽 및 아래쪽 화살표를 클릭하여 인증서를 재구성할 수도 있습니다.
변경 사항을 저장하려면 업데이트 정책 체인 ( Update Policy Chain )을 클릭합니다.
TLS 종료 정책의 기능 확인
3scale 로그인 자격 증명이 있어야 합니다. TLS 종료 정책을 사용하여 APIcast를 구성해야 합니다.
정책이 다음 명령으로 작동하는 경우 명령줄에서 테스트할 수 있습니다.
curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v
curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v
다음과 같습니다.
public_URL
스테이징 공용 기본 URL입니다.
port
포트 번호입니다.
user_key
인증할 사용자 키입니다.
path_to_certificate
로컬 파일 시스템의 CA 인증서 경로입니다.
TLS 종료에서 파일 제거
이 섹션에서는 TLS 종료 정책에서 인증서 및 키 파일을 제거하는 단계를 설명합니다.
- 3scale 로그인 자격 증명이 필요합니다.
- TLS 종료 정책을 사용하여 APIcast를 구성하여 정책에 인증서를 추가해야 합니다.
인증서를 제거하려면 다음을 수행합니다.
- TLS 종료 링크를 클릭합니다.
-
인증서와 키를 제거하려면
x아이콘을 클릭합니다. - 인증서 제거를 완료되면 정책 업데이트를 클릭합니다.
변경 사항을 저장하려면 업데이트 정책 체인 ( Update Policy Chain )을 클릭합니다.
3.1.34. 업스트림 링크 복사링크가 클립보드에 복사되었습니다!
업스트림 정책을 사용하면 정규식을 사용하여 Host 요청 헤더를 구문 분석하고 Private Base URL에 정의된 업스트림 URL을 다른 URL로 교체할 수 있습니다.
예를 들면 다음과 같습니다.
regex /foo 가 있는 정책 및 URL 필드 newexample.com 은 URL https://www.example.com/foo/123/ 을 newexample.com으로 바꿉니다.
정책 체인 참조:
| 속성 | description | 값 | 필수 여부 |
|---|---|---|---|
| regex |
| data type: string, 유효한 정규식 구문 | 제공됨 |
| url |
| data type: string, 이 URL이 유효한 URL인지 확인하십시오. | 제공됨 |
정책 오브젝트 예
정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.35. 업스트림 연결 링크 복사링크가 클립보드에 복사되었습니다!
업스트림 연결 정책을 사용하면 3scale 설치에서 API 백엔드 서버를 구성한 방법에 따라 각 API에 대해 다음 지시문의 기본값을 변경할 수 있습니다.
-
proxy_connect_timeout -
proxy_send_timeout -
proxy_read_timeout
업스트림 연결 정책을 구성하려면 다음을 수행합니다.
- 3scale 설치에 액세스할 수 있어야 합니다.
- 모든 배포가 완료될 때까지 기다려야 합니다.
다음 절차를 따르십시오.
- API에 Upstream 연결 정책을 추가하려면 3scale API Management 관리 포털에서 정책 활성화에 설명된 단계를 수행하고 Upstream Connection 을 선택합니다.
- 업스트림 연결 링크를 클릭합니다.
- 정책을 활성화하려면 Enabled 확인란을 선택합니다.
업스트림 연결에 대한 옵션을 구성합니다.
-
send_timeout -
connect_timeout -
read_timeout
-
- 업스트림 연결을 사용하여 API 설정을 완료하면 업데이트 정책 을 클릭합니다.
변경 사항을 저장하려면 업데이트 정책 체인 ( Update Policy Chain )을 클릭합니다.
3.1.36. 업스트림 상호 TLS 링크 복사링크가 클립보드에 복사되었습니다!
업스트림 상호 TLS 정책을 사용하면 구성에 설정된 인증서를 기반으로 APIcast와 업스트림 API 간에 상호 TLS 연결을 설정하고 검증할 수 있습니다.
verify 필드가 활성화되면 정책은 업스트림 API에서 서버 인증서도 확인합니다. ca_certificates 에는 APIcast가 서버의 유효성을 확인하는 데 사용하는 ------ BEGINECDHERTIFICATE----- 및 -----END ECDHERTIFICATE-------를 포함하여 개인 정보 보안 강화된 SASL(PEM) 형식의 인증서가 포함되어 있습니다.
검증 필드를 활성화해야 하며 업스트림 API의 인증서를 확인하기 위해 ca_certificates 가 채워야 합니다. verify 필드가 활성화되지 않으면 업스트림 API의 APIcast 인증서 확인만 발생합니다.
정책 체인에서 업스트림 TLS를 구성하려면 3scale 설치에 액세스할 수 있어야 합니다.
- Upstream 상호 TLS 정책을 API에 추가하려면 3scale API Management 관리 포털에서 정책 활성화에 설명된 단계를 수행하고 Upstream Mutual TLS 를 선택합니다.
- 업스트림 상호 TLS 링크를 클릭합니다.
- 정책을 활성화하려면 Enabled 확인란을 선택합니다.
인증서 유형 선택:
path
OpenShift에서 생성한 인증서와 같은 인증서 경로를 지정하려면 다음을 수행합니다.
포함됨
타사 생성된 인증서를 파일 시스템에서 업로드하여 사용하려는 경우.
- 인증서 에서 클라이언트 인증서를 지정합니다.
- 인증서 키의 키를 나타냅니다.
- 업스트림 상호 TLS를 사용하여 API 설정을 완료하면 정책 체인 업데이트 를 클릭합니다.
변경 사항을 승격하려면 다음을 수행합니다.
- [=<_product] 페이지 > 통합 > 설정으로 이동합니다.
- APIcast 구성에서 v #을 클릭하여 APIcast를 스테이징합니다.
V # 은 승격할 구성의 버전 번호를 나타냅니다.
경로 구성
다음과 같이 OpenShift 및 Kubernetes 시크릿의 인증서 경로를 사용합니다.
임베디드 구성
http 양식 및 파일 업로드에 다음 구성을 사용합니다.
추가 필드인 ca_certificates 에 대한 자세한 내용을 확인하고 Upstream Mutual TLS, 정책 구성 스키마를 확인합니다.
추가 고려 사항
업스트림 상호 TLS 정책은 APICAST_PROXY_PROXY_CERTIFICATE_KEY 및 APICAST_PROXY_HTTPS_CERTIFICATE 환경 변수 값을 덮어씁니다. 정책에 의해 설정된 인증서를 사용하므로 해당 환경 변수가 적용되지 않습니다.
3.1.37. URL 재작성 링크 복사링크가 클립보드에 복사되었습니다!
URL 재작성 정책을 사용하면 요청 및 쿼리 문자열의 경로를 수정할 수 있습니다.
3scale APIcast 정책과 결합하면 정책 체인의 APIcast 정책 앞에 URL Rewriting 정책이 배치되면 APIcast 매핑 규칙이 수정된 경로에 적용됩니다. 정책 체인에서 APIcast 이후에 URL 재작성 정책이 배치되면 매핑 규칙이 원래 경로에 적용됩니다.
정책은 다음 두 가지 작업 세트를 지원합니다.
명령
요청 경로를 다시 작성하는 데 적용할 명령 목록입니다.
query_args_commands
요청의 쿼리 문자열을 다시 작성하는 데 적용할 명령 목록입니다.
경로 재작성 명령
다음은 명령 목록의 각 명령이 구성된 구성 매개변수입니다.
op
적용할 작업입니다. 사용 가능한 옵션은
sub및gsub입니다.하위작업은 첫 번째 일치 항목만 지정된 정규식으로 대체합니다.gsub작업은 일치하는 모든 항목이 지정된 정규식으로 교체됩니다. 하위 및 g sub 작업에 대한 설명서를 참조하십시오.regex
일치시킬 Perl 호환 정규식입니다.
replace
일치하는 경우 사용되는 대체 문자열입니다.
options
이는 선택 사항입니다. regex 일치를 수행하는 방법을 정의하는 옵션입니다. 사용 가능한 옵션에 대한 자세한 내용은 OpenResty Lua 모듈 프로젝트 설명서의 ngx.re.match 섹션을 참조하십시오.
break
이는 선택 사항입니다. 확인란이 활성화된 상태에서 true로 설정하면 명령이 마지막 URL이 적용되고 목록의 모든 후행 명령이 삭제됩니다.
쿼리 문자열 재작성하기 위한 명령
다음은 query_args_commands 목록의 각 명령이 구성된 구성 매개변수입니다.
op
쿼리 인수에 적용할 작업입니다. 다음 옵션을 사용할 수 있습니다.
add
기존 인수에 값을 추가합니다.
set
설정되지 않은 경우 arg를 생성하고 설정 시 값을 바꿉니다.
push
설정되지 않은 경우 arg를 생성하고 설정 시 값을 추가합니다.
삭제
arg를 삭제합니다.
ARG
작업이 적용되는 쿼리 인수 이름입니다.
value
쿼리 인수에 사용되는 값을 지정합니다. 값 유형 "liquid"의 경우 값은
{{ variable_from_context }}형식이어야 합니다.삭제작업의 경우 값이 고려되지 않습니다.value_type
이는 선택 사항입니다. 쿼리 인수 값이 평가되는 방법을 정의하고 일반 텍스트의 경우
일반텍스트 또는 리쿼드 템플릿으로 평가를 위한유동성일 수 있습니다. 자세한 내용은 4.1절. “정책에서 변수 및 필터 사용”의 내용을 참조하십시오. 지정하지 않으면 기본적으로 "plain" 유형이 사용됩니다.
예제
URL 재작성 정책은 다음과 같이 구성됩니다.
APIcast로 전송되는 원래 요청 URI입니다.
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
URL 재작성을 적용한 후 API 백엔드에 API 캐스트가 전송하는 URI입니다.
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
다음과 같은 변환이 적용됩니다.
-
하위 문자열
/api/v1/은 유일한 경로 재작성 명령과 일치하며/internal/로 교체됩니다. -
user_key쿼리 인수가 삭제됩니다. -
value
pushvalue가pusharg쿼리 인수에 추가 값으로 추가됩니다. -
쿼리 인수
setarg의 값은 구성된 값setvalue로 교체됩니다. -
쿼리 인수
가 원래 URL에 존재하지 않기 때문에 명령 추가가 적용되지 않았습니다.addarg
정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale API Management 섹션에서 정책 체인 생성 을 참조하십시오.
3.1.38. 캡처를 사용하여 URL 다시 쓰기 링크 복사링크가 클립보드에 복사되었습니다!
캡처를 사용하여 URL 재작성 정책은 URL 재작성 정책의 대안이며 API 백엔드에 전달하기 전에 API 요청의 URL을 다시 작성할 수 있습니다.
Captures로 URL Rewritings 정책은 URL에서 인수를 검색하고 다시 작성된 URL에서 해당 값을 사용합니다.
정책은 변환 구성 매개변수를 지원합니다. 요청 URL에 적용되는 변환을 설명하는 오브젝트 목록입니다. 각 트랜션 오브젝트는 다음 두 가지 속성으로 구성됩니다.
match_rule
이 규칙은 들어오는 요청 URL과 일치합니다.
{nameOfArgument}형식으로 이름이 지정된 인수를 포함할 수 있습니다. 이러한 인수는 다시 작성된 URL에서 사용할 수 있습니다. URL은match_rule과 정규식으로 비교됩니다. 이름이 지정된 인수와 일치하는 값은 다음 문자(PCRE regex 표기법)만 포함해야 합니다.[\w-.~%!$&'()*,;=@:]. 다른 regex 토큰은 문자열 시작 부분에^, 문자열 끝에$와 같은match_rule표현식에 사용할 수 있습니다.템플릿
원래 URL을 사용하여 다시 작성하는 URL 템플릿입니다.
match_rule에서 이름이 지정된 인수를 사용할 수 있습니다.
원래 URL의 쿼리 매개변수는 템플릿에 지정된 쿼리 매개변수와 병합됩니다.
예제
Captures로 URL Rewritings 정책은 다음과 같이 구성됩니다.
APIcast로 전송되는 원래 요청 URI입니다.
https://api.example.com/api/v1/products/123/details?user_key=abc123secret
https://api.example.com/api/v1/products/123/details?user_key=abc123secret
URL 재작성을 적용한 후 API 백엔드에 API 캐스트가 전송하는 URI입니다.
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
3.1.39. WebSocket 링크 복사링크가 클립보드에 복사되었습니다!
WebSocket 정책은 업스트림 API에 WebSocket 프로토콜 연결을 활성화합니다. WebSocket 프로토콜을 활성화하려면 다음을 고려하십시오.
WebSocket 프로토콜은 추가 헤더를 허용하지 않습니다.
- 인증 정보 위치에 대한 쿼리 매개 변수를 사용하여 WebSocket 정책을 구성합니다.
- WebSocket 정책은 OIDC(OpenID Connect) 인증 방법을 지원하지 않습니다.
- WebSocket 프로토콜은 HTTP/2 표준의 일부가 아닙니다.
WebSocket 연결을 활성화하는 지정된 업스트림 API의 경우 해당 백엔드를 http[s] 또는 ws[s] 로 정의할 수 있습니다.
정책 체인에 WebSocket 정책을 추가하는 경우 3scale API Management APIcast 정책 이전이어야 합니다.
3.2. 3scale API Management 표준 정책의 정책 체인 링크 복사링크가 클립보드에 복사되었습니다!
각 API 제품에 대해 정책 체인을 지정할 수 있습니다. 정책 체인은 다음을 수행합니다.
- APIcast가 요청에 적용되는 정책을 지정합니다.
- 해당 정책에 대한 구성 정보를 제공합니다.
- APIcast가 정책을 적용하는 순서를 결정합니다.
체인에서 정책을 올바르게 정렬하려면 APIcast가 정책을 API 소비자 요청에 적용하는 방법을 이해해야합니다.
3.2.1. APIcast NGINX 단계 3scale API Management 정책을 처리하는 방법 링크 복사링크가 클립보드에 복사되었습니다!
3scale API 게이트웨이 또는 APIcast는 NGINX 프록시 웹 서버를 사용하여 정책을 적용합니다. APIcast가 API 소비자로부터 요청을 수신하면 APIcast는 순서가 지정된 일련의 NGINX 단계로 요청을 처리합니다. 각 NGINX 단계에서 APIcast는 다음 정책을 적용하여 원래 요청을 수정할 수 있습니다.
- 업스트림 API 정책 체인의 정책입니다. 정책 체인은 순서가 지정된 정책 목록입니다. 기본적으로 업스트림 API의 정책 체인에는 3scale APIcast 정책이 포함됩니다. API 공급자는 3scale 제품의 정책 체인에 정책을 추가할 수 있습니다. APIcast는 업스트림 API 정책 체인의 정책을 해당 업스트림 API로만 전송되는 API 소비자 요청에 적용합니다.
- 글로벌 3scale 정책 체인의 정책입니다. API 공급자는 3scale 환경 변수를 설정하여 글로벌 정책 체인을 업데이트할 수 있습니다. APIcast는 글로벌 정책 체인의 정책을 모든 API 소비자 요청에 적용합니다.
동일한 정책이 업스트림 API 정책 체인과 글로벌 정책 체인에 있는 경우 업스트림 API 정책 체인의 정책 구성이 우선합니다.
APIcast가 모든 NGINX 단계에서 필요한 처리를 수행한 후 APIcast는 요청의 결과를 업스트림 API로 보냅니다. 결과적으로, 원하는 동작을 달성하기 위해서는 처리가 API 소비자 요청을 수정할 수 있기 때문에 NGINX 단계 프로세스 정책의 순서를 이해하는 것이 중요합니다.
NGINX 단계의 순서 및 설명
APIcast가 API 소비자로부터 요청을 수신하면 APIcast는 업스트림 API의 정책 체인과 글로벌 정책 체인에 정책을 적용하여 요청을 처리합니다. 각 3scale 정책은 하나 이상의 함수를 정의합니다. APIcast는 순서가 지정된 일련의 NGINX 단계에서 정책 함수를 실행합니다. 각 단계에서 NGINX는 적용되는 정책에 정의된 함수를 실행하고 해당 단계에서 실행을 지정합니다. 다음 표에는 정책 함수를 실행하는 NGINX 단계가 나열되어 있습니다. 이 표에 나열되지 않은 추가 NGINX 단계는 정책 체인의 정책 순서에 영향을 받지 않는 처리를 수행합니다.
| NGINX 단계 | 이 단계의 처리 설명 |
|---|---|
|
| 요청의 대상 URI를 수정하는 모든 함수를 실행합니다. |
|
| 클라이언트의 요청 권한을 확인하는 모든 함수를 실행합니다. |
|
|
업스트림 API로 전송할 요청 콘텐츠를 생성합니다. |
|
| 로드 밸런싱 기능을 실행합니다. |
|
| 요청 헤더를 처리하는 모든 함수를 실행합니다. |
|
| 요청 본문을 처리하는 모든 함수를 실행합니다. |
|
| NGINX가 헤더와 본문에서 함수를 실행한 후 요청을 처리하는 모든 함수를 실행합니다. |
|
| 요청에 대한 로그 정보를 생성합니다. |
|
| Prometheus 끝점에서 수신한 모든 데이터에서 작동합니다. |
정책 순서의 영향을 받지 않는 처리를 수행하는 NGINX 단계의 예:
-
APIcast가 시작되면 NGINX는
init단계와 관련된 작업을 실행합니다. -
APIcast 작업자가 시작되면 NGINX는
init_worker단계와 관련된 작업을 실행합니다. -
APIcast가 HTTPS 연결을 종료하면 NGINX는
ssl_certificate단계와 관련된 작업을 실행합니다.
NGINX가 정책 함수를 실행하는 순서
API 공급자는 3scale 제품에 하나 이상의 정책을 추가하여 정책 체인을 구성할 수 있습니다. 각 단계에서 NGINX는 해당 단계에서 실행을 지정하는 정책 함수만 처리합니다. 각 정책 함수는 하나의 NGINX 단계에서 처리하는 동안 APIcast가 기본 동작을 변경하는 방법을 지정합니다. 예를 들어 header_filter 단계에서 NGINX는 header_filter 를 지정하고 요청 헤더에서 정상적으로 작동하는 함수를 처리합니다. 각 단계에서 NGINX는 관련 기능을 정책 체인에 있는 순서대로 처리합니다.
정책은 컨텍스트 오브젝트를 통해 데이터를 공유할 수 있습니다. 정책은 각 단계에서 컨텍스트 오브젝트를 읽고 수정할 수 있습니다.
NGINX가 정책 함수를 실행하는 순서는 다음에 따라 다릅니다.
- 정책 체인의 정책 위치
- 특정 정책 기능을 처리하는 NGINX 단계
필요한 동작을 얻으려면 정책 체인의 위치에 따라 정책 적용 결과가 다를 수 있으므로 정책 체인의 순서를 올바르게 지정해야 합니다. 다음 다이어그램에서는 NGINX에서 정책을 적용하는 순서의 예를 보여줍니다.
이전 그림에서 정책 A 는 정책 체인에서 먼저 사용됩니다. 그러나 NGINX는 NGINX의 첫 번째 단계인 재작성 단계와 관련이 있기 때문에 먼저 정책 B 에서 함수를 처리합니다.
이제 정책 A 및 정책 B 가 포함된 제품의 정책 체인을 다음과 같이 고려하십시오.
정책 A 는 다음을 지정합니다.
-
NGINX가
액세스단계에서 실행되도록 하는 함수A1 -
NGINX가
header_filter단계에서 실행되도록A2함수
-
NGINX가
정책 B 는 다음을 지정합니다.
-
NGINX의 함수
B1이재작성단계에서 실행됨 -
NGINX가
header_filter단계에서 실행되도록 하는 함수B2
-
NGINX의 함수
다음 그림은 NGINX가 제품의 정책 기능을 실행하는 순서를 보여줍니다.
APIcast가 이 제품에서 노출한 업스트림 API에 대한 액세스를 수신하면 APIcast는 제품의 정책 체인을 확인하고 다음 표에 설명된 대로 함수를 실행합니다.
| NGINX 단계 | NGINX가 이 단계에서 실행되는 함수 |
|---|---|
|
|
정책 B 가 |
|
|
정책 A 가 |
|
|
정책 A 또는 정책 B 는 |
|
|
정책 A 또는 정책 B 는 |
|
|
정책 체인은 정책 A 및 정책 B 를 지정합니다. 결과적으로 이 단계는 A 정책 A가 |
|
| 정책 A 또는 정책 B 는 이 단계에서 실행할 함수를 지정하지 않습니다. |
|
| 정책 A 또는 정책 B 는 이 단계에서 실행할 함수를 지정하지 않습니다. |
|
| 정책 A 또는 정책 B 는 이 단계에서 실행할 함수를 지정하지 않습니다. |
이 예에서 정책 A 는 정책 체인에 있지만 정책 B 의 함수는 NGINX가 실행하는 첫 번째 기능입니다. 이는 정책 B 가 다른 단계보다 먼저 발생하는 재작성 단계에서 NGINX 프로세스에서 처리하는 함수 B1 을 지정하기 때문입니다.
다른 예를 들어 다음 정책 체인을 고려하십시오.
- URL 재작성
- 3scale APIcast (모든 제품에 할당된 기본 정책)
URL 재작성 정책은 요청의 대상 경로를 수정합니다. APIcast는 재작성 단계에서 URL Rewriting 함수를 실행합니다. 3scale APIcast 정책은 APIcast가 재작성 단계에서 실행되는 함수와 APIcast가 세 단계로 실행되는 함수를 정의합니다. URL 재작성 정책이 처음 이면 3scale APIcast 정책은 다시 작성된 경로에 매핑 규칙을 적용합니다. 3scale APIcast 정책이 첫 번째이고 URL Rewriting 정책이 두 번째인 경우 3scale APIcast 정책은 매핑 규칙을 원래 경로에 적용합니다.
3.2.2. 3scale API Management 관리 포털에서 정책 체인 수정 링크 복사링크가 클립보드에 복사되었습니다!
3scale 관리 포털에서 제품 정책 체인을 APIcast 게이트웨이 구성의 일부로 수정합니다.
절차
- 3scale에 로그인합니다.
- 에 대한 정책 체인을 구성할 API 제품으로 이동합니다.
- [your_product_name] > 통합 > 정책에서 정책 추가를 클릭합니다.
- 정책 체인 섹션에서 화살표 아이콘을 사용하여 정책 체인의 정책을 다시 정렬합니다.
- Update Policy Chain 을 클릭하여 정책 체인을 저장합니다.
다음 단계
Admin Portal의 왼쪽 탐색 패널에서 이제 APIcast로 승격하지 않은 구성 변경 사항이 있음을 나타내는 경고가 있습니다. APIcast에 정책 체인 업데이트를 승격하고 필요에 따라 업데이트를 테스트합니다. 원하는 동작을 확인한 후 업데이트를 Production APIcast로 승격합니다. APICAST_CONFIGURATION_CACHE 환경 변수가 0보다 큰 숫자(기본값)로 설정된 경우 APIcast에서 업데이트된 구성을 사용하는 데 해당 수 시간이 걸립니다.
3.2.3. JSON 구성 파일에서 3scale API Management 정책 체인 생성 링크 복사링크가 클립보드에 복사되었습니다!
APIcast의 기본 배포를 사용하는 경우 JSON 구성 파일을 생성하여 외부에서 정책 체인을 제어할 수 있습니다.
JSON 구성 파일 정책 체인에는 다음 정보로 구성된 JSON 배열이 포함되어 있습니다.
-
id값이 있는services는 정책 체인이 숫자별로 적용되는 서비스를 지정합니다. -
policy_chain개체 및 후속 개체를 포함하는프록시오브젝트입니다. -
policy_chain개체: 정책 체인을 정의하는 값을 포함합니다. -
정책을식별하고 정책 동작을 구성하는 데 필요한이름및구성데이터를 모두 지정하는 개별 정책 오브젝트
다음은 사용자 정의 정책 sample_policy_1 및 API 인트로스펙션 표준 정책 token_introspection 에 대한 정책 체인의 예입니다.
모든 정책 체인에는 내장 정책 apicast 가 포함되어야합니다. 정책 체인에 apicast 정책을 배치하면 정책 동작에 영향을 미칩니다.
3.2.4. 3scale API Management 표준 정책 기능을 실행하는 NGINX 단계 링크 복사링크가 클립보드에 복사되었습니다!
다음 표에는 NGINX가 해당 단계에서 실행되는 함수를 정의하는 표준 정책이 포함된 기본 NGINX 단계가 나열되어 있습니다. 표에는 NGINX가 처리하는 순서대로 단계가 나열되어 있습니다.
정책 체인은 특정 단계에서 NGINX가 처리하는 정책을 두 개 이상 포함할 수 있습니다. 이 경우 체인의 정책 순서가 원하는 결과를 얻기 위해 API 요청을 처리하는 올바른 순서인지 확인합니다. 표에는 정책이 알파벳순으로 나열됩니다.
| NGINX 단계 | 이 단계에서 처리되는 함수를 정의하는 표준 정책 |
|---|---|
|
|
3scale APIcast |
|
|
3scale APIcast |
|
|
3scale APIcast |
|
| 업스트림 상호 TLS |
|
|
|
|
| 응답/요청 콘텐츠 제한 |
|
|
3scale APIcast |
|
|
엣지 제한 |
3.2.5. 3scale API Management 표준 정책 및 이를 처리하는 NGINX 단계 링크 복사링크가 클립보드에 복사되었습니다!
다음 표에는 표준 정책과 NGINX 단계 또는 해당 정책의 기능 또는 함수가 나열되어 있습니다. 이 표를 사용하여 정책 체인에서 정책을 올바르게 정렬하여 업스트림 API에 대한 올바른 요청을 생성합니다.
| 표준 정책 | 정책 함수를 실행하는 NGINX 단계 |
|---|---|
| 3scale APIcast |
|
| 익명 액세스 |
|
| 3scale 인증 캐싱 | 정책 체인에서는 이 정책의 위치는 중요하지 않습니다. |
| 3scale Batcher |
|
| 3scale Referrer |
|
| Camel 서비스 |
|
| 조건부 정책 | 정책 체인에서는 이 정책의 위치는 중요하지 않습니다. |
| 콘텐츠 캐싱 |
|
| CORS 요청 처리 |
|
| 사용자 정의 메트릭 |
|
| echo |
|
| 엣지 제한 |
|
| 헤더 수정 |
|
| HTTP 응답 코드 덮어쓰기 |
|
| IP 확인 |
|
| JWT 클레임 확인 |
|
| 유동적인 컨텍스트 디버그 |
|
| 로깅 |
|
| 유지 관리 모드 |
|
| NGINX 필터 |
|
| OAuth 2.0 상호 TLS 클라이언트 인증 |
|
| OAuth 2.0 토큰 인트로스펙션 |
|
| 프록시 서비스 | 정책 체인에서는 이 정책의 위치는 중요하지 않습니다. |
| 속도 제한 헤더 |
|
| 응답/요청 콘텐츠 제한 |
|
| Retry | 정책 체인에서는 이 정책의 위치는 중요하지 않습니다. |
| rh-SSO/Keycloak 역할 검사 |
|
| 라우팅 |
|
| SOAP |
|
| TLS 클라이언트 인증서 검증 |
|
| TLS 종료 |
|
| 업스트림 |
|
| 업스트림 연결 | 정책 체인에서는 이 정책의 위치는 중요하지 않습니다. |
| 업스트림 상호 TLS |
|
| URL 재작성 |
|
| 캡처를 사용하여 URL 다시 쓰기 |
|
| WebSocket |
|
3.3. API를 사용하여 프록시 정책 체인 수정 링크 복사링크가 클립보드에 복사되었습니다!
정책 체인에서 정책을 관리하려면 3scale 관리 포털을 사용하는 대신 계정 관리 API를 사용할 수 있습니다. API라고 하는 계정 관리 API를 사용하면 API 트래픽을 제어하는 프록시 정책 체인을 변경할 수 있습니다. 정책을 추가, 제거, 재정렬 또는 수정하여 전체 기능을 프록시 정책 체인 업데이트 라는 엔드포인트로 처리할 수 있습니다. 프록시 정책 체인 업데이트 끝점을 사용하여 API를 호출합니다.
PUT /admin/api/services/{service_id}/proxy/policies.json
PUT /admin/api/services/{service_id}/proxy/policies.json
엔드포인트 호출에는 요청 본문에 access_token 및 policies_config 매개변수가 포함되어야 합니다. policies_config 요청 본문 매개변수는 URL로 인코딩된 JSON 배열이어야 합니다. 배열의 각 요소는 정책 구성을 나타냅니다.
프록시 정책 체인 업데이트 끝점은 업데이트된 프록시 정책 체인을 반환합니다. 입력이 잘못된 경우 오류가 발생합니다.
정책 체인을 보려면 계정 관리 API에 대해 다음 GET 호출을 사용합니다.
GET /admin/api/services/{service_id}/proxy/policies.json
GET /admin/api/services/{service_id}/proxy/policies.json
GET 호출 예제 정책 체인 출력
이전 JSON 응답에서 policies_config 속성의 페이로드는 프록시 정책 체인 업데이트 엔드포인트에 대한 호출에서 policies_config 매개변수의 예상 값을 나타내는 배열입니다.
3.3.1. curl 명령을 사용하여 정책 체인 업데이트 링크 복사링크가 클립보드에 복사되었습니다!
다음 예제에서는 curl 명령과 jq 툴을 사용하여 프록시 정책 체인을 읽고 업데이트하는 방법을 보여줍니다. 자리 표시자 값 {admin_portal_url}, {service_id}, {access_token} 을 사용자 환경을 나타내는 값으로 바꿉니다.
3.3.1.1. curl 요청에 policies_config 인라인 제공 링크 복사링크가 클립보드에 복사되었습니다!
절차
현재 정책 체인을 가져옵니다.
curl -s "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json?access_token={access_token}" | jq '.policies_config' -c$ curl -s "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json?access_token={access_token}" | jq '.policies_config' -cCopy to Clipboard Copied! Toggle word wrap Toggle overflow 참고-
curl의-s옵션을 사용하면 "실질" 모드가 요청 응답에 속하지 않는 출력을 억제할 수 있습니다. -
jq '.policies_config'는 응답의policies_configJSON 속성에서 정책 체인 배열을 추출합니다. -
jq툴의-C 옵션은 여러 행을 방지하기 위해 출력을 컴팩트 모드로 출력합니다.
이 명령은 정책 체인의 CORS 및 APIcast 정책을 표시하는 응답을 반환합니다. 예를 들면 다음과 같습니다.
[{"name":"cors","version":"builtin","configuration":{"allow_headers":[],"allow_methods":["GET","POST","PUT"],"allow_origin":"https://example.com","allow_credentials":true},"enabled":true},{"name":"apicast","version":"builtin","configuration":{},"enabled":true}][{"name":"cors","version":"builtin","configuration":{"allow_headers":[],"allow_methods":["GET","POST","PUT"],"allow_origin":"https://example.com","allow_credentials":true},"enabled":true},{"name":"apicast","version":"builtin","configuration":{},"enabled":true}]Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
- 체인에 정책을 추가, 제거 또는 재정렬하거나 구성을 변경하여 정책 체인을 편집합니다.
정책 체인을 업데이트합니다.
다음
curl명령 예에서 CORS 정책은 체인에서 제거되지만 정책 체인에 대한 다른 변경을 수행할 수 있습니다.curl -X PUT "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json" -d 'access_token={access_token}' -d 'policies_config=[{"name":"apicast","version":"builtin","configuration":{},"enabled":true}]'$ curl -X PUT "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json" -d 'access_token={access_token}' -d 'policies_config=[{"name":"apicast","version":"builtin","configuration":{},"enabled":true}]'Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.3.1.2. 파일에서 policies_config 콘텐츠 제공 링크 복사링크가 클립보드에 복사되었습니다!
절차
현재 정책 체인을 파일에 저장합니다.
curl -s "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json?access_token={access_token}" | jq '.policies_config' > policies_config.jsoncurl -s "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json?access_token={access_token}" | jq '.policies_config' > policies_config.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
체인에 정책을 추가, 제거 또는 다시 정렬하거나 구성을 변경하여
policies_config.json파일에서 정책 체인을 편집합니다. 정책 체인을 업데이트합니다.
curl -X PUT "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json" -d 'access_token={access_token}' --data-urlencode policies_config@policies_config.json$ curl -X PUT "{admin_portal_url}/admin/api/services/{service_id}/proxy/policies.json" -d 'access_token={access_token}' --data-urlencode policies_config@policies_config.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow
3.4. 사용자 정의 3scale API Management APIcast 정책 링크 복사링크가 클립보드에 복사되었습니다!
APIcast 동작을 수정하도록 사용자 정의 정책을 구성합니다. 먼저 사용자 지정 정책을 포함하여 APIcast 정책을 구성하는 정책 체인을 정의한 다음 APIcast에 정책 체인을 추가합니다.
Red Hat 3scale은 사용자 정의 정책을 추가하는 방법을 제공하지만 사용자 정의 정책을 지원하지 않습니다.
APIcast를 위한 사용자 정의 정책은 3scale 배포 구성에 따라 다릅니다.
- 이러한 APIcast 자체 관리 배포(OpenShift의 APIcast) 및 설치한 컨테이너 환경에서 APIcast에 사용자 지정 정책을 추가합니다.
- APIcast 호스팅에 사용자 정의 정책을 추가할 수 없습니다.
프로덕션 게이트웨이에 직접 정책을 변경하지 마십시오. 항상 변경 사항을 테스트합니다.
3.4.1. 3scale API Management APIcast 배포를 위한 사용자 정의 정책 정보 링크 복사링크가 클립보드에 복사되었습니다!
사용자 정의 APIcast 정책을 완전히 생성하거나 표준 정책을 수정할 수 있습니다.
사용자 정의 정책을 생성하려면 다음을 이해해야 합니다.
- 정책은 Lua로 작성되었습니다.
- 정책을 준수하여 적절한 파일 디렉터리에 배치해야 합니다.
- 정책 동작은 정책 체인에 배치되는 방법에 따라 영향을 받습니다.
- 사용자 지정 정책을 추가하는 인터페이스는 완전히 지원되지만 사용자 지정 정책 자체는 지원되지 않습니다.
3scale API Management 인스턴스에 사용자 지정 정책을 추가하려면 3scale API Management Operator 를 사용하여 사용자 정의 정책 삽입을 참조하십시오.
3.4.2. 다른 OpenShift Container Platform에서 3scale API Management에 사용자 정의 정책 추가 링크 복사링크가 클립보드에 복사되었습니다!
통합 OpenShift Container Platform 레지스트리에서 사용자 정의 정책이 포함된 APIcast 이미지를 가져와서 OpenShift Container Platform (OCP)의 APIcast에 사용자 정의 정책을 추가할 수 있습니다.
절차
- 3scale API Management Operator를 사용하여 사용자 지정 정책 삽입
- 기본 OpenShift 클러스터에 APIcast 게이트웨이를 배포하지 않는 경우 기본 OpenShift 클러스터의 내부 레지스트리에 대한 액세스를 설정합니다.
- 3scale 2.14 APIcast OpenShift 템플릿을 다운로드 합니다.
템플릿을 수정하려면 기본
이미지디렉터리를 내부 레지스트리의 전체 이미지 이름으로 교체합니다.image: <registry>/<project>/amp-apicast:latest
image: <registry>/<project>/amp-apicast:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow OpenShift 템플릿을 사용하여 APIcast를 배포하여 사용자 지정 이미지를 지정합니다.
oc new-app -f customizedApicast.yml
$ oc new-app -f customizedApicast.ymlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
APIcast에 사용자 정의 정책이 추가되고 새 이미지가 빌드되면 해당 정책이 이미지와 함께 배포된 경우 관리 포털에서 사용 가능한 대로 자동으로 표시됩니다. 기존 서비스는 사용 가능한 정책 목록에서 이 새 정책을 볼 수 있으므로 모든 정책 체인에서 사용할 수 있습니다.
사용자 정의 정책이 이미지에서 제거되고 APIcast가 다시 시작되면 목록에서 정책을 더 이상 사용할 수 없으므로 더 이상 정책 체인에 추가할 수 없습니다.
3.4.3. 3scale API Management 사용자 정의 정책에 외부 Lua 종속 항목 포함 링크 복사링크가 클립보드에 복사되었습니다!
APIcast에서 3scale 이미지에 아직 없는 Lua 라이브러리를 사용할 수 있도록 외부 Lua 종속성을 사용자 지정 정책에 추가할 수 있습니다.
이 절차에서는 응답 본문을 JSON에서 XML로 변환하는 사용자 지정 정책 예제 를 사용하여 이 작업을 수행하는 방법을 보여줍니다. 예제 사용자 지정 정책에는 Lua로 작성된 xml2lua XML 구문 분석기가 필요합니다. 전체 예제는 빌드 및 테스트를 위해 단축되지만 예제 절차에 따라 사용자 지정 정책을 배포할 수 없습니다. 외부 Lua 종속성이 있는 사용자 정의 정책을 배포하려면 이 절차의 단계를 수행하고 다른 OpenShift Container Platform에서 3scale API Management에 사용자 지정 정책을 추가하는 절차를 수행해야 합니다.
XML에서 XML로의 JSON 사용자 지정 정책은 예제일 뿐입니다. 프로덕션 환경에서 사용할 수 없습니다.
전제 조건
- 3scale 사용자 지정 정책.
- 외부 Lua 라이브러리에 액세스할 수 있습니다.
절차
사용자 지정 정책이 포함된 디렉터리에서 외부 Lua 라이브러리를 식별하는 파일을 추가합니다.
파일 이름은
Roverfile여야 합니다. XML에서XML사용자 지정 정책 예제에서Roverfile에는 다음 내용이 있습니다.luarocks { group 'production' { module { 'xml2lua' }, } }luarocks { group 'production' { module { 'xml2lua' }, } }Copy to Clipboard Copied! Toggle word wrap Toggle overflow lua-rover는 LuaRocks 관련 래퍼입니다.lua-rover는 종속 항목에 대한 전송 잠금을 제공합니다. LuaRocks는 Lua 모듈을 위한 패키지 관리자입니다.사용자 지정 정책이 포함된 디렉터리에서
lua-rover잠금 파일을 추가합니다.파일 이름은
Roverfile.lock여야 합니다. XML에서XML사용자 지정 정책 예제에서Roverfile.lock에는 다음 내용이 있습니다.xml2lua 1.5-2||productionbash-4.4
xml2lua 1.5-2||productionbash-4.4Copy to Clipboard Copied! Toggle word wrap Toggle overflow Roverfile및Roverfile.lock을 사용하면 APIcast 또는 3scale Operator가 종속 라이브러리를 가져올 수 있습니다.사용자 지정 정책을 정의하는 파일에서 Lua 종속성을 지정하는 행을 추가합니다.
XML에서 XML사용자 지정 정책 예제에서는 다음 행을 지정합니다.local xml2lua = require("xml2lua")local xml2lua = require("xml2lua")Copy to Clipboard Copied! Toggle word wrap Toggle overflow 사용자 지정 정책을 빌드하는 데 사용하는 Dockerfile에서
Roverfile및Roverfile.lock을 복사하고rover 설치를실행합니다.XML사용자 지정 정책 예제에서는 다음 행을 Dockerfile에 추가합니다.COPY Roverfile . COPY Roverfile.lock . RUN rover install --roverfile=/opt/app-root/src/Roverfile
COPY Roverfile . COPY Roverfile.lock . RUN rover install --roverfile=/opt/app-root/src/RoverfileCopy to Clipboard Copied! Toggle word wrap Toggle overflow Dockerfile은 APIcast 또는 3scale Operator를 사용하여 정책을 빌드할 수 있습니다.
사용자 지정 정책의
Makefile에서 사용자 지정 정책에 따라빌드대상을 지정합니다.예를 들어
빌드대상은 다음과 같을 수 있습니다.TARGET_IMAGE="apicast/json_to_xml:latest" # IP="http://localhost:8080" build: docker build . --build-arg IMAGE=registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.14 -t $(TARGET_IMAGE)
TARGET_IMAGE="apicast/json_to_xml:latest" # IP="http://localhost:8080" build: docker build . --build-arg IMAGE=registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.14 -t $(TARGET_IMAGE)Copy to Clipboard Copied! Toggle word wrap Toggle overflow
다음 단계
외부 Lua 종속성이 있는 사용자 지정 정책을 배포하는 나머지 단계는 다른 사용자 지정 정책을 배포하는 것과 동일합니다. 즉, 이미지를 리포지토리로 푸시하고 APIcast 이미지를 방금 빌드한 이미지로 교체해야 합니다.
4장. APIcast 네이티브 배포와 정책 체인 통합 링크 복사링크가 클립보드에 복사되었습니다!
네이티브 APIcast 배포의 경우 THREESCALE_CONFIG_FILE 환경 변수를 사용하여 구성 파일을 지정하여 사용자 정의 정책 체인 을 통합할 수 있습니다. 다음 예제에서는 config 파일 example.json 을 지정합니다.
THREESCALE_CONFIG_FILE=example.json bin/apicast
THREESCALE_CONFIG_FILE=example.json bin/apicast
4.1. 정책에서 변수 및 필터 사용 링크 복사링크가 클립보드에 복사되었습니다!
일부 표준 정책은 일반 문자열 값뿐만 아니라 요청 컨텍스트에서 존재하는 변수도 사용할 수 있는 Liquid templatelating을 지원합니다.
컨텍스트 변수를 사용하려면 해당 이름을 {{ 및 }} 로 래핑합니다(예: {{ uri }} ). 변수가 오브젝트인 경우 해당 속성에 액세스할 수도 있습니다(예: {{ some somevar.attr }} ).
다음은 모든 정책에서 사용할 수 있는 표준 변수입니다.
URI
이 경로에서 제외된 쿼리 매개변수가 있는 요청 경로입니다. 포함된 NGINX 변수 $uri 의 값입니다.
host
요청의 호스트입니다. 이 값은 포함된 NGINX 변수 $host 의 값입니다.
remote_addr
포함된 NGINX 변수 $remote_addr 의 값인 클라이언트의 IP 주소입니다.
headers
요청 헤더를 포함하는 오브젝트입니다.
{{headers['Some-Header']}}를 사용하여 특정 헤더 값을 가져옵니다.http_method
요청 메서드: GET, POST 등.
이러한 표준 변수는 요청 컨텍스트에서 사용되지만 정책은 컨텍스트에 더 많은 변수를 추가할 수 있습니다. 단계는 APIcast의 모든 실행 단계를 나타냅니다. 다음과 같은 경우 정책 체인의 모든 정책에서 변수를 사용할 수 있습니다.
- 동일한 단계에서 변수가 정책에 추가된 경우 추가 후 다음 정책에서 사용됩니다.
- 변수가 단계에 추가되면 이 변수를 다음 단계에서 사용할 수 있습니다.
다음은 표준 3scale APIcast 정책이 컨텍스트에 추가하는 변수의 몇 가지 예입니다.
-
JWT: OpenID Connect 인증에 대한 JWT 토큰의 구문 분석된 JSON 페이로드입니다. -
credentials: 애플리케이션 자격 증명을 보유한 오브젝트입니다. 예:"app_id": "972f7b4f","user_key": "13b668c4d1e10eaebaa5144b4749713f". -
service: 현재 요청을 처리하는 서비스 구성을 보유하는 오브젝트입니다. 예: 서비스 ID는 {{ service.id }}로 사용할 수 있습니다.
컨텍스트에서 사용 가능한 전체 오브젝트 및 값 목록은 Liquid 컨텍스트 디버그 를 참조하십시오.
변수는 Liquid 템플릿의 도움말과 함께 사용됩니다. 예: {{ remote_addr }}, {{ headers['ECDHE-Header'] }}, {{ jwt.aud }}. 값에 대한 변수를 지원하는 정책에는 일반적으로 _type 접미사가 있는 특수 매개변수(예: value_type,name_type. 즉 일반 텍스트에 "plain", "liquid")가 있습니다.
APIcast는 변수 값에 적용할 수 있는 Liquid 필터도 지원합니다. 필터는 Liquid 변수의 값에 NGINX 함수를 적용합니다.
필터는 변수 출력 태그 {{ }}; 변수 이름 또는 파이프 문자 | 및 필터 이름에 따라 리터럴 값에 따라 배치됩니다. 예:
-
{{ 'username:password' | encode_base64 }}, 여기서username:password는 변수입니다. -
{{ URI | escape_uri }}
일부 필터에는 매개변수가 필요하지 않으므로 변수 대신 빈 문자열을 사용할 수 있습니다. 예: {{ '' | utctime }} 는 현재 시간을 UTC 표준 시간대로 반환합니다.
필터는 다음과 같이 연결할 수 있습니다: {{ variable | function1 | function2 }} }} 예: {{ '' | utctime | escape_uri }} }}
다음은 사용 가능한 함수 목록입니다.
5장. Fuse의 정책 확장을 사용하여 3scale API Management 메시지 콘텐츠 변환 링크 복사링크가 클립보드에 복사되었습니다!
Red Hat Fuse를 사용하여 Red Hat 3scale API Management에 대해 매우 유연한 정책 확장을 구현할 수 있습니다. OpenShift의 Fuse에서 정책 확장을 만든 다음 3scale 관리 포털에서 정책 확장을 구성할 수 있습니다. APIcast Camel 프록시 정책을 사용하면 요청 및 응답 메시지 콘텐츠(예: Apache Camel 통합 프레임워크에 구현된 XML에서 JSON으로)에서 복잡한 변환을 수행할 수 있습니다.
또한 정적 APIcast 컨테이너 이미지를 다시 빌드하고 재배포하는 대신 Camel에서 사용자 지정 정책 확장을 동적으로 추가하거나 수정할 수 있습니다. Camel DSL(Domain Specific Language)로 작성된 모든 Camel 엔터프라이즈 통합 패턴(EIP)을 사용하여 APIcast 정책 확장을 구현할 수 있습니다. 이를 통해 Java 또는 XML과 같은 친숙한 프로그래밍 언어를 사용하여 정책 확장을 작성할 수 있습니다. 이 주제의 예제에서는 Camel Netty4 HTTP 구성 요소를 사용하여 Java에서 HTTP 프록시를 구현합니다.
3scale API 백엔드에서 Fuse Camel 애플리케이션을 이미 사용하고 있는 경우에는 이 기능이 필요하지 않습니다. 이 경우 기존 Fuse Camel 애플리케이션을 사용하여 변환을 수행할 수 있습니다.
필수 소프트웨어 구성 요소
동일한 OpenShift 클러스터에 다음 Red Hat Integration 구성 요소가 배포되어 있어야 합니다.
- OpenShift 7.10의 Fuse.
- 3scale On-premises 2.14.
- APIcast 내장(기본 스테이징 및 프로덕션) 또는 APIcast 자체 관리.
3scale과는 다른 OpenShift 프로젝트에서 사용자 지정 Fuse 정책을 배포할 수 있지만 필수는 아닙니다. 그러나 두 프로젝트 간의 통신이 가능한지 확인해야 합니다. 자세한 내용은 OpenShift SDN을 사용하여 네트워크 정책 구성을 참조하십시오.
추가 리소스
5.1. Fuse에서 Apache Camel 변환과 APIcast 통합 링크 복사링크가 클립보드에 복사되었습니다!
OpenShift에서 Fuse에서 Apache Camel 애플리케이션으로 작성된 변환과 APIcast를 통합할 수 있습니다. 정책 확장 변환이 3scale로 구성 및 배포되면 3scale 트래픽이 Camel 정책 확장을 통해 메시지 콘텐츠를 변환합니다. 이 경우 Camel은 역방향 HTTP 프록시로 작동하며 APIcast에서 3scale 트래픽을 Camel로 보낸 다음 Camel에서 트래픽을 API 백엔드로 보냅니다.
이 주제의 예제에서는 Camel Netty4 HTTP 구성 요소를 사용하여 HTTP 프록시를 생성합니다.
- HTTP 프록시 프로토콜을 통해 수신된 요청은 HTTP 본문을 대문자로 변환하여 대상 서비스로 전달됩니다.
- 대상 서비스의 응답은 대문자로 변환한 다음 클라이언트로 반환하여 처리됩니다.
- 이 예에서는 HTTP 및 HTTPS 사용 사례에 필요한 구성을 보여줍니다.
사전 요구 사항
OpenShift 7.10 및 3scale 2.14에 Fuse가 동일한 OpenShift 클러스터에 배포되어 있어야 합니다. 설치에 대한 자세한 내용은 다음을 참조하십시오.
- OpenShift 및 3scale에 Fuse를 설치하고 프로젝트를 생성하려면 클러스터 관리자 권한이 있어야 합니다. 그러나 배포 구성을 생성하거나 Pod를 배포하거나 프로젝트당 액세스 권한을 편집하여 서비스를 생성할 수 있습니다.
절차
Camel
netty4-http구성 요소를 사용하여 Java에 HTTP 프록시를 구현하도록 Apache Camel 애플리케이션을 작성합니다. 그런 다음 Camel 구성 요소를 사용하여 메시지를 변환할 수 있습니다.다음 간단한 예제에서는 서비스에서 요청 및 응답의 대문자 변환을 수행합니다.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 이 간단한 예에서 Java 키 저장소 파일이
/tls/keystore.jks에 마운트된 경우 청취 포트는8443으로 설정됩니다. - 2
- 3scale에서 Camel 프록시 정책을 호출하면
HTTP_SCHEME,HTTP_HOST,HTTP_PORT및HTTP_PATH헤더의 값이 3scale의 백엔드 API에 대해 구성된 값에 따라 자동으로 설정됩니다. - 3
- 이 간단한 예제에서는 메시지 내용을 대문자로 변환합니다. Camel Enterprise Integration Patterns를 사용하여 요청 및 응답 메시지 콘텐츠(예: XML에서 JSON으로)에서 보다 복잡한 변환을 수행할 수 있습니다.
- OpenShift에 Camel 애플리케이션을 배포하고 서비스로 노출합니다. 자세한 내용은 OpenShift에서 Fuse에 애플리케이션 생성 및 배포를 참조하십시오.
5.2. OpenShift에서 Apache Camel을 사용하여 생성된 APIcast 정책 확장 구성 링크 복사링크가 클립보드에 복사되었습니다!
OpenShift에서 Fuse를 사용하여 Apache Camel 변환을 구현한 후 3scale 관리 포털을 사용하여 APIcast 정책 체인에서 정책 확장으로 구성할 수 있습니다.
정책 확장을 통해 Camel HTTP 프록시를 사용하도록 3scale 제품을 구성할 수 있습니다. 이 서비스는 3scale 트래픽을 HTTP 프록시를 통해 전송하여 타사 프록시에서 요청 응답 수정을 수행하는 데 사용됩니다. 이 경우 타사 프록시는 OpenShift에서 Fuse를 사용하여 구현한 Apache Camel입니다. TLS를 사용하여 Camel HTTP 프록시 서비스에 안전하게 연결하도록 APIcast를 구성할 수도 있습니다.
정책 확장 코드는 OpenShift의 Fuse의 Apache Camel 애플리케이션에 구현되며 3scale에서 수정하거나 삭제할 수 없습니다.
사전 요구 사항
OpenShift 7.10 및 3scale 2.14에 Fuse가 동일한 OpenShift 클러스터에 배포되어 있어야 합니다. 설치에 대한 자세한 내용은 다음을 참조하십시오.
- OpenShift의 Fuse에서 Apache Camel 애플리케이션을 사용하여 APIcast 정책 확장을 구현해야 합니다. 볼 수 있습니다. 5.1절. “Fuse에서 Apache Camel 변환과 APIcast 통합”
- OpenShift 포드에 Apache Camel 애플리케이션을 배포하여 서비스로 노출해야 합니다. 자세한 내용은 OpenShift에서 Fuse에 애플리케이션 생성 및 배포를 참조하십시오.
절차
- 3scale 관리 포털에서 통합 > 정책을 선택합니다.
- POLICIES > Add policy > Camel Service 를 선택합니다.
적절한 필드에 Camel HTTP 프록시 서비스에 연결하는 데 사용되는 OpenShift 경로를 입력합니다.
https_PROXY:http프로토콜 및 TLS 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.http://camel-proxy.my-3scale-management-project.svc:8443
http://camel-proxy.my-3scale-management-project.svc:8443Copy to Clipboard Copied! Toggle word wrap Toggle overflow http_proxy:http프로토콜 및 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.http://camel-proxy.my-3scale-management-project.svc:8080
http://camel-proxy.my-3scale-management-project.svc:8080Copy to Clipboard Copied! Toggle word wrap Toggle overflow all_proxy: 프로토콜이 지정되지 않은 경우http프로토콜 및 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.http://camel-proxy.my-3scale-management-project.svc:8080
http://camel-proxy.my-3scale-management-project.svc:8080Copy to Clipboard Copied! Toggle word wrap Toggle overflow
- 업데이트된 정책 구성을 스테이징 또는 프로덕션 환경으로 승격합니다. 예를 들어 Promote v를 클릭합니다. 3에서 Preging APIcast 로 이동합니다.
3scale
curl명령을 사용하여 APIcast 정책 구성을 테스트합니다. 예를 들면 다음과 같습니다.curl "https://testapi-3scale-apicast-staging.myuser.app.dev.3sca.net:443/?user_key=MY_USER_KEY" -k
curl "https://testapi-3scale-apicast-staging.myuser.app.dev.3sca.net:443/?user_key=MY_USER_KEY" -kCopy to Clipboard Copied! Toggle word wrap Toggle overflow APIcast는 Camel HTTP 프록시 연결에 사용할 새 TLS 세션을 설정합니다.
- 메시지 내용이 변환되었는지 확인합니다. 이 예에서는 대문자로 변환됩니다.
APIcast를 무시하고 TLS를 사용하여 직접 Camel HTTP 프록시를 테스트하려면 사용자 정의 HTTP 클라이언트를 사용해야 합니다. 예를 들어
netcat명령을 사용할 수 있습니다.print "GET https://mybackend.example.com HTTP/1.1\nHost: mybackend.example.com\nAccept: */*\n\n" | ncat --no-shutdown --ssl my-camel-proxy 8443
$ print "GET https://mybackend.example.com HTTP/1.1\nHost: mybackend.example.com\nAccept: */*\n\n" | ncat --no-shutdown --ssl my-camel-proxy 8443Copy to Clipboard Copied! Toggle word wrap Toggle overflow 이 예제에서는
GET후 전체 URL을 사용하여 HTTP 프록시 요청을 생성하고ncat --ssl매개변수를 사용하여 포트8443에서my-camel-proxy호스트에 TLS 연결을 지정합니다.참고프록시에서
CONNECT방법을 사용하여 HTTP 터널링을 지원하지 않기 때문에curl또는 기타 일반적인 HTTP 클라이언트를 사용하여 Camel HTTP 프록시를 직접 테스트할 수 없습니다.CONNECT와 함께 HTTP 터널링을 사용하는 경우 전송은 엔드 투 엔드 암호화로, Camel HTTP 프록시가 페이로드를 중재하는 것을 허용하지 않습니다.
추가 리소스
6장. APIcast 환경 변수 링크 복사링크가 클립보드에 복사되었습니다!
APIcast 환경 변수를 사용하면 APIcast의 동작을 수정할 수 있습니다. 지원되는 환경 변수는 다음과 같습니다.
- 지원되지 않거나 더 이상 사용되지 않는 환경 변수가 나열되지 않음
- 일부 환경 변수 기능이 APIcast 정책으로 이동했을 수 있습니다.
- all_proxy, ALL_PROXY
- APICAST_ACCESS_LOG_BUFFER
- APICAST_ACCESS_LOG_FILE
- APICAST_BACKEND_CACHE_HANDLER
- APICAST_CACHE_MAX_TIME
- APICAST_CACHE_STATUS_CODES
- APICAST_CONFIGURATION_CACHE
- APICAST_CONFIGURATION_LOADER
- APICAST_CUSTOM_CONFIG
- APICAST_ENVIRONMENT
- APICAST_EXTENDED_METRICS
- APICAST_HTTPS_CERTIFICATE
- APICAST_HTTPS_CERTIFICATE_KEY
- APICAST_HTTPS_PORT
- APICAST_HTTPS_PROXY_PROTOCOL
- APICAST_HTTPS_VERIFY_DEPTH
- APICAST_HTTP_PROXY_PROTOCOL
- APICAST_LOAD_SERVICES_WHEN_NEEDED
- APICAST_LOG_FILE
- APICAST_LOG_LEVEL
- APICAST_MANAGEMENT_API
- APICAST_MODULE
- APICAST_OIDC_LOG_LEVEL
- APICAST_PATH_ROUTING
- APICAST_PATH_ROUTING_ONLY
- APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE
- APICAST_POLICY_LOAD_PATH
- APICAST_PROXY_HTTPS_CERTIFICATE
- APICAST_PROXY_HTTPS_CERTIFICATE_KEY
- APICAST_PROXY_HTTPS_PASSWORD_FILE
- APICAST_PROXY_HTTPS_SESSION_REUSE
- APICAST_REPORTING_THREADS
- APICAST_RESPONSE_CODES
- APICAST_SERVICE_CACHE_SIZE
- APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
- APICAST_SERVICES_LIST
- APICAST_SERVICES_FILTER_BY_URL
- APICAST_UPSTREAM_RETRY_CASES
- APICAST_WORKERS
- BACKEND_ENDPOINT_OVERRIDE
- HTTP_KEEPALIVE_TIMEOUT
- http_proxy HTTP_PROXY
- https_PROXY HTTPS_PROXY
- no_proxy NO_PROXY
- OPENSSL_VERIFY
- OPENTRACING_CONFIG
- OPENTRACING_HEADER_FORWARD
- OPENTRACING_TRACER
- RESOLVER
- THREESCALE_CONFIG_FILE
- THREESCALE_DEPLOYMENT_ENV
- THREESCALE_PORTAL_ENDPOINT
ALL_PROXY
기본값: 값이 없음
value: string
프로토콜별 프록시가 지정되지 않은 경우 서비스에 연결하는 데 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.
APICAST_ACCESS_LOG_BUFFER
기본값: 값이 없음
value: 양의 정수
액세스 로그 쓰기를 바이트 청크에 포함할 수 있습니다. 결과적으로 시스템 호출 수가 줄어들어 게이트웨이의 성능이 향상됩니다.
APICAST_ACCESS_LOG_FILE
기본값: stdout
액세스 로그를 저장할 파일을 정의합니다.
APICAST_BACKEND_CACHE_HANDLER
기본값: strict
값: strict | resilient
더 이상 사용되지 않음: 대신 캐싱 정책을 사용합니다.
백엔드를 사용할 수 없는 경우 권한 부여 캐시 작동 방법을 정의합니다. 백엔드를 사용할 수 없는 경우 캐시된 애플리케이션은 엄격하게 제거됩니다. 복원력은 백엔드에서 권한 부여가 거부되는 경우에만 수행됩니다.
APICAST_CACHE_MAX_TIME
기본값: 1m
value: string
응답이 시스템에서 캐시되도록 선택되면 이 변수의 값은 캐시할 최대 시간을 나타냅니다. cache-control 헤더가 설정되지 않은 경우 캐시 시간은 정의된 시간입니다.
이 값의 형식은 proxy_cache_valid NGINX 지시문 으로 정의됩니다.
이 매개변수는 콘텐츠 캐싱 정책을 사용하는 API에서만 사용되며 요청은 캐시될 수 있습니다.
APICAST_CACHE_STATUS_CODES
기본값: 200, 302
value: string
업스트림의 응답 코드가 이 환경 변수에 정의된 상태 코드 중 하나와 일치하면 응답 콘텐츠가 NGINX에 캐시됩니다. 캐싱 시간은 헤더 캐시 시간 값 또는 APICAST_CACHE_MAX_TIME 환경 변수에서 정의한 최대 시간 등 이러한 값 중 하나에 따라 달라집니다.
이 매개변수는 콘텐츠 캐싱 정책을 사용하는 API에서만 사용되며 요청은 캐시될 수 있습니다.
APICAST_CONFIGURATION_CACHE
기본값: 0
value: integer
구성이 저장될 간격(초)을 지정합니다. 값은 0 ( APICAST_CONFIGURATION_LOADER의 부팅 값과 호환되지 않음) 또는 60 이상으로 설정해야 합니다. 예를 들어 APICAST_CONFIGURATION_CACHE 가 120으로 설정된 경우 게이트웨이는 120초(120초)마다 API 관리자의 구성을 다시 로드합니다. 값 < 0은 다시 로드를 비활성화합니다.
APICAST_CONFIGURATION_LOADER
값: boot | lazy
기본값: lazy
구성을 로드하는 방법을 정의합니다. Boot는 게이트웨이가 시작될 때 API 관리자에 구성을 요청합니다. 지연은 들어오는 각 요청에 대해 필요에 따라 로드됩니다(각 요청 APICAST_CONFIGURATION_CACHE 가 0이어야 합니다).
APICAST_CUSTOM_CONFIG
더 이상 사용되지 않음: 대신 정책을 사용합니다.
기존 APIcast 논리를 재정의하는 사용자 정의 논리를 구현하는 Lua 모듈의 이름을 정의합니다.
APICAST_ENVIRONMENT
value: string[:]
예: production:cloud-hosted
APIcast는 콜론(:)으로 구분된 환경 목록(또는 경로)을 로드해야 합니다. 이 목록은 CLI에서 -e 또는 --environment 매개변수 대신 사용하고 예를 들어 컨테이너 이미지에 기본 환경으로 저장할 수 있습니다. CLI에 전달된 모든 값이 이 변수를 덮어씁니다.
APICAST_EXTENDED_METRICS
기본값: false
value: boolean
예: "true"
Prometheus 지표에 대한 추가 정보를 활성화합니다. 다음 메트릭에는 APIcast에 대한 자세한 정보를 제공하는 service_id 및 service_system_name 레이블이 있습니다.
-
total_response_time_seconds -
upstream_response_time_seconds -
upstream_status
APICAST_HTTPS_CERTIFICATE
기본값: 값이 없음
HTTPS에 대한 PEM 형식으로 X.509 인증서가 있는 파일의 경로입니다.
APICAST_HTTPS_CERTIFICATE_KEY
기본값: 값이 없음
PEM 형식의 X.509 인증서 보안 키가 있는 파일의 경로입니다.
APICAST_HTTPS_PORT
기본값: 값이 없음
HTTPS 연결을 수신하기 시작해야 하는 포트 APIcast를 제어합니다. HTTP 포트로 충돌하는 경우 HTTPS에만 사용됩니다.
APICAST_HTTPS_PROXY_PROTOCOL
기본값: false 값: 부울 예: true
이 매개변수는 HTTPS 리스너에 대한 프록시 프로토콜을 활성화합니다.
APICAST_HTTPS_VERIFY_DEPTH
기본값: 1
값: positive 정수
클라이언트 인증서 체인의 최대 길이를 정의합니다. 이 매개변수에 값이 1 인 경우 클라이언트 인증서 체인에 추가 인증서를 포함할 수 있습니다. 예를 들면 루트 인증 기관입니다.
APICAST_HTTP_PROXY_PROTOCOL
기본값: false
값: 부울
예: true
이 매개변수는 HTTP 리스너에 대한 프록시 프로토콜을 활성화합니다.
APICAST_LOAD_SERVICES_WHEN_NEEDED
3scale 2.14에서는 APICAST_LOAD_SERVICES_WHEN_NEEDED 환경 변수가 제거되었습니다. 이제 기본적으로 활성화되어 있습니다. THREESCALE_PORTAL_ENDPOINT 를 참조하십시오.
기본값:false
값:
-
true또는1의 경우 true -
False ,
0또는false의 경우 비어 있습니다.
이 옵션은 많은 서비스가 구성된 경우 사용할 수 있습니다. 그러나 성능은 서비스 수, APIcast와 3scale 관리 포털 간의 대기 시간, 구성의 Time To Live(TTL)와 같은 추가 요인에 따라 달라집니다.
기본적으로 APIcast는 관리 포털에서 구성을 다운로드할 때마다 모든 서비스를 로드합니다. 이 옵션을 활성화하면 구성에서 지연 로드를 사용합니다. APIcast는 요청의 호스트 헤더에 지정된 호스트에 대해 구성된 항목만 로드합니다.
-
APICAST_CONFIGURATION_CACHE에서 정의한 캐싱이 적용됩니다. -
APICAST_CONFIGURATION_LOADER가부팅되면 이 옵션이 비활성화됩니다. -
APICAST_PATH_ROUTING과 호환되지 않습니다.
APICAST_LOG_FILE
기본값: stderr
OpenResty 오류 로그를 포함하는 파일을 정의합니다. 이 파일은 error_log 지시문에서 bin/apicast 에서 사용합니다. 파일 경로는 절대 또는 APIcast 접두사 디렉터리를 기준으로 할 수 있습니다. 기본 접두사 디렉터리는 APIcast입니다. 자세한 내용은 NGINX 설명서를 참조하십시오.
APICAST_LOG_LEVEL
기본값: warn
값: debug | info | notice | warn | error | crit | alert | emerg
OpenResty 로그의 로그 수준을 지정합니다.
APICAST_MANAGEMENT_API
값:
-
Disabled: 완전히 비활성화됨, 포트에서 수신 대기합니다. -
status: 상태 점검을 위해/status/끝점을 활성화하고 사용 가능한 정책 목록을 표시하는/policies끝점을 활성화합니다. -
policies:/policies끝점만 활성화합니다. -
debug: 전체 API가 열려 있습니다.
Management API 는 강력하며 APIcast 구성을 제어할 수 있습니다. 디버깅에만 디버그 수준을 활성화해야 합니다.
APICAST_MODULE
기본값: apicast
더 이상 사용되지 않음: 대신 정책을 사용합니다.
API 게이트웨이 논리를 구현하는 기본 Lua 모듈의 이름을 지정합니다. 사용자 정의 모듈은 기본 apicast.lua 모듈의 기능을 재정의할 수 있습니다. 모듈을 사용하는 방법에 대한 예를 참조하십시오.
APICAST_OIDC_LOG_LEVEL
값: debug | info | notice | warn | error | crit | alert | emerg
기본값: err
OpenID Connect 통합과 관련된 로그 수준을 설정할 수 있습니다.
APICAST_PATH_ROUTING
값:
-
true또는1의 경우 true -
False ,
0또는false의 경우 비어 있습니다.
이 매개변수를 true 로 설정하면 게이트웨이는 기본 호스트 기반 라우팅 외에도 경로 기반 라우팅을 사용합니다. API 요청은 요청의 Host 헤더 값이 Public Base URL 과 일치하는 서비스 목록에서 일치하는 매핑 규칙이 있는 첫 번째 서비스로 라우팅됩니다.
APICAST_PATH_ROUTING_ONLY
값:
-
true또는1의 경우 true -
False ,
0또는false의 경우 비어 있습니다.
이 매개변수를 true 로 설정하면 게이트웨이는 경로 기반 라우팅을 사용하며 기본 호스트 기반 라우팅으로 대체되지 않습니다. API 요청은 요청의 Host 헤더 값이 Public Base URL 과 일치하는 서비스 목록에서 일치하는 매핑 규칙이 있는 첫 번째 서비스로 라우팅됩니다.
이 매개변수는 APICAST_PATH_ROUTING 보다 우선합니다. APICAST_PATH_ROUTING_ONLY 가 활성화된 경우 APIcast는 APICAST_PATH_ROUTING 값과 관계없이 경로 기반 라우팅만 수행합니다.
APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE
최소 20m 값을 사용합니다.
기본값: 20m
value: string
batcher 정책에서 사용하는 공유 메모리의 최대 크기를 설정합니다.
허용되는 크기 단위는 k 및 m 입니다.
http {
lua_shared_dict batched_reports 20m;
...
}
http {
lua_shared_dict batched_reports 20m;
...
}
APICAST_POLICY_LOAD_PATH
기본값:APICAST_DIR/policies
value: string[:]
예:~/apicast/policies:$PWD/policies
콜론(::) APIcast에서 정책을 찾아야 하는 경로 목록. 먼저 개발 디렉터리에서 정책을 로드하거나 예제를 로드하는 데 사용할 수 있습니다.
APICAST_PROXY_HTTPS_CERTIFICATE
기본값:
value: string
예: /home/apicast/my_certificate.crt
업스트림에 연결할 때 APIcast에서 사용할 클라이언트 SSL 인증서의 경로입니다. 이 인증서는 구성의 모든 서비스에 사용됩니다.
APICAST_PROXY_HTTPS_CERTIFICATE_KEY
기본값:
value: string
예: /home/apicast/my_certificate.key
클라이언트 SSL 인증서의 키 경로입니다.
APICAST_PROXY_HTTPS_PASSWORD_FILE
기본값:
value: string
예: /home/apicast/passwords.txt
APICAST_PROXY_HTTPS_CERTIFICATE_KEY 로 지정된 SSL 인증서 키의 암호가 있는 파일의 경로입니다.
APICAST_PROXY_HTTPS_SESSION_REUSE
기본값: On
값:
-
On: SSL 세션을 사용합니다. -
Off: SSL 세션을 재사용하지 않습니다.
APICAST_REPORTING_THREADS
기본값: 0
value: 정수 >= 0
실험적: 과도한 부하에서 예기치 않은 성능이 있을 수 있으며 보고서가 손실될 수 있습니다.
0보다 큰 값은 백엔드에 대한 대역 외 보고를 활성화합니다. 이는 성능을 높이기 위한 새로운 실험 기능입니다. 클라이언트에는 백엔드 대기 시간이 표시되지 않으며 모든 항목이 비동기식으로 처리됩니다. 이 값은 대기 시간을 추가하여 클라이언트가 제한되기 전에 동시에 실행할 수 있는 비동기 보고서 수를 결정합니다.
APICAST_RESPONSE_CODES
기본값: <empty>(false)
값:
-
true또는1의 경우 true -
False ,
0또는false의 경우 비어 있습니다.
true 로 설정하면 APIcast는 3scale에서 API 백엔드에서 반환된 응답의 응답 코드를 기록합니다. 자세한 내용은 API 의 3scale API Management 응답 코드 로그 설정 및 평가를 참조하십시오.
APICAST_SERVICE_CACHE_SIZE
기본값: 1000
값: 정수 >= 0
APIcast가 내부 캐시에 저장할 수 있는 서비스 수를 지정합니다. Lua의 lru 캐시가 모든 항목을 초기화하므로 높은 값이 성능에 영향을 미칩니다.
APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
${ID} 를 실제 서비스 ID로 바꿉니다. 값은 관리 포털의 구성 내역에 표시되는 구성 버전이어야 합니다. 특정 버전으로 설정하면 자동 업데이트되지 않으며 항상 해당 버전을 사용합니다.
APICAST_SERVICES_LIST
value: 쉼표로 구분된 서비스 ID 목록
APICAST_SERVICES_LIST 환경 변수는 3scale API Manager에서 구성하는 서비스를 필터링하는 데 사용됩니다. 이는 게이트웨이의 특정 서비스에 대한 구성만 적용하여 목록에 지정되지 않은 해당 서비스 식별자를 삭제합니다. 제품 > [gradle_product_name] > 개요 의 관리 포털에서 제품의 서비스 식별자는 설정, 방법 및 설정, API 호출의 ID 를 참조하십시오.
APICAST_SERVICES_FILTER_BY_URL
값: .*.example.com 과 같은 PCRE(Perl Compatible Regular Expression)입니다.
3scale API Manager에 구성된 서비스를 필터링합니다.
이 필터는 Public Base URL ( staging 또는 production)과 일치합니다. 필터와 일치하지 않는 서비스는 삭제됩니다. 정규식을 컴파일할 수 없는 경우 서비스가 로드되지 않습니다.
서비스가 일치하지만 “APICAST_SERVICES_LIST” 에 포함된 경우 서비스는 삭제되지 않습니다.
예 6.1. backend 끝점에 적용된 Regexp 필터
Regexp 필터 http://.*.foo.dev 는 다음 백엔드 엔드포인트에 적용됩니다.
이 경우 1 과 3 은 APIcast로 구성되며 2 및 4 는 삭제됩니다.
APICAST_UPSTREAM_RETRY_CASES
값: error | timeout | invalid_header | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off
이는 재시도 정책이 구성된 경우에만 사용되며 업스트림 API에 대한 요청을 다시 시도해야 하는 시기를 지정합니다. Nginx의 PROXY_NEXT_UPSTREAM 모듈 과 동일한 값을 허용합니다.
APICAST_WORKERS
기본값: auto
값: integer | auto
nginx worker_processes 지시문에 사용할 값입니다. 기본적으로 APIcast는 1 이 사용되는 개발 환경을 제외하고 auto 를 사용합니다.
BACKEND_ENDPOINT_OVERRIDE
구성의 백엔드 끝점을 재정의하는 URI입니다. OpenShift 배포 외부 AMP를 배포할 때 유용합니다. 예:https://backend.example.com.
HTTP_KEEPALIVE_TIMEOUT
기본값: 75
value: positive 정수
예:1
이 매개변수는 서버 측에서 keep-alive 클라이언트 연결이 열려 있는 시간 초과를 설정합니다. 0 값은 keep-alive 클라이언트 연결을 비활성화합니다.
기본적으로 게이트웨이는 HTTP_KEEPALIVE_TIMEOUT을 비활성화 상태로 유지합니다. 이 구성을 사용하면 기본값이 75초 인 NGINX에서 keepalive 시간 초과를 사용할 수 있습니다.
http_proxy,HTTP_PROXY
기본값: 값이 없음
value: string
HTTP 서비스에 연결하는 데 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.
https_proxy, HTTPS_PROXY
기본값: 값이 없음
value: string
HTTPS 서비스에 연결하는 데 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.
no_proxy,NO_PROXY
기본값: 값이 없음
value: string\[,<string>\]; *
예:foo,bar.com,.extra.dot.com
요청을 프록시해서는 안 되는 쉼표로 구분된 호스트 이름 및 도메인 이름을 정의합니다. 모든 호스트와 일치하는 단일 * 문자로 설정하면 프록시를 효과적으로 비활성화합니다.
OPENSSL_VERIFY
값:
-
0,false: 피어 확인을 비활성화합니다. -
1,true: 피어 검증을 활성화
OpenSSL Peer 확인을 제어합니다. OpenSSL은 시스템 인증서 저장소를 사용할 수 없기 때문에 기본적으로 해제되어 있습니다. 사용자 정의 인증서 번들이 필요하며 신뢰할 수 있는 인증서에 추가해야 합니다.
https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate 을 사용하고 export-builtin-trusted-certs 로 생성된 인증서 번들을 가리키는 것이 좋습니다.
OPENTRACING_CONFIG
OPENTRACING_TRACER 가 설정되지 않은 경우 이 환경 변수는 opentracing tracer의 구성 파일을 결정하는 데 사용됩니다.
각 추적기에는 기본 설정 파일 * jaeger: conf.d/opentracing/jaeger.example.json이 있습니다.
이 변수를 사용하여 파일 경로를 설정하여 기본적으로 제공된 것과 다른 구성을 마운트하도록 선택할 수 있습니다.
예:/tmp/jaeger/jaeger.json
OPENTRACING_HEADER_FORWARD
기본값:uber-trace-id
이 환경 변수는 열린 정보를 전달하는 데 사용되는 HTTP 헤더를 제어하며 이 HTTP 헤더는 업스트림 서버로 전달됩니다.
OPENTRACING_TRACER
예:jaeger
이 환경 변수는 현재 사용할 수 있는 오픈 트래싱 추적기인 jaeger 에서만 로드할 추적 라이브러리를 제어합니다.
비어 있는 경우 opentracing 지원이 비활성화됩니다.
RESOLVER
OpenResty에서 사용할 사용자 정의 DNS 확인 프로그램을 지정할 수 있습니다. RESOLVER 매개변수가 비어 있으면 DNS 확인자가 자동으로 검색됩니다.
THREESCALE_CONFIG_FILE
게이트웨이 구성을 사용하여 JSON 파일의 경로입니다. 게이트웨이가 성공적으로 실행되도록 THREESCALE_PORTAL_ENDPOINT 또는 THREESCALE_CONFIG_FILE 을 제공해야 합니다. 이 두 환경 변수에서 THREESCALE_CONFIG_FILE 이 우선합니다.
게이트웨이 구성을 사용하여 파일을 빌드하려면 서비스 수에 따라 다음 두 가지 대안이 있습니다.
사용 가능한 3scale API 끝점을 사용합니다.
프록시 구성 표시,프록시 구성 표시, 최신 구성 또는 프록시 구성 목록. 서비스 ID를 알고 있어야 합니다. 다음 옵션을 사용합니다.
-
프록시 구성 목록 공급자 끝점: <
schema>://<admin-portal>/admin/api/account/proxy_configs/<env>.json - 끝점은 각 서비스의 최신뿐만 아니라 공급자의 저장된 모든 프록시 구성을 반환합니다.
-
JSON에서 반환된
proxy_configs배열을 반복합니다. -
proxy_config.content가 동일한proxy_config.content.id인 모든중에서 가장 높은 proxy_config.content를 선택합니다. ID는 서비스 중 하나입니다.proxy_config.version
-
프록시 구성 목록 공급자 끝점: <
- 그런 다음 서비스를 반복하여 구성 파일을 빌드합니다. 이 단계에서는 사용 가능한 3scale API 끝점 또는 동등한 3scale toolbox 명령을 사용합니다.
컨테이너 이미지를 사용하여 게이트웨이를 배포할 때 다음을 수행합니다.
- 파일을 이미지에 읽기 전용 볼륨으로 구성합니다.
- 볼륨을 마운트한 위치를 나타내는 경로를 지정합니다.
예제 폴더에 샘플 구성 파일을 찾을 수 있습니다.
THREESCALE_DEPLOYMENT_ENV
기본값: production
값: 스테이징 | 프로덕션
이 환경 변수의 값은 구성이 다운로드될 환경을 정의합니다. 이는 새 APIcast를 사용할 때 3scale 스테이징 또는 프로덕션입니다.
이 값은 3scale Service Management API에 수행된 권한 부여/보고서 요청의 X-3scale-User-Agent 헤더에서도 사용됩니다. 3scale은 통계용으로만 사용됩니다.
THREESCALE_PORTAL_ENDPOINT
다음 형식으로 암호 및 포털 끝점이 포함된 URI:
<schema>://<password>@<admin-portal>.
다음과 같습니다.
예:https://access-token@account-admin.3scale.net.
THREESCALE_PORTAL_ENDPOINT 환경 변수가 제공되고 APICAST_CONFIGURATION_LOADER=boot 인 경우 게이트웨이는 초기화 시 3scale에서 구성을 다운로드합니다. 이 구성에는 [ your_product_name] > Integration 아래의 API 통합 페이지에 제공된 모든 설정이 포함됩니다.
이 환경 변수를 사용하여 마스터 관리 포털로 단일 게이트웨이를 생성할 수도 있습니다.
게이트웨이를 성공적으로 실행하려면 THREESCALE_PORTAL_ENDPOINT 또는 THREESCALE_CONFIG_FILE 을 제공해야 합니다. THREESCALE_CONFIG_FILE 은 THREESCALE_PORTAL_ENDPOINT 보다 우선합니다.
3scale 2.14에서는 APICAST_LOAD_SERVICES_WHEN_NEEDED 환경 변수가 제거되었습니다. 이제 기본적으로 활성화되어 있습니다.
기본적으로 필요한 경우 구성을 가져옵니다. 다음은 논리 사양입니다.
THREESCALE_PORTAL_ENDPOINT에는 URL에 경로가 포함되어 있지 않습니다.APICAST_CONFIGURATION_LOADER=boothttp://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?version=latesthttp://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?version=latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow /admin/api/account/proxy_configs/${env}엔드포인트가 일시 중지되었습니다.APICAST_CONFIGURATION_LOADER=lazyhttp://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?host=<hostname_of_the_request>&version=latesthttp://${THREESCALE_PORTAL_ENDPOINT}/admin/api/account/proxy_configs/<env>.json?host=<hostname_of_the_request>&version=latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow /admin/api/account/proxy_configs/${env}엔드포인트가 일시 중지되었습니다.
THREESCALE_PORTAL_ENDPOINT에는 마스터 끝점이 있는 URL의 경로, 즉/master/api/proxy/configs가 포함됩니다.APICAST_CONFIGURATION_LOADER=boothttp://${THREESCALE_PORTAL_ENDPOINT}/<env>.jsonhttp://${THREESCALE_PORTAL_ENDPOINT}/<env>.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow 이는 현재 동작과 동일한 마스터 끝점의 모든 서비스에 적용됩니다.
APICAST_CONFIGURATION_LOADER=lazyhttp://${THREESCALE_PORTAL_ENDPOINT}/<env>.json?host=<hostname_of_the_request>http://${THREESCALE_PORTAL_ENDPOINT}/<env>.json?host=<hostname_of_the_request>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 이는 현재 동작과 동일한 마스터 끝점의 호스트와 일치하는 모든 서비스에 적용됩니다.
APICAST_CONFIGURATION_LOADER=boot | APICAST_CONFIGURATION_LOADER=lazy | |
|---|---|---|
| 끝점에는 경로가 없습니다. |
|
|
| 끝점에 경로가 있습니다. |
|
|
7장. 성능 향상을 위해 APIcast 구성 링크 복사링크가 클립보드에 복사되었습니다!
이 문서에서는 APIcast의 성능 문제를 디버깅하기 위한 일반적인 지침을 제공합니다. 또한 사용 가능한 캐싱 모드를 소개하고 성능 향상을 위해 어떻게 도움이 될 수 있는지 설명하고 프로파일링 모드에 대한 세부 정보를 제공합니다. 내용은 다음 섹션으로 구성됩니다.
7.1. 일반 지침 링크 복사링크가 클립보드에 복사되었습니다!
일반적인 APIcast 배포에는 다음 세 가지 구성 요소를 고려해야 합니다.
- APIcast.
- 요청을 승인하고 사용량을 추적하는 3scale 백엔드 서버입니다.
- 업스트림 API입니다.
APIcast에서 성능 문제가 발생하는 경우:
- 문제를 담당하는 구성 요소를 식별합니다.
- 업스트림 API의 대기 시간을 측정하여 APIcast와 3scale 백엔드 서버가 도입하는 대기 시간을 결정합니다.
- 벤치마크를 실행하는 데 사용하는 것과 동일한 툴로 새 측정을 수행하지만 업스트림 API를 직접 가리키는 대신 APIcast를 가리킵니다.
이러한 결과를 비교하면 APIcast 및 3scale 백엔드 서버에서 도입한 대기 시간을 파악할 수 있습니다.
자체 관리형 APIcast를 사용한 SaaS(Hosted) 설치에서 APIcast에 의해 도입된 대기 시간과 3scale 백엔드 서버가 높은 경우:
- APIcast가 배포된 동일한 머신에서 3scale 백엔드 서버에 요청합니다.
- 대기 시간을 측정합니다.
3scale 백엔드 서버는 버전을 반환하는 끝점을 노출합니다. https://su1.3scale.net/status. 비교하면 키, 제한 및 대기열 백그라운드 작업을 확인하기 때문에 권한 부여 호출에 더 많은 리소스가 필요합니다. 3scale 백엔드 서버에서 이러한 작업을 몇 밀리초 내에 수행하지만 /status 엔드포인트와 같은 버전을 확인하는 것보다 더 많은 작업이 필요합니다. 예를 들어 /status 에 대한 요청이 APIcast 환경에서 약 300ms가 걸리면 캐시되지 않은 모든 요청에 더 많은 시간이 걸릴 것입니다.
7.2. 기본 캐싱 링크 복사링크가 클립보드에 복사되었습니다!
캐시되지 않은 요청의 경우 이러한 이벤트는 다음과 같습니다.
- APIcast는 일치하는 매핑 규칙에서 사용 지표를 추출합니다.
- APIcast는 메트릭과 애플리케이션 인증 정보를 3scale 백엔드 서버로 보냅니다.
3scale 백엔드 서버는 다음을 수행합니다.
- 애플리케이션 키를 확인하고 보고된 메트릭 사용이 정의된 제한 내에 있는지 확인합니다.
- 보고된 지표의 사용을 늘리기 위해 백그라운드 작업을 대기열에 넣습니다.
- 요청이 승인되어야 하는지 여부를 APIcast에 응답합니다.
- 요청이 승인된 경우 업스트림으로 이동합니다.
이 경우 3scale 백엔드 서버가 응답할 때까지 요청은 업스트림에 도달하지 않습니다.
다른 한편으로는 기본적으로 활성화된 캐싱 메커니즘을 사용하여 다음을 수행합니다.
- APIcast는 권한이 부여된 경우 3scale 백엔드 서버에 대한 권한 부여 호출 결과를 캐시에 저장합니다.
- 동일한 인증 정보 및 메트릭이 있는 다음 요청은 3scale 백엔드 서버로 이동하는 대신 캐시된 권한 부여를 사용합니다.
- 요청이 승인되지 않았거나 APIcast가 인증 정보를 처음 수신하는 경우 APIcast는 위에서 설명한 대로 3scale 백엔드 서버를 동기적으로 호출합니다.
인증이 캐시되면 APIcast는 먼저 업스트림을 호출한 다음 post action 이라는 단계에서 3scale 백엔드 서버를 호출하고 다음 요청을 준비하도록 캐시에 권한 부여를 저장합니다. 3scale 백엔드 서버에 대한 호출은 요청 시간에 발생하지 않기 때문에 대기 시간이 발생하지 않습니다. 그러나 동일한 연결로 전송된 요청은 post 작업 단계가 완료될 때까지 기다려야 합니다.
클라이언트가 keep-alive 를 사용하고 있는 시나리오를 가정하고 매초마다 요청을 보냅니다. 업스트림 응답 시간이 100ms이고 3scale 백엔드 서버의 대기 시간이 500 ms인 경우 클라이언트는 100ms로 마다 응답을 받습니다. 전체 업스트림 응답 및 보고에는 600 ms가 필요합니다. 이는 다음 요청이 시작되기 전에 400 ms를 추가로 제공합니다.
아래 다이어그램은 기본 캐싱 동작을 보여줍니다. 캐싱 메커니즘의 동작은 캐싱 정책을 사용하여 변경할 수 있습니다.
7.3. 비동기 보고 스레드 링크 복사링크가 클립보드에 복사되었습니다!
APIcast에는 3scale 백엔드 서버에 대해 권한을 부여하는 스레드 풀을 활성화하는 기능이 있습니다. 이 기능을 활성화하면 APIcast가 먼저 3scale 백엔드 서버를 호출하여 매핑 규칙과 일치하는 애플리케이션 및 지표를 확인합니다. 이는 기본적으로 활성화된 캐싱 메커니즘을 사용하는 경우와 유사합니다. 차이점은 3scale 백엔드 서버에 대한 후속 호출이 풀에 사용 가능한 보고 스레드가 있는 한 완전히 비동기적으로 보고된다는 것입니다.
보고 스레드는 전체 게이트웨이에 대해 전역적이고 모든 서비스 간에 공유됩니다. 두 번째 TCP 연결이 생성되면 권한 부여가 이미 캐시된 한 완전히 비동기 상태가 됩니다. 무료 보고 스레드가 없는 경우 동기 모드는 표준 비동기 모드로 대체되고 post 작업 단계에서 보고를 수행합니다.
APICAST_REPORTING_THREADS 환경 변수를 사용하여 이 기능을 활성화할 수 있습니다.
아래 다이어그램은 비동기 보고 스레드 풀의 작동 방식을 보여줍니다.
7.4. 3scale API Management Batcher 정책 링크 복사링크가 클립보드에 복사되었습니다!
캐시 크기를 늘려야 하는 경우 변수 APICAST_POLICY_BATCHER_SHARED_MEMORY_SIZE를 사용합니다.
기본적으로 APIcast는 수신하는 각 요청에 대해 3scale 백엔드 서버에 대한 하나의 호출을 수행합니다. 3scale API Management Batcher 정책의 목표는 3scale 백엔드 서버에 대한 요청 수를 크게 줄여 대기 시간을 줄이고 처리량을 늘리는 것입니다. 이를 위해 이 정책은 보고서를 캐시하고 권한 부여 상태를 캐시합니다.
자세한 내용은 3scale API Management Batcher 정책을 참조하십시오. 아래 다이어그램은 정책이 작동하는 방식을 보여줍니다.
8장. Prometheus에 3scale API Management APIcast Metrics 노출 링크 복사링크가 클립보드에 복사되었습니다!
3scale 이번 릴리스에서는 Prometheus 설치 및 구성이 지원되지 않습니다. 선택적으로 커뮤니티 버전의 Prometheus 를 사용하여 APIcast 관리 API 서비스에 대한 메트릭 및 경고를 시각화할 수 있습니다.
8.1. Prometheus 정보 링크 복사링크가 클립보드에 복사되었습니다!
Prometheus는 Red Hat OpenShift 환경에 배포된 Red Hat 3scale API Management APIcast 서비스를 모니터링하는 데 사용할 수 있는 오픈 소스 시스템 모니터링 툴킷입니다.
Prometheus를 사용하여 서비스를 모니터링하려면 서비스에서 Prometheus 끝점을 노출해야 합니다. 이 끝점은 메트릭 목록 및 메트릭의 현재 값을 표시하는 HTTP 인터페이스입니다. Prometheus는 이러한 대상 정의 끝점을 주기적으로 스크랩하고 수집된 데이터를 데이터베이스에 기록합니다.
8.1.1. Prometheus 쿼리 링크 복사링크가 클립보드에 복사되었습니다!
Prometheus UI에서 쿼리를PromQL(Prometheus Query Language)에 작성하여 지표 정보를 추출할 수 있습니다. PromQL을 사용하면 시계열 데이터를 실시간으로 선택하고 집계할 수 있습니다.
예를 들어 다음 쿼리를 사용하여 지표 이름이 http_requests_total 인 모든 시계열에 대해 Prometheus가 지난 5분 내에 기록된 모든 값을 선택할 수 있습니다.
http_requests_total[5m]
http_requests_total[5m]
메트릭에 대한 라벨(키:값 쌍)을 지정하여 쿼리 결과를 추가로 정의하거나 필터링할 수 있습니다. 예를 들어 다음 쿼리를 사용하여 지표 이름이 http_requests_total 이고 job 라벨이 integration 으로 설정된 모든 시계열에 대해 Prometheus가 지난 5분 내에 기록된 모든 값을 선택할 수 있습니다.
http_requests_total{job="integration"}[5m]
http_requests_total{job="integration"}[5m]
쿼리 결과는 그래프로 표시하거나 Prometheus의 표현식 브라우저에서 테이블 형식 데이터로 보거나 Prometheus HTTP API 를 사용하여 외부 시스템에서 사용할 수 있습니다. Prometheus는 데이터의 그래픽 보기를 제공합니다. Prometheus 지표를 볼 수 있는 보다 강력한 그래픽 대시보드의 경우 Grafana가 널리 사용됩니다.
PromQL 언어를 사용하여 Prometheus alertmanager 툴에서 경고를 구성할 수도 있습니다.
Grafana는 커뮤니티가 지원하는 기능입니다. 3scale API Management 제품을 모니터링하기 위해 Grafana를 배포하는 것은 Red Hat 프로덕션 SLA(서비스 수준 계약)에서 지원되지 않습니다.
8.2. Prometheus와 APIcast 통합 링크 복사링크가 클립보드에 복사되었습니다!
Prometheus와 APIcast 통합은 다음 배포 옵션에 사용할 수 있습니다.
- 자체 관리형 APIcast - 3scale 호스팅 또는 온-프레미스 API 관리자 모두.
- 3scale 온-프레미스에 포함된 APIcast입니다.
Prometheus와 APIcast 통합은 호스팅된 API 관리자 및 호스팅 APIcast에서 사용할 수 없습니다.
기본적으로 Prometheus는 표 8.2. “3scale API Management APIcast의 기본 메트릭” 에 나열된 APIcast 지표를 모니터링할 수 있습니다.
8.2.1. 추가 옵션 링크 복사링크가 클립보드에 복사되었습니다!
선택적으로 OpenShift 클러스터에 대한 클러스터 관리자 액세스 권한이 있는 경우 total_response_time_seconds, upstream_response_time_seconds ,upstream_response_time_seconds, upstream_status 지표를 확장하여 service_id 및 service_system_name 라벨을 포함할 수 있습니다. 이러한 메트릭을 확장하려면 다음 명령을 사용하여 APICAST_EXTENDED_METRICS OpenShift 환경 변수를 true 로 설정합니다.
oc set env dc/apicast APICAST_EXTENDED_METRICS=true
oc set env dc/apicast APICAST_EXTENDED_METRICS=true
3scale Batcher 정책 ( 3.1.3절. “3scale API Management Batcher”에 설명)을 사용하는 경우 Prometheus는 표 8.3. “3scale API Management APIcast Batch 정책에 대한 Prometheus 지표” 에 나열된 메트릭을 모니터링할 수 있습니다.
메트릭에 값이 없는 경우 Prometheus는 지표를 숨깁니다. 예를 들어 nginx_error_log 에 보고할 오류가 없는 경우 Prometheus는 nginx_error_log 지표를 표시하지 않습니다. nginx_error_log 메트릭은 값이 있는 경우에만 표시됩니다.
추가 리소스
Prometheus에 대한 자세한 내용은 Prometheus: 시작하기를 참조하십시오.
8.3. 3scale API Management APIcast의 OpenShift 환경 변수 링크 복사링크가 클립보드에 복사되었습니다!
Prometheus 인스턴스를 구성하려면 표 8.1. “3scale API Management APIcast의 Prometheus 환경 변수” 에 설명된 OpenShift 환경 변수를 설정할 수 있습니다.
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
|
|
Prometheus 지표에 대한 추가 정보를 활성화하는 부울 값입니다. 다음 메트릭에는 APIcast에 대한 자세한 정보를 제공하는
|
|
추가 리소스
환경 변수 설정에 대한 자세한 내용은 관련 OpenShift 가이드를 참조하십시오.
- OpenShift 4: 애플리케이션
- OpenShift 3.11: 개발자 가이드
- Red Hat 3scale API Management 지원 구성
8.4. Prometheus에 노출되는 3scale API Management APIcast 지표 링크 복사링크가 클립보드에 복사되었습니다!
3scale APIcast를 모니터링하도록 Prometheus를 설정한 후 기본적으로 표 8.2. “3scale API Management APIcast의 기본 메트릭” 에 나열된 지표를 모니터링할 수 있습니다.
표 8.3. “3scale API Management APIcast Batch 정책에 대한 Prometheus 지표” 에 나열된 메트릭은 3scale Batcher 정책을 사용하는 경우에만 사용할 수 있습니다.
| 메트릭 | 설명 | 유형 | 라벨 |
|---|---|---|---|
|
| HTTP 연결 수 | 게이지 | state(accepted,active,handled,reading,total,waiting,writing) |
|
| APIcast 오류 | 카운터 |
|
|
| 작업자 간에 공유되는 사전의 용량 | 게이지 |
|
|
| 작업자 간에 공유되는 사전의 여유 공간 | 게이지 |
|
|
| 메트릭을 관리하는 Lua 라이브러리의 오류 수 | 카운터 | none |
|
| 클라이언트에 응답을 보내는 데 필요한 시간(초)
참고: | histogram |
|
|
| 업스트림 서버의 응답 시간(초)
참고: | histogram |
|
|
| 업스트림 서버의 HTTP 상태
참고: | 카운터 |
|
|
| 3scale 백엔드(Apisonator)에 대한 권한 부여 및 보고 | 카운터 |
|
| 메트릭 | 설명 | 유형 | 라벨 |
|---|---|---|---|
|
| APIcast에서 클라이언트로 전송한 응답 상태 수 | 카운터 | status |
|
| 3scale 일괄 처리 정책의 auths 캐시에 적중 | 카운터 | none |
|
| 3scale 일괄 처리 정책의 auths 캐시에 있는 누락 | 카운터 | none |
|
| 콘텐츠 캐싱 정책을 통과하는 요청 수 | 카운터 |
상태 ( |
9장. OpenTelemetry SDK와 APIcast 통합 링크 복사링크가 클립보드에 복사되었습니다!
OpenTelemetry SDK 와 APIcast의 통합을 통해 시스템 성능 및 동작에 대한 인사이트를 제공하는 Telemetry 데이터를 내보낼 수 있습니다. APIcast는 NGINX OpenTelemetry 추적 라이브러리를 사용합니다. 이러한 통합은 성능 문제를 식별하고 해결하는 데 도움이 되므로 시스템 안정성이 향상됩니다.
사전 요구 사항
APIcast 내보내기 추적을 지원하는 추적 수집기.
-
APIcast에서 유일하게 구현된 내보내기 는 gRPC(Remote Procedure call)
OTLP/gRPC를 통한OTLP(OpenTelemetry Protocol)입니다. -
OTLP over HTTP (
OTLP/HTTP)는 APIcast에서 사용되지 않습니다. -
기존 수집기에서 APIcast
OTLP/gRPC추적을 지원하지 않는 경우 추적 프록시로 OpenTelemetry 수집기 가 필요합니다.
-
APIcast에서 유일하게 구현된 내보내기 는 gRPC(Remote Procedure call)
9.1. OTP 및 gRPC 추적 수신 대기를 배포하기 위한 Jaeger 서비스 예 링크 복사링크가 클립보드에 복사되었습니다!
Jaeger 1.35 이상에서는 APIcast 내보내기 기능이 포함된 추적 수집기를 지원합니다. 결과적으로 Jaeger는 gRPC(Remote Procedure calls) OTLP/gRPC 를 통해 기본OTLP(OpenTelemetry Protocol)의 OpenTelemetry SDK에서 추적 데이터를 수신할 수 있습니다.
다음 예제는 프로덕션에 적합하지 않습니다.
Jaeger 배포 예
oc apply -f - <<EOF
oc apply -f - <<EOF
Jaeger 서비스 인스턴스는 포트 4317에서 OTLP/gRPC 추적을 수신 대기하고 포트 16686의 3scale 관리 포털에 배포됩니다.
추적 헤더 예:
"Traceparent": "00-4335058ae8ec72f9636d8c0da08c62be-137a4beaae638572-01",
"Traceparent": "00-4335058ae8ec72f9636d8c0da08c62be-137a4beaae638572-01",
9.2. 추적을 위한 APIcast 구성 링크 복사링크가 클립보드에 복사되었습니다!
3scale API에 대한 확장 가능하고 안정적인 게이트웨이 인프라를 보장하기 위해 추적을 위해 APIcast를 수동으로 구성할 수 있습니다. 그러면 API 서비스를 위한 안정적이고 확장 가능한 게이트웨이 인프라를 확보할 수 있습니다.
절차
APIcast 계측을 위한 구성 파일을 생성합니다.
구성 파일 사양은 NGINX 조정 라이브러리 리포지터리 에 정의되어 있습니다.
$ oc apply -f - <<EOF
$ oc apply -f - <<EOFCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy to Clipboard Copied! Toggle word wrap Toggle overflow
openTelemetry속성을 지정하는 APIcast CR(사용자 정의 리소스)을 정의합니다. CR 정의에서openTelemetry.tracingConfigSecretRef.name속성을 openTelemetry 구성 세부 정보가 포함된 보안 이름으로 설정합니다. 다음 예제에서는 openTelemetry 구성을 기준으로 한 콘텐츠만 보여줍니다.Copy to Clipboard Copied! Toggle word wrap Toggle overflow
9.3. 추가 리소스 링크 복사링크가 클립보드에 복사되었습니다!
II 부. API 버전 관리 링크 복사링크가 클립보드에 복사되었습니다!
10장. API 버전 관리 링크 복사링크가 클립보드에 복사되었습니다!
Red Hat 3scale API Management를 사용하면 API 버전 관리가 가능합니다. 3scale로 API를 관리할 때 API를 올바르게 버전화하는 세 가지 방법이 있습니다. 다음 방법은 3scale 아키텍처로 인한 추가 기능을 제공하는 3scale 게이트웨이 내에서 API를 버전화할 수 있는 방법의 예입니다.
10.1. 목표 링크 복사링크가 클립보드에 복사되었습니다!
이 안내서는 3scale 내에서 API 버전 관리 시스템을 구현하기에 충분한 정보를 제공하도록 설계되었습니다.
한 번 더 많은 API를 검색해 볼 수 있습니다. 사용자는 다양한 키워드로 자신의 즐겨 찾기를 검색 할 수 있습니다 : 작문가, 뮤지션, 싱가장, 제목, 제목 등. API의 초기 버전 (v1)이 있다고 가정하고 이제 새롭고 향상된 버전 (v2)을 개발했다고 가정합니다.
다음 섹션에서는 3scale를 사용하여 API 버전 관리 시스템을 구현하는 가장 일반적인 세 가지 방법에 대해 설명합니다.
- URL 버전 관리.
- 엔드포인트 버전 관리.
- 사용자 정의 헤더 버전 관리.
10.2. 사전 요구 사항 링크 복사링크가 클립보드에 복사되었습니다!
- 이 퀵 스타트 가이드를 사용하기 전에 3scale로 첫 번째 단계를 완료합니다.
10.3. URL 버전 관리 링크 복사링크가 클립보드에 복사되었습니다!
이 경우 (예: 가사에 의해, 뮤지션 제목 등에 의해) 다양한 끝점이 있는 경우, URL 버전 관리에는 API 버전이 URI의 일부로 포함됩니다.
- api.songs.com/v1/songwriter
- api.songs.com/v2/songwriter
- api.songs.com/v1/song
- api.songs.com/v2/song
- 기타 제품
이 방법을 사용할 때는 API 버전을 사용하려는 v1 이후 계획되어 있어야 합니다.
그런 다음 3scale 게이트웨이는 URI에서 끝점 및 버전을 추출합니다. 이 방법을 사용하면 모든 버전/엔드포인트 조합에 대한 애플리케이션 계획을 설정할 수 있습니다. 그런 다음 메트릭을 해당 계획 및 끝점과 연결할 수 있으며 각 버전의 각 끝점에 대한 사용량을 차트로 지정할 수 있습니다.
다음 화면 캡처에서는 3scale의 유연성을 보여줍니다.
그림 10.1. 버전 관리 계획 기능
남은 유일한 작업은 3scale 관리 포털의 [your_API_name] > Integration > Configuration 으로 이동하여 다음 다이어그램에 표시된 대로 URI를 지표에 매핑하는 것입니다.
그림 10.2. URI를 메트릭에 매핑
이제 두 가지 버전의 API가 있으며 각각 다른 기능이 활성화되어 있습니다. 또한 사용법에 대한 모든 제어 및 가시성을 확보할 수 있습니다.
API v2로 이동해야 하는 모든 사용자에게 통신하려면 이를 요청하는 내부 노트를 보낼 수 있습니다. 누가 이동했는지 모니터링하고 v2에서의 활동이 증가하는 동안 v1의 활동이 어떻게 감소하는지 확인할 수 있습니다. 3scale에 권한 부여 호출에 메트릭을 추가하면 전체 트래픽이 v1 vs에 도달했는지 확인할 수 있습니다. v2 끝점은 v1을 사용 중단하는 안전한 시기를 파악할 수 있습니다.
그림 10.3. 버전 관리
일부 사용자가 v1을 계속 사용하는 경우 해당 사용자만 필터링하여 v2로 전환에 대한 다른 내부 노트를 보낼 수 있습니다.
3scale은 사용 중단 알림을 전송하는 3단계 방법을 제공합니다.
- ECDHE > 애플리케이션 > 나열 으로 이동하여 사용 중단 노트를 보내려는 애플리케이션 계획별 목록을 필터링하고 검색을 클릭합니다.
- multiselector를 클릭하여 특정 버전에 대한 모든 애플리케이션을 선택합니다. 새 옵션을 표시하고 이메일 전송,애플리케이션 계획 변경 및 상태 변경 등 대량 작업을 수행할 수 있습니다.
- 이메일 보내기 를 클릭하고 단계에 따라 선택한 애플리케이션 소유자에게 사용 중단 알림을 보냅니다.
다음 이미지는 시각적 참조를 제공합니다.
그림 10.4. 사용 중단 노트 전송
엔드포인트에 대해 수행되는 각 authrep 호출에 대해 인증이 한 번만 인증하지만 엔드포인트에 대해 한 번, API 버전에 대해 한 번 보고합니다. 호출은 한 번만 인증될 수 있기 때문에 두 번 정상이 없습니다. 특정 API 버전의 끝점에 대해 전체 버전 트래픽을 서로 비교하는 데 사용할 수 있는 버전 번호(v1, v2 등) 뒤에 이름이 지정된 편리한 메트릭에서 히트를 집계합니다.
10.4. 끝점 버전 관리 링크 복사링크가 클립보드에 복사되었습니다!
끝점 버전 관리에서는 api.cons.com/author_v1 과 같은 API 버전에 대해 다른 끝점을 가질 수 있습니다. 게이트웨이는 엔드포인트 자체에서 끝점과 버전을 추출합니다. 이 메서드와 이전 메서드를 사용하면 API 공급자가 외부 URL을 내부 URL에 매핑할 수 있습니다.
끝점 버전 관리 방법은 온프레미스 구성의 일부로 제공되는 LUA 스크립트를 사용하여 URL 재작성이 필요하므로 온프레미스 배포 메서드에서만 수행할 수 있습니다.
| EXTERNAL | INTERNAL | |
| api.songs.com/songwriter_v1 | 다음과 같이 다시 작성할 수 있습니다. | internal.songs.com/search_by_songwriter |
| api.songs.com/songwriter_v2 | 다음과 같이 다시 작성할 수 있습니다. | internal.songs.com/songwriter |
거의 모든 기능(mapping, 애플리케이션 계획 기능 등)은 이전 방법과 동일하게 작동합니다.
10.5. 사용자 정의 헤더 버전 관리 링크 복사링크가 클립보드에 복사되었습니다!
사용자 정의 헤더 버전 관리에서는 URI 대신 헤더(즉, "x-api-version")를 사용하여 버전을 지정합니다.
그런 다음 게이트웨이는 헤더에서 경로 및 버전에서 끝점을 추출합니다. 이전과 마찬가지로 원하는 경로/버전 조합을 분석하고 시각화할 수 있습니다. 이 접근 방식에는 사용하는 API 관리 시스템에 관계없이 몇 가지 불편 사항이 있습니다. 자세한 내용은 API 버전 관리 방법, 간단한 참조를 참조하십시오. 다음은 3scale의 작동 방식에 대한 몇 가지 포인터입니다.
- 이전 방법과 마찬가지로 사용자 정의 헤더 버전 관리는 authrep 호출을 올바르게 라우팅하기 위해 요청 헤더의 일부 구문 분석/처리가 필요하기 때문에 온프레미스 호스팅 API에만 적용할 수 있습니다. 이 유형의 사용자 지정 처리는 Lua 스크립팅을 통해서만 수행할 수 있습니다.
- 이 방법을 사용하면 이전 방법을 세밀하게 분리하는 것이 달성하기가 훨씬 어렵습니다.
- 이 방법의 가장 중요한 장점은 개발자가 지정한 URL과 끝점이 변경되지 않는다는 것입니다. 개발자가 하나의 API 버전에서 다른 API 버전으로 전환하려는 경우 헤더만 변경해야 합니다. 다른 모든 것은 동일하게 작동합니다.
III 부. API 인증 링크 복사링크가 클립보드에 복사되었습니다!
11장. 인증 패턴 링크 복사링크가 클립보드에 복사되었습니다!
이 튜토리얼이 끝나면 API에서 인증 패턴을 설정하는 방법과 API와 통신하는 애플리케이션에 미치는 영향을 알아봅니다.
API에 따라 API에 액세스하기 위해 자격 증명을 발행하려면 다른 인증 패턴을 사용해야 할 수 있습니다. 이는 API 키에서 openAuth 토큰 및 사용자 정의 구성에 이르기까지 다양합니다. 이 튜토리얼에서는 사용 가능한 표준 인증 패턴에서 선택하는 방법을 설명합니다.
11.1. 지원되는 인증 패턴 링크 복사링크가 클립보드에 복사되었습니다!
Red Hat 3scale API Management는 기본적으로 다음과 같은 인증 패턴을 지원합니다.
- 표준 API 키: 식별자 및 시크릿 토큰으로 작동하는 임의의 문자열 또는 해시입니다.
- 애플리케이션 식별자 및 키 쌍: 변경할 수 있는 식별자 및 변경 가능한 시크릿 키 문자열입니다.
- OpenID Connect
11.2. 인증 패턴 설정 링크 복사링크가 클립보드에 복사되었습니다!
11.2.1. 서비스의 인증 모드를 선택합니다. 링크 복사링크가 클립보드에 복사되었습니다!
작업하려는 API 서비스로 이동합니다. (이 경우 이 서비스를 선택하는 API라는 서비스가 하나만 있을 수 있습니다). Integration 섹션으로 이동합니다.
사용하는 각 서비스는 다른 인증 패턴을 사용할 수 있지만 서비스당 하나의 패턴만 사용할 수 있습니다.
그러면 서비스 동작이 예기치 않게 될 수 있으므로 자격 증명을 등록한 후에는 인증 패턴을 변경할 수 없습니다. 인증 패턴을 변경하려면 새 서비스를 생성하고 고객을 마이그레이션하는 것이 좋습니다.
11.2.2. 사용하려는 인증 모드를 선택합니다. 링크 복사링크가 클립보드에 복사되었습니다!
인증 모드를 선택하려면 AUTHENTICATION 섹션으로 스크롤합니다. 다음 옵션 중 하나를 선택할 수 있습니다.
- API 키(user_key)
- app_id 및 App_Key pair
- OpenID Connect
11.2.3. API에서 올바른 유형의 인증 정보를 수락하는지 확인 링크 복사링크가 클립보드에 복사되었습니다!
선택한 인증 정보 유형에 따라 API 호출(키 필드, ID 등)에서 다양한 매개변수를 허용해야 할 수 있습니다. 이러한 매개변수의 이름은 3scale에서 내부적으로 사용되는 것과 동일하지 않을 수 있습니다. 3scale 백엔드 호출에 올바른 매개변수 이름이 사용되는 경우 3scale 인증이 올바르게 작동합니다.
11.2.4. 인증 정보 테스트용 애플리케이션 생성 링크 복사링크가 클립보드에 복사되었습니다!
인증 정보 세트가 작동하는지 확인하려면 API를 사용하기 위해 자격 증명을 발행할 새 애플리케이션을 생성할 수 있습니다. 관리자 포털 대시보드의 계정 영역으로 이동하여 사용할 계정을 클릭하고 새 애플리케이션을 클릭합니다.
양식을 작성하고 저장을 클릭하면 API를 사용할 자격 증명이 포함된 새 애플리케이션이 생성됩니다. 이제 이러한 인증 정보를 사용하여 API에 대한 호출을 수행할 수 있으며 레코드는 3scale에 등록된 애플리케이션 목록에 대해 확인됩니다.
11.3. 표준 인증 패턴 링크 복사링크가 클립보드에 복사되었습니다!
3scale은 다음 섹션에 설명된 인증 패턴을 지원합니다.
11.3.1. API 키 링크 복사링크가 클립보드에 복사되었습니다!
지원되는 가장 간단한 형태의 인증 정보는 단일 API 모델입니다. 여기에서 API에 대한 권한이 있는 각 애플리케이션에는 단일(unique) 긴 문자 문자열이 있습니다. 예를 들면 다음과 같습니다.
API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13
API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13
기본적으로 key 매개변수의 이름은 user_key 입니다. 이 레이블을 사용하거나 API-키 와 같은 다른 레이블을 선택할 수 있습니다. 다른 레이블을 선택하는 경우 3scale에 대한 권한 부여 호출을 수행하기 전에 값을 매핑해야 합니다. 문자열은 API를 사용하기 위해 식별자와 시크릿 토큰 모두에서 작동합니다. 보안 요구 사항이 낮은 환경에서 또는 API 호출 시 SSL 보안이 있는 환경에서만 이러한 패턴을 사용하는 것이 좋습니다. 다음은 토큰 및 애플리케이션에서 수행할 수 있는 작업입니다.
- Application Suspend: API에 대한 애플리케이션 액세스를 일시 중지하고 실제로 관련 키를 사용하여 API에 대한 모든 호출이 일시 중단됩니다.
- 애플리케이션 재시작: 애플리케이션 일시 중단 작업의 영향을 해제합니다.
- Key Regenerate: 이 작업은 애플리케이션에 대한 새로운 난수 문자열 키를 생성하고 이를 애플리케이션과 연결합니다. 이 작업을 수행한 직후 이전 토큰과의 호출은 수락됩니다.
후자의 작업은 관리 포털의 API 관리 및 API 개발자 사용자 콘솔에서 (허용된 경우)에서 트리거할 수 있습니다.
11.3.2. app_id 및 App_Key 쌍 링크 복사링크가 클립보드에 복사되었습니다!
API 키 패턴은 애플리케이션의 ID와 시크릿 사용 토큰을 하나의 토큰으로 결합합니다. 그러나 이 패턴은 다음 두 개를 구분합니다.
- API를 사용하는 각 애플리케이션은 애플리케이션 ID(App ID )라는 변경 불가능한 초기 식별자를 발행합니다. 앱 ID는 일정하며 시크릿일 수도 있고 아닐 수도 있습니다.
- 또한 각 애플리케이션은 1~5개의 애플리케이션 키(App_Keys )를 보유할 수 있습니다. 각 키는 App_ID와 직접 연결되며 시크릿으로 처리되어야 합니다.
app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4
app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4
기본 설정에서 개발자는 애플리케이션당 최대 5개의 키를 생성할 수 있습니다. 이를 통해 개발자는 새 키를 생성하고, 코드에 추가하고, 애플리케이션을 재배포한 다음 이전 키를 비활성화할 수 있습니다. 이로 인해 애플리케이션이 API 키 재생 방식을 중단하지 않습니다.
통계 및 속도 제한은 항상 API 키가 아닌 애플리케이션 ID 수준으로 유지됩니다. 개발자가 두 가지 통계 세트를 추적하려는 경우 두 개의 키가 아닌 두 개의 애플리케이션을 생성해야 합니다.
또한 시스템의 모드를 변경하고 애플리케이션 키가 없는 상태에서 애플리케이션을 생성할 수 있습니다. 이 경우 3scale 시스템은 앱 ID만 기반으로 액세스를 인증합니다(키 검사가 수행되지 않음). 이 모드는 위젯 유형 시나리오에나 속도 제한이 애플리케이션이 아닌 사용자에게 적용되는 경우 유용합니다. 대부분의 경우 API에서 애플리케이션당 하나 이상의 애플리케이션 키가 있어야 합니다. 이 설정은 [your_API_name] > 통합 > 설정에서 사용할 수 있습니다.
11.3.3. OpenID Connect 링크 복사링크가 클립보드에 복사되었습니다!
OpenID Connect 인증에 대한 자세한 내용은 OpenID Connect 통합 장을 참조하십시오.
11.4. 참조 필터링 링크 복사링크가 클립보드에 복사되었습니다!
3scale은 애플리케이션이 API에 액세스할 수 있는 IP 주소 또는 도메인 이름을 허용 목록에 추가하는 데 사용할 수 있는 참조 필터링 기능을 지원합니다. API 클라이언트는 참조 자 헤더에 참조 값을 지정합니다. 참조 헤더의 목적 및 사용은 RFC 7231, section 5.5.2: Referer 에 설명되어 있습니다. Referer 는 RFC 및 헤더에서 참조 자의 공식 잘못된 철자입니다.
참조 필터링 기능이 작동하려면 서비스 정책 체인에서 APIcast Referrer 정책을 활성화해야 합니다.
참조 필터링 기능을 활성화하려면 [your_API_name] > 애플리케이션 > 설정 > 사용 규칙으로 이동합니다. 참조 필요 필터링을 선택하고 제품 업데이트를 클릭합니다.
API에 액세스할 수 있는 개발자는 개발자 포털에서 허용된 도메인/IP 참조자를 구성해야 합니다.
이 서비스에 속하는 모든 애플리케이션에 대한 애플리케이션 세부 정보 페이지에 새 참조 필터 섹션이 표시됩니다. 여기에서 관리자는 이 애플리케이션에 허용되는 참조 헤더 값의 허용 목록을 구성할 수도 있습니다.
애플리케이션당 최대 5개의 참조 값을 설정할 수 있습니다.
값은 라틴 문자, 숫자 및 특수 문자 *, ., 및 - 로만 구성할 수 있습니다. * 와일드카드 값에 사용할 수 있습니다. 값이 * 로 설정되면 참조 값이 허용되므로 참조자 검사를 건너뜁니다.
참조 필터링 기능 및 3scale API Management Referrer 정책이 활성화되면 권한 부여는 다음과 같이 작동합니다.
- 참조 필터가 지정되지 않은 애플리케이션은 일반적으로 제공된 자격 증명을 통해서만 권한이 부여됩니다.
-
Referrer Filters 값이 설정된 애플리케이션의 경우 APIcast는 요청의 참조 헤더에서 참조 값을 추출하고 AuthRep(authorize 및 report) 요청의
참조요청에서 Service Management API로 보냅니다.다음 표는 참조 필터링 매개변수의 다양한 조합에 대한 AuthRep 응답을 보여줍니다.
참조 매개변수 가 전달됩니까? | 앱에 대해 구성된 참조 필터 | 참조 매개변수 값 | HTTP 응답 | 응답 본문 |
|---|---|---|---|---|
| 제공됨 | 제공됨 | 일치 참조 필터 | 200 OK |
|
| 제공됨 | 제공되지 않음 | 일치 참조 필터 | 200 OK |
|
| 제공됨 | 제공됨 | 참조 필터와 일치하지 않음 | 409 충돌 |
< |
| 제공됨 | 제공되지 않음 | 참조 필터와 일치하지 않음 | 200 OK |
|
| 제공됨 | 제공됨 |
| 200 OK |
|
| 제공됨 | 제공되지 않음 |
| 200 OK |
|
| 제공되지 않음 | 제공됨 | — | 409 충돌 |
|
| 제공되지 않음 | 제공되지 않음 | — | 200 OK |
|
AuthRep에서 승인하지 않은 호출은 "Authorization Failed" 오류와 함께 APIcast에서 거부됩니다. 서비스 통합 페이지에서 정확한 상태 코드와 오류 메시지를 구성할 수 있습니다.
12장. 3scale API Management와 OpenID Connect ID 공급자 통합 링크 복사링크가 클립보드에 복사되었습니다!
API 요청을 인증하기 위해 Red Hat 3scale API Management는 OpenID Connect 사양 을 준수하는 ID 공급자와 통합할 수 있습니다. 3scale과의 완전한 호환성을 위해 ID 공급자는 RH-SSO(Red Hat Single Sign-On) 또는 기본 Keycloak 클라이언트 등록을 구현하는 타사 ID 공급자일 수 있습니다. 3scale API 게이트웨이(APIcast)와의 호환성을 위해 OpenID Connect를 구현하는 모든 ID 공급자를 사용할 수 있습니다.
3scale는 RFC 7591 동적 클라이언트 등록 메커니즘 을 사용하지 않습니다. 3scale과 OpenID Connect ID 공급자 간의 완전한 호환성을 위해 기본 Keycloak 클라이언트 등록에 종속되어 있습니다.
OpenID Connect의 기반은 OAuth 2.0 인증 프레임워크(RFC 6749)입니다. OpenID Connect는 API 요청에서 JSON 웹 토큰(JWT)(RFC 7519) 을 사용하여 해당 요청을 인증합니다. OpenID Connect ID 공급자와 3scale을 통합하면 프로세스에는 다음 두 가지 주요 부분이 있습니다.
- APIcast는 요청에서 JWT를 구문 분석하고 확인합니다. 성공하면 APIcast가 API 소비자 클라이언트 애플리케이션의 ID를 인증합니다.
- 3scale Zync 구성 요소는 3scale 애플리케이션 세부 정보를 OpenID Connect ID 공급자와 동기화합니다.
3scale은 RH-SSO가 OpenID Connect ID 공급자인 경우 이러한 통합 포인트를 모두 지원합니다. 지원되는 구성 페이지에서 지원되는 RH-SSO 버전을 참조하십시오. 그러나 RH-SSO는 요구 사항이 아닙니다. OpenID Connect 사양과 기본 Keycloak 클라이언트 등록을 지원하는 모든 ID 공급자를 사용할 수 있습니다. APIcast 통합은 RH-SSO 및 ForgeRock 으로 테스트됩니다.
다음 섹션에서는 OpenID Connect ID 공급자를 사용하도록 3scale을 구성하는 정보와 지침을 제공합니다.
- 3scale API Management 및 OpenID Connect ID 공급자 통합 개요
- APIcast에서 JSON 웹 토큰을 처리하는 방법
- 3scale API Management Zync가 OpenID Connect ID 공급자와 애플리케이션 세부 정보를 동기화하는 방법
- Red Hat Single Sign-On과 3scale API Management를 OpenID Connect ID 공급자로 통합
- 타사 OpenID Connect ID 공급자와 3scale API Management 통합
- OpenID Connect ID 공급자를 사용하여 3scale API Management 테스트
- 3scale API Management 통합 및 OpenID Connect ID 공급자의 예
12.1. 3scale API Management 및 OpenID Connect ID 공급자 통합 개요 링크 복사링크가 클립보드에 복사되었습니다!
각 기본 Red Hat 3scale API Management 구성 요소는 다음과 같이 인증에 참여합니다.
- APIcast는 API 소비자 애플리케이션에서 제공하는 인증 토큰의 진위 여부를 확인합니다. 기본 3scale 배포에서 API 제품의 OpenID Connect 구성에 대한 자동 검색을 구현하므로 APIcast를 수행할 수 있습니다.
- API 공급자는 관리 포털을 사용하여 인증 흐름을 설정합니다.
- 3scale 관리형 API에서 표준 API 키 또는 애플리케이션 식별자 및 키 쌍을 사용하여 요청을 인증하지 않으면 API 공급자가 3scale을 OpenID Connect ID 공급자와 통합해야 합니다. 아래 그림에서 OpenID Connect ID 공급자는 Red Hat Single Sign-On입니다.
- 인증이 구성되고 실시간 개발자 포털을 통해 API 소비자는 개발자 포털을 사용하여 특정 3scale API 제품에 대한 액세스를 제공하는 애플리케이션 계획을 구독합니다.
- OpenID Connect가 3scale과 통합되면 subscription에서 API 소비자 애플리케이션에 대해 구성된 흐름을 트리거하여 OpenID Connect ID 공급자에서 JSON 웹 토큰(JWT)을 가져옵니다. API 공급자는 OpenID Connect를 사용하도록 API 제품을 구성할 때 이 흐름을 지정합니다.
그림 12.1. OpenID Connect ID 공급자가 있는 기본 3scale 구성 요소를 보여줍니다.
애플리케이션 계획을 구독하면 API 소비자는 통합 OpenID Connect ID 공급자에서 인증 자격 증명을 받습니다. 이러한 인증 정보를 사용하면 API 소비자 애플리케이션이 업스트림 API로 전송하는 요청을 활성화할 수 있습니다. 이 API는 API 소비자가 액세스할 수 있는 3scale API 제품에서 제공하는 API입니다.
인증 정보에는 클라이언트 ID와 클라이언트 시크릿이 포함됩니다. API 소비자가 생성한 애플리케이션은 이러한 자격 증명을 사용하여 OpenID Connect ID 공급자에서 JSON 웹 토큰(JWT)을 가져옵니다. OpenID Connect와 3scale 통합을 구성할 때 API 소비자 애플리케이션이 JWT를 가져오는 방법에 대한 흐름을 선택합니다. Red Hat Single Sign-On과 기본 인증 코드 흐름을 사용하는 API 소비자 애플리케이션에서는 다음을 수행해야 합니다.
- 업스트림 API 백엔드에 대한 첫 번째 요청 전에 OpenID Connect ID 공급자를 사용하여 OAuth 권한 부여 흐름을 시작합니다. 인증 코드 흐름은 최종 사용자를 Red Hat Single Sign-On으로 리디렉션합니다. 최종 사용자가 로그인하여 권한 부여 코드를 가져옵니다.
- JWT에 대한 권한 부여 코드를 교환합니다.
- 인증 시 Red Hat Single Sign-On에서 JWT를 수신합니다.
- JWT가 포함된 API 요청을 업스트림 API 백엔드에 보냅니다.
- 만료될 때까지 동일한 JWT를 사용하여 후속 API 요청을 보냅니다.
- JWT를 새로 고치거나 새 요청을 OpenID Connect ID 공급자로 보내 새 JWT를 가져옵니다. 필요한 작업은 OpenID Connect ID 공급자에 따라 다릅니다.
APIcast는 API 소비자로부터 요청을 수신하고 요청에서 JWT를 확인합니다. APIcast가 JWT를 확인하는 경우 APIcast는 JWT를 포함한 요청을 업스트림 API 백엔드에 보냅니다.
그림 12.2. OpenID Connect ID 공급자가 Red Hat Single Sign-On이지만 다른 OpenID Connect ID 공급자와의 구성이 가능함을 보여줍니다.
12.2. APIcast에서 JSON 웹 토큰을 처리하는 방법 링크 복사링크가 클립보드에 복사되었습니다!
APIcast는 OpenID Connect ID 공급자가 API 소비자 애플리케이션을 인증할 때 반환되는 JSON 웹 토큰(JWT)을 확인하여 각 요청을 처리합니다. 요청에는 통합 OpenID Connect ID 공급자가 발행한 형식의 JWT가 포함됩니다. JWT는 Authorization 헤더에 있어야 하며 Bearer 스키마를 사용해야 합니다. 예를 들어 헤더는 다음과 같아야 합니다.
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbSIsInN1YiI6ImFiYzEyMyIsIm5iZiI6MTUzNzg5MjQ5NCwiZXhwIjoxNTM3ODk2MDk0LCJpYXQiOjE1Mzc4OTI0OTQsImp0aSI6ImlkMTIzNDU2IiwidHlwIjoiQmVhcmVyIn0.LM2PSmQ0k8mR7eDS_Z8iRdGta-Ea-pJRrf4C6bAiKz-Nzhxpm7fF7oV3BOipFmimwkQ_-mw3kN--oOc3vU1RE4FTCQGbzO1SAWHOZqG5ZUx5ugaASY-hUHIohy6PC7dQl0e2NlAeqqg4MuZtEwrpESJW-VnGdljrAS0HsXzd6nENM0Z_ofo4ZdTKvIKsk2KrdyVBOcjgVjYongtppR0cw30FwnpqfeCkuATeINN5OKHXOibRA24pQyIF1s81nnmxLnjnVbu24SFE34aMGRXYzs4icMI8sK65eKxbvwV3PIG3mM0C4ilZPO26doP0YrLfVwFcqEirmENUAcHXz7NuvA
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbSIsInN1YiI6ImFiYzEyMyIsIm5iZiI6MTUzNzg5MjQ5NCwiZXhwIjoxNTM3ODk2MDk0LCJpYXQiOjE1Mzc4OTI0OTQsImp0aSI6ImlkMTIzNDU2IiwidHlwIjoiQmVhcmVyIn0.LM2PSmQ0k8mR7eDS_Z8iRdGta-Ea-pJRrf4C6bAiKz-Nzhxpm7fF7oV3BOipFmimwkQ_-mw3kN--oOc3vU1RE4FTCQGbzO1SAWHOZqG5ZUx5ugaASY-hUHIohy6PC7dQl0e2NlAeqqg4MuZtEwrpESJW-VnGdljrAS0HsXzd6nENM0Z_ofo4ZdTKvIKsk2KrdyVBOcjgVjYongtppR0cw30FwnpqfeCkuATeINN5OKHXOibRA24pQyIF1s81nnmxLnjnVbu24SFE34aMGRXYzs4icMI8sK65eKxbvwV3PIG3mM0C4ilZPO26doP0YrLfVwFcqEirmENUAcHXz7NuvA
JWT를 안전하게 디코딩하는 데 필요한 여러 가지 오픈 소스 도구가 있습니다. 공개 웹 도구에서 JWT를 디코딩하지 않도록 주의하십시오. 디코딩된 JWT에서는 토큰에 다음 세 부분이 있음을 확인할 수 있습니다.
- 헤더는 토큰이 어떻게 형성되었는지, 토큰 서명에 사용된 알고리즘에 대한 정보를 제공합니다.
- 페이로드는 요청을 보낸 API 소비자를 식별합니다. 세부 정보에는 이 API 사용자가 수행할 수 있는 읽기 및 쓰기 작업, API 소비자에 대한 이메일 주소, API 소비자에 대한 기타 정보가 포함될 수 있습니다.
- 서명은 토큰이 변경되지 않았음을 나타내는 암호화 서명입니다.
APIcast는 JWT에서 다음 특성을 확인합니다.
무결성
JWT가 악의적인 사용자에 의해 변경되고 있습니까? 서명이 유효한가요?
JWT에는 토큰 수신자가 알려진 발급자가 토큰에 서명했는지 확인할 수 있는 서명이 포함되어 있습니다. 이 확인은 또한 해당 콘텐츠가 생성된 대로 유지되도록 합니다. 3scale은 공개/개인 키 쌍을 기반으로 RSA 서명을 지원합니다. 발행자는 개인 키를 사용하여 JWT에 서명합니다. APIcast는 공개 키를 사용하여 토큰을 확인합니다. APIcast는 OpenID Connect Discovery 를 사용하여 JWT 서명을 확인하는 데 사용할 수 있는 JSON 웹 키(JWK)를 가져옵니다.
타이밍
현재 시간이 토큰을 처리할 수 있는 시간 이후입니까? JWT가 만료됩니까? 즉, APIcast는 JWT
nbf(이전가 아님) 및만료시간(종료 시간) 클레임을 확인합니다.issuer
APIcast로 알려진 OpenID Connect ID 공급자가 발행한 JWT가 있습니까? 즉, APIcast는 JWT에 지정된 발행자가 OpenID Connect Issuer 필드에 구성된 API 공급자와 동일한 발행자인지 확인합니다. 발행자의 사양은 3scale 및 OpenID Connect ID 공급자를 통합하는 절차의 일부입니다. 이는 JWT의 클레임
입니다.클라이언트 ID
토큰에 APIcast로 알려진 3scale 클라이언트 애플리케이션 ID가 포함되어 있습니까? 이 클라이언트 ID는 3scale 을 OpenID Connect ID 공급자와 통합하기 위해 지정된 API 공급자가 ClientID 토큰과 일치해야 합니다. 이는 JWT가 발행된 JWT
azp(인증자) 및aud(기호) 클레임입니다.
JWT 검증 또는 권한 부여 검사가 실패하면 APIcast에서 Authentication failed 오류를 반환합니다. 그렇지 않으면 APIcast가 요청을 3scale 업스트림 API 백엔드로 전송합니다. Authorization 헤더는 요청에 남아 있으므로 API 백엔드에서 JWT를 사용하여 사용자 및 클라이언트 ID를 확인할 수도 있습니다.
12.3. 3scale API Management Zync가 OpenID Connect ID 공급자와 애플리케이션 세부 정보를 동기화하는 방법 링크 복사링크가 클립보드에 복사되었습니다!
Zync는 3scale 애플리케이션에 대한 데이터를 OpenID Connect ID 공급자로 안정적으로 푸시하는 3scale 구성 요소입니다. 이러한 상호 작용에서 3scale 애플리케이션은 OpenID Connect ID 공급자 클라이언트에 해당합니다. 즉, Zync는 OpenID Connect ID 공급자와 통신하여 OpenID Connect 클라이언트를 생성, 업데이트 및 삭제합니다.
Zync는 Keycloak 기본 클라이언트 등록을 구현합니다. 이 API를 사용하면 클라이언트 표현이 Keycloak 및 Red Hat Single Sign-On과 관련이 있습니다. ID 공급자는 3scale 애플리케이션의 인증 자격 증명인 클라이언트 ID와 클라이언트 시크릿을 반환합니다.
3scale가 애플리케이션을 생성, 업데이트 또는 삭제할 때마다 Zync는 OpenID Connect ID 공급자와 통신하여 해당 클라이언트를 적절하게 업데이트합니다. 동기화를 성공적으로 수행하려면 지정된 3scale 제품에 대해 다음 설정이 필요합니다.
- 인증 메커니즘은 OpenID Connect입니다.
OpenID Connect Issuer 유형 은 다음 중 하나입니다.
- Red Hat Single Sign-On 이 OpenID Connect ID 공급자인 경우 Red Hat Single Sign-On. 이 발행자 유형을 사용하면 Zync는 클라이언트 등록 요청을 Keycloak/Red Hat Single Sign-On 기본 클라이언트 등록 API로 보냅니다.
- 다른 OpenID Connect ID 공급자를 위한 REST API 이 발행자 유형에서 Zync REST API 예제에 표시된 대로 Zync 클라이언트 등록 요청을 보냅니다.
-
다음과 같은 URL은 OpenID Connect Issuer:
http://id:/api_endpoint입니다.
OpenShift 클러스터에 배포할 때 두 개의 Zync 프로세스가 있습니다.
zync
zync는
system-sidekiq에서 알림을 수신하고 background 작업을zync-que로 큐에 추가하는 REST API입니다. 새로운, 업데이트 및 삭제된 3scale 애플리케이션에 대한 알림이 있습니다.zync-que
zync-que는
system-app및 OpenID Connect ID 공급자와 통신하는 이러한 백그라운드 작업을 처리합니다. 예를 들어 Red Hat Single Sign-On이 구성된 OpenID Connect ID 공급자인 경우 Zync는 Red Hat Single Sign-On 영역에서 클라이언트를 생성, 업데이트 및 삭제합니다.
12.4. Red Hat Single Sign-On과 3scale API Management를 OpenID Connect ID 공급자로 통합 링크 복사링크가 클립보드에 복사되었습니다!
API 공급자는 Red Hat 3scale API Management를 OpenID Connect ID 공급자로 Red Hat Single Sign-On과 통합할 수 있습니다. 여기에 설명된 절차는 API 요청을 인증하기 위해 OpenID Connect가 필요한 3scale API 제품에 대한 것입니다.
이 절차의 일부는 Zync가 Red Hat Single Sign-On과 통신하기 때문에 3scale Zync와 Red Hat Single Sign-On 간의 SSL 연결을 설정하여 토큰을 교환하는 것입니다. Zync와 Red Hat Single Sign-On 간의 SSL 연결을 구성하지 않으면 토큰은 모든 사용자에게 열려 있습니다.
3scale 2.2 이상 버전에서는 SSL_CERT_FILE 환경 변수를 사용하는 Red Hat Single Sign-On의 사용자 정의 CA 인증서를 지원합니다. 이 변수는 인증서 번들의 로컬 경로를 가리킵니다. 3scale과 Red Hat Single Sign-On을 OpenID Connect ID 공급자로 통합하는 작업은 다음 순서로 다음 요소를 구성하는 것으로 구성됩니다.
- Red Hat Single Sign-On에서 신뢰할 수 있는 CA(인증 기관)에서 발급한 인증서를 사용하지 않는 경우 사용자 정의 CA 인증서를 사용하도록 3scale Zync를 구성해야 합니다. Red Hat Single Sign-On에서 신뢰할 수 있는 CA에서 발급한 인증서를 사용하는 경우에는 필요하지 않습니다.
- 3scale 클라이언트를 갖도록 Red Hat Single Sign-On을 구성합니다.
- Red Hat Single Sign-On에서 작동하도록 3scale을 구성합니다.
사전 요구 사항
Red Hat Single Sign-On 서버는
HTTPS를 통해 사용할 수 있어야 하며zync-que에서 연결할 수 있어야 합니다. 이를 테스트하려면zync-quePod 내에서curl https://rhsso-fqdn를 실행할 수 있습니다. 예를 들면 다음과 같습니다.oc rsh -n $THREESCALE_PROJECT $(oc get pods -n $THREESCALE_PROJECT --field-selector=status.phase==Running -o name | grep zync-que) /bin/bash -c "curl -v https://<rhsso-fqdn>/auth/realms/master"
$ oc rsh -n $THREESCALE_PROJECT $(oc get pods -n $THREESCALE_PROJECT --field-selector=status.phase==Running -o name | grep zync-que) /bin/bash -c "curl -v https://<rhsso-fqdn>/auth/realms/master"Copy to Clipboard Copied! Toggle word wrap Toggle overflow - OpenShift 클러스터 관리자 권한.
- Red Hat Single Sign-On과 OpenID Connect 통합을 구성하려는 3scale API 제품입니다.
자세한 내용은 다음 섹션을 참조하십시오.
12.4.1. 사용자 정의 인증 기관 인증서를 사용하도록 3scale API Management Zync 구성 링크 복사링크가 클립보드에 복사되었습니다!
이는 Red Hat Single Sign-On에서 신뢰할 수 있는 CA(인증 기관)에서 발급한 인증서를 사용하는 경우에는 필요하지 않습니다. 그러나 Red Hat Single Sign-On에서 신뢰할 수 있는 CA에서 발급한 인증서를 사용하지 않는 경우 Red Hat 3scale API Management Zync를 3scale 클라이언트를 갖도록 설정하고 3scale 클라이언트를 설정하기 전에 Red Hat Single Sign-On을 구성해야 합니다.
절차
-
.pem형식으로 CA 인증서 체인을 가져와서 각 인증서를 별도의 파일로 저장합니다(예:customCA1.pem,customCA2.pem등). 각 인증서 파일을 테스트하여 유효한 CA인지 확인합니다. 예를 들어 다음과 같습니다.
openssl x509 -in customCA1.pem -noout -text | grep "CA:"
$ openssl x509 -in customCA1.pem -noout -text | grep "CA:"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 그러면
CA:TRUE또는CA:FALSE가 출력됩니다. 각 인증서 파일에 대한 출력이CA:TRUE로 설정되어야 합니다. 출력이CA:FALSE인 경우 인증서는 유효한 CA가 아닙니다.아래
cURL명령을 사용하여 각 인증서 파일을 검증합니다. 예를 들어 다음과 같습니다.curl -v https://<secure-sso-host>/auth/realms/master --cacert customCA1.pem
$ curl -v https://<secure-sso-host>/auth/realms/master --cacert customCA1.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow &
lt;secure-sso-host>를 Red Hat Single Sign-On 호스트의 정규화된 도메인 이름으로 바꿉니다.예상되는 응답은 Red Hat Single Sign-On 영역의 JSON 구성입니다. 검증에 실패하면 인증서가 올바르지 않을 수 있습니다.
zync-quePod에서/etc/pki/tls/cert.pem파일의 기존 콘텐츠를 수집합니다.oc exec <zync-que-pod-id> -- cat /etc/pki/tls/cert.pem > zync.pem
$ oc exec <zync-que-pod-id> -- cat /etc/pki/tls/cert.pem > zync.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow 각 사용자 정의 CA 인증서 파일의 내용을
zync.pem에 추가합니다. 예를 들면 다음과 같습니다.cat customCA1.pem customCA2.pem ... >> zync.pem
$ cat customCA1.pem customCA2.pem ... >> zync.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow 새 파일을
zync-quePod에 configmap 오브젝트로 연결합니다.oc create configmap zync-ca-bundle --from-file=./zync.pem oc set volume dc/zync-que --add --name=zync-ca-bundle --mount-path /etc/pki/tls/zync/zync.pem --sub-path zync.pem --source='{"configMap":{"name":"zync-ca-bundle","items":[{"key":"zync.pem","path":"zync.pem"}]}}'$ oc create configmap zync-ca-bundle --from-file=./zync.pem $ oc set volume dc/zync-que --add --name=zync-ca-bundle --mount-path /etc/pki/tls/zync/zync.pem --sub-path zync.pem --source='{"configMap":{"name":"zync-ca-bundle","items":[{"key":"zync.pem","path":"zync.pem"}]}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow 이렇게 하면
zync-quePod에 인증서 번들 추가가 완료됩니다.인증서가 연결되고 내용이 올바른지 확인합니다.
oc exec <zync-que-pod-id> -- cat /etc/pki/tls/zync/zync.pem
$ oc exec <zync-que-pod-id> -- cat /etc/pki/tls/zync/zync.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow 새 CA 인증서 번들을 가리키도록 Zync에서
SSL_CERT_FILE환경 변수를 구성합니다.oc set env dc/zync-que SSL_CERT_FILE=/etc/pki/tls/zync/zync.pem
$ oc set env dc/zync-que SSL_CERT_FILE=/etc/pki/tls/zync/zync.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow
12.4.2. 3scale API Management 클라이언트를 갖도록 Red Hat Single Sign-On 구성 링크 복사링크가 클립보드에 복사되었습니다!
OpenShift Red Hat Single Sign-On 대시보드에서 Red Hat 3scale API Management 클라이언트를 보유하도록 Red Hat Single Sign-On을 구성합니다. 이는 특수 관리 클라이언트입니다. API 소비자가 개발자 포털의 API를 구독할 때마다 3scale은 이 절차에서 생성한 Red Hat Single Sign-On 관리 클라이언트를 사용하여 API 소비자 애플리케이션에 대한 클라이언트를 생성합니다.
절차
- Red Hat Single Sign-On 콘솔에서 3scale 클라이언트의 영역을 생성하거나 3scale 클라이언트를 포함할 기존 영역을 선택합니다.
- 새 영역 또는 선택한 영역의 왼쪽 탐색 패널에서 클라이언트를 클릭합니다.
- 생성 을 클릭하여 새 클라이언트를 생성합니다.
-
클라이언트 ID 필드에서 이 클라이언트를 3scale 클라이언트로 식별하는 데 도움이 되는 이름을 지정합니다(예:
oidc-issuer-for-3scale). -
클라이언트 프로토콜 필드를
openid-connect로 설정합니다. - 새 클라이언트를 저장합니다.
새 클라이언트의 설정에서 다음을 설정합니다.
-
보안 유형에
액세스하십시오. -
표준 흐름은
OFF로 설정되어 있습니다. -
OFF로 활성화된 직접 액세스 권한 부여. ON에 사용되는 서비스 계정. 이 설정을 사용하면 이 클라이언트에서 서비스 계정을 발행할 수 있습니다.- 저장을 클릭합니다.
-
보안 유형에
클라이언트에 대한 서비스 계정 역할을 설정합니다.
- 클라이언트의 서비스 계정 역할 탭으로 이동합니다.
- 클라이언트 역할 드롭다운 목록에서 realm-management 를 클릭합니다.
- 사용 가능한 역할 창에서 manage-clients 를 선택하고, 선택한 항목 추가를 클릭하여 역할을 할당합니다.
클라이언트 자격 증명을 확인합니다.
-
클라이언트 ID(<
client_id>)를 기록해 둡니다. -
클라이언트의 Credentials 탭으로 이동하여 Secret 필드(<
client_secret>)를 기록해 둡니다.
-
클라이언트 ID(<
권한 부여 흐름을 원활하게 테스트하려면 사용자를 영역에 추가합니다.
- 창 왼쪽에서 사용자를 확장합니다.
- 사용자 추가를 클릭합니다.
-
사용자 이름을 입력하고 이메일 확인 을
ON으로 설정한 다음 저장을 클릭합니다. -
자격 증명 탭에서 암호를 설정합니다. 두 필드에 암호를 입력하고 다음 로그인 시 암호 재설정을 방지하려면 임시 스위치를
OFF로 설정하고 암호 설정을 클릭합니다. - 팝업 창이 표시되면 암호 설정을 클릭합니다.
12.4.3. Red Hat Single Sign-On에서 작동하도록 3scale API Management 구성 링크 복사링크가 클립보드에 복사되었습니다!
3scale 관리 포털에서 통합 설정을 지정하여 Red Hat 3scale API Management를 Red Hat Single Sign-On에서 작동하도록 구성합니다.
절차
- 3scale 관리 포털의 최상위 선택기에서 제품을 클릭하고 OpenID Connect 인증을 활성화하는 3scale API 제품을 선택합니다.
- [gradle_product_name] > 통합 > 설정으로 이동합니다.
인증 에서 OAuth 2.0 흐름에 대해 OpenID Connect Use OpenID Connect를 선택합니다.
그림 12.3. OPENID CONNECT (OIDC) BASICS 섹션을 표시합니다.
- OpenID Connect Issuer Type 필드에서 설정이 Red Hat Single Sign-On 인지 확인합니다.
OpenID Connect Issuer 필드에 구성된 OpenID Connect ID 공급자의 URL을 입력합니다. 이 URL의 형식은 다음과 같습니다.
https://<client_id>:<client_secret>@<rhsso_host>:<rhsso_port>/auth/realms/<realm_name>
https://<client_id>:<client_secret>@<rhsso_host>:<rhsso_port>/auth/realms/<realm_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 자리 표시자를 Red Hat Single Sign-On 클라이언트 자격 증명, Red Hat Single Sign-On 서버의 호스트 및 포트, Red Hat Single Sign-On 클라이언트를 포함하는 영역 이름으로 교체합니다.
참고두 제품에서 동일한 인증 정보를 사용하려면 각 제품 또는 동일한 발행자에 대해 고유한 OIDC 발행자를 구성해야 하지만 다른 영역을 구성해야 합니다. 또는 애플리케이션을 두 개의 개별 제품으로 분할하여 인증에 동일한 영역을 가진 동일한 OIDC 공급자를 사용할 수 있습니다. 5단계 및 6단계를 참조하십시오.
OIDC AUTHORIZATIONECDHEO W에서 다음 중 하나 이상을 선택합니다.
권한 부여 코드 흐름
Red Hat Single Sign-On에서 이는 표준 흐름입니다.
- 암시적 워크플로우
서비스 계정 흐름
클라이언트 인증 정보 흐름이라고도 합니다.
직접 액세스 부여 워크플로우
리소스 소유자 암호 자격 증명이라고도 합니다.
그림 12.4. 권한 부여 흐름을 선택하는 위치를 표시합니다.
이렇게 하면 API 소비자가 OpenID Connect ID 공급자에서 JSON 웹 토큰(JWT)을 가져오는 방법을 구성합니다. 3scale이 OpenID Connect ID 공급자로 Red Hat Single Sign-On을 통합하면 Zync는 인증 코드 흐름 만 활성화된 Red Hat Single Sign-On 클라이언트를 생성합니다. 이 흐름은 대부분의 경우에 가장 안전하고 적합한 것으로 권장됩니다. OpenID Connect ID 공급자가 지원하는 OAuth 2.0 흐름 을 선택해야 합니다.
- 아래로 스크롤하여 제품 업데이트를 클릭하여 구성을 저장합니다.
- 왼쪽 탐색 패널에서 통합 > 구성을 클릭합니다.
- 아래로 스크롤하여 Promote v를 클릭합니다. X to APIcast Preging.
다음 단계
Red Hat Single Sign-On과 ID 공급자의 통합을 테스트합니다. 모든 항목이 예상대로 작동하는 경우 Integration > Configuration 페이지로 돌아가 아래로 스크롤하여 APIcast 스테이징 버전을 프로덕션 버전으로 승격합니다.
12.5. 타사 OpenID Connect ID 공급자와 3scale API Management 통합 링크 복사링크가 클립보드에 복사되었습니다!
API 공급자는 3scale과 타사 OpenID Connect ID 공급자 간의 HTTP 통합을 구성할 수 있습니다. 즉, Red Hat Single Sign-On 이외의 OpenID Connect ID 공급자를 구성할 수 있습니다. 3scale에서는 이 통합을 사용하여 API 소비자의 요청을 인증하고 타사 ID 공급자를 최신 3scale 애플리케이션 세부 정보로 업데이트합니다.
3scale를 타사 OpenID Connect ID 공급자와 통합하는 데 필요한 대부분의 작업에는 다음 작업이 포함됩니다.
- 3scale Zync 관련 사전 요구 사항을 충족합니다.
- 3scale 애플리케이션의 요청을 승인하도록 OpenID Connect ID 공급자를 구성합니다.
사전 요구 사항
- 3scale Zync가 설치되어 있습니다.
선택한 타사 OpenID Connect ID 공급자에서 다음을 수행합니다.
- 3scale에서 제공하는 Zync의 OpenAPI 사양을 준수합니다.
-
요청에 매개 변수로 선언된 <
client_id> 및 <client_secret>을 사용하여 클라이언트를 등록할 수 있습니다. 3scale은 3scale과 타사 OpenID Connect ID 공급자 간의 통합에서 항상 클라이언트 ID 관리의 소스입니다. - 3scale 애플리케이션에서 요청을 승인하도록 구성됩니다.
구성에서 이전 사전 요구 사항을 충족할 수 없는 경우 Zync abstract 어댑터를 기반으로 하는 사용자 지정 어댑터를 구현해야 합니다. Zync는 이 어댑터를 사용하여 OpenID Connect ID 공급자와 상호 작용합니다. 이 어댑터를 생성하려면 3scale Zync REST API 예제에 포함된 rest_adapter.rb 를 수정할 수 있습니다.
요구 사항에 가장 적합한 방법에 따라
rest_adapter.rb모듈을zync-quePod에 포함할 수 있습니다. 예를 들어 볼륨을 통해configMap을 마운트하거나 Zync에 대한 새 이미지를 빌드할 수 있습니다.
절차
- 3scale 관리 포털의 최상위 선택기에서 제품을 클릭하고 OpenID Connect 인증을 활성화하는 3scale API 제품을 선택합니다.
- [gradle_product_name] > 통합 > 설정으로 이동합니다.
인증 에서 OAuth 2.0 흐름에 대해 OpenID Connect Use OpenID Connect를 선택합니다.
OPENID CONNECT (OIDC) BASICS 섹션이 표시됩니다.
- OpenID Connect Issuer 유형 필드에서 설정이 REST API 인지 확인합니다.
OpenID Connect Issuer 필드에 OpenID Connect ID 공급자의 URL을 입력합니다. 이 URL의 형식은 다음과 같습니다.
https://<client_id>:<client_secret>@<oidc_host>:<oidc_port>/<endpoint>
https://<client_id>:<client_secret>@<oidc_host>:<oidc_port>/<endpoint>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 예를 들어 Zync
rest_adapter.rb예에서 URL 끝점은{endpoint}/clients로 하드 코딩됩니다. 끝점은{endpoint}/register또는 다른 것일 수 있습니다.OIDC AUTHORIZATIONECDHEO W에서 다음 중 하나 이상을 선택합니다.
- 권한 부여 코드 흐름
- 암시적 워크플로우
- 서비스 계정 흐름
- 직접 액세스 부여 워크플로우
이렇게 하면 API 소비자 애플리케이션이 OpenID Connect ID 공급자에서 JSON 웹 토큰(JWT)을 수신하는 방법을 구성합니다. Authorization Code Flow 는 대부분의 경우 가장 안전하고 적합한 것으로 권장됩니다. OpenID Connect ID 공급자가 지원하는 OAuth 2.0 흐름 을 선택해야 합니다.
- 아래로 스크롤하여 제품 업데이트를 클릭하여 구성을 저장합니다.
- 왼쪽 탐색 패널에서 통합 > 구성을 클릭합니다.
- 아래로 스크롤하여 Promote v를 클릭합니다. X to APIcast Preging.
다음 단계
타사 ID 공급자와의 통합을 테스트합니다. 모든 항목이 예상대로 작동하는 경우 Integration > Configuration 페이지로 돌아가 아래로 스크롤하여 APIcast 스테이징 버전을 프로덕션 버전으로 승격합니다.
12.6. OpenID Connect ID 공급자와 3scale API Management 통합 테스트 링크 복사링크가 클립보드에 복사되었습니다!
OpenID Connect ID 공급자와 3scale을 통합한 후 통합을 테스트하여 다음을 확인합니다.
- API 소비자는 3scale 관리 API를 구독할 때 액세스 자격 증명을 받습니다.
- APIcast는 API 소비자의 요청을 인증할 수 있습니다.
사전 요구 사항
- 특정 3scale API 제품에 대해 3scale과 OpenID Connect ID 공급자 간의 통합이 제공됩니다. 이 통합에서는 Authorization Code Flow 를 사용합니다.
- API 소비자가 개발자 포털에서 구독할 수 있는 애플리케이션 계획을 사용할 수 있습니다. 이 애플리케이션 계획에서는 OpenID Connect 인증을 구성한 3scale 제품인 3scale API에 대한 액세스를 제공합니다.
- 업스트림 API로 요청을 전송하는 애플리케이션입니다. 업스트림 API는 서브스크립션을 통해 API 소비자 애플리케이션이 액세스할 수 있는 3scale 제품의 백엔드입니다. 또는 Postman을 사용하여 요청을 보낼 수도 있습니다.
절차
개발자 포털에서 애플리케이션 계획을 구독합니다.
그러면 개발자 포털에서 애플리케이션이 생성됩니다. OpenID Connect ID 공급자는 개발자 포털의 애플리케이션 페이지에 표시되는 클라이언트 ID와 클라이언트 시크릿을 반환해야 합니다.
- 애플리케이션의 클라이언트 ID 및 클라이언트 시크릿을 기록해 둡니다.
- OpenID Connect ID 공급자에 동일한 클라이언트 ID 및 클라이언트 시크릿이 있는지 확인합니다. 예를 들어 RH-SSO(Red Hat Single Sign-On)가 OpenID Connect ID 공급자인 경우 구성된 RH-SSO 영역에 새 클라이언트가 표시됩니다.
- 관리 포털의 애플리케이션 페이지의 REDIRECT URL 필드에 API 요청을 업스트림 API로 보내는 애플리케이션의 URL을 입력합니다.
- OpenID Connect ID 공급자에 올바른 리디렉션 URL이 있는지 확인합니다.
다음 끝점을 사용하여 OpenID Connect ID 공급자에 대한 인증 요청을 수신하는 URL을 검색합니다.
.well-known/openid-configuration
.well-known/openid-configurationCopy to Clipboard Copied! Toggle word wrap Toggle overflow 예를 들어 다음과 같습니다.
https://<rhsso_host>:<rhsso_port>/auth/realms/<realm_name>/.well-known/openid-configuration
https://<rhsso_host>:<rhsso_port>/auth/realms/<realm_name>/.well-known/openid-configurationCopy to Clipboard Copied! Toggle word wrap Toggle overflow - 기본 URL의 경우 OpenID Connect Issuer 필드에 구성된 API 공급자가 구성된 값을 사용합니다.
업스트림 API를 사용하는 애플리케이션을 작성하는 API 소비자는 다음을 수행합니다.
- OpenConnect ID 공급자를 사용하여 권한 부여 흐름을 시작합니다. 이 요청에는 3scale 애플리케이션의 클라이언트 ID 및 클라이언트 시크릿이 포함되어야 합니다. 경우에 따라 최종 사용자 ID도 필요합니다.
- 권한 부여 코드가 포함된 ID 공급자의 응답을 받습니다.
API 소비자의 애플리케이션은 다음을 수행합니다.
- JWT에 대한 권한 부여 코드를 손상시킵니다.
- 인증 시 RH-SSO에서 JWT를 받습니다.
- JWT가 포함된 API 요청을 업스트림 API 백엔드에 보냅니다.
APIcast가 요청에서 JWT를 수락하면 애플리케이션이 API 백엔드에서 응답을 받습니다.
또는 API 소비자 애플리케이션 대신 Postman을 사용하여 토큰 흐름이 올바르게 구현되었는지 테스트합니다.
12.7. OpenID Connect ID 공급자와 3scale API Management 통합의 예 링크 복사링크가 클립보드에 복사되었습니다!
이 예에서는 Red Hat 3scale API Management와 Red Hat Single Sign-On을 OpenID Connect ID 공급자로 통합할 때의 흐름을 보여줍니다. 이 예제에는 다음과 같은 특징이 있습니다.
- 관리 포털에서 API 공급자는 3scale API 제품을 정의하고 Red Hat Single Sign-On을 OpenID Connect ID 공급자로 사용하도록 구성했습니다.
이 제품의 OpenID Connect 구성은 다음과 같습니다.
-
공개 기본 URL:
https://api.example.com -
개인 기본 URL:
https://internal-api.example.com -
OpenID Connect Issuer:
https://zync:/auth/realms/myrealm - 표준 흐름인 권한 부여 코드 흐름이 선택됩니다.
-
공개 기본 URL:
3scale 개발자 포털에는 다음과 같은 특징이 있는 애플리케이션이 있습니다. 이 애플리케이션은 개발자 포털의 특정 애플리케이션 계획에서 제공하는 3scale API 제품에 대한 액세스를 구독하는 API 소비자의 결과입니다.
-
클라이언트 ID:
myclientid -
클라이언트 시크릿:
myclientsecret -
리디렉션 URL:
https://myapp.example.com
-
클라이언트 ID:
Red Hat Single Sign-On에서는 다음과 같은 특성을 가진 클라이언트가 있습니다.
-
클라이언트 ID:
myclientid -
클라이언트 시크릿:
myclientsecret -
리디렉션 URL:
https://myapp.example.com
-
클라이언트 ID:
myrealm영역에는 다음 사용자가 있습니다.-
사용자 이름:
myuser -
암호:
mypassword
-
사용자 이름:
-
myrealm의 3scale Zync 클라이언트에는 올바른 서비스 계정 역할이 있습니다.
흐름은 다음과 같습니다.
최종 사용자(API 소비자)는 다음 엔드포인트에서 인증 서버인 Red Hat Single Sign-On으로 권한 부여 요청을 보냅니다.
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/auth
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/authCopy to Clipboard Copied! Toggle word wrap Toggle overflow 요청 시 애플리케이션은 다음 매개변수를 제공합니다.
-
클라이언트 ID:
myclientid -
리디렉션 URL:
https://myapp.example.com
-
클라이언트 ID:
- 애플리케이션은 최종 사용자를 Red Hat Single Sign-On 로그인 창으로 리디렉션합니다.
최종 사용자는 다음 인증 정보를 사용하여 Red Hat Single Sign-On에 로그인합니다.
-
사용자 이름:
myuser -
암호:
mypassword
-
사용자 이름:
- 구성에 따라 및 최종 사용자가 이 특정 애플리케이션에서 인증하는 처음인지 여부에 따라 동의 창이 표시될 수 있습니다.
- Red Hat Single Sign-On은 최종 사용자에게 권한 부여 코드를 발행합니다.
API 소비자 애플리케이션은 다음 끝점을 사용하여 JWT에 대한 권한 부여 코드를 교환하도록 요청을 보냅니다.
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/token
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/tokenCopy to Clipboard Copied! Toggle word wrap Toggle overflow 요청에는 권한 부여 코드와 이러한 매개변수가 포함됩니다.
-
클라이언트 ID:
myclientid -
클라이언트 시크릿:
myclientsecret -
리디렉션 URL:
https://myapp.example.com.
-
클라이언트 ID:
-
Red Hat Single Sign-On은
eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A와 같은 access_token 필드가 있는 JWT(JSON 웹 토큰)를 반환합니다. API 소비자 애플리케이션은 다음과 같은 헤더를 사용하여 API 요청을
https://api.example.com로 보냅니다.Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A.
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A.Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
애플리케이션은
https://internal-api.example.com에서 성공적인 응답을 받아야 합니다.