1.21. 3scale Istio 어댑터 사용

1.21.1. Red Hat OpenShift Service Mesh와 3scale 어댑터 통합

이러한 예제를 사용하여 3scale Istio 어댑터로 서비스에 대한 요청을 구성할 수 있습니다.

사전 요구 사항

Red Hat OpenShift Service Mesh 버전 2.x
작업 중인 3scale 계정(SaaS 또는 3scale 2.9 on-Premises)
백엔드 캐시를 활성화하려면 3scale 2.9 이상 필요
Red Hat OpenShift Service Mesh 사전 요구 사항
Mixer 정책 적용이 활성화되었는지 확인합니다. Mixer 정책 시행 업데이트 섹션에서는 현재 Mixer 정책 시행 상태를 확인하고 정책 시행을 활성화하는 지침을 제공합니다.
- 업그레이드 시 SMCP(Service Mesh Control Plane)를 올바르게 구성해야 합니다.

참고

3scale Istio Adapter를 구성하려면 사용자 정의 리소스 파일에 어댑터 매개변수를 추가하는 방법에 대한 Red Hat OpenShift Service Mesh 사용자 정의 리소스를 참조하십시오.

참고

특히 kind: handler 리소스에 주의하십시오. 3scale 계정 인증 정보로 업데이트해야 합니다. 선택적으로 service_id를 처리기에 추가할 수 있지만 3scale 계정의 하나의 서비스에만 처리기를 렌더링하므로 이전 버전과의 호환성을 위해서만 유지됩니다. service_id를 처리기에 추가하는 경우 다른 서비스에 3scale을 활성화하려면 다른 service_ids로 더 많은 처리기를 생성해야 합니다.

아래 단계에 따라 3scale 계정당 단일 처리기를 사용합니다.

절차

3scale 계정에 대한 처리기를 생성하고 계정 인증 정보를 지정합니다. 서비스 식별자를 생략합니다.
```
  apiVersion: "config.istio.io/v1alpha2"
  kind: handler
  metadata:
   name: threescale
  spec:
   adapter: threescale
   params:
     system_url: "https://<organization>-admin.3scale.net/"
     access_token: "<ACCESS_TOKEN>"
   connection:
     address: "threescale-istio-adapter:3333"
```
필요한 경우, 3scale 구성에서 제공하는 URL을 재정의하기 위해 params 섹션에 backend_url 필드를 제공할 수 있습니다. 어댑터가 3scale 온프레미스 인스턴스와 동일한 클러스터에서 실행되고 내부 클러스터 DNS를 사용하려는 경우 유용할 수 있습니다.
다음과 같이 3scale 계정에 속하는 서비스의 배포 리소스를 편집하거나 패치합니다.
1. 유효한 service_id에 해당하는 값을 사용하여 "service-mesh.3scale.net/service-id" 레이블을 추가합니다.
2. 1단계에서 처리기 리소스의 이름이 값이 되도록 "service-mesh.3scale.net/credentials" 레이블을 추가합니다.
더 많은 서비스를 추가하려는 경우 2단계를 수행하여 3scale 계정 인증 정보 및 서비스 식별자에 연결합니다.

3scale 구성으로 규칙 구성을 수정하여 3scale 처리기에 규칙을 전송합니다.

규칙 구성 예

  apiVersion: "config.istio.io/v1alpha2"
  kind: rule
  metadata:
    name: threescale
  spec:
    match: destination.labels["service-mesh.3scale.net"] == "true"
    actions:
      - handler: threescale.handler
        instances:
          - threescale-authorization.instance

1.21.1.1. 3scale 사용자 정의 리소스 생성

어댑터에는 handler, instance, rule 사용자 정의 리소스를 생성할 수 있는 도구가 포함되어 있습니다.

표 1.29. 사용법
옵션	설명	필수 항목	기본값
`-h, --help`	사용 가능한 옵션에 대한 도움말 출력 생성	아니요
`--name`	이 URL의 고유 이름, 토큰 쌍	예
`-n, --namespace`	템플릿을 생성할 네임스페이스	아니요	istio-system
`-t, --token`	3scale 액세스 토큰	예
`-u, --url`	3scale 관리자 포털 URL	예
`--backend-url`	3scale 백엔드 URL. 설정하면 시스템 설정에서 읽은 값을 재정의합니다.	아니요
`-s, --service`	3scale API/서비스 ID	아니요
`--auth`	지정을 위한 3scale 인증 패턴(1=API Key, 2=App Id/App Key, 3=OIDC)	아니요	하이브리드
`-o, --output`	생성된 매니페스트를 저장할 파일	아니요	표준 출력
`--version`	CLI 버전을 출력하고 즉시 종료합니다.	아니요

