This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
This example demonstrates how to use Apigee Adapter for Envoy by installing and running Envoy locally, not inside a Kubernetes cluster. You can follow the example in this document for both Apigee and Apigee hybrid installations.
API proxy calls go through Envoy running as a native application. Apigee provides API management services, such as API product and developer app creation. Envoy communicates with the Apigee management plane through the adapter's remote service. The adapter also pushes analytics data to Apigee where you can see it in Apigee Analytics.
Prerequisites
Before you begin: |
---|
|
|
|
Check your gcloud configuration
- Check that your
gcloud
configuration is set to the Google Cloud project associated with your Apigee organization.To list the current settings. See also gcloud config.
gcloud config list
If necessary, set the correct Google Cloud project ID with this command:
gcloud config set project project-id
- You must be authenticated with Google Cloud SDK (gcloud) for your Google Cloud project. See also
gcloud auth login.
gcloud auth login
Provision Apigee
In this step, you will use the Remote Service CLI to provision Apigee Adapter for Envoy assets to Apigee. The provisioning command deploys API proxies used for Apigee adapter operations, sets up a certificate on Apigee, and generates credentials the remote service will use to securely connect from your system to Apigee.
- Go to the
$CLI_HOME
directory:cd $CLI_HOME
- (Optional) By default, the adapter looks for default service account credentials in your Google
Cloud project for permission to send analytics data to Apigee. If you don't want to use the
default
service account credentials, you can create a service account and reference its key in the
provisioning command. The service account must have the
apigee.analyticsAgent
role. For instructions, see Creating and managing service accounts. - Create the following environment variables. These variables will be used as
parameters to the provisioning script:
export ORG=organization_name
export ENV=environment_name
export RUNTIME=host_alias_url
export NAMESPACE=hybrid_runtime_namespace
## Apigee hybrid onlyexport AX_SERVICE_ACCOUNT=analytics_service_account
## OptionalWhere:
Variable Description organization_name The name of your Apigee organization. environment_name The name of an environment in your organization. host_alias_url - For Apigee hybrid, a URL that includes the
hostAlias
for a virtual host defined in your hybrid configuration. - For Apigee, a hostname from the environment group that includes the environment. You can find environment groups in the Apigee UI under Admin > Environments > Groups.
Note: The URL must start with
https://
. For example:https://apitest.mydomain.net
hybrid_runtime_namepace (Apigee hybrid only) The namespace in which the Hybrid runtime components are deployed. Note: The default namespace for a hybrid deployment is
apigee
.analytics_service_account (Optional) The path to a Google Cloud service account key JSON file that has the Apigee Analytics Agent
role. For a detailed description of this parameter, see Provision command. - For Apigee hybrid, a URL that includes the
- If you are not an owner of the Google Cloud project associated with the Apigee organization, be sure that your Google Cloud user account includes either the Apigee Organization Admin role, or both the API Creator and the Deployer roles. See Granting, changing, and revoking access to resources.
- Get an access token:
TOKEN=$(gcloud auth print-access-token);echo $TOKEN
- Provision the remote service proxy to Apigee. The command output is redirected to a config file
that you will use in a later step.
If you are not upgrading, use this command to provision Apigee. If you are provisioning to Apigee hybrid, be sure to add the
--namespace $NAMESPACE
parameter:./apigee-remote-service-cli provision --organization $ORG --environment $ENV \ --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
If you are upgrading, use this command with the
--force-proxy-install
flag to provision Apigee. If you are provisioning to Apigee hybrid, be sure to add the--namespace $NAMESPACE
parameter:./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \ --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
- Check the contents of the
config.yaml
file. It should look something like this:# Configuration for apigee-remote-service-envoy (platform: Google Cloud) # generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28 apiVersion: v1 kind: ConfigMap metadata: name: apigee-remote-service-envoy namespace: apigee data: config.yaml: | tenant: remote_service_api: https://apitest.mydomain.com/remote-service org_name: my-org env_name: test analytics: collection_interval: 10s auth: jwt_provider_key: https://apitest.mydomain.com/remote-service/token --- apiVersion: v1 kind: Secret metadata: name: my-org-new-test-policy-secret namespace: apigee type: Opaque data: remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci... remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS... remote-service.properties: a2lkPTIwMjAtMDctMDZ... --- apiVersion: v1 kind: Secret metadata: name: my-org-new-test-analytics-secret namespace: apigee type: Opaque data: client_secret.json: ewogICJ0eXBlIjogInNlcnZ... --- apiVersion: v1 kind: ServiceAccount metadata: name: apigee-remote-service-envoy namespace: apigee
Run apigee-remote-service-envoy
You can run the Remote Service either as a native binary or on Docker.
Run the service natively
Execute the service binary with the config file that was output by the provisioning command:
$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml
Run the service on Docker
Docker images are published with release tags. For this install, use the latest version. There are three image variations to choose from:
Variation | Image |
---|---|
Google distroless | google/apigee-envoy-adapter:v2.0.3 |
Ubuntu | google/apigee-envoy-adapter:v2.0.3-ubuntu |
Ubuntu with Boring Crypto | google/apigee-envoy-adapter:v2.0.3-boring |
For example, to run the scratch image with your local config.yaml
available as /config.yaml
via a volume mount, use this command:
docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3
Create a sample Envoy configuration file
Generate a sample Envoy configuration file using the CLI:
- Make sure you are in the
$ENVOY_HOME
directory. - List the available configuration templates:
$CLI_HOME/apigee-remote-service-cli samples templates
Execute the samples command. For TEMPLATE, substitute one of the supported Envoy templates:
$CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml
The command creates the file
./samples/envoy-config.yaml
.
For more information, see Samples command.
Install and run the Envoy proxy
Follow these steps to install and run the Envoy proxy:
- Download an Envoy binary or build it.
- Run Envoy using a sample configuration file that you generated previously for the
httpbin.org
service:envoy -c ./samples/envoy-config.yaml
Test the installation
- Configure an API product and get an API key as explained in How to obtain an API key.
- Call the
httpbin
service without an API key:curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
The service is now being managed by Apigee, and because you did not supply an API key, the call returns the following error.
curl -i http://localhost:8080/headers -H "HOST:httpbin.org" HTTP/1.1 403 Forbidden date: Tue, 12 May 2020 17:51:36 GMT server: envoy content-length: 0 x-envoy-upstream-service-time: 11
- Make an API call using the key:
export APIKEY=YOUR_API_KEY
curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"
The call should succeed with a 200 status and return a list of headers in the response. For example:
curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS" HTTP/1.1 200 OK server: envoy date: Tue, 12 May 2020 17:55:34 GMT content-type: application/json content-length: 828 access-control-allow-origin: * access-control-allow-credentials: true x-envoy-upstream-service-time: 301 { "headers": { "Accept": "*/*", "Content-Length": "0", "Host": "httpbin.default.svc.cluster.local", "User-Agent": "curl/7.70.0-DEV", "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS", "X-Apigee-Accesstoken": "", "X-Apigee-Api": "httpbin.default.svc.cluster.local", "X-Apigee-Apiproducts": "httpbin", "X-Apigee-Application": "httpbin", "X-Apigee-Authorized": "true", "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS", "X-Apigee-Developeremail": "user@mydomain.com", "X-Apigee-Environment": "test", "X-Apigee-Organization": "my-org", "X-Apigee-Scope": "", "X-B3-Parentspanid": "1476f9a2329bbdfa", "X-B3-Sampled": "0", "X-B3-Spanid": "1ad5c19bfb4bc96f", "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa" } }
Uninstall Apigee Envoy adapter
To remove an Apigee Envoy adapter installation:
- Wherever you chose to have envoy adapter run (natively or on Docker), remove it.
- Delete the remote-service and remote-token proxies from your Apigee environment(s). See Deleting an API proxy.
- Remove any unused API products or operations used by the Envoy adapter use cases. See Deleting an API product.
Next steps
API traffic to the httpbin
service is now managed by Apigee. Here are
some features you can explore and try:
- Access Apigee Analytics in the Edge UI. Go to Analyze > API Metrics > API Proxy Performance.
- Explore the CLI options in the Reference.