2.11. 3scale Istio 어댑터 사용

주의

더 이상 지원되지 않는 Red Hat OpenShift Service Mesh 릴리스에 대한 문서를 보고 있습니다.

서비스 메시 버전 1.0 및 1.1 컨트롤 플레인은 더 이상 지원되지 않습니다. 서비스 메시 컨트롤 플레인 업그레이드에 대한 자세한 내용은 서비스 메시 업그레이드를 참조하십시오.

특정 Red Hat OpenShift Service Mesh 릴리스의 지원 상태에 대한 자세한 내용은 제품 라이프사이클 페이지를 참조하십시오.

3scale Istio Adapter는 Red Hat OpenShift Service Mesh 내에서 실행되는 서비스에 레이블을 지정하고 해당 서비스를 3scale API 관리 솔루션과 통합할 수 있는 선택적 어댑터입니다. Red Hat OpenShift Service Mesh에는 필요하지 않습니다.

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

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

사전 요구 사항

  • Red Hat OpenShift Service Mesh 버전 1.x
  • 작업 중인 3scale 계정(SaaS 또는 3scale 2.5 on-Premises)
  • 백엔드 캐시를 활성화하려면 3scale 2.9 이상 필요
  • Red Hat OpenShift Service Mesh 사전 요구 사항
참고

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

참고

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

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

절차

  1. 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를 사용하려는 경우 유용할 수 있습니다.

  2. 다음과 같이 3scale 계정에 속하는 서비스의 배포 리소스를 편집하거나 패치합니다.

    1. 유효한 service_id에 해당하는 값을 사용하여 "service-mesh.3scale.net/service-id" 레이블을 추가합니다.
    2. 1단계에서 처리기 리소스의 이름이 값이 되도록 "service-mesh.3scale.net/credentials" 레이블을 추가합니다.
  3. 더 많은 서비스를 추가하려는 경우 2단계를 수행하여 3scale 계정 인증 정보 및 서비스 식별자에 연결합니다.

  4. 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

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

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

표 2.16. 사용법

옵션설명필수 항목기본값

-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 버전을 출력하고 즉시 종료합니다.

아니요

 
2.11.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]"

추가 리소스

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

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

  1. 이 명령을 실행하여 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}
  2. 터미널에 샘플 출력이 생성됩니다. 필요한 경우 이러한 샘플을 편집하고 oc create 명령을 사용하여 오브젝트를 생성합니다.

  3. 요청이 어댑터에 도달하면 어댑터는 서비스가 3scale의 API에 매핑되는 방식을 알아야 합니다. 다음 두 가지 방법으로 이러한 정보를 제공할 수 있습니다.

    1. 워크로드에 레이블 지장(권장)
    2. 처리기를 service_id로 하드 코딩

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

    참고

    처리기에 아직 포함되지 않은 경우, 이 예제에 제공된 서비스 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}"''

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

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

사전 요구 사항

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

절차

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

2.11.2. 3scale로 통합 설정 구성

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

참고

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

절차

  1. [your_API_name] → 통합으로 이동합니다.
  2. 설정을 클릭합니다.

  3. 배포에서 Istio 옵션을 선택합니다.

    • 인증에서 API Key (user_key) 옵션은 기본적으로 선택됩니다.
  4. 제품 업데이트를 클릭하여 선택 사항을 저장합니다.
  5. 설정을 클릭합니다.
  6. 구성 업데이트를 클릭합니다.

2.11.3. 캐싱 동작

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

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

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

2.11.4. 요청 인증

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

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

2.11.4.1. 인증 패턴 적용

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

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

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

2.11.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"]로 변경합니다.

2.11.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"]로 변경합니다.

2.11.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

2.11.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"] | ""

2.11.5. 3scale Adapter 지표

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

2.11.6. 3scale Istio 어댑터 검증

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

절차

  1. Service Mesh Control Plane 네임스페이스에서 3scale-adapter Pod가 실행 중인지 확인합니다. 

    $ oc get pods -n <istio-system>

  2. 3scale-adapter Pod에서 버전과 같이 자체 부팅에 대한 정보를 출력했는지 확인합니다. 

    $ oc logs <istio-system>
  3. 3scale 어댑터 통합으로 보호되는 서비스에 대한 요청을 수행할 때 항상 올바른 인증 정보가 없는 요청을 시도하여 실패하는지 확인합니다. 3scale 어댑터 로그를 확인하여 추가 정보를 수집합니다.

추가 리소스

2.11.7. 3scale Istio 어댑터 문제 해결 체크리스트

3scale Istio 어댑터를 설치하는 관리자는 통합이 제대로 작동하지 않을 수 있는 여러 시나리오가 있습니다. 다음 목록을 사용하여 설치 문제를 해결합니다.

  • YAML 들여쓰기가 잘못되었습니다.
  • YAML 섹션이 누락되었습니다.
  • YAML 변경 사항을 클러스터에 적용하는 것을 잊어버렸습니다.
  • service-mesh.3scale.net/credentials 키를 사용하여 서비스 워크로드의 레이블을 지정하는 것을 잊어버렸습니다.
  • 서비스 워크로드에 service_id가 포함되지 않은 처리기를 사용할 때 service-mesh.3scale.net/service-id로 레이블을 지정하여 계정별로 재사용할 수 있도록 하는 것을 잊었버렸습니다.
  • Rule 사용자 지정 리소스는 잘못된 처리기 또는 인스턴스 사용자 지정 리소스를 가리키거나 참조에 해당 네임스페이스 접미사가 없습니다.
  • Rule 사용자 정의 리소스 match 섹션은 구성 중인 서비스와 일치하지 않거나 현재 실행 중이거나 존재하지 않는 대상 워크로드를 가리킵니다.
  • 처리기의 3scale 관리 포털의 잘못된 액세스 토큰 또는 URL입니다.
  • 인스턴스 사용자 정의 리소스의 params/subject/properties 섹션은 쿼리 매개 변수, 헤더 및 권한 부여 클레임과 같은 잘못된 위치를 지정하거나 매개 변수 이름이 테스트에 사용되는 요청과 일치하지 않기 때문에 app_id, app_key, 또는 client_id에 대한 올바른 매개 변수를 나열하지 못합니다.
  • 구성 생성기가 실제로 어댑터 컨테이너 이미지에 있고 oc exec 호출 해야 한다는 사실을 인식하지 못한 채 구성 생성기를 사용하지 못했습니다 .