Apigee Connect

이 섹션에서는 하이브리드 관리 영역과 런타임 영역의 MART 서비스 사이의 통신을 위해 Apigee Connect를 사용하는 방법을 설명합니다.

소개

Apigee Connect를 사용하면 인터넷에 MART 엔드포인트를 노출할 필요 없이 Apigee Hybrid 관리 영역을 런타임 영역의 MART 서비스에 안전하게 연결할 수 있습니다. Apigee Connect를 사용할 경우 호스트 별칭 및 승인된 DNS 인증서로 MART 인그레스 게이트웨이를 구성할 필요가 없습니다.

Apigee Connect가 표시된 하이브리드 런타임 영역에서 실행되는 기본 서비스

기본 요건

Apigee Hybrid 1.2.0 이상

하이브리드 런타임에 Apigee Connect 추가

Apigee Connect는 Apigee Hybrid 버전 1.3.0 이상을 새로 설치할 때 기본적으로 사용 설정됩니다. 따라서 이 단계는 이전 버전에서 업그레이드하는 경우에만 필요할 수 있습니다.

Apigee Connect가 구성되었고 사용 설정되었으면 MART 인그레스가 무시됩니다. 관리 영역은 Apigee Connect를 사용해서만 MART에 연결됩니다. 하이브리드 런타임 영역 간의 모든 MART 트래픽은 안전한 Apigee Connect 연결을 통해 전달됩니다.

Apigee Hybrid에서 Apigee Connect를 사용 설정하고 사용하려면 다음 단계를 따르세요.

Google Cloud API 라이브러리에서 Apigee Connect API를 사용 설정합니다. Google Cloud 콘솔 또는 gcloud를 사용하여 API를 사용 설정할 수 있습니다. Google Cloud 콘솔에서 API 사용 설정에 대한 자세한 내용은 3단계: API 사용 설정을 참조하세요. gcloud를 사용해서 API를 사용 설정하려면 다음 안내를 따르세요.
1. gcloud에서 현재 프로젝트를 Apigee가 사용 설정되었고 Apigee 조직이 프로비저닝된 동일한 Google Cloud 프로젝트로 설정합니다.
```
$ gcloud config set project YOUR_GCP_PROJECT_ID
```
  여기서 YOUR_GCP_PROJECT_ID는 프로젝트 ID입니다.
2. Apigee Connect API가 이미 사용 설정되었는지 확인합니다.
```
gcloud services list
```
```
NAME                                 TITLE
apigee.googleapis.com                Apigee API
apigeeconnect.googleapis.com         Apigee Connect API
bigquery.googleapis.com              BigQuery API

...
```
3. 결과에 apigeeconnect.googleapis.com이 없으면 API를 사용 설정합니다.
```
$ gcloud services enable apigeeconnect.googleapis.com
```

Apigee Hybrid 설치 안내의 서비스 계정 만들기 단계에서 만든 MART 서비스 계정에 Apigee Connect 에이전트 역할을 추가합니다.

필요한 경우 MART 서비스 계정의 이메일 주소를 가져옵니다.

gcloud iam service-accounts list

NAME                          EMAIL                                                 DISABLED
apigee-mart                   apigee-mart@hybrid-example.iam.gserviceaccount.com       False

...

MART 서비스 계정에 이미 역할이 할당되었는지 확인합니다.

gcloud projects get-iam-policy YOUR_GCP_PROJECT_ID

...

- members:
  - serviceAccount:apigee-mart@hybrid-example.iam.gserviceaccount.com
  role: roles/apigeeconnect.Agent

...

결과에 role: roles/apigeeconnect.Agent가 없으면 역할을 할당합니다.
```
gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT_ID \
--member serviceAccount:YOUR_MART_SERVICE_ACCOUNT_EMAIL --role roles/apigeeconnect.Agent
```
여기서 YOUR_GCP_PROJECT_ID는 Google Cloud 프로젝트의 ID이고 YOUR_MART_SERVICE_ACCOUNT_EMAIL은 MART 서비스 계정 이메일 주소입니다.

Apigee Connect 에이전트 역할은 사전 정의되어 있으며 다음 권한이 할당됩니다.

권한	설명
`apigeeconnect.endpoints.connect`	Apigee Connect 에이전트를 설정할 수 있는 권한입니다.

Google Cloud 콘솔 또는 API를 통한 액세스 권한 부여 할당에 대한 자세한 내용은 다음을 참조하세요.

서비스 계정 만들기에 설명된 대로 MART 서비스 계정의 키 파일이 hybrid_files/service_accounts 디렉터리에 있는지 확인합니다.
재정의 파일을 엽니다. connectAgent:enabled 속성이 true로 설정되지 않았거나 누락되었으면 다음 스탠자를 추가하거나 업데이트합니다.
Apigee Connect 스탠자는 즉시 k8sCluster 스탠자를 따라야 합니다.

