운영 가이드

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

API 키를 가져오는 방법

다음 예시에서는 Envoy용 Apigee 어댑터를 통해 프록시된 대상 서비스에 대한 API 호출을 검증하는 데 사용할 수 있는 API 키를 가져오는 방법을 설명합니다.

1. Apigee에 로그인

브라우저에서 Apigee UI를 엽니다.
UI에서 Envoy용 Apigee 어댑터를 구성하는 데 사용된 조직과 동일한 조직을 선택합니다.

2. 개발자 만들기

기존 개발자를 테스트에 사용하거나 다음과 같이 새 개발자를 만들 수 있습니다.

측면 탐색 메뉴에서 게시 > 개발자를 선택합니다.
+ Developer를 클릭합니다.
새 개발자를 만들려면 대화상자를 작성합니다. 원하는 모든 개발자 이름/이메일을 사용할 수 있습니다.

3. API 제품 만들기

아래에 제공된 제품 만들기 예시를 따르세요. API 제품 구성 정보도 참조하세요.

측면 탐색 메뉴에서 게시 > API 제품을 선택합니다.
+API 제품을 클릭합니다.
다음과 같이 제품 세부정보 페이지를 작성합니다. 안내되기 전까지 저장을 클릭하지 않습니다.

필드	값
Name	`httpbin-product`
표시 이름	`httpbin product`
환경	`your_environment` `apigee-remote-service-cli`로 Envoy용 Apigee 어댑터를 프로비저닝할 때 사용한 환경으로 설정합니다.
액세스	`Private`
할당량	1분마다 요청 5개 API 제품 구성 정보도 참조하세요.

Apigee 원격 서비스 대상 섹션에서 Apigee 원격 서비스 대상 추가를 클릭합니다.

Apigee 원격 서비스 대상 대화상자에 다음 값을 추가합니다.

속성	값	설명
대상 이름	대상 서비스의 이름을 입력합니다. 예를 들면 `httpbin.org`입니다.	Envoy 프록시로 인해 앞쪽에 배치된 대상 엔드포인트입니다.
API 프록시	`remote-service`	Envoy 어댑터를 설치하는 동안 Apigee에 프로비저닝된 `remote-service` 프록시입니다.
경로	특정 경로와 일치하도록 `/resource_path`를 입력합니다. 예를 들면 `/httpbin`입니다.	대상 엔드포인트에서 일치시킬 요청 경로입니다. 이 경로의 API 프록시 호출은 이 API 제품과 일치합니다.

저장을 클릭합니다.

4. 개발자 앱 만들기

측면 탐색 메뉴에서 게시 > 앱을 선택합니다.
+앱을 클릭합니다.
다음과 같이 개발자 앱 페이지를 작성합니다. 안내되기 전까지 저장하지 않습니다.

Name	`httpbin-app`
표시 이름	`httpbin app`
개발자	이전에 만든 개발자를 선택하거나 목록에서 원하는 개발자를 선택합니다.

다음으로 앱에 제품 2개를 추가합니다.
1. 먼저 사용자 인증 정보 섹션에서 + 제품 추가를 클릭하고 방금 구성한 제품 httpbin-product를 선택합니다.
2. 그런 다음 remote-service 제품을 추가합니다. Apigee를 프로비저닝할 때 이 제품이 자동으로 생성되었습니다.
만들기를 클릭합니다.
사용자 인증 정보에서 키 옆에 있는 표시를 클릭합니다.
고객 키의 값을 복사합니다. 이 값은 httpbin 서비스에 API를 호출하기 위해 사용할 API 키입니다.

API 제품 정보

API 제품은 Apigee 원격 서비스의 기본 제어 지점입니다. API 제품을 만들고 대상 서비스에 결합하는 경우 Envoy용 Apigee 어댑터를 처리하도록 구성하는 모든 요청에 적용되는 정책을 만듭니다.

API 제품 정의

Apigee에서 API 제품을 정의할 때 요청을 평가하는 데 사용되는 여러 매개변수를 설정할 수 있습니다.

대상
요청 경로
할당량
OAuth 범위

원격 서비스 대상

