4장. APIcast 정책

4.1.1. 3scale 관리 포털에서 정책 활성화
링크 복사

관리 포털에서 3scale API 제품에 대해 하나 이상의 정책을 활성화할 수 있습니다.

사전 요구 사항

3scale API 제품

절차

3scale에 로그인합니다.
Admin Portal(관리 포털) 대시보드에서 정책을 활성화할 API 제품을 선택합니다.
[your_product_name] 에서 Integration > Policies 로 이동합니다.
POLICIES (정책) 섹션에서 Add policy(정책 추가 )를 클릭합니다.
추가할 정책을 선택하고 필수 필드에 값을 입력합니다.
Update Policy chain(정책 체인 업데이트)을 클릭하여 정책 체인을 저장합니다.

4.1.2. 3scale Auth Caching
링크 복사

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

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

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

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

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

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

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

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

중요

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

4. none - 캐싱 비활성화.

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

구성 속성

Expand

속성	description	값	필수 여부
caching_type	`caching_type` 속성을 사용하면 캐시가 작동할 모드를 정의할 수 있습니다.	데이터 유형: 열거된 문자열 [resilient, strict, allow, none]	제공됨

정책 오브젝트 예

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

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

Copy to Clipboard

Toggle word wrap

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

4.1.3. 3scale Batcher
링크 복사

3scale Batcher 정책은 표준 APIcast 인증 메커니즘에 대한 대안을 제공하며, APIcast가 수신하는 각 API 요청에 대해 3scale 백엔드(Service Management API)에 대한 하나의 호출이 수행됩니다.

중요

이 정책을 사용하려면 정책 체인의 3scale APIcast 정책 앞에 3scale Batcher 를 배치해야 합니다.

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

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

각 요청에서 정책은 인증 정보가 캐시되는지 여부를 확인합니다.
- 자격 증명이 캐시되면 정책은 3scale 백엔드를 호출하는 대신 캐시된 권한 부여 상태를 사용합니다.
- 인증 정보가 캐시되지 않은 경우 정책은 백엔드를 호출하고 구성 가능한 TTL(Time to Live)을 사용하여 권한 부여 상태를 캐시합니다.
3scale 백엔드에 대한 요청에 해당하는 사용량을 즉시 보고하는 대신 정책에 따라 사용 카운터가 누적되어 배치의 백엔드에 보고합니다. 별도의 스레드가 구성 가능한 빈도를 사용하여 누적 사용 카운터를 3scale 백엔드에 보고합니다.

3scale Batcher 정책은 처리량을 개선하지만 정확성은 낮습니다. 사용 제한 및 현재 사용률은 3scale에 저장되며, APIcast는 3scale 백엔드에 호출할 때만 올바른 인증 상태를 가져올 수 있습니다. 3scale Batcher 정책이 활성화되면 APIcast가 3scale에 호출을 전송하지 않는 기간이 있습니다. 이 시간 동안 호출을 수행하는 애플리케이션은 정의된 제한 사항을 넘을 수 있습니다.

속도 제한의 정확성보다 처리량이 더 중요한 경우 이 정책을 로드 API에 사용합니다. 3scale Batcher 정책은 보고 빈도 및 권한 부여 TTL이 속도 제한 기간보다 훨씬 적은 경우 정확성 측면에서 더 나은 결과를 제공합니다. 예를 들어 제한이 일당이고 보고 빈도 및 권한 부여 TTL이 몇 분으로 구성된 경우.

3scale Batcher 정책은 다음과 같은 구성 설정을 지원합니다.

auths_ttl: 권한 부여 캐시가 만료될 때 TTL(초)을 설정합니다.
- 현재 호출에 대한 인증이 캐시되면 APIcast는 캐시된 값을 사용합니다. auths_ttl 매개변수에 시간 설정이 완료되면 APIcast가 캐시를 제거하고 3scale 백엔드를 호출하여 권한 부여 상태를 검색합니다.
- auths_ttl 매개 변수를 0 이 아닌 값으로 설정합니다. auths_ttl 을 값 0 으로 설정하면 요청이 캐시될 때 권한 부여 카운터가 업데이트되어 속도 제한이 적용되지 않습니다.
batch_report_seconds: 배치 보고서 APIcast가 3scale 백엔드에 전송하는 빈도를 설정합니다. 기본값은 10 초입니다.

4.1.4. 3scale Referrer
링크 복사

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

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

4.1.5. 익명 액세스
링크 복사

익명 액세스 정책은 인증 없이 서비스를 노출합니다. 예를 들어 인증 매개 변수를 보내도록 조정할 수 없는 레거시 애플리케이션에 유용할 수 있습니다. 익명 액세스 정책은 API 키 및 앱 Id / 앱 키 인증 옵션만 사용하여 서비스를 지원합니다. 정책이 제공된 자격 증명이 없는 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.6. Camel 서비스
링크 복사

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

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

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

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

참고

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

설정

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

"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/"
      }
    }
]

"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/"
      }
    }
]

Copy to Clipboard

Toggle word wrap

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

사용 사례 예

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

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

프로젝트 예

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

4.1.7. 조건 정책
링크 복사

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

중요

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

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

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

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

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

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

Copy to Clipboard

Toggle word wrap

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

APIcast
캐싱
헤더
URL 다시 작성
업스트림

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

APIcast
캐싱
업스트림

조건

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

이 예에서는 요청 경로가 /example_path 인지 확인합니다.

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

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

Copy to Clipboard

Toggle word wrap

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

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

{
  "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"
}

{
  "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"
}

Copy to Clipboard

Toggle word wrap

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

유동에서 지원되는 변수

uri
호스트
remote_addr
헤더['Header-Header']

업데이트된 변수 목록은 다음에서 확인할 수 있습니다. ngx_variable.lua

이 예제에서는 요청의 백엔드 헤더가 staging 인 경우 업스트림 정책을 실행합니다.

{
   "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"
                  }
               ]
            }
         }
      ]
   }
}

{
   "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"
                  }
               ]
            }
         }
      ]
   }
}

Copy to Clipboard

Toggle word wrap

4.1.8. 컨텐츠 캐싱
링크 복사

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

콘텐츠 캐싱 정책이 정책 체인에 있을 때 APIcast는 요청 업스트림을 보내기 전에 HEAD 요청을 GET 요청으로 변환합니다. 이 변환을 원하지 않는 경우 정책 체인에 Content Caching 정책을 추가하지 마십시오.

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"
            }
          ]
        }
      }
    ]
  }
}

{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

지원되는 구성

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

업스트림 응답 헤더

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

4.1.9. CORS 요청 처리
링크 복사

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

허용된 헤더
허용된 메서드
허용되는 원본 헤더
허용되는 인증 정보
최대 경과 시간

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

참고

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

구성 속성

Expand

속성	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 요청을 허용할지 여부를 지정할 수 있습니다.	데이터 유형: 부울	제공되지 않음
max_age	`max_age` 속성을 사용하면 preflight 요청 결과를 캐시할 수 있는 기간을 설정할 수 있습니다.	데이터 유형: 정수	제공되지 않음

정책 오브젝트 예

{
  "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",
   "max_age" : 200
  }
}

{
  "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",
   "max_age" : 200
  }
}

Copy to Clipboard

Toggle word wrap