이 구성에서는 다운로드된 서비스 계정 키에 대한 경로를 제공해야 합니다. 키는 Apigee Connect 에이전트 역할이 있는 서비스 계정에 사용되어야 합니다.
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  serviceAccountPath: ./service-accounts/MART_SA_KEYFILE.json
```
참고: 기본적으로 replicaCountMin 1이 connectAgent에 사용됩니다. 프로덕션 배포와 같은 다른 사용 사례에서는 replicaCountMin을 3으로 변경하세요. 예를 들면 다음과 같습니다.
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  replicaCountMin: 3
  serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
```
조직에 Apigee Connect 기능을 사용 설정합니다. 기능 이름은 features.mart.connect.enabled입니다.
1. 동기화 담당자 액세스 사용 설정 섹션에 설명된 대로 Apigee Hybrid를 처음 설치할 때 사용한 Apigee 조직 관리자 역할이 있는 서비스 계정 키를 찾습니다. 이것은 apigee-org-admin 서비스 계정입니다. 아래 설명된 대로 API 호출을 수행하는 데 필요한 토큰을 생성하려면 이 키가 필요합니다.
2. 다음 두 명령어를 실행하여 토큰을 가져옵니다.
```
export GOOGLE_APPLICATION_CREDENTIALS=org-admin-service-account-file
$ export TOKEN=$(gcloud auth application-default print-access-token)
```
  여기서 org-admin-service-account-file은 시스템에서 Apigee 조직 관리자 역할이 있는 서비스 계정 키에 대한 경로입니다.
3. Apigee Connect가 이미 사용 설정되었는지 확인합니다.
```
curl  https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Authorization: Bearer $TOKEN"
```
  결과를 확인합니다.
```
  "properties": {
    "property": [
      {
        "name": "features.mart.connect.enabled",
        "value": "true"
      },
      {
        "name": "features.hybrid.enabled",
        "value": "true"
      }
    ]
  },
```
4. 결과에 true로 설정된 features..mart.connect.enabled가 없으면 다음 Apigee API를 호출하여 조직에 Apigee Connect를 사용 설정합니다.
```
curl -v -X PUT \
   https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "name" : "your_org_name",
  "properties" : {
    "property" : [ {
      "name" : "features.hybrid.enabled",
      "value" : "true"
    }, {
      "name" : "features.mart.connect.enabled",
      "value" : "true"
    } ]
  }
}'
```
  참고: 권장사항은 원래 MART 엔드포인트 속성을 요청 본문에 두는 것입니다. 그렇지 않으면 원래 MART 구성 속성이 손실됩니다. Apigee Connect가 사용 설정되었으면 MART 서버 엔드포인트 구성이 무시됩니다. 관리 영역은 MART 서비스 엔드포인트 대신 Apigee Connect를 통해 MART 서버와 연결됩니다.
  팁: 기존 Apigee Hybrid 설치를 업그레이드하는 경우, Apigee Connect 사용을 중지하고 MART Istio 인그레스 엔드포인트 사용으로 직접 되돌리는 기능을 남겨둘 수 있습니다. 이렇게 하려면 다음과 같이 MART 서비스 엔드포인트에 대해 이름 값 쌍을 포함합니다.
```
curl -v -X PUT \
   https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "name" : "your_org_name",
  "properties" : {
    "property" : [ {
      "name" : "features.hybrid.enabled",
      "value" : "true"
    }, {
      "name" : "features.mart.server.endpoint",
      "value" : "https://HOST_ALIAS_DNS"
    }, {
      "name" : "features.mart.connect.enabled",
      "value" : "true"
    } ]
  }
}'
```
클러스터에서 Apigee Connect 에이전트를 시작합니다.
위 단계 중에서 항목을 변경한 경우에는 다음 명령어를 사용해서 Apigee Connect 에이전트를 시작합니다.
```
 $APIGEECTL_HOME/apigeectl apply -f your_overrides_file.yaml --org
```

참고: Apigee Connect가 사용 설정된 상태에서 mart 구성 스탠자는 serviceAccountPath 값만 포함하면 됩니다. 다른 값은 무시되며 생략 가능합니다.

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"  # ignored when Apigee Connect is enabled.
  serviceAccountPath: ./service-accounts/example-project-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem  # ignored when Apigee Connect is enabled.
  sslKeyPath: ./certs/privkey.key  # ignored when Apigee Connect is enabled.

Apigee Connect 에이전트 로그를 확인합니다. 보고된 오류가 없으면 업그레이드가 성공합니다.
```
kubectl logs -n namespace apigee-connect-agent-pod-name
```
Apigee Connect 에이전트에서 다음 로그 카테고리를 보고합니다.

