운영 가이드

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

Apigee Edge 문서 보기

API 키를 가져오는 방법

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

1. Apigee에 로그인

Apigee UI에 로그인합니다.
Envoy용 Apigee 어댑터를 프로비저닝하는 데 사용된 것과 동일한 조직을 선택합니다.

2. 개발자 만들기

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

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

3. API 제품 만들기

아래에 제공된 제품 만들기 예시를 따르세요.

측면 탐색 메뉴에서 게시 > API 제품을 선택합니다.
+만들기를 클릭합니다.

다음과 같이 제품 세부정보 섹션을 작성합니다. 다음 표에는 필수 입력란만 나와 있습니다.

필드	값	설명
이름	`httpbin-product`	API 제품의 고유한 이름입니다.
표시 이름	`httpbin product`	UI 또는 기타 표시 컨텍스트에서 보려는 설명이 포함된 이름입니다.
액세스	`Public`	이 예시에서는 공개를 선택하는 것이 좋습니다.

작업 섹션에서 작업 추가를 클릭합니다.
소스 섹션에서 원격 서비스를 선택합니다.
원격 서비스 필드에 원격 서비스 이름을 직접 입력할 수 있도록 소스 전환 버튼을 변경합니다.
원격 서비스 필드에 원격 서비스 이름을 입력합니다. 어댑터가 수신되는 HTTP 요청을 프록시하는 대상 서비스입니다. 테스트를 위해 Kubernetes에서 httpbin.org 또는 httpbin.default.svc.cluster.local를 사용합니다.
작업 섹션에서 경로에 /를 입력합니다. 경로 옵션에 대한 자세한 내용은 리소스 경로 구성을 참조하세요.
저장을 클릭하여 작업을 저장합니다.
저장을 클릭하여 API 제품을 저장합니다.

자세한 내용은 API 제품 관리를 참조하세요.

4. 개발자 앱 만들기

개발자 앱에는 어댑터를 통해 API 프록시를 호출하는 데 필요한 API 키가 포함됩니다.

측면 탐색 메뉴에서 게시 앱을 선택합니다.
+앱을 클릭합니다.
다음과 같이 앱 세부정보 섹션을 작성합니다. 다음 표에는 필수 입력란만 나와 있습니다.

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

사용자 인증 정보 섹션에서 + 제품 추가를 클릭하고 방금 구성한 제품 httpbin-product를 선택합니다.
만들기를 클릭합니다.
사용자 인증 정보에서 키 옆에 있는 표시를 클릭합니다.
고객 키의 값을 복사합니다. 이 값은 Envoy용 Apigee 어댑터를 통해 httpbin 서비스에 API 호출을 수행하는 데 사용할 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-token/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 has 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 키 실패를 참조하세요.

자체 ID 공급업체 사용

기본적으로 Envoy용 Apigee 어댑터는 ID 공급업체 서비스로 remote-token API 프록시를 사용하여 클라이언트 애플리케이션을 인증하고 OAuth 2.0 클라이언트 사용자 인증 정보 부여 유형을 기반으로 JWT 토큰을 제공합니다. 그러나 remote-token 프록시를 사용하지 못할 수도 있습니다. Apigee에서 제공하는 ID 공급업체가 아닌 ID 공급업체를 사용해야 하는 경우 다른 ID 공급업체를 사용하도록 어댑터를 구성할 수 있습니다. Apigee 이외의 ID 공급업체 사용 사례 및 필수 구성에 대한 자세한 내용은 Apigee 커뮤니티 문서 Apigee Envoy Adapter로 자체 ID 공급업체 사용을 참조하세요.

로깅

$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 애널리틱스에 대한 자세한 내용은 애널리틱스 서비스 개요를 참조하세요.

멀티 테넌트 환경 지원

이제 어댑터를 사용 설정하여 Apigee 조직에 여러 환경을 제공할 수 있습니다. 이 기능을 사용하면 Apigee 조직 하나와 연결된 Envoy용 Apigee 어댑터 하나를 사용하여 여러 환경을 제공할 수 있습니다. 이 변경사항 이전에는 어댑터 하나가 항상 Apigee 환경 하나에 연결되었습니다.