정책 구성 방법에 대한 자세한 내용은 3scale 관리 포털의 정책 체인 수정을 참조하십시오.

4.1.10. 사용자 정의 지표
링크 복사

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

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

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

요청 흐름 예

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

구성 예

이 정책은 업스트림 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"
        }
      }
    ]
  }
}

{
  "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"
        }
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

이 정책은 업스트림 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"
        }
      }
    ]
  }
}

{
  "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"
        }
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

4.1.11. 에코
링크 복사

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

구성 속성

Expand

속성	description	값	필수 여부
status	Echo 정책이 클라이언트로 반환되는 HTTP 상태 코드	데이터 유형: 정수	제공되지 않음
종료	Echo 정책에서 사용할 종료 모드를 지정합니다. `요청` 종료 모드에서는 들어오는 요청이 처리되지 않도록 중지합니다. `set` exit 모드는 재작성 단계를 건너뜁니다.	data type: enumerated string [request, set]	제공됨

정책 오브젝트 예

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

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

Copy to Clipboard

Toggle word wrap

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

4.1.12. 에지 제한
링크 복사

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

최종 사용자 속도 제한: 요청의 Authorization 헤더에 전달되는 JWT 토큰의 sub (제목) 클레임 값으로 제한 값을 지정합니다. {{ jwt.sub }} 로 구성됩니다.
두 번째(RPS) 속도 제한당 요청.
서비스당 글로벌 속도 제한: 애플리케이션당 대신 서비스당 제한을 적용합니다.
동시 연결 제한: 허용된 동시 연결 수를 설정합니다.

제한 유형

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

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

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

제한 정의

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

key 는 다음 속성으로 정의된 개체입니다.

name: 키의 이름을 정의합니다. 범위에서 고유해야 합니다.
scope: 키의 범위를 정의합니다. 지원되는 범위는 다음과 같습니다.
- 하나의 서비스(서비스)에 영향을 주는 서비스 범위 단위.
- 모든 서비스(글로벌)에 영향을 주는전역범위입니다.
name_type: name 값이 평가되는 방법을 정의합니다.
- 일반 텍스트(일반)
- 유동(유동)

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

leaky_bucket_limiters: rate, burst.
- rate: 지연 없이 초당 수행할 수 있는 요청 수를 정의합니다.
- burst: 허용 비율을 초과할 수 있는 초당 요청 양을 정의합니다. 비율에 따라 지정된 허용 속도 위에 있는 요청에 대해 인위적인 지연이 도입됩니다 . 버스트 에 정의된 것보다 초당 더 많은 요청 수를 초과하면 요청이 거부됩니다.
fixed_window_limiters:count,window.count 는 창에 정의된 초 단위의 요청 수를 정의합니다 .
connection_limiters:conn,burst,delay.
- Conn: 허용되는 동시 연결의 최대 수를 정의합니다. 버스트 커넥션 수를 초당 초과할 수 있습니다.
- 지연: 제한을 초과하는 연결을 지연하는 시간(초)을 정의합니다.

예

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

{
  "key": { "name": "service_A" },
  "count": 10,
  "window": 60
}

{
  "key": { "name": "service_A" },
  "count": 10,
  "window": 60
}

Copy to Clipboard

Toggle word wrap

지연이 1초인 버스트 10을 사용하여 100개의 연결을 허용합니다.

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

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

Copy to Clipboard

Toggle word wrap

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

유동 템플릿

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

예제

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

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

Copy to Clipboard

Toggle word wrap

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

조건 적용

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

조건은 다음 속성으로 정의됩니다.

combine_op: 작업 목록에 적용된 부울 연산자. 또는 및 및 의 값이 지원됩니다.
작업: 평가해야 하는 조건 목록입니다. 각 작업은 다음 속성을 사용하여 오브젝트로 표시됩니다.
- left: 작업의 왼쪽 부분입니다.
- left_type: left 속성이 평가되는 방법(일반 또는 유동).
- right: 운영의 올바른 부분.
- right_type: 올바른 속성이 평가되는 방법(일반 또는 유동).
- op: 왼쪽과 오른쪽 부분 사이에 Operator가 적용됩니다. 다음 두 값은 == (equals) 및 != (동일하지 않음)로 지원됩니다.

예제

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

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

Copy to Clipboard

Toggle word wrap

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

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

오류 처리

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

limits_exceeded_error: 구성된 제한이 초과될 경우 클라이언트에 반환될 오류 상태 코드와 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.
- status_code: 제한이 초과될 때 요청의 상태 코드입니다. 기본값: 429.
- error_handling: 다음과 같은 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.
  - exit: 처리 요청을 중지하고 오류 메시지를 반환합니다.
  - log: 처리 요청을 완료하고 출력 로그를 반환합니다.
configuration_error: 잘못된 구성이 있는 경우 클라이언트에 반환될 오류 상태 코드와 메시지를 지정합니다. 다음 매개변수를 구성해야 합니다.
- status_code : 구성 문제가 있는 경우 상태 코드입니다. 기본값: 500.
- error_handling: 다음과 같은 옵션을 사용하여 오류를 처리하는 방법을 지정합니다.
  - exit: 처리 요청을 중지하고 오류 메시지를 반환합니다.
  - log: 처리 요청을 완료하고 출력 로그를 반환합니다.

4.1.13. 헤더 수정
링크 복사

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

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}}"
      }
    ]
  }
}

