Menu Close
Settings Close

Language and Page Formatting Options

API 게이트웨이 관리

Red Hat 3scale API Management 2.9

설치를 관리하기 위한 고급 목표의 중점.

초록

이 가이드에서는 기본 설치 후 수행할 수 있는 구성 작업에 관한 정보를 제공합니다.

preface

이 가이드는 고급 구성 기능에 중간 기능을 3scale 설치에 적용하는 데 도움이 됩니다. 설치에 대한 기본 내용은 Installing 3scale을 참조하십시오.

I 부. API 게이트웨이

1장. 운영 APIcast

이 섹션에서는 고급 APIcast 구성을 사용할 때 고려해야 할 개념에 대해 설명합니다.

1.1. 공개 기반 URL

Public Base URL 은 개발자가 API 제품에 대한 요청을 만드는 데 사용하는 URL이며, 이는 3scale에 공개적으로 노출됩니다. 이는 APIcast 인스턴스의 URL입니다.

셀프 관리 배포 옵션 중 하나를 사용하는 경우 관리 중인 도메인 이름에 제공된 환경(staging and production) 환경 각각에 대해 고유한 공용 기본 URL을 선택할 수 있습니다. 이 URL은 API 백엔드 중 하나와 달라야 하며, https://api.yourdomain.com:443 와 같을 수 있습니다. 여기서 yourdomain.com 은 사용자에게 속하는 도메인입니다. Public Base URL을 설정하면 변경 사항을 저장하고 필요한 경우 스테이징 변경 사항을 프로덕션으로 승격합니다.

참고

지정한 Public Base URL은 OpenShift 클러스터에서 사용할 수 있는 포트를 사용해야 합니다. 기본적으로 OpenShift 라우터는 표준 HTTP 및 HTTPS 포트(80 및 443)에서만 연결을 수신 대기합니다. 사용자가 다른 포트를 통해 API에 연결하려면 OpenShift 관리자와 협력하여 포트를 활성화합니다.

APIcast는 공용 기본 URL에 지정된 호스트 이름에 대한 호출만 허용합니다. Echo API 의 예로 https://echo-api.3scale.net:443 를 공용 기본 URL로 지정하는 경우 올바른 호출은 다음과 같습니다.

curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"

API에 대한 공용 도메인이 없는 경우 요청에 APIcast IP 주소를 사용할 수 있지만 도메인이 실제가 아닌 경우에도 Public Base URL 필드에 값을 지정해야 합니다. 이 경우 Host(호스트) 헤더에 호스트를 제공해야 합니다. 예를 들면 다음과 같습니다.

curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"

로컬 머신에 배포하는 경우 "localhost"만 도메인으로 사용할 수 있으므로 Public Base URL은 다음과 같이 표시되며 다음과 같이 요청을 만들 수 있습니다.

curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"

여러 API 제품이 있는 경우 이 Public Base URL을 각 제품에 적절하게 설정합니다. APIcast는 호스트 이름을 기반으로 요청을 라우팅합니다.

1.2. 매핑 규칙

API에 대한 요청에 따라 매핑 규칙은 보고할 지표 또는 메서드를 정의합니다. 다음은 매핑 규칙의 예입니다.

매핑 규칙

이 규칙은 / 로 시작하는 GET 요청이 메트릭 적중 을 1씩 증가함을 의미합니다. 이 규칙은 API에 대한 모든 요청과 일치합니다. 그러나 대부분의 경우 너무 일반적이므로 이 규칙을 변경할 수 있으며 보다 구체적인 규칙이 추가되면 종종 두 번 카운트가 발생합니다.

Echo API에 대한 다음 규칙은 더 구체적인 예를 보여줍니다.

Hello World 매핑 규칙

1.2.1. 제품 및 백엔드에서 규칙 매핑

매핑 규칙은 API 제품 및 API 백엔드 수준에서 작동합니다. 이 섹션에서는 각 수준에서 매핑 규칙의 동작에 대해 알아보고 매핑 규칙이 작동하는 방식을 설명하는 예제를 봅니다.

제품 수준에서 매핑 규칙

  • 매핑 규칙이 우선합니다. 즉, 제품 매핑 규칙이 평가되는 첫 번째 규칙입니다.
  • 매핑 규칙은 리디렉션된 트래픽을 수신하는 백엔드와 관계없이 항상 평가됩니다.

백엔드 수준에서 매핑 규칙

  • 백엔드에 매핑 규칙을 추가하면 백엔드가 결합된 모든 제품에 추가됩니다.
  • 매핑 규칙은 제품 수준에서 정의된 매핑 규칙 다음에 평가합니다.
  • 매핑 규칙은 트래픽이 매핑 규칙이 속하는 동일한 백엔드로 리디렉션되는 경우에만 평가됩니다.
  • 제품의 백엔드 경로는 언급된 제품에 번들로 묶인 백엔드의 각 매핑 규칙에 자동으로 앞에 추가됩니다.

제품 및 백엔드를 사용하여 룰 매핑의 예

이 예에서는 백엔드와 제품부터 시작합니다.

  • Echo API 백엔드:

    • 프라이빗 엔드 포인트가 있음: https://echo-api.3scale.net
    • 다음 패턴과 함께 2개의 매핑 규칙이 포함되어 있습니다.
/hello
/bye
  • collectd API 제품:

    • 이 공용 엔드 포인트가 있음 : https://cool.api
    • 이 라우팅 경로 /echo 와 함께 Echo API 백엔드를 사용합니다.
  • 다음 패턴을 사용한 매핑 규칙은 자동으로 API 제품의 일부입니다.
/echo/hello
/echo/bye

이제 동일한 Echo API 백엔드를 사용하는 Tools For Devs 라는 추가 제품을 고려해 보십시오.

1.2.2. 매핑 규칙 일치

매핑 규칙 일치는 접두사로 수행되며 임의로 복잡할 수 있습니다. 표기법은 OpenAPI 및 ActiveDocs 사양을 따릅니다.

  • 매핑 규칙은 슬래시(/)로 시작해야 합니다.
  • 리터럴 문자열(예: /hello)을 통해 경로에서 일치를 수행할 수 있습니다.
  • 매핑 규칙은 쿼리 문자열 또는 본문에 매개 변수를 포함할 수 있습니다(예: /{word}?value={value}). APIcast는 다음과 같은 방식으로 매개변수를 가져옵니다.

    • GET 메서드: 쿼리 문자열에서 다음을 수행합니다.
    • POST,DELETE 또는 PUT 메서드: 본문에서.
  • 매핑 규칙은 이름이 지정된 와일드카드(예: /{word})를 포함할 수 있습니다. 이 규칙은 자리 표시자 {word} 의 모든 내용과 일치하므로 /morning과 같은 요청이 규칙과 일치합니다. 와일드카드는 슬래시 간에 또는 슬래시와 점 사이에 나타날 수 있습니다. 매개 변수에는 와일드카드가 포함될 수도 있습니다.
  • 기본적으로 모든 매핑 규칙은 지정한 정렬에 따라 처음부터 마지막까지 평가됩니다. 규칙 /v1 을 추가하면 경로가 /v 1로 시작하는 요청(예: /v 1/word 또는 /v1/sentence )과 일치합니다.
  • 패턴 끝에 달러 기호($)를 추가하여 정확한 일치를 지정할 수 있습니다. 예를 들어 /v1/word$/v1/word 요청만 일치하며 /v1/word/hello 요청과 일치하지 않습니다. 정확한 일치를 위해 모든(/)와 일치하는 기본 매핑 규칙이 비활성화되었는지 확인해야 합니다.
  • 둘 이상의 매핑 규칙이 요청 경로와 일치할 수 있지만 일치하지 않으면 요청이 HTTP 404 상태 코드로 삭제됩니다.

1.2.3. 룰 워크플로 매핑

매핑 규칙에는 다음과 같은 워크플로우가 있습니다.

  • 새 매핑 규칙을 정의할 수 있습니다( 매핑 규칙 추가참조).
  • 실수로 수정되지 않도록 다음 재로드 시 매핑 규칙이 회색으로 표시됩니다.
  • 기존 매핑 규칙을 편집하려면 오른쪽의 연필 아이콘을 클릭하여 먼저 활성화해야 합니다.
  • 규칙을 삭제하려면 휴지통 아이콘을 클릭합니다.
  • 통합 > 구성 변경 사항을 승격하면 모든 수정 및 삭제가 저장됩니다.

매핑 규칙 추가

새 매핑 규칙을 추가하려면 다음 단계를 수행합니다.

  1. Add Mapping Rule (맵 규칙 추가)을 클릭합니다.
  2. 다음 설정을 지정합니다.

    • 동사: HTTP 요청 동사(GET,POST,DELETE 또는 PUT).
    • 패턴: 일치시킬 패턴(예: /hello).
    • 스케일링 또는 늘리기 방법: 지표 또는 메서드 이름입니다.
    • 증가 기준: 지표 증가 번호(예: 1).
    • 마지막?: 이 매핑 규칙을 마지막 매핑 규칙으로 간주해야 하는 경우 다른 매핑 규칙 처리를 중지합니다.
    • 위치: 매핑 규칙의 실행 위치를 나타내는 번호로 매핑 규칙을 정렬합니다.
  3. Create Mapping Rule (맵 규칙 만들기)을 클릭하여 변경 사항을 적용합니다.

다른 매핑 규칙 중지

다른 매핑 규칙 처리를 중지하려면 새 매핑 규칙을 생성할 때 Last? (마지막?)를 선택할 수 있습니다. 예를 들어 API 통합 설정에 정의된 다음 매핑 규칙이 있고 각 규칙과 관련된 다양한 메트릭이 있는 경우 다음을 수행합니다.

(get) /path/to/example/search
(get) /path/to/example/{id}

(get) /path/to/example/search 를 호출하면 APIcast는 나머지 매핑 규칙 처리를 중지하고 규칙이 일치된 후 메트릭을 늘립니다.

1.3. 호스트 헤더

이 옵션은 호스트 헤더가 예상과 일치하지 않는 한 트래픽을 거부하는 해당 API 제품에만 필요합니다. 이 경우 호스트는 게이트웨이 중 하나이므로 API 제품 앞에 게이트웨이를 두면 문제가 발생합니다 ( 예: xxx-yyy.staging.apicast.io).

이 문제를 방지하려면 인증 설정의 Host Header(호스트 헤더) 필드에 API 제품이 예상되는 호스트를 정의할 수 있으며 호스트 APIcast 인스턴스가 호스트를 다시 작성합니다.

호스트 다시 작성

1.4. API 백엔드 보호

프로덕션 환경에서 작동하는 APIcast가 있으면 인증 정보 없이 API 제품에 대한 직접 액세스를 제한할 수 있습니다. 이 작업을 수행하는 가장 쉬운 방법은 APIcast에서 설정한 Secret Token을 사용하는 것입니다. 설정 방법에 대한 자세한 내용은 Advanced APIcast 설정을 참조하십시오.

1.5. 개인 API와 함께 APIcast 사용

APIcast를 사용하면 인터넷에서 공개적으로 액세스할 수 없는 API를 보호할 수 있습니다. 충족해야 하는 요구 사항은 다음과 같습니다.

  • 자체 관리 APIcast는 배포 옵션으로 사용해야 합니다.
  • APIcast는 공용 인터넷에서 액세스할 수 있어야 하며 3scale Service Management API에 대한 아웃바운드 호출을 수행할 수 있어야 합니다.
  • API 제품은 APIcast에서 액세스할 수 있어야 합니다.

이 경우 프라이빗 기본 URL 필드에 API의 내부 도메인 이름 또는 IP 주소를 설정하고 나머지 단계를 정상적으로 따를 수 있습니다. 그러나 스테이징 APIcast 인스턴스가 3scale에서 호스팅되고 개인 API 백엔드에 액세스할 수 없으므로 스테이징 환경을 활용할 수 없으며 테스트 호출은 성공하지 못합니다. 하지만 프로덕션 환경에 APIcast를 배포하면 구성이 올바르면 APIcast가 예상대로 작동합니다.

1.6. OpenTracing을 사용하여 APIcast 구성

OpenTracing은 마이크로 서비스를 프로파일링 및 모니터링하는 데 사용되는 API 사양 및 방법입니다. 버전 3.3 이후부터 APIcast에는 OpenTracing Libraries 및 Jaeger Tracer 라이브러리가 포함됩니다.

1.6.1. 사전 요구 사항

APIcast 배포에 분산 추적을 추가하려면 다음 사전 요구 사항을 확인해야 합니다.

  • 각 외부 요청에는 일반적으로 HTTP 헤더를 통해 고유한 요청 ID가 연결되어 있어야 합니다.
  • 각 서비스는 요청 ID를 다른 서비스로 전달해야 합니다.
  • 각 서비스는 로그에 요청 ID를 출력해야 합니다.
  • 각 서비스는 요청의 시작 및 종료 시간과 같은 추가 정보를 기록해야 합니다.
  • 로그를 집계하고 HTTP 요청 ID를 통해 구문 분석하는 방법을 제공해야 합니다.

1.6.2. 절차

OpenTracing을 구성하려면 다음 환경 변수를 사용합니다.

  • OPENTRACING_TRACER: 사용할 추적 프로그램 구현을 정의하려면 다음을 수행합니다. 현재 Jaeger만 사용할 수 있습니다.
  • OPENTRACING_CONFIG: 추적 프로그램의 기본 구성 파일을 지정하려면 다음을 수행합니다. 여기에서 예를 확인할 수 있습니다.
  • OPENTRACING_HEADER_FORWARD: 선택 사항: OpenTracing 구성에 따라 이 환경 변수를 설정할 수 있습니다.

이러한 변수에 대한 자세한 내용은 APIcast 환경 변수를 참조하십시오.

통합이 제대로 작동하는지 테스트하려면 Jaeger 추적 인터페이스에서 추적이 보고되는지 확인해야 합니다.

1.6.3. 추가 정보

OpenTracing 및 Jaeger 통합은 업스트림 프로젝트에서 사용할 수 있습니다. https://github.com/3scale/apicast

1.6.4. OpenShift 인스턴스에 Jaeger 설치

이 섹션에서는 실행 중인 OpenShift 인스턴스에 Jaeger 설치에 대한 정보를 제공합니다.

주의

Jaeger는 APIcast의 사용을 제외하고 3scale에서 지원하지 않는 타사 구성 요소입니다. 다음 지침은 참조 예제로만 제공되며 프로덕션용으로는 적합하지 않습니다.

  1. 현재 네임스페이스에 Jaeger all-in-one을 설치합니다.

    oc process -f https://raw.githubusercontent.com/jaegertracing/jaeger-openshift/master/all-in-one/jaeger-all-in-one-template.yml | oc create -f -
  2. Jaeger 구성 파일 jaeger_config.json 을 생성하고 다음을 추가합니다.

    {
        "service_name": "apicast",
        "disabled": false,
        "sampler": {
          "type": "const",
          "param": 1
        },
        "reporter": {
          "queueSize": 100,
          "bufferFlushInterval": 10,
          "logSpans": false,
          "localAgentHostPort": "jaeger-agent:6831"
        },
        "headers": {
          "jaegerDebugHeader": "debug-id",
          "jaegerBaggageHeader": "baggage",
          "TraceContextHeaderName": "uber-trace-id",
          "traceBaggageHeaderPrefix": "testctx-"
        },
        "baggage_restrictions": {
            "denyBaggageOnInitializationFailure": false,
            "hostPort": "127.0.0.1:5778",
            "refreshInterval": 60
        }
     }
    • 모든 요청을 샘플링하려면 샘플러 상수 1을 설정합니다.
    • 보고자의 위치 및 큐 크기 설정
    • 요청을 추적하는 데 사용할 TraceContextHeaderName 을 포함하여 헤더 설정
  3. Jaeger 구성 파일에서 ConfigMap을 생성하고 APIcast에 마운트합니다.

    oc create configmap jaeger-config --from-file=jaeger_config.json
    oc set volumes dc/apicast --add -m /tmp/jaeger/ --configmap-name jaeger-config
  4. 방금 추가한 구성으로 OpenTracing 및 Jaeger를 활성화합니다.

    oc set env deploymentConfig/apicast OPENTRACING_TRACER=jaeger OPENTRACING_CONFIG=/tmp/jaeger/jaeger_config.json
  5. Jaeger 인터페이스가 실행 중인 URL을 찾습니다.

    oc get route
    (…) jaeger-query-myproject.127.0.0.1.nip.io
  6. Openshift Health 검사에서 채워지는 데이터를 표시하는 이전 단계에서 Jaeger 인터페이스를 엽니다.
  7. 마지막 단계는 전체 요청 추적을 볼 수 있도록 OpenTracing 및 Jaeger 지원을 백엔드 API에 추가하는 것입니다. 각 백엔드에서 사용되는 프레임워크와 언어에 따라 달라집니다. 참조 예는 Jaeger와 함께 OpenTracing을 사용하여 Kubernetes에서 애플리케이션 지표를 수집하는 것을 확인할 수 있습니다.

Jaeger 구성에 대한 자세한 내용은 다음을 참조하십시오.

2장. Docker 컨테이너화된 환경 운영

2.1. Docker 컨테이너화된 환경에서 APIcast 문제 해결

이 섹션에서는 Docker 컨테이너화된 환경에서 APIcast를 사용할 때 찾을 수 있는 가장 일반적인 문제에 대해 설명합니다.

2.1.1. Docker 데몬 오류에 연결할 수 없습니다.

docker: Docker 데몬에 연결할 수 없습니다. 이 호스트에서 Docker 데몬이 실행 중입니까? Docker 서비스가 시작되지 않았기 때문에 오류 메시지가 표시될 수 있습니다. sudo systemctl status docker.service 명령을 실행하여 Docker 데몬의 상태를 확인할 수 있습니다.

Docker 컨테이너 환경에는 기본적으로 RHEL의 루트 권한이 필요하므로 이 명령을 root 사용자로 실행해야 합니다. 자세한 내용은 여기를참조하십시오.).

2.1.2. 기본 Docker 명령줄 인터페이스 명령

분리된 모드(-d 옵션)에서 컨테이너를 시작하고 실행 중인 APIcast 인스턴스가 있는지 로그를 확인하려면 로그 명령 sudo docker logs <container> 를 사용할 수 있습니다. 여기서<container> 는 컨테이너 이름(위 예제의 "apicast ") 또는 컨테이너 ID입니다. sudo docker ps 명령을 사용하여 실행 중인 컨테이너 및 ID 및 이름 목록을 가져올 수 있습니다.

컨테이너를 중지하려면 sudo docker stop <container> 명령을 실행합니다. sudo docker rm <container> 명령을 실행하여 컨테이너를 제거할 수도 있습니다.

사용 가능한 명령에 대한 자세한 내용은 Docker 명령 참조를 참조하십시오.

3장. 고급 APIcast 구성

이 섹션에서는 스테이징 환경에서 3scale의 API 게이트웨이의 고급 설정 옵션에 대해 설명합니다.

3.1. 시크릿 토큰 정의

보안상의 이유로 3scale 게이트웨이에서 API 백엔드로의 모든 요청에는 X-3scale-proxy-secret-token 이라는 헤더가 포함되어 있습니다. Integration(통합) 페이지의 Authentication Settings(인증 설정 )에서 이 헤더의 값을 설정할 수 있습니다.

프록시 시크릿 토큰

시크릿 토큰을 설정하는 것은 프록시와 API 간의 공유 보안 역할을 하므로, 원하지 않는 경우 게이트웨이에서 제공되지 않는 모든 API 요청을 차단할 수 있습니다. 그러면 샌드박스 게이트웨이를 사용하여 트래픽 관리 정책을 설정하는 동안 공용 엔드포인트를 보호하기 위한 추가 보안 계층이 추가됩니다.

API 백엔드에는 게이트웨이가 작동하기 위한 공용 확인 가능한 도메인이 있어야 하므로 API 백엔드를 알고 있는 누구나 자격 증명 확인을 바이패스할 수 있습니다. 스테이징 환경의 API 게이트웨이가 프로덕션 사용을 위한 것이 아니라 항상 펜스를 사용할 수 있게 하는 것이 더 나기 때문에 이 문제가 되지 않습니다.

3.2. 인증 정보

3scale 내의 API 자격 증명은 사용 중인 인증 모드에 따라 user _key 또는 app_id/app_key 입니다. OpenID Connect는 스테이징 환경의 API 게이트웨이에 유효하지만 Integration(통합) 페이지에서는 테스트할 수 없습니다.

그러나 API에서 서로 다른 자격 증명 이름을 사용할 수 있습니다. 이 경우 API 키 모드를 사용하는 경우 user_key의 사용자 지정 이름을 설정해야 합니다.

사용자 지정 user_key

또는 app_id 및 app_ key 의 경우 :

Custom app_key/app_id

예를 들어 API에 적합한 경우 app_id 의 이름을 key 로 바꿀 수 있습니다. 게이트웨이는 name 키를 사용하여 3scale 백엔드에 대한 권한 부여 호출을 수행하기 전에 app_id 로 변환합니다. 새 자격 증명 이름은 영숫자여야 합니다.

쿼리 문자열(또는 GET이 아닌 경우 본문)에서 API가 자격 증명을 통과하는지 또는 헤더에서 자격 증명을 전달할지 여부를 결정할 수 있습니다.

프록시 인증 정보 위치
참고

인증 정보를 추출할 때 APIcast는 헤더 이름을 정규화합니다. 이는 대/소문자를 구분하지 않으며 밑줄과 하이픈이 동일하게 처리됩니다. 예를 들어 App Key 매개변수를 App_Key 로 설정하면 app-key 와 같은 다른 값도 유효한 앱 키 헤더로 허용됩니다.

3.3. 오류 메시지 구성

이 섹션에서는 APIcast 오류 메시지를 구성하는 방법에 대해 설명합니다.

프록시로서 3scale APIcast는 다음과 같은 방식으로 요청을 관리합니다.

  • 오류가 없으면 APIcast는 클라이언트의 요청을 API 백엔드 서버로 전달하고 수정 없이 클라이언트에 API 응답을 반환합니다. 응답을 수정하려면 헤더 수정 정책을 사용할 수 있습니다.
  • 404 Not Found 또는 400 Bad Request 와 같은 오류 메시지로 API가 응답하면 APIcast에서 메시지를 클라이언트에 반환합니다. 그러나 APIcast에서 인증 누락 과 같은 다른 오류를 탐지하면 APIcast에서 오류 메시지를 전송하고 요청을 종료합니다.

따라서 APIcast에서 반환하도록 이러한 오류 메시지를 구성할 수 있습니다.

  • 인증 실패: 이 오류는 false 자격 증명으로 인해 또는 애플리케이션이 일시적으로 일시 중단되었기 때문에 API 요청에 유효한 자격 증명이 포함되어 있지 않습니다. 또한 이 오류는 지표가 비활성화될 때 생성됩니다. 즉 값이 0 입니다.
  • 인증 누락: 이 오류는 API 요청에 인증 정보가 포함되지 않을 때마다 생성됩니다. 사용자가 API 요청에 자격 증명을 추가하지 않을 때 발생합니다.
  • 일치하는 항목 없음: 이 오류는 요청이 매핑 규칙과 일치하지 않으므로 메트릭이 업데이트되지 않음을 의미합니다. 이는 반드시 오류일 필요는 없지만 사용자가 임의 경로를 시도하거나 매핑 규칙이 합법적인 사례를 다루지 않음을 의미합니다.
  • 사용 제한 초과: 이 오류는 클라이언트가 요청된 엔드포인트의 속도 제한에 도달했음을 나타냅니다. 요청이 여러 매핑 규칙과 일치하는 경우 클라이언트는 두 개 이상의 속도 제한에 도달할 수 있습니다.

오류를 구성하려면 다음 단계를 따르십시오.

  1. [your_product_name] > 통합 > 설정에서 이동합니다.
  2. Gateway 응답 에서 구성할 오류 유형을 선택합니다.
  3. 이러한 필드의 값을 지정합니다.

    • 응답 코드: 3자리 HTTP 응답 코드.
    • 컨텐츠 유형: Content-Type 헤더의 값입니다.
    • 응답 본문: 응답 메시지 본문의 값입니다.
  4. 변경 사항을 저장하려면 Update Product(제품 업데이트 )를 클릭합니다.

3.4. 설정 내역