1.21.1.1.1. URL 예제에서 템플릿 생성

참고

배포된 어댑터의 매니페스트를 생성하며 3scale 어댑터 컨테이너 이미지에서 oc exec를 통해 다음 명령을 실행합니다.
3scale-config-gen 명령을 사용하여 YAML 구문 및 들여쓰기 오류를 방지할 수 있습니다.
주석을 사용하는 경우 --service를 생략할 수 있습니다.
이 명령은 oc exec를 통해 컨테이너 이미지 내에서 호출해야 합니다.

절차

3scale-config-gen 명령을 사용하여 토큰, URL 쌍을 단일 처리기로 여러 서비스에서 공유할 수 있도록 템플릿 파일을 자동 생성합니다.
```
$ 3scale-config-gen --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]"
```

다음 예제에서는 처리기에 포함된 서비스 ID로 템플릿을 생성합니다.

$ 3scale-config-gen --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]"

추가 리소스

토큰.

1.21.1.2. 배포된 어댑터에서 매니페스트 생성

참고

NAME은 3scale로 관리 중인 서비스와 식별하는 데 사용하는 식별자입니다.
CREDENTIALS_NAME 참조는 규칙 구성의 match 섹션에 해당하는 식별자입니다. CLI 툴을 사용하는 경우 NAME 식별자로 자동 설정됩니다.
해당 값은 특정할 필요가 없습니다. 레이블 값은 규칙의 내용과 일치해야 합니다. 자세한 정보는 어댑터를 통한 서비스 트래픽 라우팅을 참조하십시오.

이 명령을 실행하여 istio-system 네임스페이스의 배포된 어댑터에서 매니페스트를 생성합니다.

$ export NS="istio-system" URL="https://replaceme-admin.3scale.net:443" NAME="name" TOKEN="token"
oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \
-it -- ./3scale-config-gen \
--url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS}

터미널에 샘플 출력이 생성됩니다. 필요한 경우 이러한 샘플을 편집하고 oc create 명령을 사용하여 오브젝트를 생성합니다.
요청이 어댑터에 도달하면 어댑터는 서비스가 3scale의 API에 매핑되는 방식을 알아야 합니다. 다음 두 가지 방법으로 이러한 정보를 제공할 수 있습니다.
1. 워크로드에 레이블 지장(권장)
2. 처리기를 service_id로 하드 코딩

필요한 주석으로 워크로드를 업데이트합니다.

참고

처리기에 아직 포함되지 않은 경우, 이 예제에 제공된 서비스 ID만 업데이트해야 합니다. 처리기의 설정이 우선합니다.

$ export CREDENTIALS_NAME="replace-me"
export SERVICE_ID="replace-me"
export DEPLOYMENT="replace-me"
patch="$(oc get deployment "${DEPLOYMENT}"
patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''

1.21.1.3. 어댑터를 통한 서비스 트래픽 라우팅

3scale 어댑터를 통해 서비스 트래픽을 유도하려면 다음 단계를 따르십시오.

사전 요구 사항

3scale 관리자의 인증 정보 및 서비스 ID

프로세스

kind: rule 리소스의 구성에서 이전에 생성한 destination.labels["service-mesh.3scale.net/credentials"] == "threescale" 규칙과 일치합니다.
서비스를 통합하기 위해 대상 워크로드 배포에서 위의 레이블을 PodTemplateSpec에 추가합니다. threescale 값은 생성된 처리기의 이름을 나타냅니다. 이 처리기에서는 3scale를 호출하는 데 필요한 액세스 토큰을 저장합니다.
destination.labels["service-mesh.3scale.net/service-id"] == "replace-me" 레이블을 워크로드에 추가하여 요청 시 인스턴스를 통해 서비스 ID를 어댑터에 전달합니다.

1.21.2. 3scale로 통합 설정 구성

3scale 통합 설정을 구성하려면 다음 절차를 따르십시오.

참고

3scale SaaS 고객의 경우, Red Hat OpenShift Service Mesh는 조Early Access 프로그램의 일부로 활성화됩니다.

절차

[your_API_name] 통합으로 이동합니다.
설정을 클릭합니다.
배포에서 Istio 옵션을 선택합니다.
- 인증에서 API Key (user_key) 옵션은 기본적으로 선택됩니다.
제품 업데이트를 클릭하여 선택 사항을 저장합니다.
설정을 클릭합니다.
구성 업데이트를 클릭합니다.

1.21.3. 캐싱 동작