{
  "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}}"
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

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

4.1.14. HTTP 상태 코드 Overwrite
링크 복사

API 공급자는 API 제품에 HTTP 상태 코드 Overwrite 정책을 추가할 수 있습니다. 이 정책을 사용하면 업스트림 응답 코드를 사용자가 지정하는 응답 코드로 변경할 수 있습니다. 3scale은 HTTP 상태 코드 Overwrite 정책을 업스트림 서비스에서 보낸 응답 코드에 적용합니다. 즉, 3scale이 노출하는 API가 상황에 맞지 않는 코드를 반환하는 경우 애플리케이션에 의미가 있는 응답 코드로 해당 코드를 변경하도록 HTTP 상태 코드 Overwrite 정책을 구성할 수 있습니다.

정책 체인에서 변경할 응답 코드를 생성하는 모든 정책은 HTTP Status Code Overwrite 정책 앞에 있어야 합니다. 변경하려는 상태 코드를 생성하는 정책이 없는 경우 HTTP 상태 코드 Overwrite 정책의 정책 체인 위치는 중요하지 않습니다.

관리 포털에서 제품의 정책 체인에 HTTP 상태 코드 Overwrite 정책을 추가합니다. 정책 체인에서 정책을 클릭하여 변경할 업스트림 응답 코드와 대신 반환하려는 응답 코드를 지정합니다. 덮어쓸 각 추가 업스트림 응답 코드에 대해 더하기 기호를 클릭합니다. 예를 들어 HTTP 상태 코드 Overwrite 정책을 사용하여 업스트림 201, "Created", 응답 코드, 200, "OK", 응답 코드를 변경할 수 있습니다.

변경하려는 응답 코드의 또 다른 예는 콘텐츠 제한을 초과할 때 응답입니다. 업스트림에서 413 을 반환하고 페이로드가 너무 커서 414 의 응답 코드가 너무 길면 request-URI가 너무 길면 도움이 될 수 있습니다.

관리 포털에서 HTTP 상태 코드 Overwrite 정책을 추가하는 대안은 3scale API를 정책 체인 구성 파일과 함께 사용하는 것입니다.

예제

정책 체인 구성 파일에서 다음 JSON 구성은 두 개의 업스트림 응답 코드를 덮어씁니다.

{
  "name": "statuscode_overwrite",
  "version": "builtin",
  "configuration": {
    "http_statuses": [
      {
        "upstream": 200,
        "apicast": 201
      },
      {
        "upstream": 413,
        "apicast": 414
      }
    ]
  }
}

{
  "name": "statuscode_overwrite",
  "version": "builtin",
  "configuration": {
    "http_statuses": [
      {
        "upstream": 200,
        "apicast": 201
      },
      {
        "upstream": 413,
        "apicast": 414
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

4.1.15. HTTP2 엔드 포인트
링크 복사

HTTP2 Endpoint 정책을 사용하면 요청 및 APIcast를 전송하는 소비자 애플리케이션 간에 HTTP/2 프로토콜 연결을 사용할 수 있습니다. HTTP2 끝점 정책이 제품의 정책 체인에 있는 경우, 요청을 하는 소비자 애플리케이션에서 업스트림 서비스로의 전체 통신 흐름이 HTTP/2 프로토콜을 사용할 수 있습니다.

HTTP2 끝점 정책이 정책 체인에 있는 경우:

요청 인증은 JSON 웹 토큰 또는 App_ID 및 App_Key 쌍을 통해 지정해야 합니다. API 키 인증은 지원되지 않습니다.
HTTP2 끝점 정책은 3scale APIcast 정책 앞에 있어야 합니다.
업스트림 서비스의 백엔드는 HTTP/1.1 일반 텍스트 또는 TLS(Transport Layer Security)를 구현할 수 있습니다.
정책 체인에는 TLS 종료 정책도 포함되어야 합니다.

4.1.16. IP 확인
링크 복사

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

구성 속성

Expand

속성	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-For` 및 `X-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"
  }
}

{
  "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"
  }
}

Copy to Clipboard

Toggle word wrap

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

4.1.17. JWT 청구 확인
링크 복사

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

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"
          }
      ]
  }
}

{
  "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"
          }
      ]
  }
}

Copy to Clipboard

Toggle word wrap

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

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

3scale 설치에 액세스할 수 있어야 합니다.
모든 배포가 완료될 때까지 기다려야 합니다.

정책 구성

API에 JWT 클레임 검사 정책을 추가하려면 3scale 관리 포털의 활성화 정책에 설명된 단계에 따라 JWT Claim 검사를 선택합니다.
JWT Claim Check 링크를 클릭합니다.
정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
규칙을 추가하려면 더하기 아이콘을 클릭합니다.
resource_type 을 지정합니다.
운영자를 선택합니다.
규칙에서 제어하는 리소스를 나타냅니다.
허용되는 메서드를 추가하려면 더하기 아이콘을 클릭합니다.
트래픽이 차단될 때 사용자에게 표시하려면 오류 메시지를 입력합니다.
JWT Claim Check를 사용하여 API 설정을 마치면 Update Policy(정책 업데이트 )를 클릭합니다.
해당 섹션에서 더하기 + 아이콘을 클릭하여 더 많은 리소스 유형과 허용되는 방법을 추가할 수 있습니다.
Update Policy(정책 체인 업데이트)를 클릭하여 변경 사항을 저장합니다.

4.1.18. 유동 컨텍스트 디버그
링크 복사

참고

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",
        ...
      }
      ...
    }

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

Copy to Clipboard

Toggle word wrap

4.1.19. 로깅
링크 복사

로깅 정책에는 다음 두 가지 목적이 있습니다.

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

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

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

이 정책은 enable_access_logs 구성 매개변수만 지원합니다.
액세스 로그를 활성화하려면 enable_access_logs 매개변수를 선택하거나 로깅 정책을 비활성화합니다.
API에 대한 액세스 로깅을 비활성화하려면 다음을 수행합니다.
1. 정책을 활성화합니다.
2. enable_access_logs 매개변수 지우기
3. Submit(제출) 버튼을 클릭합니다.
기본적으로 이 정책은 정책 체인에서 활성화되지 않습니다.

4.1.19.1. 모든 API에 대한 로깅 정책 구성
링크 복사

APICAST_ENVIRONMENT 를 사용하여 정책이 모든 API 제품에 전역적으로 적용되는 구성을 로드할 수 있습니다. 다음은 이를 달성하는 방법의 예입니다. APICAST_ENVIRONMENT는 배포 유형, 템플릿 또는 운영자 유형에 따라 파일 경로를 가리키는 데 사용됩니다.

로깅 정책을 전역적으로 구성하려면 배포 유형에 따라 다음을 고려하십시오.

템플릿 기반 배포의 경우 ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트해야 합니다.
3scale Operator 기반 배포의 경우:
- 3scale 2.11 이전 버전에서는 ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트해야 합니다.
- 3scale 2.11로 APIManager CR(사용자 정의 리소스)에서 참조하는 보안을 사용해야 합니다.
APIcast Operator 배포의 경우:
- 3scale 2.11 이전 버전에서는 구성할 수 없습니다.
- 3scale 2.11로 APIManager CR(사용자 정의 리소스)에서 참조하는 보안을 사용해야 합니다.
Docker에 배포된 APIcast 자체 관리의 경우 컨테이너에 파일을 마운트해야 합니다.

로깅 옵션은 API에서 올바르게 포맷되지 않은 로그 관련 문제를 방지하는 데 도움이 됩니다.

다음은 모든 서비스에서 로드되는 정책의 예입니다.

custom_env.lua file

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 },
}

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 },
}

Copy to Clipboard

Toggle word wrap

4.1.19.1.1. ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트하여 모든 API에 대한 로깅 정책 구성
링크 복사

custom_env.lua 파일을 사용하여 ConfigMap을 생성합니다.

oc create configmap logging --from-file=/path/to/custom_env.lua

oc create configmap logging --from-file=/path/to/custom_env.lua

Copy to Clipboard

Toggle word wrap

ConfigMap의 볼륨을 마운트합니다(예: apicast-staging ):

oc set volume dc/apicast-staging --add --name=logging --mount-path=/opt/app-root/src/config/custom_env.lua --sub-path=custom_env.lua -t configmap --configmap-name=logging

oc set volume dc/apicast-staging --add --name=logging --mount-path=/opt/app-root/src/config/custom_env.lua --sub-path=custom_env.lua -t configmap --configmap-name=logging

Copy to Clipboard

Toggle word wrap

환경 변수를 설정합니다.

oc set env dc/apicast-staging APICAST_ENVIRONMENT=/opt/app-root/src/config/custom_env.lua

oc set env dc/apicast-staging APICAST_ENVIRONMENT=/opt/app-root/src/config/custom_env.lua

Copy to Clipboard

Toggle word wrap

4.1.19.1.2. APIManager CR(사용자 정의 리소스)에서 참조하는 보안을 사용하여 모든 API에 대한 로깅 정책 구성
링크 복사

Operator 기반 배포의 3scale 2.11에서 로깅 정책을 시크릿으로 구성하고 APIManager CR(사용자 정의 리소스)의 보안을 참조합니다.

참고