요청이 대상 결합(예: httpbin.org)과 요청 경로(예: /httpbin)와 일치하는 경우 API 제품 정의가 요청에 적용됩니다. 잠재적 대상의 목록은 API 제품에 속성으로 저장됩니다.

기본적으로 Apigee 원격 서비스는 Envoy의 특별한 :authority (host) 헤더를 대상 목록과 비교하여 확인하지만 다른 헤더를 사용하도록 구성할 수 있습니다.

API 리소스 경로

입력된 경로가 다음 규칙에 따라 일치됩니다.

단일 슬래시(/)는 단독으로 모든 경로와 일치합니다.
*은 어디서나 유효하고 세그먼트 내에서 일치합니다(슬래시 간).
**은 끝에서 유효하며 줄 끝의 모든 항목과 일치합니다.

할당량

할당량은 앱이 시간, 일, 주 또는 월 단위로 API에 제출할 수 있는 요청 메시지 수를 지정합니다. 앱이 할당량 한도에 도달하면 후속 API 호출이 거부됩니다.

할당량 사용 사례

할당량을 사용하면 클라이언트가 지정된 기간 동안 서비스에 보낼 수 있는 요청 수를 적용할 수 있습니다. 할당량은 운영 트래픽 관리가 아닌 개발자 및 파트너와의 비즈니스 계약 또는 SLA를 시행하는 데 자주 사용됩니다. 예를 들어 할당량을 사용하여 무료 서비스의 트래픽을 제한하면서 유료 고객에 대한 전체 액세스를 허용할 수 있습니다.

할당량은 API 제품에서 정의됨

할당량 매개변수는 API 제품에서 구성됩니다. 예를 들어 API 제품을 만들 때 허용되는 할당량 한도, 시간 단위, 간격을 선택적으로 설정할 수 있습니다.

Apigee UI의 할당량 한도 설정

API 키는 API 제품에 다시 매핑되므로 API 키가 확인될 때마다 적절한 할당량 카운터가 감소할 수 있습니다(연결된 제품에 할당량이 정의되어 있는 경우).

Apigee 런타임과 달리 제품 정의에 입력된 할당량은 Apigee 원격 서비스에서 자동으로 적용됩니다. 요청이 승인되면 요청은 허용된 할당량을 기준으로 산정됩니다.

할당량이 유지되는 위치

할당량은 원격 서비스 프로세스에 의해 로컬에서 유지관리 및 확인되며 Apigee 런타임으로 비동기식으로 유지관리됩니다. 즉, 할당량을 유지관리하는 원격 서비스가 두 개 이상 있는 경우 할당량은 정확하지 않으며 초과될 수 있습니다. Apigee 런타임 연결이 중단되면 로컬 할당량은 Apigee 런타임에 다시 연결될 때까지 독립 실행형 할당량으로 계속됩니다.

OAuth 범위

JWT 토큰을 사용하면 토큰을 허용된 OAuth 범위의 하위 집합으로 제한할 수 있습니다. 발급된 JWT 토큰에 할당된 범위가 API 제품의 범위에서 확인됩니다.

개발자 앱 정보

API 제품을 구성한 후 개발자와 연결된 앱을 만듭니다. 이 앱은 API 키 또는 JWT 토큰을 사용하여 연결된 API 제품에 대한 클라이언트 액세스를 허용합니다.

JWT 기반 인증 사용

API 키를 사용하는 대신 JWT 토큰을 사용하여 인증된 API 프록시 호출을 수행할 수 있습니다. 이 섹션에서는 apigee-remote-service-cli token 명령어를 사용하여 JWT 토큰을 생성, 검사, 순환하는 방법을 설명합니다. Apigee Hybrid 환경의 경우 이 명령어를 사용하여 JWT를 보관할 Kubernetes 보안 비밀을 만들 수 있습니다.

개요

JWT 확인 및 인증은 JWT 인증 필터를 사용하여 Envoy에서 처리됩니다.

인증 후 Envoy ext-authz 필터는 요청 헤더 및 JWT를 apigee-remote-service-envoy로 전송합니다. JWT의 api_product_list 및 scope 클레임과 요청의 대상에 대해 승인하기 위해 Apigee API 제품과 일치하는지 확인합니다.

Apigee JWT 토큰 만들기

CLI를 사용하여 Apigee JWT 토큰을 만들 수 있습니다.

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