3scale System API의 응답은 기본적으로 어댑터 내에서 캐시됩니다. 항목이 cacheTTLSeconds 값보다 오래되면 캐시에서 제거됩니다. 또한 기본적으로 캐시된 항목의 자동 새로 고침은 cacheRefreshSeconds 값에 따라 만료되기 몇 초 전에 시도됩니다. 이 값을 cacheTTLSeconds 값보다 높게 설정하여 자동 새로 고침을 비활성화할 수 있습니다.

cacheEntriesMax를 양수가 아닌 값으로 설정하여 캐싱을 완전히 비활성화할 수 있습니다.

새로 고침 프로세스를 사용하면 호스트가 연결할 수 없는 캐시된 값은 만료가 지나면 제거되기 전에 다시 시도됩니다.

1.21.4. 요청 인증

이 릴리스에서는 다음 인증 방법을 지원합니다.

표준 API 키: 식별자와 시크릿 토큰으로 작동하는 임의의 단일 문자열 또는 해시입니다.
애플리케이션 식별자 및 키 쌍: 변경 불가능한 식별자 및 변경 가능한 시크릿 키 문자열입니다.
OpenID 인증 방법: JSON 웹 토큰에서 구문 분석된 클라이언트 ID 문자열입니다.

1.21.4.1. 인증 패턴 적용

인증 동작을 구성하려면 다음 인증 방법 예제에 설명된 인스턴스 사용자 정의 리소스를 수정합니다. 다음에서 인증 자격 증명을 허용할 수 있습니다.

요청 헤더
요청 매개변수
요청 헤더 및 쿼리 매개변수 둘 다

참고

헤더에서 값을 지정하는 경우 소문자여야 합니다. 예를 들어 User-Key로 헤더를 보내려면 구성에서 request.headers["user-key"]로 참조되어야 합니다.

1.21.4.1.1. API 키 인증 방법

서비스 메시는 subject 사용자 정의 리소스 매개변수의 user 옵션에 지정된 대로 쿼리 매개변수 및 요청 헤더에서 API 키를 찾습니다. 사용자 정의 리소스 파일에 지정된 순서로 값을 확인합니다. 원하지 않는 옵션을 생략하여 API 키 검색을 쿼리 매개변수 또는 요청 헤더로 제한할 수 있습니다.

이 예에서 서비스 메시는 user_key 쿼리 매개변수에서 API 키를 찾습니다. API 키가 쿼리 매개변수에 없으면 서비스 메시가 user-key 헤더를 확인합니다.

API 키 인증 방법 예

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

어댑터가 다른 쿼리 매개변수 또는 요청 헤더를 검사하도록 하려면 이름을 적절하게 변경합니다. 예를 들어 "key"라는 쿼리 매개변수에서 API 키를 확인하려면 request.query_params["user_key"]을 request.query_params["key"]로 변경합니다.

1.21.4.1.2. 애플리케이션 ID 및 애플리케이션 키 쌍 인증 방법

서비스 메시는 subject 사용자 정의 리소스 매개변수의 properties 옵션에 지정된 대로 쿼리 매개변수 및 요청 헤더에서 애플리케이션 ID와 애플리케이션 키를 찾습니다. 애플리케이션 키는 선택 사항입니다. 사용자 정의 리소스 파일에 지정된 순서로 값을 확인합니다. 원하지 않는 옵션을 제외하여 자격 증명 검색을 쿼리 매개변수 또는 요청 헤더로 제한할 수 있습니다.

이 예에서 서비스 메시는 쿼리 매개변수의 애플리케이션 ID 및 애플리케이션 키를 먼저 찾고 필요한 경우 요청 헤더로 이동합니다.

애플리케이션 ID 및 애플리케이션 키 쌍 인증 방법 예

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
  namespace: istio-system
spec:
  template: authorization
  params:
    subject:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
    action:
      path: request.url_path
      method: request.method | "get"

어댑터가 다른 쿼리 매개변수 또는 요청 헤더를 검사하도록 하려면 이름을 적절하게 변경합니다. 예를 들어, identification라는 쿼리 매개변수의 애플리케이션 ID를 확인하려면 request.query_params["app_id"]을 request.query_params["identification"]로 변경합니다.

1.21.4.1.3. OpenID 인증 방법

OIDC(OpenID Connect) 인증 방법을 사용하려면 subject 필드에서 properties 값을 사용하여 client_id 또는 필요한 경우 app_key로 설정할 수 있습니다.

이전에 설명된 방법을 사용하여 이 오브젝트를 조작할 수 있습니다. 아래 설정 예에서 클라이언트 식별자(애플리케이션 ID)는 azp 레이블 아래에 있는 JSON 웹 토큰(JWT)에서 구문 분석됩니다. 필요에 따라 수정할 수 있습니다.