다음 절차는 3scale Operator에만 유효합니다. 그러나 이러한 단계를 사용하여 APIcast 연산자를 유사한 방식으로 구성할 수 있습니다.

사전 요구 사항

Lua로 코딩된 하나 이상의 사용자 지정 환경.

절차

사용자 지정 환경 콘텐츠를 사용하여 보안을 생성합니다.

oc create secret generic custom-env --from-file=./custom_env.lua

$ oc create secret generic custom-env --from-file=./custom_env.lua

Copy to Clipboard

Toggle word wrap

APIcast 사용자 지정 환경을 사용하여 APIManager CR을 구성하고 배포합니다.

apimanager.yaml content:

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: apimanager-apicast-custom-environment
spec:
  apicast:
    productionSpec:
      customEnvironments:
        - secretRef:
            name: custom-env
    stagingSpec:
      customEnvironments:
        - secretRef:
            name: custom-env

apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: apimanager-apicast-custom-environment
spec:
  apicast:
    productionSpec:
      customEnvironments:
        - secretRef:
            name: custom-env
    stagingSpec:
      customEnvironments:
        - secretRef:
            name: custom-env

Copy to Clipboard

Toggle word wrap

APIManager CR을 배포합니다.
```
oc apply -f apimanager.yaml
```
```
$ oc apply -f apimanager.yaml
```
Copy to Clipboard Toggle word wrap

보안이 없는 경우 Operator는 CR을 실패로 표시합니다. 보안을 변경하려면 APIcast를 반영하려면 Pod/컨테이너를 다시 배포해야 합니다.

사용자 지정 환경 업데이트

사용자 지정 환경 콘텐츠를 수정해야 하는 경우 다음 두 가지 옵션이 있습니다.

권장 사항: 다른 이름으로 다른 보안을 생성하고 APIManager CR 필드를 업데이트합니다.
```
customEnvironments[].secretRef.name
```
```
customEnvironments[].secretRef.name
```
Copy to Clipboard Toggle word wrap
Operator는 새 사용자 지정 환경 콘텐츠를 로드하는 롤링 업데이트를 트리거합니다.
기존 보안 콘텐츠를 업데이트하고 APIcast 전환 spec.apicast.productionSpec.replicas 또는 spec.apicast.stagingSpec.replicas 를 0으로 다시 배포한 다음 이전 값으로 돌아갑니다.

4.1.19.1.3. Docker에 배포된 APIcast 셀프 관리용 모든 API에 대한 로깅 정책 구성
링크 복사

다음 docker 명령을 사용하여 custom_env.lua를 마운트하여 이 특정 환경에서 APIcast를 실행합니다.

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

Copy to Clipboard

Toggle word wrap

다음은 고려해야 할 docker 명령의 주요 개념입니다.

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

4.1.19.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
  }
}

Copy to Clipboard

Toggle word wrap

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

{
  "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": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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,
    "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"
      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

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

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

Copy to Clipboard

Toggle word wrap

응답 상태가 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"
    }
  }
}

{
  "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"
    }
  }
}

Copy to Clipboard

Toggle word wrap

4.1.19.3. 사용자 정의 로깅에 대한 추가 정보
링크 복사

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

NGINX 기본 지시문 변수: log_format. 예: {{remote_addr}}
응답 및 요청 헤더:
- {{req.headers.FOO}}: 요청에서 FOO 헤더를 가져오려면 다음을 수행합니다.
- {{Res.headers.FOO}}: 응답에서 FOO 헤더를 검색하려면 다음을 수행하십시오.
{{service.id}} 및 이러한 매개변수에서 제공하는 모든 서비스 속성과 같은 서비스 정보:
- THREESCALE_CONFIG_FILE
- THREESCALE_PORTAL_ENDPOINT

4.1.20. 유지 관리 모드
링크 복사

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

구성 속성

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

Expand

속성	value	default	description
status	정수, 선택 사항	503	응답 코드
message	문자열, 선택 사항	503 서비스 사용 불가 - 유지 관리	응답 메시지

유지 관리 모드 정책 예

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

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

Copy to Clipboard

Toggle word wrap

특정 업스트림에 대한 유지보수 모드 적용

{
    "name": "maintenance_mode",
    "version": "builtin",
    "configuration": {
        "message_content_type": "text/plain; charset=utf-8",
        "message": "Echo API /test is currently Unavailable",
        "condition": {
            "combine_op": "and",
            "operations": [
                {
                    "left_type": "liquid",
                    "right_type": "plain",
                    "op": "==",
                    "left": "{{ original_request.path }}",
                    "right": "/test"
                }
            ]
        },
        "status": 503
    }
}

{
    "name": "maintenance_mode",
    "version": "builtin",
    "configuration": {
        "message_content_type": "text/plain; charset=utf-8",
        "message": "Echo API /test is currently Unavailable",
        "condition": {
            "combine_op": "and",
            "operations": [
                {
                    "left_type": "liquid",
                    "right_type": "plain",
                    "op": "==",
                    "left": "{{ original_request.path }}",
                    "right": "/test"
                }
            ]
        },
        "status": 503
    }
}

Copy to Clipboard

Toggle word wrap

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

4.1.21. NGINX 필터
링크 복사

NGINX는 일부 요청 헤더를 자동으로 확인하고 해당 헤더의 유효성을 검사할 수 없는 경우 요청을 거부합니다. 예를 들어 NGINX는 NGINX가 검증할 수 없는 If-Match 헤더가 있는 요청을 거부합니다. NGINX에서 특정 헤더의 검증을 건너뛰려면 NGINX 필터 정책을 추가합니다.

NGINX 필터 정책을 추가하면 검증을 건너뛰기를 원하는 하나 이상의 요청 헤더를 지정합니다. 지정하는 각 헤더에 대해 요청에 헤더를 유지할지 여부를 나타냅니다. 예를 들어 다음 JSON 코드는 If-Match 헤더의 검증을 건너뛰지만 업스트림 서버로 전달되는 요청에 If-Match 헤더를 유지하도록 NGINX Filter 정책을 추가합니다.

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": true}
    ]
  }
}

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": true}
    ]
  }
}

Copy to Clipboard

Toggle word wrap

다음 예제에서는 If-Match 헤더의 유효성 검사를 건너뛰지만, 이 코드는 업스트림 서버로 요청을 보내기 전에 If-Match 헤더를 삭제하도록 NGINX에 지시합니다.

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": false}
    ]
  }
}

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": false}
    ]
  }
}

Copy to Clipboard

Toggle word wrap

업스트림 서버로 이동하는 요청에 지정된 헤더를 추가하는지 여부에 관계없이 NGINX에서 지정하는 헤더의 유효성을 검사할 수 없는 경우 NGINX가 응답 코드를 방지합니다.

중요

헤더 수정 정책 및 NGINX 필터 정책에 대해 동일한 헤더를 지정하는 것은 잠재적인 충돌 소스입니다.

4.1.22. 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": { }
  }
}

{
  "$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": { }
  }
}

Copy to Clipboard

Toggle word wrap

4.1.23. OAuth 2.0 토큰 인트로스펙션
링크 복사