또는 표준 OAuth 토큰 엔드포인트를 사용합니다. Curl 예시는 다음과 같습니다.

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

JWT 토큰 사용

토큰을 받은 후 Authorization 헤더의 Envoy에 전달합니다. 예를 들면 다음과 같습니다.

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

JWT 토큰 실패

Envoy 거부

Envoy가 토큰을 거부하는 경우 다음과 같은 메시지가 표시될 수 있습니다.

Jwks remote fetch is failed

이 경우 Envoy 구성의 remote_jwks 섹션에 유효한 URI가 포함되어 있고, Envoy에서 연결 가능하고, Apigee 프록시를 설치할 때 인증서를 올바르게 설정했는지 확인합니다. GET 호출로 URI를 직접 호출하여 유효한 JSON 응답을 받을 수 있어야 합니다.

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

curl https://myorg-eval-test.apigee.net/remote-service/certs

Envoy에서 보내는 다른 메시지는 다음과 같이 표시됩니다.

'Jwt의 잠재고객은 허용되지 않습니다.'
'Jwt 발급자가 구성되지 않았습니다.'

이러한 메시지는 수정해야 할 Envoy 구성의 요구사항에서 보내집니다.

토큰 검사

CLI를 사용하여 토큰을 검사할 수 있습니다. 예

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

또는

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

디버깅

유효한 API 키 실패를 참조하세요.

로깅

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy 서비스에서 로깅 수준을 조정할 수 있습니다. 모든 로깅은 stderr로 전송됩니다.

요소	필수	설명
-l, --log-level	유효한 수준: 디버그, 정보, 경고, 오류	로깅 수준을 조정합니다. 기본값: 정보
-j, --json-log		로그 출력을 JSON 레코드로 반환합니다.

Envoy는 로깅을 제공합니다. 자세한 내용은 다음 Envoy 문서 링크를 참조하세요.

정책 보안 비밀 이름 변경

클러스터에 배포된 Kubernetes 보안 비밀은 어댑터가 원격 서비스 프록시와의 통신을 인증하는 데 필요로 하는 사용자 인증 정보를 포함합니다. 이 보안 비밀은 구성 가능한 볼륨 마운트 지점을 필요로 합니다. 기본적으로 마운트 지점은 /policy-secret입니다. 마운트 지점을 변경하려면 다음 단계를 따르세요.

다음 명령어를 실행합니다.

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

예:

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

편집기에서 $CLI_HOME/samples/apigee-envoy-adapter.yaml을 엽니다.

마운트 지점 이름을 새 이름으로 변경합니다.

volumeMounts:
  - mountPath: /config
    name: apigee-remote-service-envoy
    readOnly: true
  - mountPath: /opt/apigee/tls
    name: tls-volume
    readOnly: true
  - mountPath: /my-mount-point
    name: policy-secret
    readOnly: true

파일을 저장하고 서비스 메시에 적용합니다.

kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

네트워크 프록시 사용

Apigee-remote-service-envoy 바이너리 환경에서 HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 사용하여 HTTP 프록시를 삽입할 수 있습니다. 이러한 경우 NO_PROXY 환경 변수는 특정 호스트가 프록시를 통해 전송되지 않도록 제외하는 데 사용될 수 있습니다.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

apigee-remote-service-envoy에서 프록시에 연결할 수 있어야 한다는 점을 기억하세요.

측정항목 및 분석 정보

Prometheus 측정항목 엔드포인트는 :5001/metrics에서 사용할 수 있으며, 이 포트 번호를 구성할 수 있습니다. 구성 파일을 참조하세요.

Envoy 애널리틱스

다음 링크는 Envoy 프록시 분석 데이터를 가져오는 방법을 설명합니다.

Istio 애널리틱스

다음 링크는 Envoy 프록시 분석 데이터를 가져오는 방법을 설명합니다.

Apigee 애널리틱스

Envoy용 Apigee 원격 서비스는 분석 처리를 위해 Apigee에 요청 통계를 보냅니다. Apigee에서는 연결된 API 제품 이름으로 이러한 요청을 보고합니다.

Apigee 애널리틱스에 대한 자세한 내용은 애널리틱스 서비스 개요를 참조하세요.