여러 환경 지원을 구성하려면 config.yaml 파일에서 tenant:env_name 값을 "*"로 변경합니다. 예를 들면 다음과 같습니다.

편집기에서 config.yaml 파일을 엽니다.

tenant.env_name 값을 "*"로 변경합니다. 예를 들면 다음과 같습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token

파일을 저장합니다.
파일을 적용합니다.
```
kubectl apply -f $CLI_HOME/config.yaml
```

멀티 환경 모드를 구성하는 경우 envoy-config.yaml 파일의 virtual_hosts:routes 섹션에 다음 메타데이터를 추가하여 Envoy에서 어댑터에 적절한 환경 값을 전송하도록 구성해야 합니다. 예를 들면 다음과 같습니다.

CLI를 사용하여 envoy-config.yaml 파일을 생성합니다. 예를 들면 다음과 같습니다.

$CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs

생성된 파일(envoy-config.yaml)을 엽니다.

파일의 virtual_host 또는 routes 섹션에 다음 메타데이터를 추가합니다.

typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

다음 예시에서는 여러 경로가 정의된 virtual_host의 구성을 보여줍니다. 여기서 각 경로는 트래픽을 특정 환경으로 보냅니다.

filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod

필요에 맞게 마지막 단계를 반복하여 환경을 추가합니다.
파일을 저장하고 적용합니다.
참고: config.yaml의 env_name을 "*" 이외의 다른 값으로 설정하면 어댑터가 Envoy에 오류를 반환하고 어댑터의 env_name 구성이 "*"로 설정되지 않았거나 env_name 속성이 전달된 apigee_environment 메타데이터와 일치하지 않으면 요청이 거부됩니다.

커스텀 보고서의 데이터 캡처

어댑터는 Envoy 메타데이터를 Apigee의 데이터 캡처 기능으로 전달할 수 있습니다. 이 기능은 커스텀 보고서에 사용할 수 있도록 Apigee 분석으로 지정한 변수에 캡처된 데이터를 전송합니다. 이 기능은 Apigee 데이터 캡처 정책과 유사한 기능을 제공합니다.

이 기능을 사용하려면 다음 안내를 따르세요.

데이터 수집기 REST 리소스를 만듭니다.
Apigee datacollectors API를 사용하여 데이터 캡처 변수를 정의합니다.
아직 만들지 않았으면 CLI를 사용하여 envoy-config.yaml 파일을 생성합니다. 예를 들면 다음과 같습니다.
```
$CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
```
생성된 파일(envoy-config.yaml)을 엽니다.

Envoy 필터를 사용하여 envoy.filters.http.apigee.datacapture 네임스페이스의 커스텀 변수 값을 설정합니다. 예를 들어 Header to Metadata 필터나 Lua 필터를 사용할 수 있습니다. 이러한 필터에 대한 자세한 내용은 Header-To-Metadata 및 Lua를 참조하세요.

커스텀 변수 이름은 dc.XXXXX 형식이어야 합니다.

Header to Metadata 필터 예시는 다음과 같습니다.

 - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

Lua 필터 예시는 다음과 같습니다.

- name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end

파일에 원하는 필터를 추가합니다. 아래 예를 참조하세요.
파일을 저장하고 적용합니다.

어댑터와 Apigee 런타임 간에 mTLS 구성

어댑터의 config.yaml 파일에 있는 tenant 섹션에 클라이언트 측 TLS 인증서를 제공하여 어댑터와 Apigee 런타임 간에 mTLS를 사용할 수 있습니다. 이 변경사항은 지원되는 모든 Apigee 플랫폼에 적용됩니다. 또한 프라이빗 클라우드용 Apigee Edge 플랫폼 분석에 mTLS를 사용 설정합니다. 예를 들면 다음과 같습니다.

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false