Promote v.[n] to Staging APIcast(v.[ n]를 스테이징 APIcast 로 승격할 때마다 [n] 은 버전 번호를 나타내며 현재 구성이 JSON 파일에 저장됩니다. 스테이징 게이트웨이는 새 요청마다 최신 구성을 가져옵니다. 각 환경에서 스테이징 또는 프로덕션에 대해 이전 구성 파일의 기록을 볼 수 있습니다.

  1. [your_product_name] > Integration > Configuration에서 탐색합니다.
  2. 관심 있는 환경 옆에 있는 Configuration history (구성 기록) 링크를 클릭합니다. 스테이징 APIcast 또는 프로덕션 APIcast.

이전 버전으로 자동 롤백할 수 없습니다. 대신 연결된 JSON 파일을 사용하여 모든 구성 버전의 기록에 액세스합니다. 이 파일을 사용하여 언제든지 배포한 구성을 확인합니다. 원하는 경우 배포를 수동으로 다시 생성할 수 있습니다.

3.5. 디버깅

게이트웨이 구성을 설정하는 것은 쉽지만 오류가 발생할 수 있습니다. 이러한 경우 게이트웨이에서 유용한 디버그 정보를 반환하여 오류를 추적할 수 있습니다.

APIcast에서 디버깅 정보를 가져오려면 다음 헤더를 API 요청에 추가해야 합니다. x-3scale-debug: {SERVICE_TOKEN} 에 연결할 API 서비스에 해당하는 서비스 토큰이 있습니다.

헤더가 있고 서비스 토큰이 유효한 경우 게이트웨이는 응답 헤더에 다음 정보를 추가합니다.

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 인코딩 사용법[version_1]=1&usage[word]=1 이며 API 요청이 메서드(지표) version_1단어가 각각 1씩 증가했음을 보여줍니다.

3.6. 경로 라우팅

APIcast는 3scale 계정(또는 API CAST_SERVICES_LIST 환경 변수가 구성된 경우)에서 구성된 모든 API 서비스를 처리합니다. 일반적으로 APIcast는 API 요청을 공용 기본 URL 과 일치시켜 요청의 호스트 이름을 기반으로 적절한 API 서비스로 라우팅합니다. 일치하는 첫 번째 서비스가 권한 부여에 사용됩니다.

경로 라우팅 기능을 사용하면 여러 서비스에서 동일한 공용 기본 URL 을 사용할 수 있으며 요청 경로를 사용하여 요청을 라우팅할 수 있습니다. 이 기능을 활성화하려면 APICAST_PATH_ROUTING 환경 변수를 true 또는 1 로 설정합니다. 활성화된 경우 APIcast는 호스트 이름과 경로를 모두 기반으로 들어오는 요청을 서비스에 매핑합니다.

이 기능은 동일한 공용 기본 URL 을 사용하여 하나의 게이트웨이를 통해 다른 도메인에서 호스팅되는 여러 백엔드 서비스를 노출하려는 경우 사용할 수 있습니다. 이를 위해 각 API 백엔드(예: 개인 기본 URL)에 대해 여러 API 서비스를 구성하고 경로 라우팅 기능을 활성화할 수 있습니다.

예를 들어 다음과 같은 방식으로 세 가지 서비스가 구성되어 있습니다.

  • Service A Public Base URL: api.example.com 매핑 규칙: /a
  • Service B Public Base URL: api2.example.com 매핑 규칙: /b
  • Service C Public Base URL: api.example.com 매핑 규칙: /c

경로 라우팅(APICAST_PATH_ROUTING=false)이 비활성화 되면 api.example.com 에 대한 모든 호출이 서비스 A와 일치하려고 합니다. 따라서 api.example.com/c 를 호출하고 api.example.com/b"No Mapping Rule matching" 오류와 함께 실패합니다.

경로 라우팅이 활성화된 경우(APICAST_PATH_ROUTING=true) 호출은 호스트와 경로와 일치합니다. 그래서:

  • api.example.com/a 는 서비스 A로 라우팅됩니다.
  • api.example.com/c 는 서비스 C로 라우팅됩니다
  • api.example.com/b 는 "조정 규칙 일치하지 않음" 오류로 인해 실패합니다. 즉, Public Base URL 이 일치하지 않기 때문에 Service B와 일치하지 않습니다.

경로 라우팅을 사용하는 경우 동일한 공용 기본 URL 을 사용하는 다양한 서비스의 매핑 규칙 사이에 충돌이 없는지 확인해야 합니다. 예를 들어 메서드 + 경로 패턴의 조합은 하나의 서비스에만 사용됩니다.

4장. APIcast 정책

APIcast 정책은 APIcast의 작동 방식을 수정하는 기능 단위입니다. APIcast를 수정하는 방법을 제어하도록 정책을 활성화, 비활성화 및 구성할 수 있습니다. 정책을 사용하여 기본 APIcast 배포에서 사용할 수 없는 기능을 추가합니다. 고유한 정책을 만들거나 Red Hat 3scale이 제공하는 표준 정책을 사용할 수 있습니다.

다음 주제에서는 표준 APIcast 정책, 자체 사용자 지정 APIcast 정책 생성 및 정책 체인에 대한 정보를 제공합니다.

정책 체인을 사용한 서비스의 제어 정책. 정책 체인은 다음을 수행합니다.

  • APIcast에서 사용하는 정책 지정
  • 정책 3scale 용도에 대한 구성 정보 제공
  • 3scale 로드 정책의 순서 지정
참고

Red Hat 3scale은 사용자 지정 정책을 추가하는 방법을 제공하지만 사용자 지정 정책을 지원하지 않습니다.

사용자 지정 정책을 사용하여 APIcast 동작을 수정하려면 다음을 수행해야 합니다.

  • APIcast에 사용자 정의 정책 추가
  • APIcast 정책을 구성하는 정책 체인 정의
  • APIcast에 정책 체인 추가

4.1. APIcast 표준 정책

3scale은 다음과 같은 표준 정책을 제공합니다.

3scale에서 표준 정책을 활성화하고 구성할 수 있습니다.

4.1.1. 3scale 인증 캐싱

3scale Auth 캐싱 정책은 APIcast에 대한 인증 호출을 캐시합니다. 운영 모드를 선택하여 캐시 작업을 구성할 수 있습니다.

3scale 인증 캐싱은 다음 모드에서 사용할 수 있습니다.

1. Strict - 인증된 호출만 캐시합니다.

"제한" 모드는 인증된 호출만 캐시합니다. 정책이 "strict" 모드에서 실행 중이고 호출이 실패하거나 거부된 경우 정책은 캐시 항목을 무효화합니다. 백엔드에 연결할 수 없는 경우 캐시된 상태에 관계없이 캐시된 모든 호출이 거부됩니다.

2. 복구 - 백엔드가 다운되면 마지막 요청에 따라 인증합니다.

"Resilient" 모드는 승인 및 거부된 호출을 모두 캐시합니다. 정책이 "resilient" 모드에서 실행 중인 경우 실패한 호출이 기존 캐시 항목을 무효화하지 않습니다. 백엔드에 연결할 수 없는 경우 캐시 상태에 따라 캐시가 계속 인증되거나 거부됩니다.

3. allow - 백엔드가 다운되면 앞과 거부되지 않은 경우 모든 것을 허용합니다.

"Allow" 모드는 승인 및 거부된 호출을 모두 캐시합니다. 정책이 "허용" 모드에서 실행 중인 경우 캐시된 호출은 캐시된 상태에 따라 계속 거부되거나 허용됩니다. 그러나 새 호출은 권한이 부여된 대로 캐시됩니다.

중요

"허용" 모드에서 작동하면 보안에 영향을 미칩니다. 이러한 함축 모드를 고려하고 "허용" 모드를 사용할 때 주의하십시오.

4. none - 캐싱 비활성화.

"없음" 모드는 캐싱을 비활성화합니다. 이 모드는 정책이 활성 상태로 유지되지만 캐싱을 사용하지 않으려는 경우에 유용합니다.

구성 속성

속성description필수 여부

caching_type

caching_type 속성을 사용하면 캐시가 작동할 모드를 정의할 수 있습니다.

데이터 유형: 열거된 문자열 [resilient, strict, allow, none]

제공됨

정책 오브젝트 예

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 정책 체인 만들기 섹션을 참조하십시오.

4.1.2. 3scale Batcher

3scale Batcher 정책은 APIcast가 수신하는 각 API 요청에 대해 3scale 백엔드(Service Management API)를 호출하는 표준 APIcast 권한 부여 메커니즘의 대안을 제공합니다.

3scale Batcher 정책은 권한 부여 상태를 캐시하고 사용 보고서를 일괄 처리하므로 3scale 백엔드에 대한 요청 수를 크게 줄입니다. 3scale Batcher 정책을 사용하면 대기 시간을 줄이고 처리량을 늘려 APIcast 성능을 향상시킬 수 있습니다.

3scale Batcher 정책이 활성화되면 APIcast는 다음과 같은 권한 부여 흐름을 사용합니다.

  1. 각 요청에서 정책은 인증 정보가 캐시되었는지 확인합니다.

    • 자격 증명이 캐시되면 정책은 3scale 백엔드를 호출하는 대신 캐시된 권한 부여 상태를 사용합니다.
    • 자격 증명이 캐시되지 않은 경우 정책은 백엔드를 호출하고 구성 가능한 TTL(Time to Live)으로 권한 부여 상태를 캐시합니다.
  2. 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_ttl0 값으로 설정하면 요청이 처음 캐시될 때 권한 부여 카운터가 업데이트되어 속도 제한이 적용되지 않습니다.
  • batch_report_seconds: 3scale 백엔드로 보내는 배치 보고서의 빈도를 설정합니다. 기본값은 10 초입니다.
중요

이 정책을 사용하려면 정책 체인에서 3scale APIcast3scale Batcher 정책을 모두 활성화합니다.

4.1.3. 3scale Referrer

3scale Referrer 정책은 Referrer 필터링 기능을 활성화합니다. 서비스 정책 체인에서 정책이 활성화되면 APIcast는 3scale Referrer 정책의 값을 서비스 관리 API 에 상위 AuthRep 호출로 보냅니다. 3scale Referrer 정책의 값은 호출에서 referrer 매개변수로 전송됩니다.

Referrer Filtering 이 작동하는 방법에 대한 자세한 내용은 인증 패턴Referrer Filtering 섹션을 참조하십시오.

4.1.4. 익명 액세스

익명 액세스 정책은 인증 없이 서비스를 노출합니다. 예를 들어 인증 매개 변수를 보내도록 조정할 수 없는 레거시 애플리케이션에 유용할 수 있습니다. 익명 정책은 API Key 및 App Id / App Key 인증 옵션을 사용하는 서비스만 지원합니다. 정책이 제공된 자격 증명이 없는 API 요청에 대해 활성화되면 APIcast는 정책에 구성된 기본 자격 증명을 사용하여 호출을 인증합니다. API 호출을 인증하려면 구성된 자격 증명이 있는 애플리케이션이 존재하고 활성화되어야 합니다.

애플리케이션 계획을 사용하여 기본 자격 증명에 사용되는 애플리케이션에 대한 속도 제한을 구성할 수 있습니다.

참고

정책 체인에서 이 두 정책을 함께 사용하는 경우 APIcast 정책에 익명 액세스 정책을 배치해야 합니다.

다음은 정책에 필요한 구성 속성입니다.

  • auth_type: 아래 대안 중 하나에서 값을 선택하고 속성이 API에 구성된 인증 옵션에 해당하는지 확인합니다.

    • app_id_and_app_key: App ID / App Key 인증 옵션의 경우.
    • user_key: API 키 인증 옵션의 경우.
  • app_id (app _id_and_app_key 인증 유형 전용): API 호출과 함께 인증 정보가 제공되지 않은 경우 권한 부여에 사용되는 애플리케이션의 앱 ID입니다.
  • app_key (app _id_and_app_key 인증 유형 전용): 인증 정보가 API 호출과 함께 제공되지 않는 경우 권한 부여에 사용되는 애플리케이션의 앱 키입니다.
  • user_key (사용자 키 auth_ type 전용): 인증 정보가 API 호출과 함께 제공되지 않는 경우 권한 부여에 사용되는 애플리케이션의 API 키입니다.

그림 4.1. 익명 액세스 정책

익명 액세스 정책

4.1.5. Camel 서비스

Camel 서비스 정책을 사용하여 정의된 Apache Camel 프록시를 통해 3scale 트래픽을 전송하는 HTTP 프록시를 정의할 수 있습니다. 이 경우 Camel은 APIcast에서 트래픽을 Camel로 전송한 다음 Camel에서 의 트래픽을 API 백엔드로 보내는 역방향 HTTP 프록시로 작동합니다.

다음 예제에서는 트래픽 흐름을 보여줍니다.

Camel 서비스 정책 요청 flow

3scale 백엔드로 전송된 모든 APIcast 트래픽에서는 Camel 프록시를 사용하지 않습니다. 이 정책은 Camel 프록시 및 API 백엔드 간 통신에만 적용됩니다.

모든 트래픽을 프록시를 통해 보내려면 HTTP_PROXY 환경 변수를 사용해야 합니다.

참고
  • Camel 서비스 정책은 모든 로드 밸런싱 정책을 비활성화하고 트래픽이 Camel 프록시로 전송됩니다.
  • HTTP_PROXY,HTTPS_PROXY 또는 ALL_PROXY 매개 변수가 정의된 경우 이 정책은 이러한 값을 덮어씁니다.
  • 프록시 연결이 인증을 지원하지 않습니다. 인증을 위해 헤더 수정 정책을 사용합니다.

4.1.5.1. 설정

다음 예는 정책 체인 구성을 보여줍니다.

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

http _proxy 또는 https_proxy 가 정의되지 않은 경우 all _proxy 값이 사용됩니다.

4.1.5.1.1. 사용 사례 예

Camel 서비스 정책은 Apache Camel을 사용하여 3scale에서 보다 세부적인 정책과 변환을 적용하도록 설계되었습니다. 이 정책은 HTTP 및 HTTPS를 통한 Apache Camel과의 통합을 지원합니다. 자세한 내용은 6장. Fuse의 정책 확장을 사용하여 3scale 메시지 컨텐츠 변환 의 내용을 참조하십시오.

일반 HTTP 프록시 정책 사용에 대한 자세한 내용은 4.1.20절. “프록시 서비스” 을 참조하십시오.

프로젝트 예

GitHub의 Camel 프록시 정책에서 사용할 수 있는 camel-netty-proxy 예제를 참조하십시오. 이 예제 프로젝트는 API 백엔드에서 대문자로 응답 본문을 변환하는 HTTP 프록시를 보여줍니다.

4.1.6. 조건부 정책

조건 정책은 정책 체인을 포함하므로 다른 APIcast 정책과 다릅니다. 각 nginx 단계에서 평가되는 조건(예: 액세스,재작성,로그 등)을 정의합니다. 조건이 true이면 조건 정책은 체인에 포함된 각 정책에 대해 해당 단계를 실행합니다.

중요

APIcast 조건 정책은 기술 프리뷰 기능 전용입니다. 기술 프리뷰 기능은 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않으며 기능적으로 완전하지 않을 수 있습니다. 따라서 프로덕션 환경에서 사용하는 것은 권장하지 않습니다. 이러한 기능을 사용하면 향후 제품 기능을 조기에 이용할 수 있어 개발 과정에서 고객이 기능을 테스트하고 피드백을 제공할 수 있습니다. Red Hat 기술 프리뷰 기능의 지원 범위에 대한 자세한 내용은 기술 프리뷰 기능 지원 범위를 참조하십시오.

다음 예제에서는 Conditional Policy에서 다음 조건을 정의한다고 가정합니다. request 메서드는 POST입니다.

APIcast --> Caching --> Conditional --> Upstream

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

이 경우 요청이 POST 인 경우 각 단계에 대한 실행 순서는 다음과 같습니다.

  1. APIcast
  2. 캐싱
  3. 헤더
  4. URL 다시 작성
  5. 업스트림

요청이 POST 가 아닌 경우 각 단계에 대한 실행 순서는 다음과 같습니다.

  1. APIcast
  2. 캐싱
  3. 업스트림

4.1.6.1. 조건

조건 정책 체인에서 정책을 실행할지 여부를 결정하는 조건은 JSON 을 사용하여 표현할 수 있으며 유동 템플릿을 사용합니다.

이 예제에서는 요청 경로가 /example_path:

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

왼쪽 및 오른쪽 피연산자는 모두 유동 또는 일반 문자열로 평가할 수 있습니다. 일반 문자열이 기본값입니다.

작업을 또는 와 결합할 수 있습니다. 이 구성은 이전 예와 백엔드 헤더의 값과 동일하게 확인합니다.

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

자세한 내용은 정책 구성 스키마 를 참조하십시오.

4.1.6.1.1. 유동 변수에서 지원되는 변수
  • uri
  • 호스트
  • remote_addr
  • 헤더['Some-Header']

업데이트된 변수 목록은 다음과 같습니다. ngx_variable.lua

이 예제에서는 요청의 백엔드 헤더가 스테이징 될 때 업스트림 정책을 실행합니다.

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

4.1.7. 컨텐츠 캐싱

콘텐츠 캐싱 정책을 사용하면 사용자 지정 조건에 따라 캐싱을 활성화 및 비활성화할 수 있습니다. 이러한 조건은 클라이언트 요청에만 적용할 수 있습니다. 여기서 업스트림 응답은 정책에서 사용할 수 없습니다.

cache-control 헤더가 전송되면 APIcast에서 설정한 시간 초과보다 우선 순위가 사용됩니다.

다음 예제 구성은 Method가 GET인 경우 응답을 캐시합니다.

설정 예

{
  "name": "apicast.policy.content_caching",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "cache": true,
        "header": "X-Cache-Status-POLICY",
        "condition": {
          "combine_op": "and",
          "operations": [
            {
              "left": "{{method}}",
              "left_type": "liquid",
              "op": "==",
              "right": "GET"
            }
          ]
        }
      }
    ]
  }
}

4.1.7.1. 지원되는 구성

  • 다음 방법에 대해 Content Caching 정책을 비활성화하도록 설정합니다. POST,PUT 또는 DELETE.
  • 하나의 규칙이 일치하고 캐시를 활성화하면 실행이 중지되고 비활성화되지 않습니다. 여기서는 우선 순위별 정렬이 중요합니다.

4.1.7.2. 업스트림 응답 헤더

NGINX proxy_cache_valid 지시문 정보는 APICAST_CACHE_ STATUS_CODES 및 APICAST_CACHE_ MAX_TIME 을 사용하여 전역적으로 설정할 수 있습니다. 업스트림에 시간 초과와 관련된 다른 동작이 필요한 경우 Cache-Control 헤더를 사용합니다.

4.1.8. CORS 요청 처리

CORS(Cross Origin Resource Sharing) 요청 처리 정책을 사용하면 다음을 지정할 수 있어 CORS 동작을 제어할 수 있습니다.

  • 허용된 헤더
  • 허용된 메서드
  • 허용되는 인증 정보
  • 허용되는 원본 헤더

CORS 요청 처리 정책은 지정되지 않은 모든 CORS 요청을 차단합니다.

참고

정책 체인에서 이 두 정책을 함께 사용하는 경우 APIcast 정책 앞에 CORS 요청 처리 정책을 배치해야 합니다.

구성 속성

속성description필수 여부

allow_headers

allow_headers 속성은 APIcast에서 허용할 CORS 헤더를 지정할 수 있는 배열입니다.

데이터 유형: 문자열 배열은 CORS 헤더여야 합니다.

아니요

allow_methods

allow_methods 속성은 APIcast에서 허용할 CORS 메서드를 지정할 수 있는 배열입니다.

데이터 유형: 열거된 문자열 배열 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT]

아니요

allow_origin

allow_origin 속성을 사용하면 원본 도메인 APIcast에서 허용하는 것을 지정할 수 있습니다.

데이터 유형: 문자열

아니요

allow_credentials

allow_credentials 속성을 사용하면 APIcast에서 인증 정보를 사용하여 CORS 요청을 허용할지 여부를 지정할 수 있습니다.

데이터 유형: 부울

아니요

정책 오브젝트 예

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.9. 사용자 정의 지표

사용자 지정 지표 정책은 업스트림 API에서 보낸 응답 후에 지표를 추가하는 가용성을 추가합니다. 이 정책의 주요 사용 사례는 응답 코드 상태, 헤더 또는 다른 NGINX 변수에 따라 지표를 추가하는 것입니다.

4.1.9.1. 사용자 정의 메트릭의 제한 사항

  • 요청이 업스트림 API로 전송되기 전에 인증이 수행되면 새 지표를 업스트림 API에 보고하기 위해 백엔드에 대한 두 번째 호출이 수행됩니다.
  • 이 정책은 배치 정책에서는 작동하지 않습니다.
  • 정책이 지표 값을 내보내기 전에 지표 포털에서 지표를 생성해야 합니다.

4.1.9.2. 요청 흐름 예

다음 차트는 인증이 캐시되지 않은 경우의 요청 흐름 및 인증이 캐시될 때의 흐름도 보여줍니다.

4.1.9.3. 구성 예

이 정책은 업스트림 API에서 400 상태를 반환하는 경우 헤더 증가로 메트릭 오류를 늘립니다.

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

이 정책은 업스트림 API에서 200 상태를 반환하는 경우 status_code 정보를 사용하여 hits 메트릭을 늘립니다.

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

4.1.10. 에코

Echo 정책은 선택적 HTTP 상태 코드와 함께 들어오는 요청을 클라이언트에 다시 출력합니다.

구성 속성

속성description필수 여부

status

Echo 정책이 클라이언트로 반환되는 HTTP 상태 코드

데이터 유형: 정수

아니요

종료

Echo 정책에서 사용할 종료 모드를 지정합니다. 요청 종료 모드에서는 들어오는 요청이 처리되지 않도록 중지합니다. set exit 모드는 재작성 단계를 건너뜁니다.

data type: enumerated string [request, set]

제공됨

정책 오브젝트 예

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.11. 에지 제한

에지 제한 정책은 백엔드 API로 전송된 트래픽의 유연한 속도 제한을 제공하는 것을 목표로 하며 기본 3scale 권한 부여와 함께 사용할 수 있습니다. 정책에서 지원하는 사용 사례의 몇 가지 예는 다음과 같습니다.

  • 최종 사용자 속도 제한: 요청의 인증 헤더에 전달된 JWT 토큰의 하위 (주체) 클레임 값에 따른 제한 비율입니다. 이는 {{ jwt.sub }} 로 구성됩니다.
  • RPS(초당 요청) 속도 제한.
  • 서비스당 글로벌 요금 제한: 애플리케이션당이 아닌 서비스당 제한을 적용합니다.
  • 동시 연결 제한: 허용된 동시 연결 수를 설정합니다.

4.1.11.1. 제한 유형

정책은 lua-resty-limit-traffic 라이브러리에서 제공하는 다음 유형의 제한을 지원합니다.

  • leaky_bucket_limiters: 평균 요청 수와 최대 버스트 크기를 기반으로 하는 누수된 버킷 알고리즘을 기반으로 합니다.
  • fixed_window_limiters: 고정된 시간에 따라(지난 n초).
  • connection_limiters: 동시 연결 수에 따라.

서비스 또는 전역적으로 제한 범위를 지정할 수 있습니다.

4.1.11.2. 제한 정의

제한에는 IP 주소, 서비스, 엔드포인트, 식별자, 특정 헤더의 값 및 기타 엔터티와 같이 제한을 정의하는 데 사용되는 엔터티를 인코딩하는 키가 있습니다. 이 키는 limiter의 key 매개변수에 지정됩니다.

key 는 다음 속성으로 정의된 오브젝트입니다.

  • name: 키 이름을 정의합니다. 범위 내에서 고유해야 합니다.
  • scope: 키의 범위를 정의합니다. 지원되는 범위는 다음과 같습니다.

    • 하나의 서비스(서비스)에 영향을 주는 서비스 범위당.
    • 모든 서비스(글로벌)에 영향을 주는글로벌범위.
  • name_type: name 값이 평가되는 방법을 정의합니다.

    • 일반 텍스트 (일반)
    • 기타 (유사)