OpenID 인증 방법 예

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
spec:
  template: threescale-authorization
  params:
    subject:
      properties:
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
        client_id: request.auth.claims["azp"] | ""
      action:
        path: request.url_path
        method: request.method | "get"
        service: destination.labels["service-mesh.3scale.net/service-id"] | ""

이 통합이 올바르게 작동하려면 클라이언트가 ID 공급자(IdP)에서 생성되도록 OIDC를 3scale에서 수행해야 합니다. 해당 서비스와 동일한 네임스페이스에서 보호하려는 서비스에 대해 요청 권한 부여를 생성해야 합니다. JWT는 요청의 Authorization 헤더로 전달됩니다.

아래에 정의된 샘플 RequestAuthentication에서 issuer, jwksUri, selector를 적절하게 대체합니다.

OpenID 정책 예

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: bookinfo
spec:
  selector:
    matchLabels:
      app: productpage
  jwtRules:
  - issuer: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
    jwksUri: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs

1.21.4.1.4. 하이브리드 인증 방법

특정 인증 방법을 적용하지 않도록 선택하고, 두 방법에 대해 유효한 자격 증명을 수락할 수 있습니다. API 키와 애플리케이션 ID/애플리케이션 키 쌍이 모두 제공되면 서비스 메시는 API 키를 사용합니다.

이 예제에서 서비스 메시는 쿼리 매개변수에서 API 키를 확인한 다음 요청 헤더를 확인합니다. API 키가 없는 경우 쿼리 매개변수에서 애플리케이션 ID와 키를 확인한 다음 요청 헤더를 확인합니다.

하이브리드 인증 방법 예

apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
  name: threescale-authorization
spec:
  template: authorization
  params:
    subject:
      user: request.query_params["user_key"] | request.headers["user-key"] |
      properties:
        app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
        app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
        client_id: request.auth.claims["azp"] | ""
    action:
      path: request.url_path
      method: request.method | "get"
      service: destination.labels["service-mesh.3scale.net/service-id"] | ""

1.21.5. 3scale Adapter 지표

기본적으로 어댑터는 /metrics 끝점의 포트 8080에서 공개되는 다양한 Prometheus 지표를 보고합니다. 이러한 지표는 어댑터와 3scale 간의 상호 작용 수행 방식에 대한 인사이트를 제공합니다. 이 서비스는 Prometheus에서 자동으로 검색 및 스크랩하도록 레이블이 지정됩니다.

참고

Service Mesh 1.x의 이전 릴리스 이후 3scale Istio 어댑터 지표에 호환되지 않는 변경 사항이 있습니다.

Prometheus에서 지표는 백엔드 캐시에 대해 한 번의 추가로 이름이 변경되었으므로, Service Mesh 2.0부터 다음 지표가 존재합니다.

표 1.30. Prometheus 지표
지표	유형	설명
`threescale_latency`	히스토그램	어댑터와 3scale 간의 대기 시간을 요청합니다.
`threescale_http_total`	카운터	3scale 백엔드에 대한 요청의 HTTP 상태 응답 코드입니다.
`threescale_system_cache_hits`	카운터	구성 캐시에서 가져온 3scale 시스템에 대한 총 요청 수입니다.
`threescale_backend_cache_hits`	카운터	백엔드 캐시에서 가져온 3scale 백엔드에 대한 총 요청 수입니다.

1.21.6. 3scale 백엔드 캐시

3scale 백엔드 캐시는 3scale Service Management API의 클라이언트에 대한 권한 부여 및 보고 캐시를 제공합니다. 이 캐시는 어댑터에 내장되어 관리자가 절충을 기꺼이 받아들인다는 가정하에 특정 상황에서 응답 대기 시간을 줄일 수 있습니다.

참고

3scale 백엔드 캐시는 기본적으로 비활성화되어 있습니다. 3scale 백엔드 캐시 기능은 낮은 대기 시간과 프로세서 및 메모리의 더 많은 리소스 소비를 위해 마지막 플러시를 수행한 후 속도 제한 및 잠재적 손실에서 부정확하게 사용됩니다.

1.21.6.1. 백엔드 캐시 활성화의 이점

다음은 백엔드 캐시 활성화의 몇 가지 이점입니다.

