This section describes using Apigee Connect (Beta) for communication between the hybrid management plane and the MART service in the runtime plane.
Introduction
Apigee Connect allows the Apigee hybrid management plane to connect securely to the MART service in the runtime plane without requiring you to expose the MART endpoint on the internet. If you use Apigee Connect, you do not need to configure the MART ingress gateway with a host alias and an authorized DNS certificate.
Prerequisites
Apigee hybrid version1.2.0 or newer must be installed and configured before setting up Apigee Connect.
- If you are installing Apigee hybrid for the first time, follow the installation instructions in the Apigee hybrid documentation.
- If you are currently using Apigee hybrid version 1.1.x, you must upgrade your installation to version 1.2.0 before continuing. For the upgrade steps, see Upgrading Apigee hybrid
Add Apigee Connect to the hybrid runtime
This section assumes you have installed or upgraded to and configured Apigee hybrid 1.2.0 or newer
When Apigee Connect is configured and enabled, the MART ingress is ignored: the management plane only connects to MART using Apigee Connect. All MART traffic between the hybrid runtime plane passes through the secure Apigee Connect connection.
Follow these steps to enable and use Apigee Connect with Apigee hybrid:
- Enable the Apigee Connect API in the
Google Cloud API Library. You can enable the API in the
Google Cloud (GCP) console or with
gcloud
. For instructions on enabling APIs in the Google Cloud console, see Step 3: Enable APIs. To usegcloud
to enable the API:
$ gcloud config set project YOUR_GCP_PROJECT_ID $ gcloud services enable apigeeconnect.googleapis.com
WhereYOUR_GCP_PROJECT_ID
is the same GCP project for which Apigee was enabled and an Apigee org was provisioned for you. - Add the Apigee Connect Agent role to the MART service account that you created
in the
Create service accounts step in the Apigee hybrid installation instructions:
$ gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT_ID --member serviceAccount:YOUR_MART_SERVICE_ACCOUNT_EMAIL --role roles/apigeeconnect.Agent
WhereYOUR_GCP_PROJECT_ID
is the same GCP project for which Apigee was enabled and an Apigee org was provisioned for you, andYOUR_MART_SERVICE_ACCOUNT_EMAIL
is the MART service account name. The name is in the form of an email address. For example:apigee-mart@my-project.iam.gserviceaccount.com
.
The Apigee Connect Agent role is predefined and has the following permission assigned to it:
Permission Description apigeeconnect.endpoints.connect
This is the permission to set up the Apigee Connect Agent. For details on assigning granting access permissions through either the GCP console or APIs, see:
- Be sure the MART service account's key file is in the
hybrid_files/service_accounts
directory, as explained in Create service accounts. - Open your overrides file and add the following stanzas. The configuration requires you to provide
the path to the downloaded service account key. The key must be for a service account with the
Apigee Connect Agent role.
# Apigee Connect Agent connectAgent: enabled: true serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
Add the stanza under the k8sCluster heading, for example:
k8sCluster: name: your_cluster_name region: your_cluster_region # Apigee Connect Agent connectAgent: enabled: true serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
# Apigee Connect Agent connectAgent: enabled: true replicaCountMin: 3 serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
- Locate the service account key with the Apigee Organization Admin role that you downloaded when you originally installed Apigee hybrid as described in the section Enable synchronizer access. You need this key to generate a token needed to make an API call as explained below.
- Execute these two commands to get a token:
$ export GOOGLE_APPLICATION_CREDENTIALS=org-admin-service-account-file $ export TOKEN=$(gcloud auth application-default print-access-token)
Where org-admin-service-account-file is the path on your system to the service account key you downloaded with the Apigee Organization Admin role. - Call the following Apigee API to enable Apigee Connect for your organization:
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" } ] } }'
- Start the Apigee Connect Agent in the cluster:
$ $APIGEECTL_HOME/apigeectl apply -f your_overrides_file.yaml -c connect-agent
- Check the Apigee Connect Agent log. If there are no errors reported, the upgrade succeeded:
$ kubectl logs -n namespace apigee-connect-agent-pod-name
The Apigee Connect Agent reports the following log categories:
Audit logs category Operations DATA_READ ConnectionService.ListConnections
DATA_WRITE Tether.Egress
- Test the installation.
mart: hostAlias: "mart.apigee-hybrid-docs.net" serviceAccountPath: ./service-accounts/example-project-apigee-mart.json sslCertPath: ./certs/fullchain.pem sslKeyPath: ./certs/privkey.key
With this upgrade, the hybrid runtime plane communicates with the management plane through Apigee Connect.
See also: Removing Apigee Connect.
Test the installation
- Open the Apigee hybrid UI.
- Verify that any Developers and Developer apps that you previously created are present in the UI. Because these entities are queried from the MART server, they will be present only if the communication between the management and runtime planes is correctly configured.
- To be sure requests are going through Apigee Connect and not through the MART ingress, check the
MART server's log. You should see entries for the Apigee Connect agent named
apigee-connect-agent-1.0
:
$ kubectl logs -n apigee apigee-mart-orgname-rc101-q72tl -c apigee-mart | grep connect
For example:
"2019-12-11 04:59:52,321 org: env: target: action: context-id: mode: pool-1-thread-1 INFO MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.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"
- In the hybrid UI, create an API product, a developer, and a developer app. Then, check the MART
service log to be sure log entries confirm the entities were sent to the runtime plane. For example,
the following log entry shows that API product called
foo-product
was received:
$ kubectl logs -n apigee apigee-mart-orgname-rc101-q72tl -c apigee-mart
2019-12-16 22:15:29,572 org: env: target: action: context-id: mode: pool-1-thread-1 INFO MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.gserviceaccount.com 1576534529566 /v1/organizations/myorg/apiproducts/foo-product/ -NA- 201 CREATE myorg 10.16.1.61 10.16.1.64 apigee-connect-agent-1.0 null 2019-12-16 22:15:30,412 org: env: target: action: context-id: mode: pool-1-thread-1 INFO MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.gserviceaccount.com 1576534530407 /v1/organizations/myorg/apps/ apiProduct=foo-product&expand=false 200 GET myorg 10.16.1.61 10.16.1.64 apigee-connect-agent-1.0 null
- Try creating and deploying a new proxy, as explained in Create and deploy a proxy.
- Configure your proxy with API key verification by following the steps in Secure an API proxy by requiring API keys. The runtime obtains the data required to validate an API key from the management plane through Apigee Connect; therefore, if API key verification works, you know that the Apigee Connect is functioning properly. You can also check the Apigee Connect logs to see a report of the data transfers.
Removing Apigee Connect
If you delete the Apigee Connect deployment, the pod status can remain in the "Terminating" state for up to seven minutes. This amount of time is expected. Apigee Connect agents wait for the existing connections to expire instead of stopping them suddenly. The delay ensures that inflight requests are not lost.