각 제한에는 유형에 따라 몇 가지 매개변수도 있습니다.

  • leaky_bucket_limiters: rate, burst.

    • rate: 지연 없이 초당 수행할 수 있는 요청 수를 정의합니다.
    • burst: 허용되는 속도를 초과할 수 있는 초당 요청 양을 정의합니다. 속도에 따라 허용된 비율보다 높은 요청에 대해 인위적인 지연이 도입됩니다 . 버스트 에 정의된 것보다 초당 더 많은 요청으로 속도를 초과하면 요청이 거부됩니다.
  • fixed_window_limiters:count,windows. count창에 정의된 초당 수행할 수 있는 요청 수를 정의합니다 .
  • connection_limiters:conn,burst,delay.

    • Conn: 허용되는 최대 동시 연결 수를 정의합니다. 초당 버스트 커넥션 수를 초과할 수 있습니다.
    • 지연: 제한을 초과하는 연결을 지연할 시간(초)을 정의합니다.

  • service_A에 대한 분당 10개의 요청을 허용합니다.

    {
      "key": { "name": "service_A" },
      "count": 10,
      "window": 60
    }
  • 버스트가 10개인 100개 연결을 허용하고 1초가 지연됩니다.

    {
      "key": { "name": "service_A" },
      "conn": 100,
      "burst": 10,
      "delay": 1
    }

각 서비스에 대해 여러 제한을 정의할 수 있습니다. 여러 제한이 정의되는 경우 한 개 이상의 제한에 도달하면 요청이 거부되거나 지연될 수 있습니다.

4.1.11.3. 유동 템플릿

에지 제한 정책을 사용하면 키에 있는 변수를 지원하여 동적 키에 대한 제한을 지정할 수 있습니다. 이를 위해 키의 name_type 매개 변수를ude로 설정해야 하며 name 매개 변수에서 변수를 사용할 수 있습니다. 예를 들어, {{ remote_addr }} (클라이언트 IP 주소의 경우 {{ jwt.sub }} ) 또는 JWT 토큰의 하위 클레임의 경우 {{ jwt.sub }}입니다.

예제

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

ms 지원에 대한 자세한 내용은 5.1절. “정책에서 변수 및 필터 사용” 의 내용을 참조하십시오.

4.1.11.4. 조건 적용

각 제한 프로그램에는 제한이 적용되는 시기를 정의하는 조건이 있어야 합니다. 조건은 제한자의 condition 속성에 지정됩니다.

조건은 다음 속성에 의해 정의됩니다.

  • combine_op: 작업 목록에 적용되는 부울 연산자입니다. 또는 의 값이 지원됩니다.
  • 운영: 평가해야 하는 조건 목록입니다. 각 작업은 다음 속성을 사용하여 오브젝트로 표시됩니다.

    • left: 작업의 왼쪽 부분입니다.
    • left_type: 왼쪽 속성을 평가하는 방법(정상 또는 유동).
    • right: 작업의 오른쪽 부분.
    • right_type: 올바른 속성 평가 방법(일반 또는 유동).
    • op: Operator가 왼쪽과 오른쪽 부분 사이에 적용됩니다. 다음은 == (equals) 및 != (동일하지 않음)의 두 가지 값이 지원됩니다.

예제

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

4.1.11.5. 속도 제한 카운터의 스토리지 구성

기본적으로 에지 제한 정책은 속도 제한 카운터에 OpenResty 공유 사전을 사용합니다. 그러나 공유 사전 대신 외부 Redis 서버를 사용할 수 있습니다. 이 기능은 여러 APIcast 인스턴스가 배포될 때 유용할 수 있습니다. redis_url 매개 변수를 사용하여 Redis 서버를 구성할 수 있습니다.

4.1.11.6. 오류 처리

제한자는 오류를 처리하는 방법을 구성하기 위해 다음 매개변수를 지원합니다.

  • limits_exceeded_error: 구성된 제한이 초과될 때 클라이언트로 반환되는 오류 상태 코드 및 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.

    • status_code: 제한을 초과할 때 요청의 상태 코드입니다. 기본값: 429.
    • error_handling: 다음 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.

      • exit: 요청 처리를 중지하고 오류 메시지를 반환합니다.
      • log: 처리 요청을 완료하고 출력 로그를 반환합니다.
  • configuration_error: 잘못된 구성이 있는 경우 클라이언트에 반환되는 오류 상태 코드 및 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.

    • status_code : 구성 문제가 있는 경우 상태 코드입니다. 기본값: 500.
    • error_handling: 다음 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.

      • exit: 요청 처리를 중지하고 오류 메시지를 반환합니다.
      • log: 처리 요청을 완료하고 출력 로그를 반환합니다.

4.1.12. 헤더 수정

헤더 수정 정책을 사용하면 기존 헤더를 수정하거나 수신 요청 또는 응답에서 추가 헤더를 추가하거나 제거할 수 있습니다. 응답 헤더와 요청 헤더를 모두 수정할 수 있습니다.

Header 수정 정책은 다음 구성 매개변수를 지원합니다.

  • 요청: 요청 헤더에 적용할 작업 목록
  • response: 응답 헤더에 적용할 작업 목록

각 작업은 다음 매개변수로 구성됩니다.

  • op: 적용할 작업을 지정합니다. add 작업은 기존 헤더에 값을 추가합니다. set 작업은 헤더와 값을 생성하고, 이미 존재하는 경우 기존 헤더의 값을 덮어씁니다. push 작업은 헤더와 값을 생성하지만 기존 헤더의 값이 이미 있는 경우 덮어쓰지 않습니다. 대신, push 는 기존 헤더에 값을 추가합니다. 삭제 작업은 헤더를 제거합니다.
  • 헤더: 만들 헤더를 지정하거나 수정할 헤더를 지정하고 헤더 이름(예: Custom-Header)으로 사용할 수 있는 모든 문자열이 될 수 있습니다.
  • value_type: 헤더 값을 평가하는 방법을 정의합니다. 일반 텍스트의 경우 일반 텍스트 또는 유동 템플릿으로 사용할 수 있습니다. 자세한 내용은 5.1절. “정책에서 변수 및 필터 사용”의 내용을 참조하십시오.
  • : 헤더에 사용할 값을 지정합니다. 값 유형의 "liquid"의 경우 값은 {{ variable_from_context }} 형식이어야 합니다. 삭제할 때는 필요하지 않습니다.

정책 오브젝트 예

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.13. IP 확인

IP 확인 정책은 IP 목록에 따라 요청을 거부하거나 허용하는 데 사용됩니다.

구성 속성

속성description데이터 유형필수 여부

check_type

check_type 속성에는 허용 목록 또는 블랙리스트 라는 두 개의 가능한 값이 있습니다.블랙리스트 는 목록의 IP에서 모든 요청을 거부합니다. 허용 목록은 목록에 없는 IP의 모든 요청을 거부합니다.

문자열은 허용 목록 또는 차단목록이어야 합니다

제공됨

ips

ips 속성을 사용하면 허용 목록 또는 차단 목록에 IP 주소 목록을 지정할 수 있습니다. 단일 IP 및 CIDR 범위를 모두 사용할 수 있습니다.

문자열 배열은 유효한 IP 주소여야 합니다

제공됨

error_msg

error_msg 속성을 사용하면 요청이 거부될 때 반환된 오류 메시지를 구성할 수 있습니다.

string

아니요

client_ip_sources

client_ip_sources 속성을 사용하면 클라이언트 IP를 검색하는 방법을 구성할 수 있습니다. 기본적으로 마지막 호출자 IP가 사용됩니다. 다른 옵션은 X-Forwarded-ForX-Real-IP 입니다.

문자열 배열, 유효한 옵션은 X-Forwarded-For,X- Real-IP,last_caller 중 하나 이상입니다.

아니요

정책 오브젝트 예

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.14. JWT 청구 확인

JWT(JSON 웹 토큰) 클레임에 따라 JWT Claim Check 정책을 사용하면 리소스 대상 및 메서드를 차단하는 새 규칙을 정의할 수 있습니다.

4.1.14.1. JWT 청구 확인 정책 정보

JWT 클레임의 값을 기반으로 라우팅하려면 JWT를 검증하고 정책이 공유하는 컨텍스트에 클레임을 저장하는 체인에 정책이 필요합니다.

JWT Claim Check 정책이 리소스와 방법을 차단하는 경우 정책은 JWT 작업도 검증합니다. 또는 메서드 리소스가 일치하지 않는 경우 요청은 백엔드 API로 계속됩니다.

예제: GET 요청의 경우 요청이 거부되지 않는 경우 JWT에 역할 클레임이 admin으로 있어야 합니다. 반면 GET 이외의 요청은 JWT 작업을 검증하지 않으므로 JWT 제약 조건 없이 POST 리소스가 허용됩니다.

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

4.1.14.2. 정책 체인에서 JWT 클레임 검사 정책 구성

정책 체인에서 JWT Claim Check 정책을 구성하려면 다음을 수행합니다.

사전 요구 사항

  • 3scale 설치에 액세스할 수 있어야 합니다.
  • 모든 배포가 완료될 때까지 기다려야 합니다.
4.1.14.2.1. 정책 구성
  1. API에 JWT Claim Check 정책을 추가하려면 표준 정책 활성화 에 설명된 단계를 따르고 JWT Claim Check를 선택합니다.
  2. JWT Claim Check 링크를 클릭합니다.
  3. 정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
  4. 규칙을 추가하려면 더하기 아이콘을 클릭합니다.
  5. resource_type 을 지정합니다.
  6. 운영자를 선택합니다.
  7. 규칙에서 제어하는 리소스를 나타냅니다.
  8. 허용되는 메서드를 추가하려면 더하기 아이콘을 클릭합니다.
  9. 트래픽이 차단될 때 사용자에게 표시하려면 오류 메시지를 입력합니다.
  10. JWT Claim Check를 사용하여 API 설정을 마치면 Update Policy(정책 업데이트 )를 클릭합니다.

    • 해당 섹션에서 더하기 + 아이콘을 클릭하여 더 많은 리소스 유형과 허용되는 방법을 추가할 수 있습니다.
  11. Update Policy(정책 체인 업데이트)를 클릭하여 변경 사항을 저장합니다.

4.1.15. 유동 컨텍스트 디버그

참고

Context Debug 정책은 개발 환경에서 디버깅 용도로만 사용되며 프로덕션 환경에서는 그렇지 않습니다.

이 정책은 컨텍스트에서 사용할 수 있는 오브젝트와 값을 포함하는 JSON 을 사용하여 API 요청에 응답하며, 플레이버 템플릿을 평가하는 데 사용할 수 있습니다. 3scale APIcast 또는 업스트림 정책과 결합되는 경우 올바르게 작동하려면 정책 체인에 Context Debug를 배치해야 합니다. 이 정책은 원형 참조를 방지하기 위해 중복된 오브젝트만 한 번만 포함하고 스텁 값으로 교체합니다.

정책이 활성화될 때 APIcast에서 반환하는 값의 예는 다음과 같습니다.

    {
      "jwt": {
        "azp": "972f7b4f",
        "iat": 1537538097,
        ...
        "exp": 1537574096,
        "typ": "Bearer"
      },
      "credentials": {
        "app_id": "972f7b4f"
      },
      "usage": {
        "deltas": {
          "hits": 1
        },
        "metrics": [
          "hits"
        ]
      },
      "service": {
        "id": "2",
        ...
      }
      ...
    }

4.1.16. 로깅

로깅 정책에는 다음 두 가지 용도가 있습니다.

  • 액세스 로그 출력을 활성화 및 비활성화하려면 다음을 수행합니다.
  • 각 서비스에 대한 사용자 정의 액세스 로그 형식을 만들고 사용자 정의 액세스 로그를 작성하는 조건을 설정할 수 있습니다.

로깅 정책을 액세스 로그 위치에 대한 글로벌 설정과 결합할 수 있습니다. APICAST_ACCESS_LOG_FILE 환경 변수를 설정하여 APIcast 액세스 로그의 위치를 구성합니다. 기본적으로 이 변수는 표준 출력 장치인 /dev/stdout 으로 설정됩니다. 글로벌 APIcast 매개변수에 대한 자세한 내용은 ??? 의 내용을 참조하십시오.

또한 로깅 정책에는 다음 기능이 있습니다.

  • 이 정책은 enable_access_logs 구성 매개 변수만 지원합니다.
  • 액세스 로그를 활성화하려면 enable_access_logs 매개변수를 선택하거나 로깅 정책을 비활성화합니다.
  • API의 액세스 로깅을 비활성화하려면 다음을 수행합니다.

    1. 정책을 활성화합니다.
    2. enable_access_logs 매개변수를 지웁니다.
    3. Submit(제출) 버튼을 클릭합니다.
  • 기본적으로 이 정책은 정책 체인에서 활성화되지 않습니다.

4.1.16.1. 모든 API에 대한 글로벌 구성

로깅 옵션은 API에서 올바르게 포맷되지 않은 로그 문제를 방지하는 데 도움이 됩니다. 사용자 지정 APIcast 환경 변수를 설정하고 모든 API에서 로깅 정책을 구현합니다. 다음은 모든 서비스에 로드된 정책의 예입니다. custom_env.lua

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

이 특정 환경에서 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 명령의 주요 개념입니다.

  • 현재 Lua 파일은 컨테이너 -v $(pwd):/config 와 공유해야 합니다.
  • APICAST_ENVIRONMENT 변수는 /config 디렉터리에 저장된 Lua 파일로 설정해야 합니다.

4.1.16.2. 예

이 섹션에서는 로깅 정책 작업 시 몇 가지 예를 설명합니다. 다음 예제에서는 다음 주의 사항을 고려합니다.

  • custom_logging 또는 enable_json_logs 속성이 활성화된 경우 기본 액세스 로그가 비활성화됩니다.
  • enable_json_logs 가 활성화된 경우 custom_logging 필드가 생략됩니다.

액세스 로그 비활성화

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

사용자 정의 액세스 로그 활성화

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

서비스 식별자를 사용하여 사용자 정의 액세스 로그 활성화

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
  }
}

JSON 형식으로 액세스 로그 구성

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

성공적인 요청에 대해서만 사용자 정의 액세스 로그 구성

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

응답 상태가 200 또는 500과 일치하는 액세스 로그 사용자 정의

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

4.1.16.3. 사용자 정의 로깅에 대한 추가 정보

사용자 정의 로깅의 경우 내보낸 변수와 함께 템플릿을 사용할 수 있습니다. 이러한 변수는 다음과 같습니다.

  • NGINX 기본 지시문 변수: log_format. 예: {{remote_addr}}.
  • 응답 및 요청 헤더:

    • {{req.headers.FOO}}: 요청에서 FOO 헤더를 가져오려면 다음을 수행합니다.
    • {{Res.headers.FOO}}: 응답에서 FOO 헤더를 검색하려면 다음을 수행합니다.
  • {{service.id}} 와 같은 서비스 정보와 이러한 매개변수에서 제공하는 모든 서비스 속성:

    • THREESCALE_CONFIG_FILE
    • THREESCALE_PORTAL_ENDPOINT

4.1.17. 유지 관리 모드

유지 관리 모드 정책을 사용하면 지정된 상태 코드 및 메시지가 있는 들어오는 요청을 거부할 수 있습니다. 유지 관리 기간 또는 API를 일시적으로 차단하는 데 유용합니다.

구성 속성

다음은 가능한 속성 및 기본값 목록입니다.

속성valuedefaultdescription

status

정수, 선택 사항

503

응답 코드

message

문자열, 선택 사항

503 서비스 사용 불가 - 유지 관리

응답 메시지

유지 관리 모드 정책 예

{
  "policy_chain": [
    {"name": "maintenance-mode", "version": "1.0.0",
    "configuration": {"message": "Be back soon..", "status": 503} },
  ]
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.18. OAuth 2.0 상호 TLS 클라이언트 인증

이 정책은 모든 API 호출에 대해 OAuth 2.0 상호 TLS 클라이언트 인증을 실행합니다.

OAuth 2.0 상호 TLS 클라이언트 인증 정책 JSON 의 예는 다음과 같습니다.

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "OAuth 2.0 Mutual TLS Client Authentication",
  "summary": "Configure OAuth 2.0 Mutual TLS Client Authentication.",
  "description": ["This policy executes OAuth 2.0 Mutual TLS Client Authentication ",
    "(https://tools.ietf.org/html/draft-ietf-oauth-mtls-12) for every API call."
  ],
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": { }
  }
}

4.1.19. OAuth 2.0 토큰 세부 검사

OAuth 2.0 토큰 세부 검사 정책을 사용하면 토큰 발행자(Red Hat Single Sign-On)의 토큰 인트로스펙션 엔드포인트(OpenID Connect) 인증 옵션이 있는 서비스에 사용되는 JSON 웹 토큰(JWT) 토큰의 유효성을 검증할 수 있습니다.

APIcast는 auth_type 필드에서 다음 인증 유형을 지원하여 이 끝점을 호출할 때 토큰 인트로스펙션 엔드 포인트 및 인증 정보 APIcast가 사용하는 인증 유형을 결정합니다.

  • use_3scale_oidc_issuer_endpoint: APIcast는 Service Integration 페이지에 구성된 OIDC Issuer 설정의 클라이언트 자격 증명, 클라이언트 ID 및 클라이언트 비밀 과 토큰 인트로스펙션 엔드포인트를 사용합니다. APIcast는 token_introspection_endpoint 필드에서 토큰 인트로스펙션 끝점을 검색합니다. 이 필드는 OIDC 발행자가 반환하는 .well-known/openid-configuration 엔드포인트에 있습니다.

예 4.1. use_3scale_oidc_issuer_endpoint로 설정된 인증 유형

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],
  • client_id+client_secret: 이 옵션을 사용하면 다른 토큰 인트로스펙션 엔드 포인트와 클라이언트 ID 및 클라이언트 시크릿 APIcast를 사용하여 토큰 정보를 요청할 수 있습니다. 이 옵션을 사용하는 경우 다음 구성 매개 변수를 설정합니다.

    • client_id: 토큰 인트로스펙션 엔드 포인트의 클라이언트 ID를 설정합니다.
    • client_secret: 토큰 인트로스펙션 엔드 포인트에 대한 클라이언트 시크릿 설정.
    • introspection_url: 인트로스펙션 엔드 포인트 URL을 설정합니다.

예 4.2. 인증 유형이 client_id+client_secret으로 설정

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "client_id+client_secret",
      "client_id": "myclient",
      "client_secret": "mysecret",
      "introspection_url": "http://red_hat_single_sign-on/token/introspection"
    }
  }
…​
],

auth_type 필드의 설정에 관계없이 APIcast는 Basic Authentication을 사용하여 Token Introspection 호출 (Authorization)을 인증합니다. 기본 <token> 헤더. 여기서 <token> 은 Base64 인코딩 <client_id>:<client_secret> 설정입니다.

OAuth 2.0 토큰 세부 검사 구성

토큰 인트로스펙션 엔드 포인트의 응답에는 활성 특성이 포함되어 있습니다. APIcast는 이 속성의 값을 확인합니다. 특성 값에 따라 APIcast는 호출을 인증하거나 거부합니다.

  • true: 호출 권한이 있음
  • false: Authentication Failed 오류와 함께 호출이 거부됩니다.

이 정책을 사용하면 동일한 JWT 토큰을 호출할 때마다 토큰 인트로스펙션 엔드 포인트를 호출하지 않도록 토큰 캐싱을 활성화할 수 있습니다. 토큰 인트로스펙션 정책에 대한 토큰 캐싱을 활성화하려면 max_cached_tokens 필드를 0 의 값으로 설정하여 기능을 비활성화하고 10000 을 비활성화합니다. 또한 max_ttl_tokens 필드에서 토큰의 TTL(Time to Live) 값을 1 에서 3600 초로 설정할 수 있습니다.

4.1.20. 프록시 서비스

프록시 서비스 정책을 사용하여 정의된 프록시를 사용하여 3scale 트래픽이 전송되는 일반 HTTP 프록시를 정의할 수 있습니다. 이 경우 프록시 서비스는 APIcast에서 트래픽을 HTTP 프록시로 전송한 다음 프록시에서 트래픽을 API 백엔드로 보내는 역방향 HTTP 프록시로 작동합니다.

다음 예제에서는 트래픽 흐름을 보여줍니다.

프록시 서비스 정책 요청 흐름

3scale 백엔드로 전송된 모든 APIcast 트래픽은 프록시를 사용하지 않습니다. 이 정책은 APIcast와 API 백엔드 간의 통신 및 프록시에만 적용됩니다.

모든 트래픽을 프록시를 통해 보내려면 HTTP_PROXY 환경 변수를 사용해야 합니다.

참고
  • 프록시 서비스 정책은 모든 로드 밸런싱 정책을 비활성화하고 트래픽이 프록시로 전송됩니다.
  • HTTP_PROXY,HTTPS_PROXY 또는 ALL_PROXY 매개 변수가 정의된 경우 이 정책은 이러한 값을 덮어씁니다.
  • 프록시 연결이 인증을 지원하지 않습니다. 인증을 위해 헤더 수정 정책을 사용합니다.

4.1.20.1. 설정

다음 예는 정책 체인 구성을 보여줍니다.

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

http _proxy 또는 https_proxy 가 정의되지 않은 경우 all _proxy 값이 사용됩니다.

4.1.20.1.1. 사용 사례 예

Proxy 서비스 정책은 HTTP를 통한 Apache Camel을 사용하여 3scale에서 보다 세부적인 정책과 변환을 적용하도록 설계되었습니다. 그러나 프록시 서비스 정책을 일반 HTTP 프록시 서비스로 사용할 수도 있습니다. HTTPS를 통한 Apache Camel과의 통합은 4.1.5절. “Camel 서비스” 의 내용을 참조하십시오.

프로젝트 예

GitHub의 camel-netty-proxy 예제를 참조하십시오. 이 프로젝트에는 API 백엔드에서 대문자로 응답 본문을 변환하는 HTTP 프록시가 표시됩니다.

4.1.21. 제한 헤더 속도

Rate Limit Headers 정책은 애플리케이션이 속도 제한을 가진 애플리케이션 계획에 서브스크립션할 때 응답 메시지에 RateLimit 헤더를 추가합니다. 이러한 헤더는 현재 시간 창에 구성된 요청 할당량 제한과 나머지 요청 할당량 및 초에 대한 유용한 정보를 제공합니다.

제품의 정책 체인에서 Rate Limit Headers 정책을 추가하는 경우 3scale APIcast 정책 앞에 있어야 합니다. 3scale APIcast 정책이 Rate Limit Headers(요금 제한 헤더) 정책 앞에 있는 경우 Rate Limit Headers(요금 제한 헤더) 정책이 작동하지 않습니다.

4.1.21.1. RateLimit 헤더

다음 RateLimit 헤더는 각 메시지에 추가됩니다.

  • RateLimit-Limit: 구성된 시간 창에 총 요청 할당량을 표시합니다(예: 10 개 요청).
  • RateLimit-Remaining: 현재 시간 창에 나머지 요청 할당량을 표시합니다(예: 5 개 요청).
  • RateLimit-Reset: 현재 시간 창에 남은 초(예: 30 초)를 표시합니다. 이 헤더의 동작은 Retry-After 헤더의 delta-초 표기법과 호환됩니다.

기본적으로 Rate Limit Headers 정책이 구성되지 않거나 애플리케이션 계획에 속도 제한이 없는 경우 응답 메시지에는 속도 제한 헤더가 없습니다.

참고

속도 제한 없이 상위 지표에 제한이 구성된 API 지표를 요청하는 경우 상위 제한이 적용되므로 속도 제한 헤더가 여전히 응답에 포함됩니다.

4.1.22. Retry

재시도 정책은 재시도 요청 수를 업스트림 API에 설정합니다. 재시도 정책은 서비스별로 구성되므로 사용자가 원하는 만큼 많은 서비스에 대해 재시도를 활성화하고 다양한 서비스에 대해 서로 다른 재시도 값을 구성할 수 있습니다.

중요

3scale 2.9부터 정책에 재시도할 사례를 구성할 수 없습니다. 이는 모든 서비스에 재시도 요청을 적용하는 환경 변수 APICAST_UPSTREAM_RETRY_CASES 로 제어됩니다. 자세한 내용은 APICAST_UPSTREAM_RETRY_CASES 를 참조하십시오.

재시도 정책 JSON 의 예는 다음과 같습니다.

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "Retry",
  "summary": "Allows retry requests to the upstream",
  "description": "Allows retry requests to the upstream",
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": {
      "retries": {
        "description": "Number of retries",
        "type": "integer",
        "minimum": 1,
        "maximum": 10
      }
    }
  }
}

4.1.23. RH-SSO/Keycloak 역할 검사