감사 로그 카테고리 작업

DATA_READ ConnectionService.ListConnections

DATA_WRITE Tether.Egress

Apigee Hybrid에서 감사 로그 확인에 대한 자세한 내용은 감사 로깅 정보를 참조하세요.

감사 로그 카테고리	작업
DATA_READ	`ConnectionService.ListConnections`
DATA_WRITE	`Tether.Egress`

이 업그레이드를 사용하면 하이브리드 런타임 영역이 Apigee Connect를 통해 관리 영역과 통신합니다.

설치를 테스트합니다.

참조: Apigee Connect 제거

설치 테스트

Apigee Hybrid UI를 엽니다.
이전에 만든 개발자 및 개발자 앱이 UI에 있는지 확인합니다. 이러한 항목은 MART 서버에서 쿼리되었기 때문에 관리 영역과 런타임 영역 간 통신이 올바르게 구성된 경우에만 제공됩니다.

요청이 MART 인그레스가 아니라 Apigee Connect를 통과하는지 확인하려면 MART 서버 로그를 확인합니다. apigee-connect-agent-1.0이라는 Apigee Connect 에이전트에 대한 항목이 표시됩니다.

kubectl logs -n apigee apigee-mart-orgname-rc101-q72tl --org | grep connect

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

"2020-07-31 04:59:52,321 org: env: target: action: context-id: mode: pool-1-thread-1 INFO.
gserviceaccount.com 1576040392317 /v1/organizations/apigee-connect-hybrid-prod/developers/
count=100&expand=true&startKey=4ee9e8f7-12b2-4cde-bf10-32d991469876 200 GET apigee-connect
-hybrid-prod 10.40.11.3 10.40.0.5 apigee-connect-agent-1.0 null"

승인 토큰을 새로고침합니다.

export TOKEN=$(gcloud auth application-default print-access-token)

Apigee API를 호출하여 apigee-mart 엔드포인트에 사용 가능한 스트리밍 연결을 확인합니다.

curl -s https://apigeeconnect.googleapis.com/v1/projects/YOUR_GCP_PROJECT_ID/endpoints/apigee_mart/connections \
  -H "Authorization: Bearer $TOKEN"

{
  "connections": [
    {
      "endpoint": "projects/865098068308/endpoints/apigee_mart",
      "cluster": {
        "name": "apigee-connect-test-cluster2",
        "region": "australia-southeast1"
      },
      "streamCount": 4
    },
    {
      "endpoint": "projects/865098068308/endpoints/apigee_mart",
      "cluster": {
        "name": "apigee-connect-test-cluster",
        "region": "us-central1"
      },
      "streamCount": 2
    }
  ]
}

Apigee Connect 에이전트 로그를 확인합니다.

kubectl logs -n namespace apigee-connect-agent-YOUR_GCP_PROJECT_ID-<....>

다음 로그는 Apigee Connect 에이전트가 시작되었고 올바르게 통신하고 있음을 나타냅니다.

I0719 11.66:10.765526 2314949 main.go:47] Agent's flag values below
I0719 11.66:10.765928 2314949 main.go:50] "alsologtostderr" : false
I0719 11.66:10.765940 2314949 main.go:50] "cluster_name" : testABC
I0719 11.66:10.765947 2314949 main.go:50] "cluster_region" : us-west2
I0719 11.66:10.765953 2314949 main.go:50] "cpu_profile_enabled" : false
I0719 11.66:10.765959 2314949 main.go:50] "http_client_timeout" : 2m0s
I0719 11.66:10.765966 2314949 main.go:50] "http_port" : 7070
I0719 11.66:10.765972 2314949 main.go:50] "http_server" : false
I0719 11.66:10.765978 2314949 main.go:50] "insecure_ssl" : false
I0719 11.66:10.765984 2314949 main.go:50] "local_cert" :
I0719 11.66:10.765990 2314949 main.go:50] "log_backtrace_at" : :0
I0719 11.66:10.766001 2314949 main.go:50] "log_dir" :
I0719 11.66:10.766007 2314949 main.go:50] "logtostderr" : true
I0719 11.66:10.766012 2314949 main.go:50] "mem_profile_enabled" : false
I0719 11.66:10.766018 2314949 main.go:50] "project" : projects/apigee-connect-hybrid-prod
I0719 11.66:10.766025 2314949 main.go:50] "resource_id" :
I0719 11.66:10.766031 2314949 main.go:50] "server_addr" : apigeeconnect.googleapis.com:443
I0719 11.66:10.766036 2314949 main.go:50] "server_cert" : ./server.crt
I0719 11.66:10.766042 2314949 main.go:50] "server_key" : ./server.key
I0719 11.66:10.766047 2314949 main.go:50] "stderrthreshold" : 2
I0719 11.66:10.766054 2314949 main.go:50] "target_server" : http://127.0.0.1/
I0719 11.66:10.766059 2314949 main.go:50] "tether_endpoint" : APIGEE_MART
I0719 11.66:10.766065 2314949 main.go:50] "v" : 0
I0719 11.66:10.766072 2314949 main.go:50] "vmodule" :
I0719 11.66:10.845441 2314949 agent.go:400] successfully initiated http client
I0719 11.66:10.845772 2314949 agent.go:728] starting metrics http server at ":7070"
I0719 11.66:11.231.69 2314949 agent.go:245] listening on tether 6407043920806543360
I0719 11.68:11.346544 2314949 agent.go:245] listening on tether 2101602677040349184
I0719 12:00:11.461084 2314949 agent.go:245] listening on tether 9109203697228840960
I0719 12:02:11.683743 2314949 agent.go:245] listening on tether 8978599308035096576
I0719 12:02:40.325633 2314949 agent.go:255] tether id 6407043920806543360 is closed