3scale Istio Adapter에서 관리하는 서비스에 액세스하는 동안 대기 시간이 길면 백엔드 캐시를 활성화합니다.
백엔드 캐시를 활성화하면 어댑터가 3scale API 관리자의 요청 승인을 계속 확인하지 못하므로 대기 시간이 줄어듭니다.
- 이렇게 하면 3scale Istio Adapter가 3scale API 관리자에게 권한 부여를 요청하기 전에 저장 및 재사용할 수 있도록 3scale 권한 부여의 메모리 내 캐시가 생성됩니다. 권한 부여는 승인 또는 거부에 소요되는 시간이 훨씬 짧습니다.
백엔드 캐싱은 3scale Istio Adapter를 실행하는 서비스 메시와 다른 지리적 위치에서 3scale API 관리자를 호스팅할 때 유용합니다.
- 일반적으로 3scale Hosted(SaaS) 플랫폼과 관련이 있지만 사용자가 다른 지리적 위치나 다른 가용성 영역에 있는 다른 클러스터에서 3scale API 관리자를 호스팅하거나 네트워크 오버헤드가 3scale API 관리자의 눈에 띄는 경우도 있습니다.

1.21.6.2. 대기 시간을 줄이기 위한 절충

다음은 대기 시간을 더 줄이기 위한 절충안입니다.

플러시가 발생할 때마다 3scale 어댑터의 권한 부여 상태 업데이트.
- 즉, 두 개 이상의 어댑터 인스턴스가 플러시 간격 간에 부정확함을 발생시킵니다.
- 제한을 초과하고 비정상적인 동작을 유발하는 요청이 너무 빈번하게 허용될 가능성이 커져, 각 요청을 처리하는 어댑터에 따라 어떤 요청은 통과하고, 어떤 요청은 통과하지 않습니다.
데이터를 플러시하고 권한 부여 정보를 업데이트할 수 없는 어댑터 캐시는 API 관리자에게 해당 정보를 보고하지 않고 종료되거나 중단될 수 있습니다.
API 관리자에 연결할 때 네트워크 연결 문제로 인해 어댑터 캐시가 요청 허용/거부 여부를 결정할 수 없는 경우 페일오픈 또는 페일클로즈 정책이 적용됩니다.
일반적으로 어댑터를 부팅한 직후나 연결이 장기간 끊긴 뒤에 캐시 누락이 발생하면, API 관리자에게 쿼리하기 위해 대기 시간이 늘어납니다.
어댑터 캐시는 활성화된 캐시가 없을 때보다 컴퓨팅 권한 부여에 훨씬 더 많은 작업을 수행해야 프로세서 리소스에 부담이 됩니다.
메모리 요구 사항은 캐시로 관리되는 제한, 애플리케이션 및 서비스 조합에 비례하여 증가합니다.

1.21.6.3. 백엔드 캐시 구성 설정

다음 포인트는 백엔드 캐시 구성 설정을 설명합니다.

3scale 구성 옵션에서 백엔드 캐시를 구성하는 설정을 찾습니다.
마지막 3가지 설정에서 백엔드 캐시 활성화를 제어합니다.
- PARAM_USE_CACHE_BACKEND - 백엔드 캐시를 활성화하려면 true로 설정합니다.
- PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS - 캐시 데이터를 API 관리자에 플러시하려는 연속 시도 사이의 시간(초)을 설정합니다.
- PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED - 캐시 데이터가 충분하지 않고 3scale API 관리자에 연결할 수 없는 경우 서비스 요청을 허용/열기 또는 거부/종료 여부를 설정합니다.

1.21.7. 3scale Istio Adapter APIcast 에뮬레이션

3scale Istio Adapter는 다음과 같은 상태가 발생하는 경우 APIcast를 수행합니다.

요청이 정의된 매핑 규칙과 일치할 수 없는 경우 반환되는 HTTP 코드는 404 Not Found입니다. 이전에는 403 Forbidden이었습니다.
제한을 초과하여 요청이 거부되면 반환된 HTTP 코드는 429 Too Many Requests입니다. 이전에는 403 Forbidden이었습니다.
CLI를 통해 기본 템플릿을 생성할 때 헤더에 대시 대신 밑줄을 사용합니다(예: user-key 대신 user_key).

1.21.8. 3scale Istio 어댑터 검증

3scale Istio 어댑터가 예상대로 작동하는지 확인해야 할 수 있습니다. 어댑터가 작동하지 않는 경우 다음 단계를 사용하여 문제를 해결합니다.

절차

```
$ oc get pods -n <istio-system>
```
3scale-adapter Pod에서 버전과 같이 자체 부팅에 대한 정보를 출력했는지 확인합니다.
```
$ oc logs <istio-system>
```
3scale 어댑터 통합으로 보호되는 서비스에 대한 요청을 수행할 때 항상 올바른 인증 정보가 없는 요청을 시도하여 실패하는지 확인합니다. 3scale 어댑터 로그를 확인하여 추가 정보를 수집합니다.