이 정책은 OpenID Connect 인증 옵션과 함께 사용할 때 역할 검사를 추가합니다. 이 정책은 RH-SSO(Red Hat Single Sign-On)에서 발행한 액세스 토큰에서 영역 역할 및 클라이언트 역할을 확인합니다. 영역 역할은 3scale의 모든 클라이언트 리소스에 역할 점검을 추가하려는 경우 지정합니다.

type 속성이 정책 구성에 지정하는 두 가지 유형의 역할 검사가 있습니다.

  • 허용 목록 (기본값): 화이트리스트 를 사용하면 APIcast는 지정된 범위가 JWT 토큰에 있는지 확인하고 JWT에 범위가 없는 경우 호출을 거부합니다.
  • blacklist: 블랙리스트 를 사용하면 JWT 토큰에 블랙리스트로 지정된 범위가 포함된 경우 APIcast에서 호출을 거부합니다.

동일한 정책에서 블랙리스트허용 목록 모두의 검사를 구성할 수는 없지만 RH-SSO/Keycloak 역할 점검 정책의 두 개 이상의 인스턴스를 APIcast 정책 체인에 추가할 수 있습니다.

정책 구성의 scopes 속성을 통해 범위 목록을 구성할 수 있습니다.

범위 오브젝트에는 다음 속성이 있습니다.

  • 리소스: 역할에서 제어하는 리소스(엔드 포인트)입니다. 이 형식은 매핑 규칙과 동일합니다. 패턴은 문자열 시작 부분부터 일치하고 정확히 일치하도록 하려면 끝에 $ 를 추가해야 합니다.
  • resource_type: 리소스 값이 평가되는 방식을 정의합니다.

    • 일반 텍스트 (일반)로: 리소스 값을 일반 텍스트로 평가합니다. 예: /api/v1/products$.
    • 다음과 같이 텍스트 (유사): 리소스 값에서 를 사용할 수 있습니다. 예: /resource_{{ jwt.aud }} 는 클라이언트 ID가 포함된 리소스에 대한 액세스를 관리합니다.
  • 방법: RH-SSO의 사용자 역할에 따라 이 매개변수를 사용하여 APIcast에서 허용되는 HTTP 메서드를 나열합니다. 예를 들어 다음을 포함하는 메서드를 허용할 수 있습니다.

    • /resource 1 에 액세스할 수 있는 role1 영역 역할입니다. 이 영역 역할이 없는 메서드의 경우 블랙리스트 를 지정해야 합니다.
    • /resource 1에 액세스하는 role1 이라는 client 1 역할.
    • /resource 1에 액세스할 수 있는 role1 및 role2 영역 역할입니다. realm_roles 에서 역할을 지정합니다. 각 역할의 범위를 나타낼 수도 있습니다.
    • /resource 1에 액세스할 액세스 토큰의 수신자인 애플리케이션 클라이언트의 role 1 이라는 클라이언트 역할입니다. 유동 클라이언트 유형을 사용하여 클라이언트에 JSON 웹 토큰(JWT) 정보를 지정합니다.
    • /resource1 에 액세스하는 액세스 토큰의 수신자인 애플리케이션 클라이언트의 클라이언트 ID를 포함하는 client 역할. 유동 클라이언트 유형을 사용하여 클라이언트 역할의 이름에 JWT 정보를 지정합니다.
    • 애플리케이션 클라이언트 ID를 포함하여 리소스에 액세스하는 role1 이라는 클라이언트 역할입니다. 유동 클라이언트 유형을 사용하여 리소스에 JWT 정보를 지정합니다 .
  • realm_roles: 이를 사용하여 영역 역할을 확인합니다(Red Hat Single Sign-On 문서의 Realm Roles 참조).

    영역 역할은 Red Hat Single Sign-On에서 발행한 JWT에 있습니다.

      "realm_access": {
        "roles": [
          "<realm_role_A>", "<realm_role_B>"
        ]
      }

    정책에 실제 역할을 지정해야 합니다.

    "realm_roles": [
      { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
    ]

    다음은 realm_roles 배열에 있는 각 오브젝트의 사용 가능한 속성입니다.

  • name: 역할의 이름을 지정합니다.
  • name_type: 이름을 평가하는 방법을 정의합니다. 일반 또는 유동일 수 있습니다 ( resource_type과 동일한 방식으로 작동).
  • client_roles: client_roles를 사용하여 클라이언트 네임스페이스에서 특정 액세스 역할을 확인합니다(Red Hat Single Sign-On 문서의 클라이언트 역할 참조).

    클라이언트 역할은 resource_access 클레임 아래에 있는 JWT에 있습니다.

      "resource_access": {
        "<client_A>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        },
        "<client_B>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        }
      }

    정책에 클라이언트 역할을 지정합니다.

    "client_roles": [
      { "name": "<client_role_A>", "client": "<client_A>" },
      { "name": "<client_role_B>", "client": "<client_A>" },
      { "name": "<client_role_A>", "client": "<client_B>" },
      { "name": "<client_role_B>", "client": "<client_B>" }
    ]

    다음은 client_roles 배열에 있는 각 오브젝트의 사용 가능한 속성입니다.

  • name: 역할의 이름을 지정합니다.
  • name_type: name 값을 평가하는 방법을 정의합니다. 일반 또는 유동일 수 있습니다 ( 리소스 유형과 동일한 방식으로 작동).
  • 클라이언트: 역할의 클라이언트를 지정합니다. 정의되지 않은 경우 이 정책은 aud 클레임을 클라이언트로 사용합니다.
  • client_type: 클라이언트 값을 평가하는 방법을 정의합니다. 일반 또는 유동일 수 있습니다 ( resource_type과 동일한 방식으로 작동).

4.1.24. 라우팅

라우팅 정책을 사용하면 요청을 서로 다른 대상 엔드포인트로 라우팅할 수 있습니다. 대상 엔드포인트를 정의한 다음 UI에서 정규 표현식을 사용하여 들어오는 요청을 라우팅할 수 있습니다.

APIcast 정책과 결합하는 경우 먼저 제공되는 두 정책에서 응답에 콘텐츠를 출력하므로 라우팅 정책을 체인에 APIcast에 배치해야 합니다. 두 번째 단계에서 콘텐츠 단계를 실행하도록 변경하면 요청이 이미 클라이언트에 전송되므로 응답에 대한 아무것도 출력하지 않습니다.

4.1.24.1. 라우팅 규칙

  • 여러 규칙이 있는 경우 라우팅 정책이 첫 번째 일치 항목을 적용합니다. 이 규칙을 정렬할 수 있습니다.
  • 일치하는 규칙이 없으면 정책은 업스트림을 변경하지 않으며 서비스 구성에 정의된 정의된 개인 기본 URL을 사용합니다.

4.1.24.2. 요청 경로 규칙

경로가 /accounts 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.3. 헤더 규칙

Test-Header 헤더 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.4. 쿼리 인수 규칙

쿼리 인수 test_query_arg 의 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.5. JWT 클레임 규칙

JWT 클레임의 값을 기반으로 라우팅하려면 JWT를 검증하고 정책이 공유하는 컨텍스트에 저장하는 체인에 정책이 있어야 합니다.

JWT 클레임 test_claim 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.6. 다중 작업 규칙

규칙은 모두 '및' combine_op를 사용하여 또는 하나 이상의 값이 true(또는' combine_op사용)로 평가되는 경우에만 지정된 업스트림에 대한 여러 개의 작업과 경로를 가질 수 있습니다. combine_op 의 기본값은 '및'입니다.

요청 경로가 /accounts 이고 헤더 Test-Header 값이 123 인 경우 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

요청 경로가 /accounts 이거나 헤더 Test-Header 값이 123 인 경우 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.7. 규칙 결합

룰을 결합할 수 있습니다. 여러 규칙이 있는 경우 선택한 업스트림 규칙은 true로 평가되는 첫 번째 규칙 중 하나입니다.

몇 가지 규칙이 있는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.8. catch-all 규칙

작업이 없는 규칙은 항상 일치합니다. 범용 규칙을 정의하는 데 유용할 수 있습니다.

이 구성은 요청을 http://some_upstream.com 로 라우팅하고 경로가 /abc 인 경우 http://another_upstream.com 로 요청을 라우팅하고, 마지막으로 요청을 http://another_upstream.com로 라우팅하고 , 이전 규칙이 true로 평가되지 않은 경우 http://default_upstream.com 로 라우팅합니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

4.1.24.9. 지원되는 작업

지원되는 작업은 ==, !=, 일치 항목입니다. 후자는 정규 표현식이 있는 문자열과 일치하며 ngx.re.match를 사용하여 구현됩니다.

이는 != 을 사용하는 구성입니다. 경로가 /accounts 가 아닌 경우 http://example.com 로 라우팅됩니다 :

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.10. 유동 템플릿

구성 값에 유동 템플릿을 사용할 수 있습니다. 이를 통해 체인에 있는 정책이 컨텍스트에 my_var 키를 저장하는 경우 동적 값으로 규칙을 정의할 수 있습니다.

이 구성은 해당 값을 사용하여 요청을 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

4.1.24.11. host _header에서 사용되는 호스트설정

기본적으로 요청이 라우팅되면 정책은 일치하는 규칙의 URL 호스트를 사용하여 Host 헤더를 설정합니다. host _header 특성을 사용하여 다른 호스트 를 지정할 수 있습니다.

이 구성은 some_host.com 을 호스트 헤더의 호스트로 지정하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

4.1.25. SOAP

SOAP 정책은 정책에 지정된 매핑 규칙을 사용하여 HTTP 요청의 SOAPAction 또는 Content-Type 헤더에 제공되는 SOAP 작업 URI와 일치합니다.

구성 속성

속성description필수 여부

패턴

pattern 속성을 사용하면 APIcast에서 SOAPAction URI에서 일치 항목을 찾을 문자열을 지정할 수 있습니다.

데이터 유형: 문자열

제공됨

metric_system_name

metric_system_name 속성을 사용하면 일치하는 패턴에서 적중을 등록할 3scale 백엔드 지표를 지정할 수 있습니다.

데이터 유형: 문자열, 유효한 메트릭이어야 합니다

제공됨

정책 오브젝트 예

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.26. TLS 클라이언트 인증서 유효성 검사

TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast는 TLS 핸드셰이크를 구현하고 허용 목록에 대해 클라이언트 인증서의 유효성을 검사합니다. 화이트리스트에는 CA(Certified Authority)에서 서명한 인증서 또는 일반 클라이언트 인증서가 포함되어 있습니다. 만료되었거나 유효하지 않은 인증서의 경우 요청이 거부되고 다른 정책은 처리되지 않습니다.

클라이언트는 APIcast에 연결하여 요청을 보내고 클라이언트 인증서를 제공합니다. APIcast는 정책 구성에 따라 들어오는 요청에 제공된 인증서의 신뢰성을 확인합니다. APIcast는 업스트림에 연결할 때 사용할 고유한 클라이언트 인증서를 사용하도록 구성할 수도 있습니다.

4.1.26.1. TLS 클라이언트 인증서 유효성 검사를 사용하도록 APIcast 설정

TLS를 종료하도록 APIcast를 구성해야 합니다. 아래 단계에 따라 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast에서 사용자가 제공한 클라이언트 인증서의 유효성 검사를 구성합니다.

사전 요구 사항

  • 3scale 설치에 액세스할 수 있어야 합니다.
  • 모든 배포가 완료될 때까지 기다려야 합니다.
4.1.26.1.1. 정책에서 작동하도록 APIcast 설정

APIcast를 설정하고 TLS를 종료하도록 구성하려면 다음 단계를 따르십시오.

  1. OpenShift 템플릿을 사용하여 APIcast 배포에 표시된 대로 액세스 토큰을 가져오고 APIcast 자체 관리를 배포해야 합니다.

    참고

    전체 게이트웨이에 대한 일부 인증서를 사용하도록 APIcast 인스턴스를 재구성해야 하므로 APIcast 자체 관리 배포가 필요합니다.

  2. 테스트 목적으로만 캐시 및 스테이징 환경 없이 lazy loader 및 --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
  3. 테스트 목적으로 인증서를 생성합니다. 또는 프로덕션 배포의 경우 인증 기관에서 제공하는 인증서를 사용할 수 있습니다.
  4. TLS 인증서로 시크릿 생성

    oc create secret tls apicast-tls
    --cert=ca/certs/server.crt
    --key=ca/keys/server.key
  5. APIcast 배포 내부의 시크릿 마운트

    oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
  6. 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
  7. 서비스에 8443 노출

    oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'
  8. 기본 경로 삭제

    oc delete route api-apicast-staging
  9. apicast 서비스를 경로로 노출

    oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
    참고

    이 단계는 사용할 모든 API 및 모든 API의 도메인 변경에 필요합니다.

  10. [your_user_key]를 플레이스 홀더에 지정하여 이전에 배포된 게이트웨이가 작동하고 구성이 저장되었는지 확인합니다.

    curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt

4.1.26.2. 정책 체인에서 TLS 클라이언트 인증서 유효성 검사 구성

정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하려면 다음을 수행합니다.

사전 요구 사항

4.1.26.2.1. 정책 구성
  1. API에 TLS 클라이언트 인증서 유효성 검사 정책을 추가하려면 표준 정책 활성화 에 설명된 단계를 따르고 TLS 클라이언트 인증서 유효성 검사를 선택합니다.
  2. TLS 클라이언트 인증서 유효성 검사 링크를 클릭합니다.
  3. 정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
  4. 허용 목록에 인증서를 추가하려면 더하기 아이콘을 클릭합니다.
  5. ----- BEGIN CERTIFICATE----- 및 -----END CERTIFICATE----- 를 포함한 인증서를 지정합니다.
  6. TLS 클라이언트 인증서 유효성 검사를 사용하여 API 설정을 마치면 Update Policy(정책 업데이트 )를 클릭합니다.

추가 사항:

  • 더하기 아이콘을 클릭하여 더 많은 인증서를 추가할 수 있습니다.
  • 위쪽 및 아래쪽 화살표를 클릭하여 인증서를 재구성할 수도 있습니다.

변경 사항을 저장하려면 Update Policy(정책 체인 업데이트 )를 클릭합니다.

4.1.26.3. TLS 클라이언트 인증서 유효성 검사 정책의 기능 확인

TLS 클라이언트 인증서 유효성 검사 정책의 기능을 확인하려면 다음을 수행합니다.

사전 요구 사항

4.1.26.3.1. 정책 기능 확인

자리 표시자에 [your_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

4.1.26.4. 화이트리스트에서 인증서 제거

허용 목록에서 인증서를 제거하려면 다음을 수행합니다.

4.1.26.4.1. 인증서 제거
  1. TLS 클라이언트 인증서 유효성 검사 링크를 클릭합니다.
  2. 허용 목록에서 인증서를 제거하려면 x 아이콘을 클릭합니다.
  3. 인증서 제거를 완료하고 나면 Update Policy(정책 업데이트 )를 클릭합니다.

변경 사항을 저장하려면 Update Policy(정책 체인 업데이트 )를 클릭합니다.

4.1.26.5. 참고 자료

인증서 사용에 대한 자세한 내용은 Red Hat Certificate System 을 참조하십시오.

4.1.27. TLS 종료

이 섹션에서는 정책의 개념, 구성, 확인 및 파일 제거와 같은 TLS(Transport Layer Security) 종료 정책에 대한 정보를 제공합니다.

TLS 종료 정책을 사용하면 모든 API에 대해 단일 인증서를 사용하지 않고 각 API에 대한 TLS 요청을 완료하도록 APIcast를 구성할 수 있습니다. APIcast는 클라이언트에 대한 연결을 설정하기 전에 구성 설정을 가져옵니다. 이러한 방식으로 APIcast는 정책의 인증서를 사용하며 TLS를 종료합니다. 이 정책은 다음 소스에서 작동합니다.

  • 정책 구성에 저장됩니다.
  • 파일 시스템에 저장됨.

기본적으로 이 정책은 정책 체인에서 활성화되지 않습니다.

4.1.27.1. 정책 체인에서 TLS 종료 구성

이 섹션에서는 PEM(개인 정보 보호 강화 메일) 형식 인증서를 사용하여 정책 체인에서 TLS 종료를 구성하는 전제 조건 및 단계에 대해 설명합니다.

사전 요구 사항

  • 사용자가 발급한 인증서
  • PEM 형식의 서버 인증서
  • PEM 형식의 인증서 개인 키
4.1.27.1.1. 정책 구성
  1. API에 TLS 종료 정책을 추가하려면 표준 정책 활성화 에 설명된 단계를 따르고 TLS 종료를 선택합니다.
  2. TLS 종료 링크를 클릭합니다.
  3. 정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
  4. 정책에 TLS 인증서를 추가하려면 더하기 아이콘을 클릭합니다.
  5. 인증서 소스를 선택합니다.

    • 포함된 인증서: 서버 인증서의 경로와 인증서 개인 키의 경로를 지정합니다.
    • 로컬 파일 시스템의 인증서: 인증서 개인 키와 서버 인증서를 탐색합니다.
  6. TLS 종료를 사용하여 API 설정을 마치면 Update Policy(정책 업데이트 )를 클릭합니다.

추가 사항:

  • 더하기 아이콘을 클릭하여 더 많은 인증서를 추가할 수 있습니다.
  • 위쪽 및 아래쪽 화살표를 클릭하여 인증서를 재구성할 수도 있습니다.

변경 사항을 저장하려면 Update Policy(정책 체인 업데이트 )를 클릭합니다.

4.1.27.2. TLS 종료 정책의 기능 확인

사전 요구 사항

4.1.27.2.1. 정책 기능 확인

정책이 다음 명령을 사용하여 작동하는 경우 명령줄에서 테스트할 수 있습니다.

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 인증서 경로

4.1.27.3. TLS 종료에서 파일 제거

이 섹션에서는 TLS 종료 정책에서 인증서 및 키 파일을 제거하는 단계를 설명합니다.

사전 요구 사항

4.1.27.3.1. 인증서 제거
  1. TLS 종료 링크를 클릭합니다.
  2. 인증서 및 키를 제거하려면 x 아이콘을 클릭합니다.
  3. 인증서 제거를 완료하고 나면 Update Policy(정책 업데이트 )를 클릭합니다.

변경 사항을 저장하려면 Update Policy(정책 체인 업데이트 )를 클릭합니다.

4.1.28. 업스트림

업스트림 정책을 사용하면 정규 표현식을 사용하여 호스트 요청 헤더를 구문 분석하고 개인 기본 URL에 정의된 업스트림 URL을 다른 URL로 바꿀 수 있습니다.

예를 들면 다음과 같습니다.

regex /foo 가 있는 정책과 URL 필드 newexample.com 은 URL https://www.example.com/foo/123/newexample.com으로 교체합니다.

정책 체인 참조:

속성description필수 여부

REGex

regex 속성을 사용하면 요청 경로와 일치하는 항목을 검색할 때 업스트림 정책에서 사용할 정규식을 지정할 수 있습니다.

data type: string, 유효한 정규식 구문이어야 합니다

제공됨

url

url 속성을 사용하여 일치 시 대체 URL을 지정할 수 있습니다. 업스트림 정책은 이 URL이 유효한지 여부를 확인하지 않습니다.

data type: string, 올바른 URL인지 확인하십시오.

제공됨

정책 오브젝트 예

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.29. 업스트림 연결

업스트림 연결 정책을 사용하면 3scale 설치에서 API 백엔드 서버를 구성한 방법에 따라 각 API에 대해 다음 지시문의 기본값을 변경할 수 있습니다.

  • proxy_connect_timeout
  • proxy_send_timeout
  • proxy_read_timeout

4.1.29.1. 정책 체인에서 업스트림 연결 구성

이 섹션에서는 정책 체인에서 업스트림 연결 정책을 구성하는 단계에 대해 설명합니다.

사전 요구 사항

  • 3scale 설치에 액세스할 수 있어야 합니다.
  • 모든 배포가 완료될 때까지 기다려야 합니다.
4.1.29.1.1. 정책 구성
  1. API에 업스트림 연결 정책을 추가하려면 표준 정책 활성화에 설명된 단계를 따르고 업스트림 연결을 선택합니다 .
  2. 업스트림 연결 링크를 클릭합니다.
  3. 정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
  4. 업스트림 연결에 대한 옵션을 구성합니다.

    • send_timeout
    • connect_timeout
    • read_timeout
  5. 업스트림 연결을 사용하여 API 설정을 마치면 Update Policy (업스트림 연결)를 클릭합니다.

변경 사항을 저장하려면 Update Policy(정책 체인 업데이트 )를 클릭합니다.

4.1.30. 업스트림 상호 TLS

업스트림 상호 TLS 정책을 사용하면 구성에 설정된 인증서를 기반으로 APIcast와 업스트림 API 간에 상호 TLS 연결을 설정할 수 있습니다. 이 정책은 다양한 업스트림 API에 대한 여러 인증서를 지원합니다.

4.1.30.1. 정책 체인에서 업스트림 상호 TLS 구성

이 섹션에서는 정책 체인에서 업스트림 상호 TLS 정책을 구성하는 단계를 설명합니다.

사전 요구 사항

  • 3scale 설치에 액세스할 수 있어야 합니다.

절차

  1. API에 업스트림 상호 TLS 정책을 추가하려면 표준 정책 활성화에 설명된 단계를 따르고 Upstream 상호 TLS 를 선택합니다.
  2. Upstream 상호 TLS 링크를 클릭합니다.
  3. 정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
  4. 인증서 유형 선택 :

    • path: OpenShift에서 생성된 것과 같이 인증서의 경로를 지정하려는 경우.
    • embedded: 타사에서 생성된 인증서를 파일 시스템에서 업로드하여 사용하려는 경우.
  5. 인증서 에서 클라이언트 인증서를 지정합니다.
  6. 인증서 키의 키를 지정합니다.
  7. Upstream Mutual TLS를 사용하여 API 설정을 마치면 정책 체인 업데이트를 클릭합니다.

변경 사항을 승격하려면 다음을 수행합니다.

  1. [your_product] 페이지 > 통합 > 구성으로 이동합니다.
  2. APIcast Configuration(APIcast 구성 )에서 Promote v# to Staging APIcast(스테이징 APIcast 로 승격)를 클릭합니다.

    • v# 은 승격할 구성의 버전 번호를 나타냅니다.

4.1.31. URL 다시 작성

URL 재작성 정책을 사용하면 요청 경로 및 쿼리 문자열을 수정할 수 있습니다.

3scale APIcast 정책과 결합하면 정책 체인의 APIcast 정책보다 먼저 URL 재작성 정책을 배치하면 APIcast 매핑 규칙이 수정된 경로에 적용됩니다. 정책 체인에서 APIcast 다음에 URL 재작성 정책을 배치하면 매핑 규칙이 원래 경로에 적용됩니다.

정책은 다음 두 가지 작업 세트를 지원합니다.

  • 명령: 요청 경로를 다시 작성하기 위해 적용할 명령 목록입니다.
  • query_args_commands: 요청의 쿼리 문자열을 다시 작성하기 위해 적용할 명령 목록입니다.

4.1.31.1. 경로를 다시 작성하기 위한 명령

다음은 명령 목록 의 각 명령이 구성된 구성 매개변수입니다.

  • op: 적용할 작업. 사용 가능한 옵션은 subgsub 입니다. 하위 작업은 첫 번째로 일치하는 일치 항목만 지정된 정규식으로 교체합니다. gsub 작업은 모든 일치 발생을 지정된 정규식으로 대체합니다. subgsub 작업에 대한 설명서를 참조하십시오.
  • regex: 일치하는 Perl 호환 정규 표현식.
  • 교체: 일치 시 사용되는 대체 문자열입니다.
  • 옵션 (선택 사항): regex 일치 방식을 정의하는 옵션입니다. 사용 가능한 옵션에 대한 자세한 내용은 OpenResty Lua 모듈 프로젝트 문서의 ngx.re.match 섹션을 참조하십시오.
  • 중단 (선택 사항): true(확인란 활성화)로 설정하면 명령이 URL을 다시 작성하는 경우 마지막으로 적용된 URL이 됩니다(목록의 모든 명령이 폐기됨).

4.1.31.2. 쿼리 문자열을 다시 작성하기 위한 명령

다음은 query_args_commands 목록의 각 명령이 구성된 구성 매개변수입니다.

  • op: 쿼리 인수에 적용할 작업입니다. 다음 옵션을 사용할 수 있습니다.

    • add: 기존 인수에 값을 추가합니다.
    • 설정: 설정되지 않은 경우 arg를 만들고 설정하면 해당 값을 바꿉니다.
    • push: 설정되지 않은 경우 arg를 만들고 설정할 때 값을 추가합니다.
    • 삭제: arg를 삭제합니다.
  • arg: 작업이 적용되는 쿼리 인수 이름입니다.
  • : 쿼리 인수에 사용되는 값을 지정합니다. 값 유형의 "liquid"의 경우 값은 {{ variable_from_context }} 형식이어야 합니다. 삭제 작업의 경우 값이 고려되지 않습니다.
  • value_type (선택 사항): 쿼리 인수 값이 평가되는 방법을 정의합니다. 일반 텍스트의 경우 일반 텍스트 또는 유동 템플릿으로 평가하기 위해 일반 텍스트 또는 유동이 될 수 있습니다. 자세한 내용은 5.1절. “정책에서 변수 및 필터 사용”의 내용을 참조하십시오. 지정하지 않으면 기본적으로 "plain" 유형이 사용됩니다.

예제

URL 재작성 정책은 다음과 같이 구성됩니다.

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

APIcast로 전송된 원래 요청 URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

URL 다시 작성을 적용한 후 APIcast가 API 백엔드로 전송하는 URI입니다.

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

다음과 같은 변환이 적용됩니다.

  1. 하위 문자열 /api/v1/ 는 유일한 경로 재작성 명령과 일치하며 /internal/ 로 대체됩니다.
  2. user_key 쿼리 인수가 삭제됩니다.
  3. pushvalue 값은 push arg 쿼리 인수에 추가 값으로 추가됩니다.
  4. 쿼리 인수 setarg원래 값은 구성된 값 setarg로 교체됩니다.
  5. 쿼리 인수 add arg가 원래 URL에 없기 때문에 명령 add 가 적용되지 않았습니다.

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.

4.1.32. 캡처를 사용하여 URL 재작성

캡처 정책으로 URL 다시 작성은 4.1.31절. “URL 다시 작성” 정책에 대한 대안이며 API 백엔드에 전달하기 전에 API 요청의 URL을 다시 작성할 수 있습니다.

captures 정책으로 다시 작성되는 URL은 URL의 인수를 검색하고 다시 작성된 URL에 해당 값을 사용합니다.

정책은 구성 매개 변수를 변환하는 기능을 지원합니다. 요청 URL에 적용되는 변환을 설명하는 개체 목록입니다. 각 tranformation 오브젝트는 두 개의 속성으로 구성됩니다.

  • match_rule: 이 규칙은 들어오는 요청 URL과 일치합니다. 명명된 인수를 {nameOfArgument} 형식으로 포함할 수 있습니다. 이러한 인수는 다시 작성된 URL에서 사용할 수 있습니다. URL은 정규 표현식으로 match_rule 과 비교됩니다. 명명된 인수와 일치하는 값에는 PCRE regex 표기법에서 다음 문자만 포함해야 합니다. [\w-.~%!$&'()*+,;=@:]+. 기타 regex 토큰은 문자열 시작 시 ^ 와 같은 match_rule 표현식에서 사용할 수 있으며 문자열 끝에는 $ 를 사용할 수 있습니다.
  • 템플릿: 원래 URL이 로 다시 작성된 URL의 템플릿입니다. match_rule 에서 명명된 인수를 사용할 수 있습니다.

원본 URL의 쿼리 매개 변수는 템플릿에 지정된 쿼리 매개 변수와 병합됩니다.

예제

captures 정책으로 URL 재작성은 다음과 같이 구성됩니다.

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

APIcast로 전송된 원래 요청 URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

URL 다시 작성을 적용한 후 APIcast가 API 백엔드로 전송하는 URI입니다.

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123

4.2. 관리 포털에서 정책 활성화

관리 포털에서 정책을 활성화하려면 다음 단계를 수행합니다.

  1. 3scale에 로그인합니다.
  2. 정책을 활성화하려는 제품 API를 선택합니다.
  3. [your_product_name] 에서 Integration > Policies 로 이동합니다.
  4. POLICIES (정책) 섹션에서 Add policy(정책 추가 )를 클릭합니다.
  5. 추가할 정책을 선택하고 필수 필드를 입력합니다.
  6. Update Policy 체인(정책 체인 업데이트) 단추를 클릭하여 정책 체인을 저장합니다.

4.3. 사용자 정의 APIcast 정책 생성

사용자 지정 APIcast 정책을 완전히 생성하거나 표준 정책을 수정할 수 있습니다.

사용자 지정 정책을 생성하려면 다음을 이해해야 합니다.

  • 정책은 Lua로 작성됩니다.
  • 정책은 를 준수하여 적절한 파일 디렉터리에 배치해야 합니다.
  • 정책 동작은 정책 체인에 배치되는 방식의 영향을 받습니다.
  • 사용자 지정 정책을 추가하는 인터페이스는 완전히 지원되지만 사용자 지정 정책 자체는 지원되지 않습니다.

4.4. APIcast에 사용자 정의 정책 추가

이 문서에서는 다양한 배포를 고려하여 APIcast에 사용자 지정 정책을 추가하는 방법에 대해 간단히 설명합니다.

4.4.1. APIcast 배포에 사용자 지정 정책 추가

사용자 지정 정책을 생성한 경우 APIcast에 추가해야 합니다. 이 작업을 수행하는 방법은 APIcast가 배포되는 위치에 따라 다릅니다.

  • 다음 APIcast 자체 관리 배포에 사용자 지정 정책을 추가할 수 있습니다. OpenShift의 APIcast 및 Docker 컨테이너 환경.
  • 호스팅된 APIcast에 사용자 지정 정책을 추가할 수 없습니다.
주의

프로덕션 게이트웨이에 직접 정책 변경을 수행하지 마십시오. 항상 변경 사항을 테스트합니다.

4.4.2. 포함된 APIcast에 사용자 정의 정책 추가

온프레미스 배포에 사용자 지정 APIcast 정책을 추가하려면 사용자 지정 정책이 포함된 OpenShift 이미지를 빌드하고 배포에 추가해야 합니다. 3scale은 프레임워크로 사용할 수 있는 샘플 리포지토리를 제공하여 온프레미스 배포에 사용자 지정 정책을 만들고 추가할 수 있습니다.

이 샘플 리포지토리에는 사용자 지정 정책에 대한 올바른 디렉터리 구조와 생성한 사용자 지정 정책이 포함된 새 APIcast OpenShift 이미지를 빌드하기 위한 이미지 스트림 및 BuildConfigs를 생성하는 템플릿이 포함되어 있습니다.

주의

apicast-custom-policies 를 빌드하면 빌드 프로세스에서 새 이미지를 the amp-apicast:latest 태그로 내보냅니다. 이 이미지 스트림 태그(:latest)에 이미지가 변경되면 기본적으로 apicast-stagingapicast-production 태그 모두 새 배포를 자동으로 시작하도록 구성됩니다. 프로덕션 서비스(또는 스테이징)의 중단을 방지하려면 자동 배포(이미지가변경될 경우 자동으로 새 배포를 시작) 확인란을 비활성화하거나 프로덕션에 대해 다른 이미지 스트림 태그(예:: amp-apicast:production)를 구성하는 것이 좋습니다.

온프레미스 배포에 사용자 지정 정책을 추가하려면 다음을 수행합니다.

  1. 다음 고려 사항에 따라 레지스트리 서비스 계정 생성에서 생성한 인증 정보를 사용하여 docker-registry 보안을 생성합니다.

    • your-registry-service-account-username12345678|username 형식으로 생성된 사용자 이름으로 바꿉니다.
    • Token Information ( 토큰 정보) 탭의 username 아래의 password 문자열로 your-registry-service-account-password 를 바꿉니다.
    • 이미지 스트림이 상주하고 registry.redhat.io 를 사용하는 모든 새 네임스페이스에 대해 docker-registry 보안을 생성합니다.

      이 명령을 실행하여 docker-registry 보안을 생성합니다.

      oc create secret docker-registry threescale-registry-auth \
        --docker-server=registry.redhat.io \
        --docker-username="your-registry-service-account-username" \
        --docker-password="your-registry-service-account-password"
  2. https://github.com/3scale/apicast-example-policy [정책 예제]를 사용하여 공용 리포지토리를 분기하거나 해당 콘텐츠를 사용하여 개인 리포지토리를 생성합니다. OpenShift에서 이미지를 빌드하려면 Git 리포지토리에서 사용할 수 있는 사용자 지정 정책 코드가 있어야 합니다. 개인 Git 리포지토리를 사용하려면 OpenShift에서 시크릿을 설정해야 합니다.
  3. 리포지토리를 로컬로 복제하고, 정책에 대한 구현을 추가하고, 변경 사항을 Git 리포지토리로 내보냅니다.
  4. openshift.yml 템플릿을 업데이트합니다. 구체적으로 다음 매개변수를 변경합니다.

    1. 정책 BuildConfig의 spec.source.git.uri: https://github.com/3scale/apicast-example-policy.git - Git 리포지토리 위치로 변경합니다.
    2. 사용자 정의 정책 BuildConfig의 spec.source.images[0].paths.sourcePath: /opt/app-root/policies/example - 예제 를 리포지토리의 policy 디렉터리에 추가한 사용자 지정 정책 이름으로 변경합니다.
    3. 선택적으로 OpenShift 오브젝트 이름 및 이미지 태그를 업데이트합니다. 그러나 변경 사항이 일관성(예: apicast-example-policy BuildConfig 빌드)인지 확인하고 apicast- custom-policies BuildConfig에서 소스로 사용되는 apicast- policy:example 이미지를 푸시해야 합니다. 따라서 태그는 동일해야 합니다.
  5. 명령을 실행하여 OpenShift 오브젝트를 생성합니다.

    oc new-app -f openshift.yml --param AMP_RELEASE=2.9
  6. 빌드가 자동으로 시작되지 않으면 다음 두 명령을 실행합니다. 변경한 경우 apicast-example-policy 를 자체 BuildConfig 이름(예: apicast-<name>-policy)으로 바꿉니다. 두 번째 명령을 실행하기 전에 첫 번째 명령이 완료될 때까지 기다립니다.

    oc start-build apicast-example-policy
    oc start-build apicast-custom-policies

기본 제공 APIcast 이미지에 the amp-apicast:latest 이미지 스트림의 변경 사항을 추적하는 트리거가 있는 경우 APIcast의 새 배포가 시작됩니다. apicast-staging 이 다시 시작되면 Integration > Policies (통합 > 정책 )로 이동하여 Add Policy (정책 추가) 버튼을 클릭하여 나열된 사용자 정의 정책을 확인합니다. 이를 선택하고 구성한 후 Update Policy(정책 체인 업데이트)를 클릭하여 스테이징 APIcast에서 사용자 지정 정책이 작동하도록 합니다.

4.4.3. 다른 OpenShift Container Platform에서 APIcast에 사용자 정의 정책 추가

통합 OpenShift Container Platform 레지스트리에서 사용자 정의 정책이 포함된 APIcast 이미지를 가져와 OpenShift Container Platform (OCP)에서 APIcast에 사용자 정의 정책을 추가할 수 있습니다.

다른 OpenShift Container Platform에서 APIcast에 사용자 정의 정책 추가

  1. APIcast 내장에 정책 추가
  2. 기본 OpenShift 클러스터에 APIcast 게이트웨이를 배포하지 않는 경우 기본 OpenShift 클러스터에서 내부 레지스트리에 대한 액세스를 설정합니다.
  3. 3 scale 2.9 APIcast OpenShift 템플릿을 다운로드합니다.
  4. 템플릿을 수정하려면 기본 이미지 디렉터리를 내부 레지스트리의 전체 이미지 이름으로 바꿉니다.

    image: <registry>/<project>/amp-apicast:latest
  5. OpenShift 템플릿을 사용하여 APIcast 배포, 사용자 지정 이미지를 지정합니다.

    oc new-app -f customizedApicast.yml
참고

사용자 지정 정책이 APIcast에 추가되고 새 이미지가 구축되면 APIcast가 이미지와 함께 배포되면 관리 포털에서 해당 정책이 자동으로 사용 가능으로 표시됩니다. 기존 서비스는 사용 가능한 정책 목록에서 이 새 정책을 확인할 수 있으므로 모든 정책 체인에서 사용할 수 있습니다.

사용자 지정 정책이 제거되고 APIcast가 다시 시작되면 목록에서 더 이상 정책을 사용할 수 없으므로 더 이상 정책 체인에 추가할 수 없습니다.

4.5. 3scale에서 정책 체인 생성

APIcast 게이트웨이 구성의 일부로 3scale에 정책 체인을 만듭니다. 관리 포털에서 정책 체인을 수정하려면 다음 단계를 따르십시오.

  1. 3scale에 로그인합니다.
  2. 정책 체인을 구성할 API 제품으로 이동합니다.
  3. [your_product_name] > Integration > Policies 에서 Add policy 를 클릭합니다.
  4. Policy 체인(정책 체인 ) 섹션에서 화살표 아이콘을 사용하여 정책 체인의 정책을 다시 지정합니다. 항상 정책 체인에 마지막에 3scale APIcast 정책을 배치합니다.

    policyChainOverview
  5. Update Policy 체인(정책 체인 업데이트) 단추를 클릭하여 정책 체인을 저장합니다.

4.6. 정책 체인 JSON 구성 파일 생성

APIcast의 기본 배포를 사용하는 경우 JSON 구성 파일을 생성하여 프리뷰 외부에서 정책 체인을 제어할 수 있습니다.

JSON 구성 파일 정책 체인에는 다음 정보로 구성된 JSON 배열이 포함되어 있습니다.

  • id 값이 있는 services 오브젝트는 정책 체인이 번호별로 적용되는 서비스를 지정합니다.
  • policy_chain 및 후속 오브젝트를 포함하는 프록시 오브젝트
  • policy_chain 오브젝트: 정책 체인을 정의하는 값이 포함된
  • 정책을 식별하고 정책 동작을 구성하는 데 필요한 이름구성 데이터를 모두 지정하는 개별 정책 오브젝트

다음은 사용자 지정 정책 sample_policy_1 및 API 인트로스펙션 표준 정책 token_ introspection 에 대한 정책 체인의 예입니다.

{
  "services":[
    {
      "id":1,
      "proxy":{
        "policy_chain":[
          {
            "name":"sample_policy_1", "version": "1.0",
            "configuration":{
              "sample_config_param_1":["value_1"],
              "sample_config_param_2":["value_2"]
            }
          },
          {
            "name": "token_introspection", "version": "builtin",
            "configuration": {
              introspection_url:["https://tokenauthorityexample.com"],
              client_id:["exampleName"],
              client_secret:["secretexamplekey123"]
          },
          {
             "name": "apicast", "version": "builtin",
          }
        ]
      }
    }
  ]
}

모든 정책 체인에는 기본 제공 정책 apicast 가 포함되어야 합니다. 정책 체인에 APIcast를 배치하면 정책 동작에 영향을 미칩니다.

5장. APIcast 네이티브 배포와 정책 체인 통합

기본 APIcast 배포의 경우 THREESCALE_CONFIG_FILE 환경 변수를 사용하여 구성 파일을 지정하여 사용자 지정 정책 체인 을 통합할 수 있습니다. 다음 예제에서는 구성 파일 example.json을 지정합니다.

THREESCALE_CONFIG_FILE=example.json bin/apicast

5.1. 정책에서 변수 및 필터 사용

일부 4.1절. “APIcast 표준 정책” 는 일반 문자열 값뿐만 아니라 요청 컨텍스트에 있는 변수도 사용할 수 있는 템플릿도 지원합니다.

컨텍스트 변수를 사용하려면 {{}} 에 이름을 래핑합니다(예: {{ uri }} ). 변수가 개체인 경우 속성(예: {{ somevar.attr }} )에 액세스할 수도 있습니다.

다음은 모든 정책에서 사용할 수 있는 표준 변수입니다.

  • uri: 쿼리 매개 변수가 이 경로에서 제외된 요청의 경로입니다. 포함된 NGINX 변수 $uri 의 값.
  • host: 요청 호스트(포함된 NGINX 변수 $host값).
  • remote_addr: 클라이언트의 IP 주소(포함된 NGINX 변수 $remote_addr의 값).
  • 헤더: 요청 헤더가 포함된 오브젝트입니다. {{headers['Some-Header']}} 를 사용하여 특정 헤더 값을 가져옵니다.
  • http_method: 요청 방법: GET, POST 등.

이러한 표준 변수는 요청 컨텍스트에서 사용되지만 정책은 컨텍스트에 변수를 추가할 수 있습니다. 단계는 APIcast에 있는 모든 실행 단계를 나타냅니다. 이러한 경우 정책 체인의 모든 정책에서 변수를 사용할 수 있습니다.

  • 동일한 단계 내에서 변수가 정책에 추가되고 추가 후 다음 정책에서 사용되는 경우.
  • 변수가 단계에서 추가되면 다음 단계에서 이 변수를 사용할 수 있습니다.

다음은 표준 3scale APIcast 정책에서 컨텍스트에 추가하는 몇 가지 변수의 예입니다.

  • jwt: JWT 토큰의 구문 분석된 JSON 페이로드(OpenID Connect 인증용).
  • 인증 정보 : 애플리케이션 자격 증명을 보유한 오브젝트입니다. 예: "app_id": "972f7b4f", "user_key": "13b668c4d1e10eaebaa5144b4749713f".
  • service: 현재 요청이 처리되는 서비스의 구성이 포함된 오브젝트입니다. 예: 서비스 ID는 {{ service.id }}로 사용할 수 있습니다.

컨텍스트에서 사용할 수 있는 오브젝트 및 값의 전체 목록은 4.1.15절. “유동 컨텍스트 디버그”을 참조하십시오.

변수는 템플릿의 도움말과 함께 사용됩니다. 예: {{ remote_addr }}, {{ headers['Some-Header'] }}, {{ jwt.aud }}. 값에 대한 변수를 지원하는 정책에는 일반적으로 일반 텍스트의 경우 "plain"이라는 두 개의 값을 허용하는 _type 접미사 (예: value_ type, name_type 등)가 포함된 특수 매개 변수가 있습니다.

APIcast는 변수의 값에 적용할 수 있는 필터도 지원합니다. 필터는 NGINX 함수를 변수의 값에 적용합니다.

필터는 파이프 문자 | 및 필터 이름을 통해 변수의 이름 또는 리터럴 값 뒤에 변수 출력 태그 {{ }} 내에 배치됩니다. 예:

  • {{ 'username:password' | encode_base64 }}, 여기서 username:password 는 변수입니다.
  • {{ uri | escape_uri }}.

일부 필터에는 매개 변수가 필요하지 않으므로 변수 대신 빈 문자열을 사용할 수 있습니다. 예: {{ '' | utctime }} 은 UTC 시간대에서 현재 시간을 반환합니다.

필터를 다음과 같이 연결할 수 있습니다. {{ variable | function1 | function2 }}. 예: {{ '' | utctime | escape_uri }}.

다음은 사용 가능한 함수 목록입니다.

6장. Fuse의 정책 확장을 사용하여 3scale 메시지 컨텐츠 변환

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(Enterprise Integration Pattern)를 사용하여 APIcast 정책 확장을 구현할 수 있습니다. 이를 통해 Java 또는 XML과 같은 친숙한 프로그래밍 언어를 사용하여 정책 확장을 작성할 수 있습니다. 이 주제의 예제에서는 Camel Netty4 HTTP 구성 요소를 사용하여 Java에서 HTTP 프록시를 구현합니다.

참고

3scale API 백엔드에서 Fuse Camel 애플리케이션을 이미 사용하고 있는 경우에는 이 기능이 필요하지 않습니다. 이 경우 기존 Fuse Camel 애플리케이션을 사용하여 변환을 수행할 수 있습니다.

필수 소프트웨어 구성 요소

다음과 같은 Red Hat 통합 구성 요소가 동일한 OpenShift 클러스터에 배포되어야 합니다.

  • Fuse on OpenShift 7.7
  • 3scale 온프레미스 2.9
  • APIcast 내장(기본 스테이징 및 생산) 또는 APIcast 자체 관리

3scale과 다른 OpenShift 프로젝트에 사용자 지정 Fuse 정책을 배포할 수 있지만 필수는 아닙니다. 그러나 두 프로젝트 간의 통신이 가능한지 확인해야 합니다. 자세한 내용은 OpenShift SDN을 사용하여 네트워크 정책 구성을 참조하십시오.

추가 리소스

6.1. Fuse에서 Apache Camel 변환과 APIcast 통합

OpenShift의 Fuse에서 Apache Camel 애플리케이션으로 작성된 변환과 APIcast를 통합할 수 있습니다. 정책 확장 변환이 3scale에 구성되고 배포되면 3scale 트래픽은 메시지 콘텐츠를 변환하는 Camel 정책 확장을 거칩니다. 이 경우 Camel은 APIcast에서 3scale 트래픽을 Camel로 전송한 다음 Camel이 API 백엔드로 트래픽을 전송하는 역방향 HTTP 프록시로 작동합니다.

이 주제의 예제에서는 Camel Netty4 HTTP 구성 요소를 사용하여 HTTP 프록시를 생성합니다.

  • HTTP 프록시 프로토콜을 통해 수신된 요청은 HTTP 본문을 대문자로 변환하여 대상 서비스로 전달됩니다.
  • target 서비스의 응답은 대문자로 변환한 다음 클라이언트로 반환하여 처리됩니다.
  • 이 예에서는 HTTP 및 HTTPS 사용 사례에 필요한 구성을 보여줍니다.

사전 요구 사항

  • 동일한 OpenShift 클러스터에 OpenShift 7.7 및 3scale 2.9에 Fuse를 배포해야 합니다. 설치 세부 사항은 다음을 참조하십시오.

  • OpenShift 및 3scale에 Fuse를 설치하고 프로젝트를 만들려면 클러스터 관리자 권한이 있어야 합니다. 그러나 배포 구성을 생성하거나, Pod를 배포하거나, 프로젝트당 편집 액세스 권한을 사용하여 서비스를 생성할 수 있습니다.

절차

  1. Camel netty4-http 구성 요소를 사용하여 Java에서 Apache Camel 애플리케이션을 작성하여 HTTP 프록시를 구현합니다. 그런 다음 Camel 구성 요소를 사용하여 메시지를 변환할 수 있습니다.

    다음 간단한 예제에서는 서비스에서 요청 및 응답의 대문자 변환을 수행합니다.

    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.util.Locale;
    
    import org.apache.camel.Exchange;
    import org.apache.camel.Message;
    import org.apache.camel.builder.RouteBuilder;
    import org.apache.camel.model.RouteDefinition;
    
    public class ProxyRoute extends RouteBuilder {
    
        @Override
        public void configure() throws Exception {
            final RouteDefinition from;
            if (Files.exists(keystorePath())) {
                from = from("netty4-http:proxy://0.0.0.0:8443?ssl=true&keyStoreFile=/tls/keystore.jks&passphrase=changeit&trustStoreFile=/tls/keystore.jks"); 1
            } else {
                from = from("netty4-http:proxy://0.0.0.0:8080");
            }
    
            from
                .process(ProxyRoute::uppercase)
                .toD("netty4-http:"
                    + "${headers." + Exchange.HTTP_SCHEME + "}://" 2
                    + "${headers." + Exchange.HTTP_HOST + "}:"
                    + "${headers." + Exchange.HTTP_PORT + "}"
                    + "${headers." + Exchange.HTTP_PATH + "}")
                .process(ProxyRoute::uppercase);
        }
    
        Path keystorePath() {
            return Path.of("/tls", "keystore.jks");
        }
    
        public static void uppercase(final Exchange exchange) { 3
            final Message message = exchange.getIn();
            final String body = message.getBody(String.class);
            message.setBody(body.toUpperCase(Locale.US));
        }
    
    }
    1
    이 간단한 예에서 Java 키 저장소 파일이 /tls/keystore.jks 에 마운트된 경우 수신 대기 포트가 8443 으로 설정됩니다.
    2
    Camel 프록시 정책을 3scale에서 호출하면 3scale의 백엔드 API에 대해 구성된 값에 따라 HTTP_SCHEME, HTTP_HOST, HTTP_PORT 및 HTTP_PATH 헤더의 값이 자동으로 설정됩니다.
    3
    이 간단한 예제에서는 메시지 내용을 대문자로 변환합니다. Camel Enterprise Integration Patterns를 사용하여 요청 및 응답 메시지 콘텐츠(예: XML에서 JSON으로)에서 더 복잡한 변환을 수행할 수 있습니다.
  2. OpenShift에 Camel 애플리케이션을 배포하고 서비스로 노출합니다. 자세한 내용은 OpenShift에서 애플리케이션 생성 및 배포를 참조하십시오.

6.2. OpenShift의 Fuse에서 Apache Camel을 사용하여 생성된 APIcast 정책 확장 구성

OpenShift에서 Fuse를 사용하여 Apache Camel 변환을 구현한 후에는 3scale 관리 포털을 사용하여 APIcast 정책 체인에서 정책 확장으로 구성할 수 있습니다.

정책 확장을 사용하면 Camel HTTP 프록시를 사용하도록 3scale 제품을 구성할 수 있습니다. 이 서비스는 HTTP 프록시를 통해 3scale 트래픽을 전송하여 타사 프록시에서 요청 응답 수정을 수행하는 데 사용됩니다. 이 경우 타사 프록시는 OpenShift에서 Fuse를 사용하여 구현된 Apache Camel입니다. TLS를 사용하여 안전하게 Camel HTTP 프록시 서비스에 연결하도록 APIcast를 구성할 수도 있습니다.

참고

정책 확장 코드는 OpenShift의 Fuse의 Apache Camel 애플리케이션에서 구현되며 3scale에서 수정하거나 삭제할 수 없습니다.

사전 요구 사항

절차

  1. 3scale 관리 포털에서 Integration > Policies 를 선택합니다.
  2. POLICIES > Add policy > Camel Service 를 선택합니다.
  3. 적절한 필드에서 Camel HTTP 프록시 서비스에 연결하는 데 사용되는 OpenShift 경로를 입력합니다.

    • https_proxy: http 프로토콜 및 TLS 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.

      http://camel-proxy.my-3scale-management-project.svc:8443
    • http_proxy: http 프로토콜 및 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.

      http://camel-proxy.my-3scale-management-project.svc:8080
    • all_proxy: 프로토콜을 지정하지 않은 경우 http 프로토콜 및 포트를 사용하여 Camel HTTP 프록시에 연결합니다. 예를 들면 다음과 같습니다.

      http://camel-proxy.my-3scale-management-project.svc:8080
  4. 업데이트된 정책 구성을 스테이징 또는 프로덕션 환경으로 승격합니다. 예를 들어 Promote v를 클릭합니다. 3 ~ Staging APIcast.
  5. 3scale curl 명령을 사용하여 APIcast 정책 구성을 테스트합니다. 예를 들면 다음과 같습니다.

    curl "https://testapi-3scale-apicast-staging.myuser.app.dev.3sca.net:443/?user_key=MY_USER_KEY" -k

    APIcast는 Camel HTTP 프록시에 연결하기 위한 새 TLS 세션을 설정합니다.

  6. 메시지 콘텐츠가 변환되었는지 확인합니다. 이 예에서는 대문자로 변환되었습니다.
  7. 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

    이 예제에서는 GET 이후 전체 URL을 사용하여 HTTP 프록시 요청을 생성하고 ncat --ssl 매개 변수를 사용하여 포트 8443my-camel-proxy 호스트에 대한 TLS 연결을 지정합니다.

    참고

    프록시가 CONNECT 메서드를 사용하여 HTTP 터널링을 지원하지 않으므로 curl 또는 기타 일반 HTTP 클라이언트를 사용하여 Camel HTTP 프록시를 직접 테스트할 수 없습니다. CONNECT 로 HTTP 터널링을 사용하는 경우 전송은 엔드 투 엔드 암호화로, Camel HTTP 프록시가 페이로드를 중재할 수 없습니다.

7장. APIcast 환경 변수

APIcast 환경 변수를 사용하면 APIcast의 동작을 수정할 수 있습니다. 지원되는 환경 변수는 다음과 같습니다.

참고
  • 지원되지 않거나 더 이상 사용되지 않는 환경 변수가 나열되지 않음
  • 일부 환경 변수 기능이 APIcast 정책으로 이동되었을 수 있습니다.

all_proxy, ALL_PROXY

기본값: 없음 : 문자열 :http://forward-proxy:80

프로토콜별 프록시가 지정되지 않은 경우 서비스에 연결하는 데 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.

APICAST_ACCESS_LOG_FILE

default: stdout

액세스 로그를 저장할 파일을 정의합니다.

APICAST_BACKEND_CACHE_HANDLER

: 엄격한 | 탄력적

기본값: strict

사용 중지됨: 대신 캐싱 정책을 사용합니다.

백엔드를 사용할 수 없을 때 권한 부여 캐시가 동작하는 방법을 정의합니다. 백엔드를 사용할 수 없는 경우 Strict는 캐시된 애플리케이션을 제거합니다. 복원력은 백엔드에서 권한을 거부하는 경우에만 적용됩니다.

APICAST_CACHE_MAX_TIME

기본값: 1m

값: 문자열

시스템에 캐시할 응답을 선택하면 이 변수의 값은 캐시할 최대 시간을 나타냅니다. cache-control 헤더가 설정되지 않은 경우 캐시할 시간이 정의된 헤더가 됩니다.

이 값의 형식은 proxy_cache_valid NGINX 지시문 으로 정의합니다.

이 매개 변수는 콘텐츠 캐싱 정책을 사용하고 요청을 캐시할 수 있는 API에서만 사용합니다.

APICAST_CACHE_STATUS_CODES

기본값: 200, 302

값: 문자열

업스트림의 응답 코드가 이 환경 변수에 정의된 상태 코드 중 하나와 일치하면 응답 콘텐츠가 NGINX에 캐시됩니다. 캐싱 시간은 헤더 캐시 시간 값 또는 APICAST_CACHE_MAX_TIME 환경 변수로 정의된 최대 시간 중 하나에 따라 달라집니다.

이 매개 변수는 콘텐츠 캐싱 정책을 사용하고 요청을 캐시할 수 있는 API에서만 사용합니다.

APICAST_CONFIGURATION_CACHE

: 숫자

기본값: 0

구성이 저장될 간격(초)을 지정합니다. 값은 0(API CAST_CONFIGURATION_LOADER의 부팅 값과 호환되지 않음) 60으로 설정해야 합니다. 예를 들어 APICAST_CONFIGURATION_CACHE 가 120으로 설정된 경우 게이트웨이는 2분(120초)마다 API 관리자에서 구성을 다시 로드합니다. 값 < 0은 다시 로드를 비활성화합니다.

APICAST_CONFIGURATION_LOADER

: 부팅 | 지연

기본값: 지연

는 구성을 로드하는 방법을 정의합니다. 부팅은 게이트웨이가 시작될 때 API 관리자에 구성을 요청합니다. lazy는 들어오는 각 요청에 대해 요청 시 로드합니다(각 요청 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

: 부울

: "true"

Prometheus 지표에 대한 추가 정보를 활성화합니다. 다음 메트릭에는 APIcast에 대한 자세한 내용을 제공하는 service_id 및 service_system_name 라벨이 있습니다.

  • total_response_time_seconds
  • upstream_response_time_seconds
  • upstream_status

APICAST_HTTPS_CERTIFICATE

default: 값 없음

HTTPS의 PEM 형식의 X.509 인증서가 있는 파일 경로입니다.

APICAST_HTTPS_CERTIFICATE_KEY

default: 값 없음

PEM 형식의 X.509 인증서 비밀 키가 있는 파일 경로입니다.

APICAST_HTTPS_PORT

default: 값 없음

APIcast가 HTTPS 연결 수신을 시작할 포트를 제어합니다. HTTP 포트와 충돌하는 경우 HTTPS에만 사용됩니다.

APICAST_HTTPS_VERIFY_DEPTH

기본값: 1

value: 양의 정수입니다.

클라이언트 인증서 체인의 최대 길이를 정의합니다. 이 매개변수의 값이 1 인 경우 클라이언트 인증서 체인에 추가 인증서를 포함할 수 있습니다. 예를 들면 루트 인증 기관입니다.

APICAST_LOAD_SERVICES_WHEN_NEEDED

값:

  • true 또는 true 의 경우 1 입니다 .
  • false,0 또는 false의 경우 비어 있음

기본값:false

이 옵션은 많은 서비스가 구성되어 있는 경우 사용할 수 있습니다. 그러나 해당 성능은 서비스 수, APIcast와 3scale 관리 포털 간의 대기 시간, 구성의 TTL(Time To Live) 등의 추가 요소에 따라 달라집니다.

기본적으로 APIcast는 관리 포털에서 구성을 다운로드할 때마다 모든 서비스를 로드합니다. 이 옵션을 활성화하면 구성에서 지연 로드를 사용합니다. APIcast는 요청의 호스트 헤더에 지정된 호스트에 대해 구성된 항목만 로드합니다.

참고

APICAST_LOG_FILE

기본값: stderr

OpenResty 오류 로그를 포함하는 파일을 정의합니다. 파일은 error_log 지시문의 bin/apicast 에서 사용됩니다. 파일 경로는 절대 경로이거나 APIcast 접두사 디렉터리와 상대적일 수 있습니다. 기본 접두사 디렉터리는 APIcast입니다. 자세한 내용은 NGINX 설명서 를 참조하십시오.

APICAST_LOG_LEVEL

: debug | info | notice | warn | error | crit | alert | emerg

기본값: warn

OpenResty 로그의 로그 수준을 지정합니다.

APICAST_MANAGEMENT_API

값:

  • Disabled: 완전히 비활성화되어 포트에서만 수신 대기합니다
  • status : 상태 점검에 대해 /status/ 끝점만 활성화됨
  • debug: 전체 API가 열려 있습니다

관리 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 또는 true 의 경우 1 입니다.
  • false,0 또는 false의 경우 비어 있음

이 매개 변수를 true 로 설정하면 게이트웨이는 기본 호스트 기반 라우팅 외에도 경로 기반 라우팅을 사용합니다. API 요청은 요청의 Host 헤더 값이 Public Base URL 과 일치하는 서비스 목록에서 일치하는 매핑 규칙이 있는 첫 번째 서비스로 라우팅됩니다.

APICAST_PATH_ROUTING_ONLY

:

  • true 또는 true 의 경우 1 입니다.
  • false,0 또는 false의 경우 비어 있음

이 매개변수를 true 로 설정하면 게이트웨이는 경로 기반 라우팅을 사용하며 기본 호스트 기반 라우팅으로 대체되지 않습니다. API 요청은 요청의 Host 헤더 값이 Public Base URL 과 일치하는 서비스 목록에서 일치하는 매핑 규칙이 있는 첫 번째 서비스로 라우팅됩니다.

이 매개변수는 APICAST_PATH_ROUTING 보다 우선합니다. APICAST_PATH_ROUTING_ONLY 가 활성화된 경우 APIcast는 APICAST_PATH_ROUTING 값과 관계없이 경로 기반 라우팅만 수행합니다.

APICAST_POLICY_LOAD_PATH

기본값: APICAST_DIR/policies

value: string[:]

:~/apicast/policies:$PWD/policies

APIcast에서 정책을 찾아야 하는 콜론(:)으로 구분된 경로 목록입니다. 개발 디렉토리에서 우선 정책을 로드하거나 예제를 로드하는 데 사용할 수 있습니다.

APICAST_PROXY_HTTPS_CERTIFICATE

기본값:

: 문자열

: /home/apicast/my_certificate.crt

업스트림과 연결할 때 APIcast가 사용할 클라이언트 SSL 인증서의 경로입니다. 이 인증서는 구성의 모든 서비스에 사용됩니다.

APICAST_PROXY_HTTPS_CERTIFICATE_KEY

기본값:

: 문자열

: /home/apicast/my_certificate.key

클라이언트 SSL 인증서의 키 경로입니다.

APICAST_PROXY_HTTPS_PASSWORD_FILE

기본값:

: 문자열

: /home/apicast/passwords.txt

APICAST_PROXY_HTTPS_CERTIFICATE_KEY 로 지정된 SSL 인증서 키의 암호가 있는 파일의 경로입니다.

APICAST_PROXY_HTTPS_SESSION_REUSE

기본값: 켜짐

:

  • 에서: SSL 세션을 재사용합니다.
  • off: SSL 세션을 재사용하지 않습니다.

APICAST_REPORTING_THREADS

기본값: 0

: 정수 >= 0

실험적: 극도의 부하에서 예측할 수 없는 성능이 있고 보고서가 손실될 수 있습니다.

0보다 큰 값은 백엔드에 대한 대역 외 보고를 활성화합니다. 이는 성능 향상을 위한 새로운 실험 기능입니다. 클라이언트는 백엔드 대기 시간이 표시되지 않으며 모든 사항이 비동기적으로 처리됩니다. 이 값은 대기 시간을 추가하여 클라이언트가 제한되기 전에 동시에 실행할 수 있는 비동기 보고서 수를 결정합니다.

APICAST_RESPONSE_CODES

:

  • true 또는 true 의 경우 1 입니다.
  • false,0 또는 false의 경우 비어 있음

기본값: <empty> (false)

true 로 설정하면 APIcast가 3scale에서 API 백엔드에서 반환한 응답의 응답 코드를 기록합니다. 3scale 고객 포털에서 응답 코드 기능에 대한 자세한 내용을 확인하십시오.

APICAST_SERVICE_CACHE_SIZE

: 정수 >= 0

기본값: 1000

APIcast가 내부 캐시에 저장할 수 있는 서비스 수를 지정합니다. Lua의 lru 캐시가 모든 항목을 초기화하므로 높은 값은 성능에 영향을 미칩니다.

APICAST_SERVICE_${ID}_CONFIGURATION_VERSION

${ID} 를 실제 서비스 ID로 바꿉니다. 값은 관리 포털의 구성 내역에서 볼 수 있는 구성 버전이어야 합니다. 특정 버전으로 설정하면 자동으로 업데이트되지 않으며 항상 해당 버전을 사용합니다.

APICAST_SERVICES_LIST

value: 쉼표로 구분된 서비스 ID 목록

APICAST_SERVICES_LIST 환경 변수는 3scale API Manager에서 구성하는 서비스를 필터링하는 데 사용됩니다. 이는 게이트웨이의 특정 서비스에 대한 구성만 적용하여 목록에 지정되지 않은 서비스 식별자를 삭제합니다. 제품 > [your_product_name] > Overview 의 관리 포털에서 제품의 서비스 식별자를 찾은 다음 Configuration, Methods 및 Settings 및 API 호출 ID 를 참조하십시오.

APICAST_SERVICES_FILTER_BY_URL

: PCRE (Perl Compatible Regular Expression) (예: .*.example.com )입니다.

3scale API Manager에서 구성된 서비스를 필터링합니다.

이 필터는 공개 기본 URL 과 일치합니다. 필터와 일치하지 않는 서비스는 삭제됩니다. 정규 표현식을 컴파일할 수 없는 경우 서비스가 로드되지 않습니다.

참고

서비스가 일치하지 않지만 APICAST_SERVICES_LIST포함된 경우 서비스가 취소되지 않습니다.

예 7.1. 예

Regexp 필터 http://.*.foo.dev 는 다음 백엔드 끝점에 적용됩니다.

이 경우 포함된 APIcast에서 13 이 구성되어 24 가 삭제됩니다.

APICAST_UPSTREAM_RETRY_CASES

: error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off

참고

이는 재시도 정책이 구성된 경우에만 사용되며 업스트림 API에 대한 요청을 다시 시도해야 하는 시기를 지정합니다. Nginx의 PROXY_NEXT_UPSTREAM 모듈과 동일한 값을 허용합니다.

APICAST_WORKERS

기본값: auto

:숫자 | auto

이는 nginx worker_processes 지시문에서 사용되는 값입니다. 기본적으로 APIcast는 1 가 사용되는 개발 환경을 제외하고 auto 를 사용합니다.

BACKEND_ENDPOINT_OVERRIDE

구성의 백엔드 엔드포인트를 재정의하는 URI입니다. OpenShift 외부에서 배포할 때 유용함. :https://backend.example.com.

HTTP_KEEPALIVE_TIMEOUT

기본값: 75 : 양의 정수 : 1

이 매개 변수는 서버 측에서 keep-alive 클라이언트 연결이 열린 동안 시간 초과를 설정합니다. 0 값은 keep-alive 클라이언트 연결을 비활성화합니다.

기본적으로 게이트웨이는 HTTP_KEEPALIVE_TIMEOUT 비활성화를 유지합니다. 이 구성을 사용하면 기본값이 75초 인 NGINX의 keepalive 타임아웃을 사용할 수 있습니다.

http_proxy, HTTP_PROXY

기본값: 없음 : 문자열 :http://forward-proxy:80

HTTP 서비스 연결에 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.

https_proxy, HTTPS_PROXY

기본값: 없음 : 문자열 :https://forward-proxy:443

HTTPS 서비스 연결에 사용할 HTTP 프록시를 정의합니다. 인증은 지원되지 않습니다.

no_proxy, NO_PROXY

default: no value : string\[,<string>\]; * Example:foo,bar.com,.extra.dot.com

요청이 프록시되지 않아야 하는 쉼표로 구분된 호스트 이름 및 도메인 이름 목록을 정의합니다. 모든 호스트와 일치하는 단일 * 문자로 설정하면 프록시가 효과적으로 비활성화됩니다.

OPENSSL_VERIFY

:

  • 0,false: 피어 확인 비활성화
  • 1,true: 피어 확인 활성화

OpenSSL Peer Verification 제어. OpenSSL은 시스템 인증서 저장소를 사용할 수 없으므로 기본적으로 꺼져 있습니다. 여기에는 사용자 정의 인증서 번들이 필요하며 이를 신뢰할 수 있는 인증서에 추가해야 합니다.

https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate 을(를) 사용하고 export-builtin-trusted-certs 에서 생성된 인증서 번들을 가리키는 것이 좋습니다.

OPENTRACING_CONFIG

이 환경 변수는 OPENTRACING_TRACER 가 설정되지 않은 경우 opentracing 추적기에 대한 구성 파일을 결정하는 데 사용됩니다.

각 추적기에는 기본 구성 파일이 있습니다. * jaeger: conf.d/opentracing/jaeger.example.json

이 변수를 사용하여 파일 경로를 설정하여 기본적으로 제공된 것과 다른 구성을 마운트하도록 선택할 수 있습니다.

Example: /tmp/jaeger/jaeger.json

OPENTRACING_HEADER_FORWARD

Default: uber-trace-id

이 환경 변수는 오픈tracing 정보를 전달하는 데 사용되는 HTTP 헤더를 제어합니다. 이 HTTP 헤더는 업스트림 서버로 전달됩니다.

OPENTRACING_TRACER

:jaeger

이 환경 변수는 로드할 추적 라이브러리를 현재 사용할 수 있는 opentracing 추적기 한 개뿐인 jaeger 를 제어합니다.

비어 있는 경우 Opentracing 지원이 비활성화됩니다.

확인자

OpenResty에서 사용할 사용자 지정 DNS 확인자를 지정할 수 있습니다. RESOLVER 매개변수가 비어 있으면 DNS 확인자가 자동으로 검색됩니다.

THREESCALE_CONFIG_FILE

게이트웨이 구성을 사용하는 JSON 파일의 경로입니다. 게이트웨이가 성공적으로 실행되도록 THREESCALE_PORTAL_ENDPOINT 또는 THREESCALE_CONFIG_FILE 을 제공해야 합니다. 이 두 환경 변수에서 THREESCALE_CONFIG_FILE 이 우선합니다.

Proxy Config ShowProxy Config Show Latest 엔드포인트는 서비스에 의해 범위가 지정되며 Proxy Configs List 서비스도 제공됩니다. 서비스 ID를 알고 있어야 합니다. 다음 옵션을 사용합니다.

  • 프록시 구성 목록 공급자 끝점을 사용합니다. <schema>://<admin-portal-domain>/admin/api/proxy_configs/<env>.json

    • 끝점은 각 서비스의 최신뿐만 아니라 공급자의 저장된 모든 프록시 구성을 반환합니다. JSON에서 반환된 proxy_configs 배열을 반복하고 proxy _config. version이 동일한 proxy_config. content.id가 동일한 proxy_config.id 중 가장 높은 proxy_config.content 를 선택합니다.
  • 서비스 목록 끝점 사용: /admin/api/services.json

    • 엔드포인트는 공급자의 모든 서비스를 나열합니다. 서비스 배열을 반복하고 각 서비스에서 서비스에서 범위가 지정된 Proxy Config Show Latest 끝점을 사용합니다.

컨테이너 이미지를 사용하여 게이트웨이를 배포하는 경우:

  1. 이미지에 파일을 읽기 전용 볼륨으로 구성합니다.
  2. 볼륨을 마운트한 위치를 나타내는 경로를 지정합니다.

예제 폴더에서 샘플 구성 파일을 찾을 수 있습니다.

THREESCALE_DEPLOYMENT_ENV

: 스테이징 | 프로덕션

기본값: production

이 환경 변수의 값은 구성을 다운로드할 환경을 정의합니다. 이는 새 APIcast를 사용할 때 3scale 스테이징 또는 프로덕션입니다.

이 값은 3 scale 서비스 관리 API에 대한 인증/보고서 요청의 X-3scale-User-Agent 헤더에도 사용됩니다. 3scale은 통계에만 사용됩니다.

THREESCALE_PORTAL_ENDPOINT

다음 형식으로 암호 및 포털 엔드 포인트를 포함하는 URI:

<schema>://<password>@<admin-portal-domain>.

다음과 같습니다.

  • <password> 는 3scale 계정 관리 API에 대한 공급자 키 또는 액세스 토큰 일 수 있습니다.
  • <admin-portal-domain> 은 3scale 관리 포털에 로그인할 URL 주소입니다.

:https://access-token@account-admin.3scale.net.

THREESCALE_PORTAL_ENDPOINT 환경 변수가 제공되면 게이트웨이는 초기화 시 3scale에서 구성을 다운로드합니다. 구성에는 API의 통합 페이지에 제공된 모든 설정이 포함됩니다.

이 환경 변수를 사용하여 마스터 관리 포털로 단일 게이트웨이를 생성할 수도 있습니다.

게이트웨이 성공적으로 실행하기 위해 THREESCALE_PORTAL_ENDPOINT 또는 THREESCALE_CONFIG_FILE (권한 우선 순위)을 제공해야 합니다.

8장. 성능 향상을 위해 APIcast 구성

이 문서에서는 APIcast의 성능 문제를 디버깅하기 위한 일반적인 지침을 제공합니다. 또한 사용 가능한 캐싱 모드를 소개하고 성능 향상과 프로파일링 모드에 대한 세부 정보를 설명합니다. 내용은 다음 섹션에서 구조화되어 있습니다.

8.1. 일반 지침

일반적인 APIcast 배포에는 고려해야 할 세 가지 구성 요소가 있습니다.

  • APIcast
  • 요청을 인증하고 사용을 추적하는 3scale 백엔드 서버
  • 업스트림 API

APIcast에서 성능 문제가 발생하면 다음을 수행합니다.

  • 문제를 담당하는 구성 요소를 식별합니다.
  • APIcast와 3scale 백엔드 서버가 도입하는 대기 시간을 확인하기 위해 업스트림 API의 대기 시간을 측정합니다.
  • 벤치마크를 실행하는 데 사용하는 것과 동일한 도구를 사용하여 새 측정을 수행하되 업스트림 API를 직접 가리키는 대신 APIcast를 가리킵니다.

이러한 결과를 비교하면 APIcast에서 도입한 대기 시간 및 3scale 백엔드 서버에 대한 아이디어를 얻을 수 있습니다.

자체 관리 APIcast를 사용한 호스팅(SaaS) 설치에서 APIcast에서 도입하고 3scale 백엔드 서버가 높은 경우 다음을 수행합니다.

  1. APIcast가 배포된 동일한 시스템에서 3scale 백엔드 서버에 요청합니다.
  2. 대기 시간을 측정합니다.

3scale 백엔드 서버는 버전을 반환하는 엔드 포인트를 표시합니다 . https://su1.3scale.net/status. 비교를 위해 인증 호출에는 키, 제한 및 대기열 백그라운드 작업을 확인하기 때문에 더 많은 리소스가 필요합니다. 3scale 백엔드 서버는 이러한 작업을 몇 밀리초 내에 수행하지만 /status 엔드포인트와 같은 버전을 확인하는 것보다 더 많은 작업이 필요합니다. 예를 들어 /status 에 대한 요청이 APIcast 환경에서 약 300ms를 사용하면 캐시되지 않은 모든 요청에 대해 인증에 더 많은 시간이 걸립니다.

8.2. 기본 캐싱

캐시되지 않은 요청의 경우 이벤트입니다.

  1. APIcast는 일치하는 매핑 규칙에서 사용량 지표를 추출합니다.
  2. APIcast는 지표와 애플리케이션 자격 증명을 3scale 백엔드 서버로 전송합니다.
  3. 3scale 백엔드 서버는 다음을 수행합니다.

    1. 애플리케이션 키를 확인하고 보고된 지표 사용량이 정의된 제한 내에 있는지 확인합니다.
    2. 보고된 지표의 사용을 늘리려면 백그라운드 작업을 대기열에 지정합니다.
    3. 요청이 승인되어야 하는지 여부에 APIcast에 응답합니다.
  4. 요청이 승인되면 업스트림으로 이동합니다.

이 경우 3scale 백엔드 서버가 응답할 때까지 요청이 업스트림에 도착하지 않습니다.

반면 기본적으로 활성화되는 캐싱 메커니즘은 다음과 같습니다.

  • APIcast는 인증 받은 경우 3scale 백엔드 서버에 대한 권한 부여 호출 결과를 캐시에 저장합니다.
  • 동일한 자격 증명 및 지표가 있는 다음 요청은 3scale 백엔드 서버로 이동하는 대신 캐시된 권한 부여를 사용합니다.
  • 요청이 인증되지 않았거나 APIcast가 인증서를 처음 수신하는 경우 APIcast는 위에서 설명한 대로 3scale 백엔드 서버를 동기적으로 호출합니다.

인증이 캐시되면 APIcast는 먼저 업스트림을 호출한 다음 사후 작업 이라고 하는 단계에서 3scale 백엔드 서버를 호출하고 캐시에 권한을 저장하여 다음 요청을 준비합니다. 3scale 백엔드 서버에 대한 호출은 요청 시간에 발생하지 않기 때문에 대기 시간을 유발하지 않습니다. 그러나 동일한 연결에 전송된 요청은 사후 작업 단계가 완료될 때까지 기다려야 합니다.

클라이언트가 keep-alive 를 사용하고 1초마다 요청을 보내는 시나리오를 생각해 보십시오. 업스트림 응답 시간이 100ms이고 3scale 백엔드 서버의 대기 시간이 500ms인 경우 클라이언트는 100ms마다 응답을 받습니다. 업스트림 응답과 보고 총 600ms가 소요됩니다. 다음 요청이 제공되기 전에 400ms가 추가로 제공됩니다.

아래 다이어그램은 설명된 기본 캐싱 동작을 보여줍니다. 캐싱 메커니즘의 동작은 캐싱 정책을 사용하여 변경할 수 있습니다.

기본 캐싱 동작

8.3. 비동기 보고 스레드

APIcast에는 3scale 백엔드 서버에 대해 권한을 부여하는 스레드 풀을 활성화하는 기능이 있습니다. 이 기능을 활성화하면 APIcast에서 먼저 3scale 백엔드 서버를 동시에 호출하여 매핑 규칙과 일치하는 애플리케이션 및 지표를 확인합니다. 이는 기본적으로 캐싱 메커니즘을 사용하는 경우와 유사합니다. 차이점은 풀에 사용 가능한 보고 스레드가 있는 한 3scale 백엔드 서버에 대한 후속 호출이 비동기적으로 완전히 보고된다는 점입니다.

보고 스레드는 전체 게이트웨이에 대해 전역적이며 모든 서비스 간에 공유됩니다. 두 번째 TCP 연결이 이루어지면 인증이 이미 캐시되는 한 완전히 비동기식일 수 있습니다. 사용 가능한 보고 스레드가 없으면 동기 모드는 표준 비동기 모드로 전환되고 사후 작업 단계에서 보고를 수행합니다.

APICAST_REPORTING_THREADS 환경 변수를 사용하여 이 기능을 활성화할 수 있습니다.

아래 다이어그램은 비동기 보고 스레드 풀의 작동 방식을 보여줍니다.

비동기 보고 스레드 풀 동작

8.4. 3scale Batcher 정책

기본적으로 APIcast는 수신하는 각 요청에 대해 3scale 백엔드 서버에 대해 하나의 호출을 수행합니다. 3scale Batcher 정책의 목표는 3scale 백엔드 서버에 대한 요청 수를 크게 줄여 대기 시간을 줄이고 처리량을 늘리는 것입니다. 이를 위해 이 정책은 권한 부여 상태 및 배치 보고서를 캐시합니다.

4.1.2절. “3scale Batcher” 3scale Batcher 정책에 대한 세부 정보를 제공합니다. 아래 다이어그램은 정책의 작동 방식을 보여줍니다.

3scale Batcher 정책 동작

9장. Prometheus에 3scale APIcast 지표 노출

중요

이번 3scale 릴리스에서는 Prometheus 설치 및 구성이 지원되지 않습니다. 선택적으로 Prometheus의 커뮤니티 버전을 사용하여 APIcast 관리 API 서비스에 대한 지표 및 경고를 시각화할 수 있습니다.

9.1. Prometheus 정보

Prometheus는 Red Hat OpenShift 환경에 배포된 3scale APIcast 서비스를 모니터링하는 데 사용할 수 있는 오픈소스 시스템 모니터링 툴킷입니다.

Prometheus를 사용하여 서비스를 모니터링하려면 서비스에서 Prometheus 끝점을 노출해야 합니다. 이 엔드포인트는 지표 목록과 지표의 현재 값을 표시하는 HTTP 인터페이스입니다. Prometheus는 이러한 대상 정의 엔드포인트를 주기적으로 스크랩하고 수집된 데이터를 데이터베이스에 씁니다.

9.1.1. Prometheus 쿼리

Prometheus UI에서는PromQL(Prometheus 쿼리 언어)에서 쿼리를 작성하여 지표 정보를 추출할 수 있습니다. PromQL을 사용하면 실시간으로 시계열 데이터를 선택하고 집계할 수 있습니다.

예를 들어 다음 쿼리를 사용하여 지표 이름 http_requests_total 이 있는 모든 시계열의 마지막 5분 내에 Prometheus가 기록한 모든 값을 선택할 수 있습니다.

http_requests_total[5m]

메트릭에 라벨 (키:값 쌍)을 지정하여 쿼리 결과를 추가로 정의하거나 필터링할 수 있습니다. 예를 들어 다음 쿼리를 사용하여 지표 이름 http_requests_totalintegration 로 설정된 작업 라벨이 있는 모든 시계열에 대해 Prometheus가 지난 5분 내에 기록한 모든 값을 선택할 수 있습니다.

http_requests_total{job="integration"}[5m]

쿼리 결과는 그래프로 표시되거나, Prometheus 표현식 브라우저에서 테이블 형식 데이터로 보거나, Prometheus HTTP API 를 사용하여 외부 시스템에서 사용할 수 있습니다. Prometheus는 데이터의 그래픽 보기를 제공합니다. Prometheus 지표를 볼 수 있는 보다 강력한 그래픽 대시보드의 경우 Grafana가 인기 있는 선택입니다.

PromQL 언어를 사용하여 Prometheus alertmanager 툴에서 경고를 구성할 수도 있습니다.

참고

Grafana는 커뮤니티에서 지원하는 기능입니다. Red Hat 3scale 제품 모니터링을 위해 Grafana 배포는 Red Hat 프로덕션 서비스 수준 계약(SLA)에서 지원되지 않습니다.

9.2. Prometheus와 APIcast 통합

다음 배포 옵션에는 Prometheus와 APIcast 통합을 사용할 수 있습니다.

  • 자체 관리 APIcast (호스트 또는 사내 API 관리자 모두)
  • 온프레미스 내장 APIcast
참고

Prometheus와의 APIcast 통합은 호스팅 API 관리자 및 호스팅 APIcast에서 사용할 수 없습니다.

기본적으로 Prometheus는 표 9.2. “3scale APIcast의 Prometheus 기본 지표” 에 나열된 APIcast 지표를 모니터링할 수 있습니다.

9.2.1. 추가 옵션

선택적으로 OpenShift 클러스터에 대한 클러스터 관리자 액세스 권한이 있는 경우, service_ id 및 service _ system_name 레이블을 포함하도록 total_ response_time_seconds, 업스트림_response_time_ seconds 및 업스트림_ status 지표를 확장할 수 있습니다. 이러한 지표를 확장하려면 다음 명령을 사용하여 APICAST_EXTENDED_METRICS OpenShift 환경 변수를 true 로 설정합니다.

oc set env dc/apicast APICAST_EXTENDED_METRICS=true

APIcast 배치 정책( 4.1.2절. “3scale Batcher”에 설명됨)을 사용하는 경우 Prometheus는 표 9.3. “3scale APIcast 배치 정책의 Prometheus 지표” 에 나열된 메트릭을 모니터링할 수도 있습니다.

참고

지표에 값이 없는 경우 Prometheus는 지표를 숨깁니다. 예를 들어 nginx_error_log 에 보고할 오류가 없는 경우 Prometheus는 nginx_error_log 지표를 표시하지 않습니다. nginx_error_log 지표는 값이 있는 경우에만 표시됩니다.

추가 리소스

Prometheus에 대한 자세한 내용은 Prometheus를 참조하십시오. 시작하기.

9.3. 3scale APIcast의 OpenShift 환경 변수

Prometheus 인스턴스를 구성하려면 표 9.1. “3scale APIcast의 Prometheus 환경 변수” 에 설명된 OpenShift 환경 변수를 설정할 수 있습니다.

표 9.1. 3scale APIcast의 Prometheus 환경 변수

환경 변수설명Default

APICAST_EXTENDED_METRICS

Prometheus 지표에 대한 추가 정보를 활성화하는 부울 값입니다. 다음 메트릭에는 APIcast에 대한 자세한 내용을 제공하는 service_id 및 service_system_name 라벨이 있습니다.

  • total_response_time_seconds
  • upstream_response_time_seconds
  • upstream_status

false

추가 리소스

환경 변수 설정에 대한 자세한 내용은 관련 OpenShift 가이드를 참조하십시오.

지원되는 구성에 대한 자세한 내용은 Red Hat 3scale API Management Supported Configurations(Red Hat 3scale API 관리 지원 구성 ) 페이지를 참조하십시오.

9.4. Prometheus에 노출된 3scale APIcast 지표

3scale APIcast를 모니터링하도록 Prometheus를 설정한 후 기본적으로 표 9.2. “3scale APIcast의 Prometheus 기본 지표” 에 나열된 지표를 모니터링할 수 있습니다.

표 9.3. “3scale APIcast 배치 정책의 Prometheus 지표” 에 나열된 메트릭은 4.1.2절. “3scale Batcher” 을 사용하는 경우에만 사용할 수 있습니다.

표 9.2. 3scale APIcast의 Prometheus 기본 지표

메트릭설명유형라벨

nginx_http_connections

HTTP 연결 수

게이지

state(accepted,active,handled,reading,total,waiting,writing)

nginx_error_log

APIcast 오류

카운터

level(debug,info,notice,warn,error,crit,alert,emerg)

openresty_shdict_capacity

작업자 간에 공유되는 사전의 용량

게이지

dict(모든 사전당 하나씩)

openresty_shdict_free_space

작업자 간에 공유되는 사전의 여유 공간

게이지

dict(모든 사전당 하나씩)

nginx_metric_errors_total

메트릭을 관리하는 Lua 라이브러리의 오류 수

카운터

none

total_response_time_seconds

클라이언트에 응답을 보내는 데 필요한 시간(초)

참고: service _id 및 service_ system_name 라벨에 액세스하려면 9.2절. “Prometheus와 APIcast 통합” 에 설명된 대로 APICAST_EXTENDED_METRICS 환경 변수를 true 로 설정해야 합니다.

histogram

service_id, service_system_name

upstream_response_time_seconds

업스트림 서버의 응답 시간(초 단위)

참고: service _id 및 service_ system_name 라벨에 액세스하려면 9.2절. “Prometheus와 APIcast 통합” 에 설명된 대로 APICAST_EXTENDED_METRICS 환경 변수를 true 로 설정해야 합니다.

histogram

service_id, service_system_name

upstream_status

업스트림 서버의 HTTP 상태

참고: service _id 및 service_ system_name 라벨에 액세스하려면 9.2절. “Prometheus와 APIcast 통합” 에 설명된 대로 APICAST_EXTENDED_METRICS 환경 변수를 true 로 설정해야 합니다.

카운터

status, service_id, service_system_name

threescale_backend_calls

3scale 백엔드에 대한 요청 승인 및 보고(Apisonator)

카운터

엔드 포인트(authrep,auth,report), status(2xx,4xx,5xx)

표 9.3. 3scale APIcast 배치 정책의 Prometheus 지표

메트릭설명유형라벨

batching_policy_auths_cache_hits

3scale 배치 정책의 인증 캐시에서 적중

카운터

none

batching_policy_auths_cache_misses

3scale 배치 정책의 인증 캐시의 누락

카운터

none

II 부. API 버전 관리

10장. API 버전 관리

Red Hat 3scale API Management를 통해 API 버전 관리. 3scale을 사용하여 API를 관리할 때 3가지 방법으로 API를 올바르게 버전화할 수 있습니다. 다음 방법은 3scale 게이트웨이 내에서 API를 버전화하여 3scale 아키텍처로 인한 추가 기능을 제공하는 방법에 대한 예입니다.

10.1. 목적

이 가이드는 3scale 내에서 API 버전 관리 시스템을 구현할 수 있는 충분한 정보를 제공하도록 설계되었습니다.

판도를 찾기 위한 API가 있다고 가정합니다. 사용자는 다른 키워드로 자신이 선호하는 용어를 검색할 수 있습니다. 즉, TV, 이탈리아어, 문구 제목 등 다양한 키워드를 검색할 수 있습니다. API의 초기 버전(v1)이 있다고 가정하고 이제 새로운 개선된 버전(v2)을 개발했다고 가정합니다.

다음 섹션에서는 3scale을 사용하여 API 버전 관리 시스템을 구현하는 세 가지 가장 일반적인 방법에 대해 설명합니다.

  • URL 버전 관리
  • 끝점 버전 지정
  • 사용자 정의 헤더 버전 지정

10.2. 사전 요구 사항

이 퀵 스타트 가이드를 사용하기 전에 API를 3scale에 연결하는 기본 사항을 완료합니다.

10.3. URL 버전 관리

(후크별, 영화 제목별 등) 검색에 필요한 끝점이 다르면 URL 버전 지정을 사용하면 API 버전이 URI의 일부로 포함됩니다.

  1. api.songs.com/v1/songwriter
  2. api.songs.com/v2/songwriter
  3. api.songs.com/v1/song
  4. api.songs.com/v2/song
참고

이 방법을 사용할 때는 API를 버전할 v1 이후 계획해야 합니다.

그런 다음 3scale 게이트웨이는 URI에서 엔드포인트 및 버전을 추출합니다. 이 접근 방식을 사용하면 모든 버전/엔드포인트 조합에 대한 애플리케이션 계획을 설정할 수 있습니다. 그런 다음 메트릭을 해당 계획 및 끝점과 연결할 수 있으며 각 버전의 각 끝점에 대한 사용량을 차트로 작성할 수 있습니다.

다음 화면 캡처는 3scale의 유연성을 보여줍니다.

그림 10.1. 버전 관리 계획 기능

버전 관리 계획 기능

3scale 관리 포털의 [your_API_name] > Integration > Configuration 으로 이동하여 다음 다이어그램에 표시된 대로 URI를 메트릭에 매핑합니다.

그림 10.2. 메트릭에 URI 매핑

메트릭에 URI 매핑

이제 각각 다른 기능이 활성화되어 있는 두 가지 버전의 API가 있습니다. 또한 사용량에 대한 완전한 제어 및 가시성을 확보할 수 있습니다.

API v2로 이동해야 하는 모든 사용자와 통신하려면 해당 작업을 수행하도록 내부 메모를 보낼 수 있습니다. 누가 이동했는지 모니터링하고 v2에 대한 활동이 증가하는 동안 v1에 대한 활동이 어떻게 감소하는지 확인할 수 있습니다. 3scale에 권한 부여 호출에 메트릭을 추가하면 v1과 v2 엔드포인트를 사용하는 전체 트래픽 양을 확인할 수 있으며 v1을 사용 중단하는 것이 안전한 시기를 알 수 있습니다.

그림 10.3. 버전 관리

버전 관리

일부 사용자가 v1을 계속 사용하는 경우 해당 사용자만 필터링하여 v2로 전환하는 데 대한 다른 내부 노트를 보낼 수 있습니다.

3scale은 사용 중단 알림을 전송하는 3단계 방법을 제공합니다.

  1. 대상 > 애플리케이션 > 나열 으로 이동하여 사용 중단 노트를 보내려는 애플리케이션 계획별로 목록을 필터링하고 Search (검색)를 클릭합니다.
  2. multiselector를 클릭하여 특정 버전의 모든 애플리케이션을 선택합니다. 새로운 옵션은 Send email (이메일 전송),애플리케이션 계획 변경, 상태 변경 등의 대량 작업을 수행할 수 있도록 합니다.
  3. Send email (이메일 전송)을 클릭하고 단계에 따라 선택한 애플리케이션 소유자에게 사용 중단 알림을 보냅니다.

다음 이미지는 시각적 참조를 제공합니다.

그림 10.4. 폐기 노트 보내기

폐기 노트 보내기

엔드포인트에 만들어진 각 authrep 호출에 대해 한 번만 인증하지만 엔드포인트에 대해 한 번(한 번 보고) API 버전에 대해 한 번 보고합니다. 호출은 한 번만 인증될 수 있으므로 이중화는 없습니다. 특정 API 버전의 엔드포인트를 만들 때마다 버전 번호(v1, v2 등) 뒤에 이름이 지정된 편리한 지표에 대한 조회를 집계합니다. 이 지표에서는 를 사용하여 전체 버전 트래픽을 서로 비교할 수 있습니다.

10.4. 끝점 버전 지정

엔드포인트 버전을 사용하면 api.cons.com/author_v1 과 같은 각 API 버전에 대해 다른 끝점을 가질 수 있습니다. 게이트웨이는 엔드포인트 자체에서 엔드포인트 및 버전을 추출합니다. 이 방법 및 이전 메서드를 사용하면 API 프로바이더가 외부 URL을 내부 URL에 매핑할 수 있습니다.

엔드포인트 버전 관리 방법은 온프레미스 구성의 일부로 제공되는 LUA 스크립트를 사용하여 URL을 다시 작성해야 하므로 온프레미스 배포 방법을 사용해서만 수행할 수 있습니다.

EXTERNAL

 

내부

api.songs.com/songwriter_v1

다음과 같이 다시 작성할 수 있습니다

internal.songs.com/search_by_songwriter

api.songs.com/songwriter_v2

다음과 같이 다시 작성할 수 있습니다

internal.songs.com/songwriter

거의 모든 사항(매핑, 애플리케이션 계획 기능 등)은 이전 방법과 정확히 동일합니다.

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. 지원되는 인증 패턴

3scale은 다음 인증 패턴을 즉시 지원합니다.

  • 표준 API 키: 식별자 및 시크릿 토큰 역할을 하는 단일 임의 문자열 또는 해시.
  • 애플리케이션 식별자 및 키 쌍: 변경할 수 없는 식별자 및 변경 가능한 시크릿 키 문자열.
  • OpenID Connect

11.2. 인증 패턴 설정

11.2.1. 서비스에 대한 인증 모드를 선택합니다

작업하려는 API 서비스로 이동합니다(이 경우 API라는 서비스만 있을 수 있습니다). Integration (통합) 섹션으로 이동합니다.

인증 모드 1 단계 선택

운영하는 각 서비스는 다른 인증 패턴을 사용할 수 있지만 서비스당 하나의 패턴만 사용할 수 있습니다.

중요

자격 증명을 등록한 후에는 인증 패턴을 변경하지 않아야 합니다. 그러면 서비스 동작을 예측할 수 없기 때문입니다. 인증 패턴을 변경하려면 새 서비스를 생성하고 고객을 마이그레이션하는 것이 좋습니다.

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를 사용할 자격 증명을 발행할 수 있습니다. 관리 포털 대시보드의 Accounts(계정) 영역으로 이동하여 사용할 계정을 클릭한 다음 새 애플리케이션을 클릭합니다.

양식을 작성하고 저장을 클릭하면 API를 사용할 자격 증명이 포함된 새 애플리케이션이 생성됩니다. 이제 이러한 자격 증명을 사용하여 API에 대한 호출을 수행할 수 있으며 3scale에 등록된 애플리케이션 목록에 대해 레코드를 확인할 수 있습니다.

11.3. 표준 인증 패턴

3scale은 다음 섹션에 설명된 인증 패턴을 지원합니다.

11.3.1. API 키

지원되는 가장 간단한 형태의 인증 정보는 단일 API 모델입니다. 여기에서 API에 대한 권한이 있는 각 애플리케이션에는 단일(별크) 긴 문자열이 있습니다. 예:

API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13

기본적으로 key 매개 변수의 이름은 user_key 입니다. 이 레이블을 사용하거나 API-key 와 같은 다른 레이블을 선택할 수 있습니다. 다른 레이블을 선택하는 경우 3scale에 권한 부여 호출을 수행하기 전에 값을 매핑해야 합니다. 문자열은 API를 사용하기 위한 식별자와 비밀 토큰 둘 다의 역할을 합니다. 보안 요구 사항이 낮은 환경에서 또는 API 호출 시 SSL 보안을 사용하는 환경에서만 이러한 패턴을 사용하는 것이 좋습니다. 다음은 토큰 및 애플리케이션에서 수행할 수 있는 작업입니다.

  • 애플리케이션 일시 중단: 그러면 API에 대한 애플리케이션 액세스 권한이 일시 중지되고, 실제로 관련 키가 있는 API에 대한 모든 호출이 일시 중단됩니다.
  • 응용 프로그램 재개: 애플리케이션 일시 중지 작업의 영향을 실행 취소합니다.
  • 키 재생성: 이 작업은 애플리케이션에 대한 새 임의 문자열 키를 생성하고 애플리케이션과 연결합니다. 이 조치를 수행한 직후 이전 토큰이 있는 호출은 허용되지 않습니다.

두 번째 작업은 관리 포털의 API 관리 및 API Developers 사용자 콘솔에서 트리거할 수 있습니다.

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

기본 설정에서 개발자는 애플리케이션당 최대 5개의 키를 만들 수 있습니다. 이를 통해 개발자는 새 키를 만들고 코드를 추가한 다음 애플리케이션을 다시 배포한 다음 이전 키를 비활성화할 수 있습니다. 이로 인해 API 키 재생성으로 인해 애플리케이션 다운 타임이 발생하지 않습니다.

통계 및 속도 제한은 API 키가 아닌 단위의 애플리케이션 ID 수준으로 항상 유지됩니다. 개발자가 두 세트의 통계를 추적하려는 경우 두 개의 키가 아닌 두 개의 애플리케이션을 생성해야 합니다.

시스템에서 모드를 변경하고 애플리케이션 키가 없으면 애플리케이션을 만들 수도 있습니다. 이 경우 3scale 시스템은 App ID만 기반으로 액세스를 인증합니다(키 검사는 수행되지 않음). 이 모드는 위젯 유형 시나리오 또는 애플리케이션 대신 속도 제한이 적용되는 위치에 유용합니다. 대부분의 경우 API가 존재하는 애플리케이션당 하나 이상의 애플리케이션 키가 있는지 적용하려고 합니다. 이 설정은 [your_API_name] > 통합 > 설정에서 사용할 수 있습니다.

11.3.3. OpenID Connect

OpenID Connect 인증에 대한 자세한 내용은 OpenID Connect 통합 장을 참조하십시오.

11.4. 참조 필터링

3scale은 애플리케이션이 API에 액세스할 수 있는 IP 주소 또는 도메인 이름을 허용 목록에 추가하는 데 사용할 수 있는 참조 필터링 기능을 지원합니다. API 클라이언트는 Referrer 헤더에 referrer 값을 지정합니다. Referrer 헤더의 목적 및 사용법은 RFC 7231, 섹션 5.5.2:에 설명되어 있습니다. referer.

Referrer 필터링 기능이 작동하려면 서비스 정책 체인에서 APIcast Referrer 정책을 활성화해야 합니다.

Referrer 필터링 기능을 사용하려면 [your_API_name] > 애플리케이션 > 설정 > 사용 규칙으로 이동합니다. Require referrer 필터링 을 선택하고 Update Product(제품 업데이트 )를 클릭합니다.

권장자 필터링 활성화

API에 액세스할 수 있는 개발자는 개발자 포털에서 허용된 도메인/IP 참조자를 구성해야 합니다.

개발자 포털에서 참조 설정

이 서비스에 속하는 모든 애플리케이션의 애플리케이션 세부 정보 페이지의 관리 포털에는 새 참조 필터 섹션이 표시됩니다. 여기에서 관리자는 이 애플리케이션에 허용된 Referrer 헤더 값의 허용 목록을 구성할 수도 있습니다.

개발자 포털에서 참조 설정

애플리케이션당 최대 5개의 참조 값을 설정할 수 있습니다.

값은 라틴어, 숫자 및 특수 문자 *, ., -. * 만 와일드카드 값에 사용할 수 있습니다. 값이 * 로 설정되면 모든 참조 값이 허용되므로 참조자 검사는 무시됩니다.

Require referrer 필터링 기능과 3scale Referrer 정책이 활성화되면 인증이 다음과 같이 작동합니다.

  1. Referrer 필터가 지정되지 않은 애플리케이션에는 일반적으로 제공된 자격 증명을 사용하는 경우에만 인증됩니다.
  2. Referrer Filters 값이 설정된 애플리케이션의 경우 APIcast는 요청의 참조 헤더 에서 참조 값을 추출하고 AuthRep(인증 및 보고) 요청 의 참조 매개 변수로 Service Management API로 보냅니다. 다음 표는 참조자 필터링 매개 변수의 다양한 조합에 대한 AuthRep 응답을 보여줍니다.
referrer 매개변수가 전달되었습니까?앱에 대해 구성된 참조 필터는 무엇입니까?referrer 매개변수 값HTTP 응답응답 본문

있음

있음

참조 필터 일치

200 OK

<status><authorized>true</authorized></status>

있음

없음

참조 필터 일치

200 OK

<status><authorized>true</authorized></status>

있음

있음

referrer 필터와 일치하지 않습니다

409 충돌

<status><authorized>false</authorized><reason>referrer "test.example.com"은</reason>을 사용할 수 없습니다 (test.example.com 은 예입니다.)

있음

없음

referrer 필터와 일치하지 않습니다

200 OK

<status><authorized>true</authorized></status>

있음

있음

*

200 OK

<status><authorized>true</authorized></status>

있음

없음

*

200 OK

<status><authorized>true</authorized></status>

없음

있음

 — 

409 충돌

<status><authorized>false</authorized><reason>referrer이 누락된</reason>

없음

없음

 — 

200 OK

<status><authorized>true</authorized></status>

AuthRep에서 승인되지 않은 호출은 "Authorization Failed" 오류와 함께 APIcast에서 거부합니다. service Integration(서비스 통합) 페이지에서 정확한 상태 코드 및 오류 메시지를 구성할 수 있습니다.

12장. OpenID Connect 통합

3scale은 다음 기능과 함께 OpenID Connect 사양을 사용하여 API 요청을 인증하기 위해 타사 IdM(Identity Providers)과 통합됩니다.

  • OpenID Connect는 OAuth 2.0 인증 프레임워크를 인증 메커니즘으로 보완하는 OAuth 2.0을 기반으로 합니다.
  • OpenID Connect 인증 옵션을 사용하면 JST(JSON 웹 토큰) 형식의 액세스 토큰을 사용하여 API 요청이 인증됩니다(RF7519).

통합은 다음 두 부분으로 구성됩니다.

Red Hat 3scale API Management는 OpenID 공급자 역할을 하는 RH -SSO(Red Hat Single Sign-On )와의 통합 지점을 모두 지원합니다. 지원되는 구성 페이지에서 지원되는 RH-SSO 버전을 참조하십시오. APIcast 통합은 ForgeRock 에서도 테스트됩니다.

두 경우 모두 OpenID Connect 인증 옵션을 사용하여 서비스의 통합 페이지에 있는 APIcast Configuration에 OpenID Connect Issuer 필드를 지정하여 통합을 구성할 수 있습니다. 자세한 내용은 Configure Red Hat Single Sign-On integration에서 참조하십시오.

12.1. JWT 확인 및 APIcast의 구문 분석

OpenID Connect 인증 모드를 사용하여 서비스에 대한 API 요청은 OpenID 공급자가 발행한 JWT 형식으로 Bearer 스키마를 사용하여 인증 헤더에 액세스 토큰을 제공해야 합니다. 헤더는 다음 예와 같이 표시되어야 합니다.

Authorization: Bearer <JWK>

예제:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbSIsInN1YiI6ImFiYzEyMyIsIm5iZiI6MTUzNzg5MjQ5NCwiZXhwIjoxNTM3ODk2MDk0LCJpYXQiOjE1Mzc4OTI0OTQsImp0aSI6ImlkMTIzNDU2IiwidHlwIjoiQmVhcmVyIn0.LM2PSmQ0k8mR7eDS_Z8iRdGta-Ea-pJRrf4C6bAiKz-Nzhxpm7fF7oV3BOipFmimwkQ_-mw3kN--oOc3vU1RE4FTCQGbzO1SAWHOZqG5ZUx5ugaASY-hUHIohy6PC7dQl0e2NlAeqqg4MuZtEwrpESJW-VnGdljrAS0HsXzd6nENM0Z_ofo4ZdTKvIKsk2KrdyVBOcjgVjYongtppR0cw30FwnpqfeCkuATeINN5OKHXOibRA24pQyIF1s81nnmxLnjnVbu24SFE34aMGRXYzs4icMI8sK65eKxbvwV3PIG3mM0C4ilZPO26doP0YrLfVwFcqEirmENUAcHXz7NuvA

JWT 토큰에는 토큰 수신자가 알려진 발행자가 토큰을 확인하고 서명했는지 그리고 해당 콘텐츠가 변경되지 않았는지 확인할 수 있는 서명이 포함되어 있습니다. 3scale은 공개/개인 키 쌍을 기반으로 RSA 서명을 지원합니다. 여기서 발행자는 개인 키를 사용하여 JWT 토큰에 서명합니다. APIcast는 공개 키를 사용하여 이 토큰을 확인합니다.

APIcast는 JWT 서명을 확인하는 데 사용할 수 있는JWK(JSON 웹 키)를 가져오기 위해 OpenID Connect Discovery 를 사용합니다.

각 요청에서 APIcast는 다음을 수행합니다.

  1. 공개 키를 사용하여 JWT 토큰을 확인합니다.
  2. 클레임 nbfexp의 유효성을 검사합니다.
  3. 클레임에 지정된 발행자가 OpenID Connect 발급자 필드에 구성된 것과 같은지 확인합니다.
  4. azp 또는 a ud 클레임 값을 추출하고 3scale에서 애플리케이션을 식별하는 클라이언트 ID로 사용하여 서비스 관리 API를 통해 호출을 인증합니다.

JWT 검증 또는 권한 부여 확인에 실패하는 경우 APIcast는 "Authenication failed" 오류를 반환합니다. 그렇지 않으면 APIcast에서 API 백엔드에 대한 요청을 프록시합니다. Authorization 헤더는 요청에 남아 있으므로 API 백엔드는 JWT 토큰을 사용하여 사용자 및 클라이언트 ID를 확인할 수 있습니다.

12.2. zync-que를 통한 클라이언트 인증 정보 동기화

3scale은 zync-que 구성 요소를 사용할 때 3scale과 RH-SSO 서버 간에 클라이언트(애플리케이션) 자격 증명을 동기화합니다. OpenID Connect 발급자 설정을 통해 이를 구성합니다.

OpenID Connect를 사용하도록 구성된 서비스를 생성, 업데이트 또는 삭제하면 zync-que 가 해당 이벤트를 수신하고 RH-SSO API를 사용하여 RH-SSO 인스턴스에 변경 사항을 전달합니다.

Red Hat Single Sign-On 통합 구성 섹션에서는 zync-que에 RH- SSO API를 사용하기 위한 올바른 자격 증명이 있는지 확인하는 데 필요한 단계를 제공합니다.

12.3. Red Hat Single Sign-On 통합 설정

다음 절차에서는 사용자 정의 CA 인증서를 사용하도록 zync-que 를 구성하는 방법을 안내합니다.

12.3.1. 사용자 정의 CA 인증서를 사용하도록 zync-que 구성

사전 요구 사항

  • RH-SSO over https 를 제공하고 zync-que 를 통해 도달할 수 있어야 합니다. 이 유형을 테스트하려면 다음을 수행합니다.

    curl https://rhsso-fqdn
  • 3scale 2.2 이상에서는 SSL_CERT_FILE 환경 변수를 사용하여 RH-SSO에 대한 사용자 지정 CA 인증서를 지원합니다. 이 변수는 인증서 번들의 로컬 경로를 가리킵니다.
참고
  • 일부 버전의 OpenSSL accept -showcerts 대신 showcerts. 사용 중인 버전에 따라 다음 명령을 수정합니다.
  • 아래 절차 중 1단계에 있는 명령은 <rhsso_fqdn> 을 나타냅니다. FQDN(전체화된 도메인 이름)은 사람이 읽을 수 있는 도메인 이름입니다(예: host.example.com ).

절차

  1. 다음 명령을 실행하여 적절한 인증서 체인을 가져옵니다.

    echo -n | openssl s_client -connect <rhsso_fqdn>:<rhsso_port> -servername <rhsso_fqdn> --showcerts | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > customCA.pem
  2. 다음 cURL 명령을 사용하여 새 인증서를 확인합니다. 예상되는 응답은 영역의 JSON 구성입니다. 검증에 실패하면 인증서가 올바르지 않을 수 있음을 나타냅니다.

    curl -v https://<secure-sso-host>/auth/realms/master --cacert customCA.pem
  3. 인증서 번들을 Zync Pod에 추가합니다.

    1. Zync 포드에서 /etc/pki/tls/cert.pem 파일의 기존 콘텐츠를 수집합니다. 다음을 실행합니다.

      oc exec <zync-que-pod-id> cat /etc/pki/tls/cert.pem > zync.pem
    2. 사용자 정의 CA 인증서 파일의 내용을 zync.pem에 추가합니다.

      cat customCA.pem >> zync.pem
    3. 새 파일을 Zync Pod에 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"}]}}'
  4. 배포 후 인증서가 연결되고 콘텐츠가 올바른지 확인합니다.

    oc exec <zync-pod-id> cat /etc/pki/tls/zync/zync.pem
  5. 새 CA 인증서 번들을 가리키도록 Zync에서 SSL_CERT_FILE 환경 변수를 구성합니다.

    oc set env dc/zync-que SSL_CERT_FILE=/etc/pki/tls/zync/zync.pem

12.3.2. Red Hat Single Sign-On 설정

RH-SSO를 구성하려면 다음 단계를 수행합니다.

  1. 영역(<REALM_NAME>)을 생성합니다.
  2. 클라이언트를 생성합니다.

    1. 클라이언트 ID를 지정합니다.
    2. Client Protocol(클라이언트 프로토콜 ) 필드에서 openid-connect 를 선택합니다.
  3. 클라이언트 권한을 구성하려면 다음 값을 설정합니다.

    1. 기밀 액세스 유형.
    2. 할인된 표준 흐름 .
    3. OFF ( 직접 액세스 권한)가 활성화됨.
    4. ON 으로 활성화되는 서비스 계정.
  4. 클라이언트에 대한 서비스 계정 역할을 설정합니다.

    1. 클라이언트의 Service Account Roles(서비스 계정 역할 ) 탭으로 이동합니다.
    2. Client Roles(클라이언트 역할 ) 드롭다운 목록에서 realm-management 를 클릭합니다.
    3. Available Roles(사용 가능한 역할 ) 창에서 manage-clients (관리자) 목록 항목을 선택하고 Add selectedœ(선택한 항목 추가)를 클릭하여 역할을 할당합니다.
  5. 클라이언트 인증 정보를 확인합니다.

    1. 클라이언트 ID(<CLIENT_ID>)를 기록합니다.
    2. 클라이언트의 Credentials(자격 증명 ) 탭으로 이동하여 Secret (시크릿) 필드(<CLIENT_SECRET>)를 기록합니다.
  6. 영역에 사용자를 추가합니다.

    1. 창의 왼쪽에 있는 Users(사용자 ) 메뉴를 클릭합니다.
    2. Add user (사용자 추가)를 클릭합니다.
    3. 사용자 이름을 입력하고 Email Verified (이메일 확인) 스위치를 ON (켜짐)으로 설정한 다음 Save(저장 )를 클릭합니다.
    4. Credentials(자격 증명 ) 탭에서 암호를 설정합니다. 두 필드에 암호를 입력하고 임시 스위치를 OFF (꺼짐)로 설정하여 다음 로그인 시 암호가 재설정되지 않도록 하고 Reset Password(암호 재설정 )를 클릭합니다.
    5. 팝업 창이 표시되면 Change password(암호 변경 )를 클릭합니다.

12.3.3. 3scale 설정

RH-SSO에서 클라이언트를 생성하고 구성한 후에는 RH-SSO에서 작동하도록 3scale을 구성해야 합니다.

3scale을 구성하려면 다음 단계를 수행합니다.

  1. OpenID Connect 활성화.

    1. OpenID Connect 인증을 활성화하려는 서비스를 선택하고 [your_product_name] > Integration > Settings 로 이동합니다.
    2. 인증 옵션에서 OAuth 2.0 흐름에 대해 OpenID Connect Use OpenID Connect를 선택합니다.
  2. APIcast 구성을 편집합니다. OpenID Connect 옵션을 선택하면 새 섹션 OpenID Connect (OIDC) Basics:

    1. OpenID Connect 발급자 유형을 선택합니다.
    2. OpenID Connect 발급자 필드를 지정하고 다음 URL 템플릿에 표시된 대로 Red Hat Single Sign-On 서버의 URL을 사용하여 이전에 명시된 클라이언트 인증 정보를 입력합니다(호스트 <RHSSO_HOST&gt ; 및 포트 <RHSSO_PORT> 에 있음).

      https://<CLIENT_ID>:<CLIENT_SECRET>@<RHSSO_HOST>:<RHSSO_PORT>/auth/realms/<REALM_NAME>
    3. 구성을 저장하려면 Update Product(제품 업데이트 )를 클릭합니다.

12.4. 타사 ID 공급자와 HTTP 통합 구성

OIDC(OpenID Connect)의 HTTP 통합을 구성하여 타사 ID 공급자(IdP)와의 자격 증명을 쉽게 동기화할 수 있습니다. 즉, 제공하는 OpenAPI 사양을 구현하여 RH-SSO 이외의 다른 IdP를 통합할 수 있습니다.

12.4.1. 사전 요구 사항

  • 3scale설정에 표시된 대로 OIDC를 인증 모드로 활성화합니다.
  • zync
  • 선택한 IdP와 3scale 간의 클라이언트 동기화를 위해 Zync와 통합

12.4.2. 절차

타사 ID 공급자와 OIDC의 HTTP 통합을 구성하려면 관리 포털에서 다음 단계를 따르십시오.

  1. [your_product_name] > 통합 > 설정으로 이동합니다.
  2. Under AUTHENTICATION, OAuth 2.0 흐름에 대해 OpenID Connect Use OpenID Connect를 선택합니다.
  3. Under AUTHENTICATION SETTINGSOpenID Connect (OIDC) 기본사항을 나타냅니다.

    1. OpenID Connect 발급자 유형에서 OpenID 공급자의 유형을 지정합니다.
    2. OpenID Connect 발급자 에서 OpenID 공급자의 위치를 지정합니다.
  4. 변경 사항을 저장하려면 Update Product(제품 업데이트 )를 클릭합니다.

12.4.3. zync REST API 예

이 예제 프로젝트는 Zync REST API 프로토콜을 구현하여 OAuth2.0 클라이언트를 동기화합니다. 3scale 애플리케이션이 생성되면 업데이트 또는 삭제된 Zync가 해당 변경 사항을 복제하려고 시도합니다.

12.4.3.1. 사전 요구 사항

3scale을 사용하도록 구성해야 합니다.

  • 인증 모드로 OIDC
  • OpenID Connect 발급자 유형으로 REST API
  • http://id:/API as OpenID Connect Issuer

12.4.3.2. 클라이언트 생성, 업데이트 및 삭제

zync는 다음 요청을 통해 클라이언트를 생성, 업데이트 또는 삭제합니다.

  • 생성 및 업데이트 → PUT /clients/:client_id
  • 삭제 → DELETE /clients/:client_id

모든 엔드포인트는 2xx 상태 코드로 응답해야 합니다. 그렇지 않으면 3scale에서 요청을 재시도합니다.

12.4.3.3. 페이로드

생성 및 업데이트의 경우 요청 페이로드는 application/json 입니다.

{
  "client_id": "ee305610",
  "client_secret": "ac0e42db426b4377096c6590e2b06aed",
  "client_name": "oidc-app",
  "redirect_uris": ["http://example.com"],
  "grant_types": ["client_credentials", "password"]
}

클라이언트 삭제 요청에는 페이로드가 없습니다.

12.4.3.4. OAuth2 인증 사용

zync는 GET 요청을 /.well-known/openid-configuration 엔드포인트로 전송하고 애플리케이션/json 응답이 필요합니다. 응답 페이로드에는 다음이 포함되어야 합니다.

{
  "token_endpoint": "http://idp.example.com/auth/realm/token"
}

OAuth2 프로토콜에서 Zync는 token_endpoint 를 사용하여 액세스 토큰을 요청하기 위해 OpenID Connect 발급자 주소에 제공된 client_ id 및 client_secret 을 교환합니다. API가 실패한 응답으로 응답하는 경우 Zync는 제공된 자격 증명을 사용하여 HTTP Basic/Digest 인증으로 대체합니다.

12.5. OAuth 2.0 지원 흐름

API 클라이언트는 이 OpenID 공급자가 지원하는 OAuth 2.0 흐름을 사용하여 3scale에 구성된 OpenID Connect(OIDC) 발행자로부터 액세스 토큰을 가져와야 합니다. RH-SSO의 경우 다음과 같은 흐름이 지원됩니다(RH-SSO 클라이언트에서 사용되는 용어는 괄호로 지정됨).

  • 권한 부여 코드(표준 흐름)
  • 리소스 소유자 암호 자격 증명 (직접 액세스 권한 부여 흐름)
  • 암시적 (implicit Flow)
  • 클라이언트 자격 증명 (서비스 계정 흐름)

3scale에서 OIDC 인증이 활성화된 클라이언트를 생성하는 경우 RH-SSO에서 Zync에서 생성한 해당 클라이언트에는 인증 코드 흐름만 활성화됩니다. 이 흐름은 대부분의 사례에 가장 안전하고 적합한 것으로 권장됩니다. 그러나 다른 흐름을 활성화할 수 있습니다.

12.5.1. OAuth 2.0 지원 흐름 작동 방식

클라이언트는 권한 부여 요청 또는 토큰 요청 또는 둘 다를 사용하여 액세스 토큰을 가져옵니다. 이러한 요청을 수신하는 URL은 그에 따라 "authorization_endpoint" 및 "token_endpoint" 에서 OpenID 공급자의 .well-known/openid-configuration 엔드포인트를 사용하여 검색할 수 있습니다. 예: https://<RHSSO_HOST>:<RHSSO_PORT>/auth/realms/<REALM_NAME>/.well-known/openid-configuration.

12.5.2. OAuth 2.0 지원 흐름 구성

관리 포털에서 3scale API에 허용된 OAuth 2.0 흐름을 구성할 수 있습니다. 새 애플리케이션을 생성하면 OIDC(OpenId Connect) 구성을 포함하여 기본 통합이 완료됩니다.

OAuth 2.0 지원 흐름을 구성하려면 다음 단계를 수행하십시오.

  1. 인증 설정 섹션으로 이동합니다. [your_product_name] > 통합 > 설정
  2. Under AUTHENTICATION 에서 OAuth 2.0 흐름에 대해 OpenID Connect Use OpenID Connect 를 선택합니다. 해당 흐름이 활성화됩니다.

    • standardFlowEnabled (Authorization Code flow) [기본적으로 선택]
    • 암시적FlowEnabled (Implicit flow)
    • ServiceAccountsEnabled (서비스 계정 흐름)
    • directAccessGrantsEnabled (Direct Access grant Flow)
  3. 하나 또는 여러 개의 흐름을 선택합니다.
  4. 변경 사항을 저장하려면 Update Product(제품 업데이트 )를 클릭합니다.

12.6. 통합을 테스트합니다

통합을 테스트하려면 다음 섹션에 나열된 단계를 수행해야 합니다.

12.6.1. 클라이언트 동기화 테스트

클라이언트 동기화를 테스트하려면 다음 단계를 수행합니다.

  1. OpenID Connect 통합을 구성한 서비스에 대한 애플리케이션을 생성합니다.
  2. 생성된 애플리케이션의 클라이언트 ID 및 클라이언트 시크릿을 기록해 둡니다.
  3. 구성된 RH-SSO 영역에 동일한 클라이언트 ID 및 클라이언트 보안이 있는지 확인합니다.
  4. 3scale 관리 포털에서 애플리케이션의 리디렉션 URL을 업데이트합니다. 리디렉션 URL 은 가능한 구체적으로 지정해야 합니다.
  5. RH-SSO에서 클라이언트의 유효한 리디렉션 URI 필드 가 그에 따라 업데이트되었는지 확인합니다.

12.6.2. API 인증 흐름 테스트

API 권한 부여 흐름을 테스트하려면 다음 단계를 수행합니다.

  1. 해당 RH-SSO 클라이언트에서 활성화된 OAuth 2.0 흐름을 사용하여 RH-SSO 서버에서 액세스 토큰을 가져옵니다.
  2. 다음과 같이 인증 헤더에서 RH-SSO에서 검색된 access_token 의 값을 사용합니다. 권한 부여: 전달자 <access_token>

토큰이 올바르고 3scale의 해당 애플리케이션이 인증되면 APIcast 게이트웨이에서 3scale 백엔드의 응답을 반환합니다.

12.7. 통합의 예

3scale의 "API" 서비스는 OpenID Connect 인증을 사용하도록 구성되어 있습니다. "API" 서비스의 공개 기반 URLhttps://api.example.com 로 구성되고 개인 기본 URLhttps://internal-api.example.com 로 구성됩니다.

API 통합에서 OpenID Connect 발급자 필드가 https://zync:/auth/realms/myrealm 으로 설정되고 영역의 클라이언트 zync올바른 서비스 계정 역할이 있습니다.

3scale에는 myclientid 클라이언트 ID, my clientsecret 클라이언트 비밀 및 https://myapp.example.com 리디렉션 URL이 있는 애플리케이션이 있습니다.

RH-SSO에서는 myrealm 영역에서 다음 값이 있는 클라이언트도 있습니다.

  • 클라이언트 ID: myclientid
  • secret: myclientsecret
  • 유효한 리디렉션 URI : https://myapp.example.com

이 클라이언트의 경우 Standard Flow가 활성화됩니다.

myrealm 영역에 myuser username 및 my password 암호가 있는 사용자가 구성되어 있습니다.

흐름은 다음과 같습니다.

  1. 엔드포인트 https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/auth 를 사용하여 애플리케이션에서 권한 부여 요청을 RH-SSO로 보냅니다. 요청 내에서 애플리케이션은 myclientid 클라이언트 ID 및 https://myapp.example.com 리디렉션 URL의 매개 변수를 제공합니다.
  2. RH-SSO는 사용자가 사용자의 자격 증명을 제공해야 하는 로그인 창을 표시합니다. 사용자 이름 myuser 및 암호 mypassword.
  3. 구성에 따라 사용자가 이 특정 애플리케이션에서 처음으로 인증하는 경우 동의 창이 표시됩니다.
  4. 사용자가 인증되면 승인에서 끝점 https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/token 을 사용하여 토큰 요청을 RH-SSO에 전송하고 클라이언트 ID myclientid, 클라이언트 시크릿 my clientsecret 및 리디렉션 URL https://myapp.example.com 을 제공합니다.
  5. RH-SSO는 "access_token" 필드 eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…가 있는 JSON을 반환합니다.xBArNhqF-A.
  6. 애플리케이션은 헤더 인증을 사용하여 https://api.example.com 로 API 요청을 보냅니다. Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…​xBArNhqF-A.
  7. 이 애플리케이션에는 https://internal-api.example.com 로부터 성공적인 응답을 수신해야 합니다.