...

하이브리드 UI에서 API 제품, 개발자, 개발자 앱을 만듭니다. 그런 후 프록시에 대해 API 호출을 수행합니다.

요청을 처리하는 동안 생성된 Connect 에이전트 로그는 상태 또는 오류를 확인하는데 도움이 됩니다.

kubectl logs -n namespace apigee-connect-agent-YOUR_GCP_PROJECT_ID-<....>

INFO: 2020/04/13 03:29:08 "961ff385-600a-427a-8864-ba066ff42330": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:08 Attempting to send response 961ff385-600a-427a-8864-ba066ff42330 on
tether 16734438331890270208
INFO: 2020/04/13 03:29:09 "e2fc0492-6e78-4c58-972b-7de8258b9e86": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:09 Attempting to send response e2fc0492-6e78-4c58-972b-7de8258b9e86 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:10 "1ab3023b-b763-4b91-bf4f-ca8c02f62e50": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:10 Attempting to send response 1ab3023b-b763-4b91-bf4f-ca8c02f62e50 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:12 "1fa3e3c3-a36e-4ff1-b2d3-5cf14f2f8fdd": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:12 Attempting to send response 1fa3e3c3-a36e-4ff1-b2d3-5cf14f2f8fdd on
tether 16734438331890270208
INFO: 2020/04/13 03:29:13 "09b7ef9d-f53d-466a-a174-e88fc7e5286d": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:13 Attempting to send response 09b7ef9d-f53d-466a-a174-e88fc7e5286d on
tether 16734438331890270208
INFO: 2020/04/13 03:29:14 "c2ce8b73-8faf-4a05-88d9-24fb2bf45552": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:14 Attempting to send response c2ce8b73-8faf-4a05-88d9-24fb2bf45552 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:15 "fdc3bac5-2b83-4b57-a28d-d8b455dae71e": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:15 Attempting to send response fdc3bac5-2b83-4b57-a28d-d8b455dae71e on
tether 12483040283652521984
INFO: 2020/04/13 03:29:16 "260026a9-f578-4447-a1d2-d8e49cf181d8": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:16 Attempting to send response 260026a9-f578-4447-a1d2-d8e49cf181d8 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:17 "bf3d74a1-94ae-4041-892f-56f1ed9c9cff": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:17 Attempting to send response bf3d74a1-94ae-4041-892f-56f1ed9c9cff on
tether 16734438331890270208
INFO: 2020/04/13 03:29:18 "6d017278-3b7a-40fb-9c63-7c34320e7df1": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200

IAM 권한 거부 오류로 인해 에이전트가 충돌하고 Connect 에이전트 오류로 생성된 로그:

F0719 12:34:33.128565 2326128 tether.go:29] failed to register stream with Apigee Connect, got
'PermissionDenied': rpc error: code = PermissionDenied desc = Permission denied on resource '//
apigeeconnect.googleapis.com/projects/apigee-connect-hybrid-prod/endpoints/APIGEE_MART' (or it
may not exist).

F0719 12:34:33.128565 2326128 tether.go:29] failed to register stream with Apigee Connect, got
'PermissionDenied': rpc error: code = PermissionDenied desc = Permission denied on resource pro
ject apigee-connect-hybrid-prod.

Apigee Connect 삭제

Apigee Connect 배포를 삭제할 경우 pod 상태는 최대 7분 동안 '종료 중' 상태로 유지될 수 있습니다. 이 시간은 예상 값입니다. Apigee Connect 에이전트는 연결을 갑자기 중지하는 대신 기존 연결이 종료될 때까지 기다립니다. 이러한 지연 시간은 진행 중인 요청이 손실되지 않도록 보장합니다.