OAuth 2.0 토큰 인트로스펙션 정책을 사용하면 토큰 발급자(Red Hat Single Sign-On)의 Token Introspection Endpoint를 사용하여 OIDC(OpenID Connect) 인증 옵션에서 서비스에 사용되는 JSON 웹 토큰(JWT) 토큰의 유효성을 검사할 수 있습니다.

APIcast는 auth_type 필드에서 다음 인증 유형을 지원하여 Token Introspection Endpoint 및 인증 정보 APIcast가 이 끝점을 호출할 때 사용하는지 확인합니다.

use_3scale_oidc_issuer_endpoint: APIcast는 클라이언트 자격 증명, 클라이언트 ID 및 클라이언트 시크릿 과 서비스 통합 페이지에 구성된 OIDC 발급자 설정의 Token Introspection Endpoint를 사용합니다. APIcast는 token_introspection_endpoint 필드에서 Token Introspection 엔드포인트를 검색합니다. 이 필드는 OIDC 발행자가 반환하는 .well-known/openid-configuration 엔드포인트에 있습니다.
use_3scale_oidc_issuer_endpoint 로 설정된 인증 유형 :
```
"policy_chain": [
…
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…
],
```
```
"policy_chain": [
…
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…
],
```
Copy to Clipboard Toggle word wrap
client_id+client_secret: 이 옵션을 사용하면 다른 토큰 Introspection Endpoint 및 클라이언트 ID 및 클라이언트 Secret APIcast에서 토큰 정보를 요청하는 데 사용할 수 있습니다. 이 옵션을 사용하는 경우 다음 구성 매개변수를 설정합니다.
- client_id: Token Introspection Endpoint의 클라이언트 ID를 설정합니다.
- client_secret: Token Introspection Endpoint에 대한 클라이언트 시크릿을 설정합니다.
- introspection_url: 인트로스펙션 엔드포인트 URL을 설정합니다.
  인증 유형을 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" } } … ],
  Copy to Clipboard Toggle word wrap

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

Token Introspection Endpoint 응답에는 활성 속성이 포함되어 있습니다. APIcast는 이 속성의 값을 확인합니다. 속성 값에 따라 APIcast는 호출을 인증하거나 거부합니다.

true: 전화가 인증되었습니다.
false: Authentication Failed 오류를 사용하여 호출이 거부됩니다.

정책을 사용하면 동일한 JWT 토큰에 대한 모든 호출에서 Token Introspection Endpoint 호출을 피하기 위해 토큰 캐싱을 활성화할 수 있습니다. Token Introspection Policy에 대한 토큰 캐싱을 활성화하려면 max_cached_tokens 필드를 0 의 값으로 설정하여 기능을 비활성화하고 10000 을 비활성화합니다. 또한 max_ttl_tokens 필드의 토큰에 대해 TTL(Time to Live) 값을 1600 초로 설정할 수 있습니다.

4.1.24. On Fail
링크 복사

API 공급자는 API 제품에 On Fail 정책을 추가할 수 있습니다. On Fail 정책이 정책 체인에 있고 지정된 API 소비자 요청에 대해 정책 실행이 실패하면 APIcast는 다음을 수행합니다.

요청 처리를 중지
요청을 보낸 애플리케이션에 지정한 상태 코드를 반환합니다.

On Fail 정책은 APIcast가 잘못된 구성 또는 사용자 지정 정책의 비호환 코드로 인해 정책을 처리할 수 없는 경우 유용합니다. 정책 체인에 On Fail 정책이 없으면 APIcast는 적용할 수 없는 정책을 건너뛰고 체인의 다른 정책을 처리하고, 요청을 업스트림 API로 보냅니다. 정책 체인의 On Fail 정책을 사용하면 APIcast에서 요청을 거부합니다.

정책 체인에서 On Fail 정책은 모든 위치에 있을 수 있습니다.

관리 포털에서 제품의 정책 체인에 On Fail 정책을 추가합니다. 정책 체인에서 정책을 클릭하여 On Fail 정책을 적용할 때 APIcast가 반환할 상태 코드를 지정합니다. 예를 들어 클라이언트의 잘못된 요청을 나타내는 400 을 지정할 수 있습니다.

4.1.25. 프록시 서비스
링크 복사

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

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

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

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

참고

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

설정

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

"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/"
      }
    }
]

"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/"
      }
    }
]

Copy to Clipboard

Toggle word wrap

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

사용 사례 예

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

프로젝트 예

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

4.1.26. 제한 헤더 속도
링크 복사

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

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

RateLimit 헤더

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

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

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

참고

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

추가 리소스

4.1.27. 응답/콘텐츠 제한 요청
링크 복사

API 공급자는 API 제품에 Response/Request Content Limits 정책을 추가할 수 있습니다. 이 정책을 사용하면 요청 크기를 업스트림 API로 제한하고 업스트림 API의 응답 크기를 제한할 수 있습니다. 이 정책이 없으면 요청/응답 크기는 무제한입니다.

이 정책은 과부하를 방지하는 데 유용합니다.

너무 큰 페이로드에서 작업해야 하기 때문에 백엔드입니다.
최종 사용자(API 소비자)는 처리할 수 있는 것보다 더 많은 데이터를 받기 때문입니다.

요청 또는 응답에서 content-length 헤더는 Response/Request Content Limits 정책을 적용하려면 3scale에 필요합니다.

관리 포털에서 Response/Request Content Limits 정책을 제품에 추가한 후 이를 클릭하여 바이트 단위로 제한을 지정합니다. 요청 제한 또는 응답 제한을 지정할 수 있습니다. 기본값인 0 은 무제한 크기를 나타냅니다.

또는 정책 체인 구성 파일을 업데이트하여 이 정책을 추가할 수 있습니다. 예를 들면 다음과 같습니다.

{
  "name": "apicast.policy.limits",
  "configuration":
  {
    "request": 100,
    "response": 100
  }
}

{
  "name": "apicast.policy.limits",
  "configuration":
  {
    "request": 100,
    "response": 100
  }
}

Copy to Clipboard

Toggle word wrap

4.1.28. Retry
링크 복사

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

중요

3scale 2.12에서는 정책에서 다시 시도할 수 있는 사례를 구성할 수 없습니다. 이는 모든 서비스에 재시도 요청을 적용하는 환경 변수 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
      }
    }
  }
}

{
  "$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
      }
    }
  }
}

Copy to Clipboard

Toggle word wrap

4.1.29. RH-SSO/Keycloak 역할 검사
링크 복사

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

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

whitelist: 이는 기본값입니다. 화이트리스트 를 사용하면 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: 이를 사용하여 realm 역할을 확인합니다. Red Hat Single Sign-On 설명서의 Realm Roles 를 참조하십시오.
영역 역할은 Red Hat Single Sign-On에서 발행한 JWT에 있습니다.
```
  "realm_access": {
    "roles": [
      "<realm_role_A>", "<realm_role_B>"
    ]
  }
```
```
  "realm_access": {
    "roles": [
      "<realm_role_A>", "<realm_role_B>"
    ]
  }
```
Copy to Clipboard Toggle word wrap
정책에 실제 역할을 지정해야 합니다.
```
"realm_roles": [
  { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
]
```
```
"realm_roles": [
  { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
]
```
Copy to Clipboard Toggle word wrap
다음은 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>"
      ]
    }
  }
```
```
  "resource_access": {
    "<client_A>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    },
    "<client_B>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    }
  }
```
Copy to Clipboard Toggle word wrap
정책에 클라이언트 역할을 지정합니다.
```
"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": "<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>" }
]
```
Copy to Clipboard Toggle word wrap
다음은 client_roles 배열에 있는 각 오브젝트의 사용 가능한 속성입니다.
- name: 역할의 이름을 지정합니다.
- name_type: name 값을 평가해야 하는 방법을 정의합니다. 값은 일반 이거나 유동적일 수 있습니다. 이 방법은 resource_type 과 동일한 방식으로 작동합니다.
- 클라이언트: 역할의 클라이언트를 지정합니다. 정의되지 않은 경우 이 정책은 aud 클레임을 클라이언트로 사용합니다.
- client_type: 클라이언트 값을 평가해야 하는 방법을 정의합니다. 값은 일반 이거나 유동적일 수 있습니다. 이 방법은 resource_type 과 동일한 방식으로 작동합니다.

4.1.30. 라우팅
링크 복사

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

라우팅은 다음 규칙을 기반으로 합니다.

중요

정책 체인에 라우팅 정책을 추가하면 라우팅 정책이 표준 3scale APIcast 정책 바로 앞에 있어야 합니다. 즉, 라우팅 정책과 3scale APIcast 정책 사이에 정책이 있을 수 없습니다. 이렇게 하면 APIcast가 업스트림 API로 전송하는 요청의 올바른 APIcast 출력이 표시됩니다. 다음은 올바른 정책 체인의 두 가지 예입니다.

Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast

Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast

Copy to Clipboard

Toggle word wrap

Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check

Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check

Copy to Clipboard

Toggle word wrap

라우팅 규칙

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

요청 경로 규칙

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

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

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

Copy to Clipboard

Toggle word wrap

헤더 규칙

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"
              }
            ]
          }
        }
      ]
    }
  }

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

Copy to Clipboard

Toggle word wrap

쿼리 인수 규칙

쿼리 인수 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"
              }
            ]
          }
        }
      ]
    }
  }

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

Copy to Clipboard

Toggle word wrap

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"
              }
            ]
          }
        }
      ]
    }
  }

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

Copy to Clipboard

Toggle word wrap

다중 작업 규칙

규칙은 'and' combined_op를 사용하여 또는 적어도 둘 중 하나가 '또는' combined _op 를 사용하여 true로 평가되는 경우에만 지정된 업스트림에 대해 여러 작업 및 경로를 지정할 수 있습니다 . 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"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Copy to Clipboard

Toggle word wrap

요청 경로가 /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"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Copy to Clipboard

Toggle word wrap

규칙 결합

룰을 결합할 수 있습니다. 여러 규칙이 있는 경우 선택한 업스트림 규칙은 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"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Copy to Clipboard

Toggle word wrap

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": []
          }
        }
      ]
    }
  }

 {
    "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": []
          }
        }
      ]
    }
  }

Copy to Clipboard

Toggle word wrap

지원되는 작업

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

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

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

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

Copy to Clipboard

Toggle word wrap

유동 템플릿

구성 값에 유동 템플릿을 사용할 수 있습니다. 이를 통해 체인에 있는 정책이 컨텍스트에 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"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Copy to Clipboard

Toggle word wrap

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": "/"
              }
            ]
          }
        }
      ]
    }
  }

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

Copy to Clipboard

Toggle word wrap

4.1.31. SOAP
링크 복사

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

구성 속성

Expand

속성	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
      }
    ]
  }
}

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

Copy to Clipboard

Toggle word wrap

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

4.1.32. TLS 클라이언트 인증서 유효성 검사
링크 복사

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

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

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

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

3scale 설치에 액세스할 수 있어야 합니다. 모든 배포가 완료될 때까지 기다려야 합니다.

정책에서 작동하도록 APIcast 설정

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

OpenShift 템플릿을 사용하여 APIcast 배포에 표시된 대로 액세스 토큰 및 배포 APIcast 자체 관리가 필요합니다.
참고
전체 게이트웨이에 대한 일부 인증서를 사용하도록 APIcast 인스턴스를 재구성해야 하므로 APIcast 자체 관리 배포가 필요합니다.

테스트 목적으로만 캐시 및 스테이징 환경 없이 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

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

Copy to Clipboard

Toggle word wrap

테스트 목적으로 인증서를 생성합니다. 또는 프로덕션 배포의 경우 인증 기관에서 제공하는 인증서를 사용할 수 있습니다.

TLS 인증서로 시크릿 생성

oc create secret tls apicast-tls
--cert=ca/certs/server.crt
--key=ca/keys/server.key

oc create secret tls apicast-tls
--cert=ca/certs/server.crt
--key=ca/keys/server.key

Copy to Clipboard

Toggle word wrap

APIcast 배포 내부의 시크릿 마운트

oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls

oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls

Copy to Clipboard

Toggle word wrap

HTTPS의 포트 8443에서 수신 대기하도록 APIcast 구성

oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key

oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key

Copy to Clipboard

Toggle word wrap

서비스에 8443 노출

oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'

oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'

Copy to Clipboard

Toggle word wrap

기본 경로 삭제
```
oc delete route api-apicast-staging
```
```
oc delete route api-apicast-staging
```
Copy to Clipboard Toggle word wrap

apicast 서비스를 경로로 노출

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

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

Copy to Clipboard

Toggle word wrap

참고

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

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

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

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

Copy to Clipboard

Toggle word wrap

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

정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하려면 3scale 로그인 인증 정보가 필요합니다. 또한 TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast 를 구성해야 합니다.

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

추가 사항:

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

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

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

TLS 클라이언트 인증서 유효성 검사 정책의 기능을 확인하려면 3scale 로그인 자격 증명이 필요합니다. 또한 TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast 를 구성해야 합니다.

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

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

Copy to Clipboard

Toggle word wrap

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

화이트리스트에서 인증서를 제거하려면 3scale 로그인 인증 정보가 필요합니다. TLS 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast 를 설정해야 합니다. 정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하여 허용 목록에 인증서를 추가해야 합니다.

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

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

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

4.1.33. TLS 종료
링크 복사

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

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

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

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

정책 체인에서 TLS 종료 구성

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

사용자가 발급한 인증서
PEM 형식의 서버 인증서
PEM 형식의 인증서 개인 키

다음 절차를 따르십시오.

API에 TLS 종료 정책을 추가하려면 표준 정책 활성화에 설명된 단계를 따르고 TLS 종료를 선택합니다.
TLS 종료 링크를 클릭합니다.
정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
정책에 TLS 인증서를 추가하려면 더하기 아이콘을 클릭합니다.
인증서 소스를 선택합니다.
- 포함된 인증서 는 기본적으로 선택됩니다. 이러한 인증서를 업로드합니다.
  - PEM 형식의 인증서 개인 키: Browse(찾아보기 )를 클릭하여 선택하고 업로드합니다.
  - PEM 형식의 인증서: Browse(찾아보기 )를 클릭하여 선택하고 업로드합니다.
- 파일 시스템의 인증서 - 이러한 인증서 경로를 선택하고 지정합니다.
  - 인증서의 경로
  - 인증서 개인 키의 경로
TLS 종료를 사용하여 API 설정을 마치면 Update Policy(정책 업데이트 )를 클릭합니다.

추가 사항:

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

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

TLS 종료 정책의 기능 확인

3scale 로그인 인증 정보가 있어야 합니다. TLS 종료 정책을 사용하여 APIcast를 구성해야 합니다.

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

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

Copy to Clipboard

Toggle word wrap

다음과 같습니다.

PUBLIC_URL= 준비 공개 기본 URL
port= 포트 번호
user_key= 인증할 사용자 키
path_to_certificate= 로컬 파일 시스템의 CA 인증서 경로

TLS 종료에서 파일 제거

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

3scale 로그인 인증 정보가 필요합니다.
TLS 종료 정책으로 APIcast를 구성하여 정책에 인증서를 추가해야 합니다.

인증서를 제거하려면 다음을 수행합니다.

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

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

4.1.34. 업스트림
링크 복사

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

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

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

정책 체인 참조:

Expand

속성	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",

      }
    ]
  }
}

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

      }
    ]
  }
}

Copy to Clipboard

Toggle word wrap

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

4.1.35. 업스트림 연결
링크 복사

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

proxy_connect_timeout
proxy_send_timeout
proxy_read_timeout

업스트림 연결 정책을 구성하려면 다음을 수행합니다.

3scale 설치에 액세스할 수 있어야 합니다.
모든 배포가 완료될 때까지 기다려야 합니다.

다음 절차를 따르십시오.

API에 업스트림 연결 정책을 추가하려면 3scale 관리 포털의 활성화 정책에 설명된 단계에 따라 업스트림 연결 을 선택합니다.
업스트림 연결 링크를 클릭합니다.
정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
업스트림 연결에 대한 옵션을 구성합니다.
- send_timeout
- connect_timeout
- read_timeout
업스트림 연결을 사용하여 API 설정을 마치면 Update Policy (업데이트 정책)를 클릭합니다.

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

4.1.36. 업스트림 상호 TLS
링크 복사

Upstream Mutual TLS 정책을 사용하면 구성에 설정된 인증서를 기반으로 APIcast와 업스트림 API 간의 상호 TLS 연결을 설정하고 검증할 수 있습니다.

verify 필드가 활성화되면 정책은 업스트림 API에서 서버 인증서도 확인합니다. ca_certificates 에는 APIcast가 서버의 유효성을 검증하는 데 사용하는 -----BEGIN CERTIFICATE----- 및 -----END CERTIFICATE----- 등의 PEM(개인 정보 보호 보안 메일) 형식 인증서가 포함되어 있습니다.

참고

확인 필드를 활성화하고 업스트림 API 인증서를 확인하기 위해 ca_certificates 가 채워져 있어야 합니다. verify 필드가 활성화되지 않으면 업스트림 API에서 APIcast 인증서만 확인합니다.

정책 체인에서 최신 상호 TLS를 구성하려면 3scale 설치에 액세스할 수 있어야 합니다.

API에 Upstream Mutual TLS 정책을 추가하려면 3scale 관리 포털의 Enabling 정책에 설명된 단계를 따라 Upstream Mutual TLS 를 선택합니다.
Upstream 상호 TLS 링크를 클릭합니다.
정책을 활성화하려면 Enabled (활성화) 확인란을 선택합니다.
인증서 유형 선택 :
- path: OpenShift에서 생성된 것과 같이 인증서의 경로를 지정하려는 경우.
- embedded: 타사에서 생성된 인증서를 파일 시스템에서 업로드하여 사용하려는 경우.
인증서 에서 클라이언트 인증서를 지정합니다.
인증서 키의 키를 지정합니다.
Upstream Mutual TLS를 사용하여 API 설정을 마치면 정책 체인 업데이트를 클릭합니다.

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

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

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

경로 구성

다음과 같이 OpenShift 및 Kubernetes 시크릿의 인증서 경로를 사용합니다.

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
      "certificate": "/secrets/client.cer",
      "certificate_type": "path",
      "certificate_key": "/secrets/client.key",
      "certificate_key_type": "path"
  }
}

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
      "certificate": "/secrets/client.cer",
      "certificate_type": "path",
      "certificate_key": "/secrets/client.key",
      "certificate_key_type": "path"
  }
}

Copy to Clipboard

Toggle word wrap

임베디드 구성

http 양식 및 파일 업로드에 다음 구성을 사용합니다.

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
    "certificate_type": "embedded",
    "certificate_key_type": "embedded",
    "certificate": "data:application/pkix-cert;name=client.cer;base64,XXXXXXXXXXX",
    "certificate_key": "data:application/x-iwork-keynote-sffkey;name=client.key;base64,XXXXXXXX"
  }
}

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
    "certificate_type": "embedded",
    "certificate_key_type": "embedded",
    "certificate": "data:application/pkix-cert;name=client.cer;base64,XXXXXXXXXXX",
    "certificate_key": "data:application/x-iwork-keynote-sffkey;name=client.key;base64,XXXXXXXX"
  }
}

Copy to Clipboard

Toggle word wrap

추가 필드에 대한 자세한 내용은 ca_certificates 및 Upstream Mutual TLS, 정책 구성 스키마를 확인합니다.

추가 고려 사항

Upstream 상호 TLS 정책은 APICAST_PROXY_HTTPS_CERTIFICATE_KEY 및 APICAST_PROXY_HTTPS_CERTIFICATE 환경 변수 값을 덮어씁니다. 정책에서 설정한 인증서를 사용하므로 해당 환경 변수가 적용되지 않습니다.

4.1.37. URL 다시 작성
링크 복사

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

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

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

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

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

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

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

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

다음은 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"
      }
    ]
  }

{
  "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"
      }
    ]
  }

Copy to Clipboard

Toggle word wrap

APIcast로 전송된 원래 요청 URI:

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

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

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

4.1.38. 캡처를 사용하여 URL 재작성
링크 복사

캡처 정책을 사용하여 URL 재작성 정책은 URL 재작성 정책 대신, API 요청의 URL을 API 백엔드에 전달하기 전에 다시 작성할 수 있습니다.

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"
      }
    ]
  }
}

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

Copy to Clipboard

Toggle word wrap

APIcast로 전송된 원래 요청 URI:

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

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

4.1.39. WebSocket
링크 복사

Websocket 정책을 사용하면 업스트림 API에 대한 WebSocket 프로토콜 연결을 활성화합니다. WebSocket 프로토콜을 활성화하려면 다음을 고려하십시오.

WebSocket 프로토콜은 JSON 웹 토큰을 지원하지 않습니다.
WebSocket 프로토콜에서는 추가 헤더를 허용하지 않습니다.
WebSocket 프로토콜은 HTTP/2 표준의 일부가 아닙니다.

WebSocket 연결을 활성화하는 지정된 업스트림 API의 경우 해당 백엔드를 http[s] 또는 ws[s] 로 정의할 수 있습니다.

Websocket 정책을 정책 체인에 추가하는 경우 Websocket 정책이 3scale APIcast 정책 앞에 있는지 확인합니다.

4.1. 기본 3scale APIcast 동작을 변경하는 표준 정책링크 복사링크가 클립보드에 복사되었습니다!

4.1.1. 3scale 관리 포털에서 정책 활성화링크 복사링크가 클립보드에 복사되었습니다!

4.1.2. 3scale Auth Caching링크 복사링크가 클립보드에 복사되었습니다!

4.1.3. 3scale Batcher링크 복사링크가 클립보드에 복사되었습니다!

4.1.4. 3scale Referrer링크 복사링크가 클립보드에 복사되었습니다!

4.1.5. 익명 액세스링크 복사링크가 클립보드에 복사되었습니다!

4.1.6. Camel 서비스링크 복사링크가 클립보드에 복사되었습니다!

4.1.7. 조건 정책링크 복사링크가 클립보드에 복사되었습니다!

4.1.8. 컨텐츠 캐싱링크 복사링크가 클립보드에 복사되었습니다!

4.1.9. CORS 요청 처리링크 복사링크가 클립보드에 복사되었습니다!

4.1.10. 사용자 정의 지표링크 복사링크가 클립보드에 복사되었습니다!

4.1.11. 에코링크 복사링크가 클립보드에 복사되었습니다!

4.1.12. 에지 제한링크 복사링크가 클립보드에 복사되었습니다!

4.1.13. 헤더 수정링크 복사링크가 클립보드에 복사되었습니다!

4.1.14. HTTP 상태 코드 Overwrite링크 복사링크가 클립보드에 복사되었습니다!

4.1.15. HTTP2 엔드 포인트링크 복사링크가 클립보드에 복사되었습니다!

4.1.16. IP 확인링크 복사링크가 클립보드에 복사되었습니다!

4.1.17. JWT 청구 확인링크 복사링크가 클립보드에 복사되었습니다!

4.1.18. 유동 컨텍스트 디버그링크 복사링크가 클립보드에 복사되었습니다!

4.1.19. 로깅링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.1. 모든 API에 대한 로깅 정책 구성링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.1.1. ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트하여 모든 API에 대한 로깅 정책 구성링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.1.2. APIManager CR(사용자 정의 리소스)에서 참조하는 보안을 사용하여 모든 API에 대한 로깅 정책 구성링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.1.3. Docker에 배포된 APIcast 셀프 관리용 모든 API에 대한 로깅 정책 구성링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.2. 로깅 정책의 예링크 복사링크가 클립보드에 복사되었습니다!

4.1.19.3. 사용자 정의 로깅에 대한 추가 정보링크 복사링크가 클립보드에 복사되었습니다!

4.1.20. 유지 관리 모드링크 복사링크가 클립보드에 복사되었습니다!

4.1.21. NGINX 필터링크 복사링크가 클립보드에 복사되었습니다!

4.1.22. OAuth 2.0 상호 TLS 클라이언트 인증링크 복사링크가 클립보드에 복사되었습니다!

4.1.23. OAuth 2.0 토큰 인트로스펙션링크 복사링크가 클립보드에 복사되었습니다!

4.1.24. On Fail링크 복사링크가 클립보드에 복사되었습니다!

4.1.25. 프록시 서비스링크 복사링크가 클립보드에 복사되었습니다!

4.1.26. 제한 헤더 속도링크 복사링크가 클립보드에 복사되었습니다!

4.1.27. 응답/콘텐츠 제한 요청링크 복사링크가 클립보드에 복사되었습니다!

4.1.28. Retry링크 복사링크가 클립보드에 복사되었습니다!

4.1.29. RH-SSO/Keycloak 역할 검사링크 복사링크가 클립보드에 복사되었습니다!

4.1.30. 라우팅링크 복사링크가 클립보드에 복사되었습니다!

4.1.31. SOAP링크 복사링크가 클립보드에 복사되었습니다!

4.1.32. TLS 클라이언트 인증서 유효성 검사링크 복사링크가 클립보드에 복사되었습니다!

4.1.33. TLS 종료링크 복사링크가 클립보드에 복사되었습니다!

4.1.34. 업스트림링크 복사링크가 클립보드에 복사되었습니다!

4.1.35. 업스트림 연결링크 복사링크가 클립보드에 복사되었습니다!

4.1.36. 업스트림 상호 TLS링크 복사링크가 클립보드에 복사되었습니다!

4.1.37. URL 다시 작성링크 복사링크가 클립보드에 복사되었습니다!

4.1.38. 캡처를 사용하여 URL 재작성링크 복사링크가 클립보드에 복사되었습니다!

4.1.39. WebSocket링크 복사링크가 클립보드에 복사되었습니다!

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

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

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.1. 기본 3scale APIcast 동작을 변경하는 표준 정책
링크 복사

4.1.1. 3scale 관리 포털에서 정책 활성화
링크 복사

4.1.2. 3scale Auth Caching
링크 복사

4.1.3. 3scale Batcher
링크 복사

4.1.4. 3scale Referrer
링크 복사

4.1.5. 익명 액세스
링크 복사

4.1.6. Camel 서비스
링크 복사

4.1.7. 조건 정책
링크 복사

4.1.8. 컨텐츠 캐싱
링크 복사

4.1.9. CORS 요청 처리
링크 복사

4.1.10. 사용자 정의 지표
링크 복사

4.1.11. 에코
링크 복사

4.1.12. 에지 제한
링크 복사

4.1.13. 헤더 수정
링크 복사

4.1.14. HTTP 상태 코드 Overwrite
링크 복사

4.1.15. HTTP2 엔드 포인트
링크 복사

4.1.16. IP 확인
링크 복사

4.1.17. JWT 청구 확인
링크 복사

4.1.18. 유동 컨텍스트 디버그
링크 복사

4.1.19. 로깅
링크 복사

4.1.19.1. 모든 API에 대한 로깅 정책 구성
링크 복사

4.1.19.1.1. ConfigMap 및 VolumeMount를 통해 컨테이너에 파일을 마운트하여 모든 API에 대한 로깅 정책 구성
링크 복사

4.1.19.1.2. APIManager CR(사용자 정의 리소스)에서 참조하는 보안을 사용하여 모든 API에 대한 로깅 정책 구성
링크 복사

4.1.19.1.3. Docker에 배포된 APIcast 셀프 관리용 모든 API에 대한 로깅 정책 구성
링크 복사

4.1.19.2. 로깅 정책의 예
링크 복사

4.1.19.3. 사용자 정의 로깅에 대한 추가 정보
링크 복사

4.1.20. 유지 관리 모드
링크 복사

4.1.21. NGINX 필터
링크 복사

4.1.22. OAuth 2.0 상호 TLS 클라이언트 인증
링크 복사

4.1.23. OAuth 2.0 토큰 인트로스펙션
링크 복사

4.1.24. On Fail
링크 복사

4.1.25. 프록시 서비스
링크 복사

4.1.26. 제한 헤더 속도
링크 복사

4.1.27. 응답/콘텐츠 제한 요청
링크 복사

4.1.28. Retry
링크 복사

4.1.29. RH-SSO/Keycloak 역할 검사
링크 복사

4.1.30. 라우팅
링크 복사

4.1.31. SOAP
링크 복사

4.1.32. TLS 클라이언트 인증서 유효성 검사
링크 복사

4.1.33. TLS 종료
링크 복사

4.1.34. 업스트림
링크 복사

4.1.35. 업스트림 연결
링크 복사

4.1.36. 업스트림 상호 TLS
링크 복사

4.1.37. URL 다시 작성
링크 복사

4.1.38. 캡처를 사용하여 URL 재작성
링크 복사

4.1.39. WebSocket
링크 복사